This document specifies which procedures and techinques are used troughout the Xen codebase to prevent or minimize the impact of certain classes of run-time errors that can occurr in the execution of a C program, due to the very minimal built-in checks that are present in the language.

The presence of such documentation is requested by MISRA C:2012 Directive 4.1, whose headline states: "Run-time failures shall be minimized".

The ECLAIR checker for MISRA C:2012 Directive 4.1 requires the documentation to be supplied using the following format:

`Documentation for MISRA C:2012 Dir 4.1: <category> <description>`

The matched categories are the ones listed below (e.g., `overflow` and `unexpected wrapping`). The content of the description is not checked and can span multiple lines.

# 1 Documentation for MISRA C:2012 Dir 4.1: overflow

Pervasive use of assertions and extensive test suite.

# 2 Documentation for MISRA C:2012 Dir 4.1: unexpected wrapping

The only wrapping that is present in the code concerns unsigned integers and they are all expected.

# 3 Documentation for MISRA C:2012 Dir 4.1: invalid shift

Pervasive use of assertions and extensive test suite.

# 4 Documentation for MISRA C:2012 Dir 4.1: division/remainder by zero

The division or remainder operations in the project code ensure that their second argument is never zero.

# 5 Documentation for MISRA C:2012 Dir 4.1: unsequenced side effects

Code executed in interrupt handlers uses spinlocks or disables interrupts at the right locations to avoid unsequenced side effects.

# 6 Documentation for MISRA C:2012 Dir 4.1: read from uninitialized automatic object

The amount of dynamically allocated objects is limited at runtime in static configurations. We make sure to initialize dynamically allocated objects before reading them, and we utilize static analysis tools to help check for that.

# 7 Documentation for MISRA C:2012 Dir 4.1: read from uninitialized allocated object

Dynamically allocated storage is used in a controlled manner, to prevent the access to uninitialized allocated storage.

# 8 Documentation for MISRA C:2012 Dir 4.1: write to string literal or const object

The toolchain puts every string literal and const object into a read-only section of memory. The hardware exception raised when a write is attempted on such a memory section is correctly handled.

# 9 Documentation for MISRA C:2012 Dir 4.1: non-volatile access to volatile object

Volatile access is limited to registers that are always accessed through macros or inline functions, or by limited code chunks that are only used to access a register.

# 10 Documentation for MISRA C:2012 Dir 4.1: access to dead allocated object

Although dynamically allocated storage is used in the project, in safety configurations its usage is very limited at runtime (it is "almost" only used at boot time). Coverity is regularly used to scan the code to detect non-freed allocated objects.

# 11 Documentation for MISRA C:2012 Dir 4.1: access to dead automatic object

Pointers to automatic variables are never returned, nor stored in wider-scoped objects. No function does the same on any pointer received as a parameter.

# 12 Documentation for MISRA C:2012 Dir 4.1: access to dead thread object

The program does not use per-thread variables.

# 13 Documentation for MISRA C:2012 Dir 4.1: access using null pointer

All possibly null pointers are checked before access.

# 14 Documentation for MISRA C:2012 Dir 4.1: access using invalid pointer

Usage of pointers is limited. Pointers passed as parameters are always checked for validity.

# 15 Documentation for MISRA C:2012 Dir 4.1: access using out-of-bounds pointer

Pointers are never used to access arrays without checking for the array size first.

# 16 Documentation for MISRA C:2012 Dir 4.1: access using unaligned pointer

Pointer conversion that may result in unaligned pointers are never used.

# 17 Documentation for MISRA C:2012 Dir 4.1: mistyped access to object

Pointer conversions that may result in mistyped accesses to objects are never used.

# 18 Documentation for MISRA C:2012 Dir 4.1: mistyped access to function

This behaviour can arise, for instance, from:

- incongruent declarations;
- functions having no prototypes;
- casts on function pointers.

The project has adopted various compiler flags and MISRA rules to lessen the likelihood of this event.

# 19 Documentation for MISRA C:2012 Dir 4.1: invalid pointer arithmetic

Pointer arithmetic is never used without checking object boundaries.

# 20 Documentation for MISRA C:2012 Dir 4.1: invalid pointer comparison

Pointers to different objects are never compared (except for pointers that are actually linker symbols, but those cases are deviated with a justification).

# 21 Documentation for MISRA C:2012 Dir 4.1: overlapping copy

The code never uses memcpy() to copy overlapping objects. The instances of assignments involving overlapping objects are very limited and motivated.

# 22 Documentation for MISRA C:2012 Dir 4.1: invalid arguments to function

Many parameters to functions are checked for validity; there is ongoing work to make this true for all parameters.

# 23 Documentation for MISRA C:2012 Dir 4.1: returned function error

Many functions that may produce an error, do return a suitable status code that is checked at each call site. There is ongoing work to make this true for all such functions.

# 24 Documentation for MISRA C:2012 Dir 4.1: tainted input

All parameters of all functions in the extenal ABI are checked before being used.

# 25 Documentation for MISRA C:2012 Dir 4.1: data race

Data that can be accessed concurrently from multiple threads and code executed by interrupt handlers is protected using spinlocks and other forms of locking, as appropriate.

# 26 Documentation for MISRA C:2012 Dir 4.1: invariant violation

The extensive checks in the code ensure that any violation of a compile-time invariant will be detected prior to release builds, and violation of run-time invariants is extensively tested. In release builds the number of invariants is greatly reduced.

# 27 Documentation for MISRA C:2012 Dir 4.1: communication error

This project does not involve any external communication.