1.. SPDX-License-Identifier: CC-BY-4.0 2 3=================================================================== 4Measures taken towards the minimization of Run-time failures in Xen 5=================================================================== 6 7This document specifies which procedures and techinques are used troughout the 8Xen codebase to prevent or minimize the impact of certain classes of run-time 9errors that can occurr in the execution of a C program, due to the very minimal 10built-in checks that are present in the language. 11 12The presence of such documentation is requested by MISRA C:2012 Directive 4.1, 13whose headline states: "Run-time failures shall be minimized". 14 15The ECLAIR checker for MISRA C:2012 Directive 4.1 requires the documentation 16to be supplied using the following format: 17 18``Documentation for MISRA C:2012 Dir 4.1: <category> <description>`` 19 20The matched categories are the ones listed below (e.g., ``overflow`` and 21``unexpected wrapping``). The content of the description is not checked and can 22span multiple lines. 23 24Documentation for MISRA C:2012 Dir 4.1: overflow 25________________________________________________ 26 27Pervasive use of assertions and extensive test suite. 28 29 30Documentation for MISRA C:2012 Dir 4.1: unexpected wrapping 31___________________________________________________________ 32 33The only wrapping that is present in the code concerns 34unsigned integers and they are all expected. 35 36 37Documentation for MISRA C:2012 Dir 4.1: invalid shift 38_____________________________________________________ 39 40Pervasive use of assertions and extensive test suite. 41 42 43Documentation for MISRA C:2012 Dir 4.1: division/remainder by zero 44__________________________________________________________________ 45 46The division or remainder operations in the project code ensure that 47their second argument is never zero. 48 49 50Documentation for MISRA C:2012 Dir 4.1: unsequenced side effects 51________________________________________________________________ 52 53Code executed in interrupt handlers uses spinlocks or disables interrupts 54at the right locations to avoid unsequenced side effects. 55 56 57Documentation for MISRA C:2012 Dir 4.1: read from uninitialized automatic object 58________________________________________________________________________________ 59 60The amount of dynamically allocated objects is limited at runtime in 61static configurations. We make sure to initialize dynamically allocated 62objects before reading them, and we utilize static analysis tools to 63help check for that. 64 65 66Documentation for MISRA C:2012 Dir 4.1: read from uninitialized allocated object 67________________________________________________________________________________ 68 69Dynamically allocated storage is used in a controlled manner, to prevent the 70access to uninitialized allocated storage. 71 72 73Documentation for MISRA C:2012 Dir 4.1: write to string literal or const object 74_______________________________________________________________________________ 75 76The toolchain puts every string literal and const object into a read-only 77section of memory. The hardware exception raised when a write is attempted 78on such a memory section is correctly handled. 79 80 81Documentation for MISRA C:2012 Dir 4.1: non-volatile access to volatile object 82______________________________________________________________________________ 83 84Volatile access is limited to registers that are always accessed 85through macros or inline functions, or by limited code chunks that are only used 86to access a register. 87 88 89Documentation for MISRA C:2012 Dir 4.1: access to dead allocated object 90_______________________________________________________________________ 91 92Although dynamically allocated storage is used in the project, in safety 93configurations its usage is very limited at runtime (it is "almost" only used 94at boot time). Coverity is regularly used to scan the code to detect non-freed 95allocated objects. 96 97 98Documentation for MISRA C:2012 Dir 4.1: access to dead automatic object 99_______________________________________________________________________ 100 101Pointers to automatic variables are never returned, nor stored in 102wider-scoped objects. No function does the same on any pointer 103received as a parameter. 104 105 106Documentation for MISRA C:2012 Dir 4.1: access to dead thread object 107____________________________________________________________________ 108 109The program does not use per-thread variables. 110 111 112Documentation for MISRA C:2012 Dir 4.1: access using null pointer 113_________________________________________________________________ 114 115All possibly null pointers are checked before access. 116 117 118Documentation for MISRA C:2012 Dir 4.1: access using invalid pointer 119____________________________________________________________________ 120 121Usage of pointers is limited. Pointers passed as parameters are 122always checked for validity. 123 124 125Documentation for MISRA C:2012 Dir 4.1: access using out-of-bounds pointer 126__________________________________________________________________________ 127 128Pointers are never used to access arrays without checking for the array size 129first. 130 131 132Documentation for MISRA C:2012 Dir 4.1: access using unaligned pointer 133______________________________________________________________________ 134 135Pointer conversion that may result in unaligned pointers are never used. 136 137 138Documentation for MISRA C:2012 Dir 4.1: mistyped access to object 139_________________________________________________________________ 140 141Pointer conversions that may result in mistyped accesses to objects 142are never used. 143 144 145Documentation for MISRA C:2012 Dir 4.1: mistyped access to function 146___________________________________________________________________ 147 148This behaviour can arise, for instance, from: 149 150- incongruent declarations; 151- functions having no prototypes; 152- casts on function pointers. 153 154The project has adopted various compiler flags and MISRA rules to lessen the 155likelihood of this event. 156 157 158Documentation for MISRA C:2012 Dir 4.1: invalid pointer arithmetic 159__________________________________________________________________ 160 161Pointer arithmetic is never used without checking object boundaries. 162 163 164Documentation for MISRA C:2012 Dir 4.1: invalid pointer comparison 165__________________________________________________________________ 166 167Pointers to different objects are never compared (except for pointers that are 168actually linker symbols, but those cases are deviated with a justification). 169 170 171Documentation for MISRA C:2012 Dir 4.1: overlapping copy 172________________________________________________________ 173 174The code never uses memcpy() to copy overlapping objects. The instances of 175assignments involving overlapping objects are very limited and motivated. 176 177 178Documentation for MISRA C:2012 Dir 4.1: invalid arguments to function 179_____________________________________________________________________ 180 181Many parameters to functions are checked for validity; there is ongoing work to 182make this true for all parameters. 183 184 185Documentation for MISRA C:2012 Dir 4.1: returned function error 186_______________________________________________________________ 187 188Many functions that may produce an error, do return a suitable status code 189that is checked at each call site. There is ongoing work to make this true for 190all such functions. 191 192 193Documentation for MISRA C:2012 Dir 4.1: tainted input 194_____________________________________________________ 195 196All parameters of all functions in the extenal ABI are checked before being 197used. 198 199 200Documentation for MISRA C:2012 Dir 4.1: data race 201_________________________________________________ 202 203Data that can be accessed concurrently from multiple threads and code executed 204by interrupt handlers is protected using spinlocks and other forms of locking, 205as appropriate. 206 207 208Documentation for MISRA C:2012 Dir 4.1: invariant violation 209___________________________________________________________ 210 211The extensive checks in the code ensure that any violation of a compile-time 212invariant will be detected prior to release builds, and violation of run-time 213invariants is extensively tested. In release builds the number of invariants 214is greatly reduced. 215 216 217Documentation for MISRA C:2012 Dir 4.1: communication error 218___________________________________________________________ 219 220This project does not involve any external communication. 221