1.. SPDX-License-Identifier: CC-BY-4.0 2 3MISRA C deviations for Xen 4========================== 5 6The following is the list of MISRA C:2012 deviations for the Xen codebase that 7are not covered by a `SAF-x-safe` or `SAF-x-false-positive-<tool>` comment, as 8specified in docs/misra/documenting-violations.rst; the lack of 9such comments is usually due to the excessive clutter they would bring to the 10codebase or the impossibility to express such a deviation (e.g., if it's 11composed of several conditions). 12 13Deviations related to MISRA C:2012 Directives: 14---------------------------------------------- 15 16.. list-table:: 17 :header-rows: 1 18 19 * - Directive identifier 20 - Justification 21 - Notes 22 23 * - D4.3 24 - Accepted for the ARM64 codebase 25 - Tagged as `disapplied` for ECLAIR on any other violation report. 26 27 * - D4.3 28 - The inline asm in 'xen/arch/arm/arm64/lib/bitops.c' is tightly coupled 29 with the surronding C code that acts as a wrapper, so it has been decided 30 not to add an additional encapsulation layer. 31 - Tagged as `deliberate` for ECLAIR. 32 33Deviations related to MISRA C:2012 Rules: 34----------------------------------------- 35 36.. list-table:: 37 :header-rows: 1 38 39 * - Rule identifier 40 - Justification 41 - Notes 42 43 * - R2.1 44 - The compiler implementation guarantees that the unreachable code is 45 removed. Constant expressions and unreachable branches of if and switch 46 statements are expected. 47 - Tagged as `safe` for ECLAIR. 48 49 * - R2.1 50 - Unreachability caused by calls to the following functions or macros is 51 deliberate and there is no risk of code being unexpectedly left out. 52 - Tagged as `deliberate` for ECLAIR. Such macros are: 53 - BUG 54 - assert_failed 55 - __builtin_unreachable 56 - ASSERT_UNREACHABLE 57 58 * - R2.1 59 - Pure declarations, that is, declarations without initializations are not 60 executable, and therefore it is safe for them to be unreachable. The most 61 notable example of such a pattern being used in the codebase is that of 62 a variable declaration that should be available in all the clauses of a 63 switch statement. 64 - ECLAIR has been configured to ignore those statements. 65 66 * - R2.1 67 - The asm-offset files are not linked deliberately, since they are used to 68 generate definitions for asm modules. 69 - Tagged as `deliberate` for ECLAIR. 70 71 * - R2.2 72 - Proving compliance with respect to Rule 2.2 is generally impossible: 73 see `<https://arxiv.org/abs/2212.13933>`_ for details. Moreover, peer 74 review gives us confidence that no evidence of errors in the program's 75 logic has been missed due to undetected violations of Rule 2.2, if any. 76 Testing on time behavior gives us confidence on the fact that, should the 77 program contain dead code that is not removed by the compiler, the 78 resulting slowdown is negligible. 79 - Project-wide deviation, tagged as `disapplied` for ECLAIR. 80 81 * - R2.6 82 - Labels deliberately marked as unused trough the pseudo-attribute 83 `__maybe_unused` are either the result of them not being in certain build 84 configurations, or as a deliberate practice (e.g., `unimplemented_insn`). 85 Given that the compiler is then entitled to remove them, the presence of 86 such labels poses no risks. 87 - Tagged as `deliberate` for ECLAIR. 88 89 * - R3.1 90 - Comments starting with '/\*' and containing hyperlinks are safe as they 91 are not instances of commented-out code. 92 - Tagged as `safe` for ECLAIR. 93 94 * - R5.3 95 - As specified in rules.rst, shadowing due to macros being used as macro 96 arguments is allowed, as it's deemed not at risk of causing developer 97 confusion. 98 - Tagged as `safe` for ECLAIR. So far, the following macros are deviated: 99 - READ_SYSREG and WRITE_SYSREG 100 - max_{t}? and min_{t}? 101 - read_[bwlq] and read_[bwlq]_relaxed 102 - per_cpu and this_cpu 103 - __emulate_2op and __emulate_2op_nobyte 104 - read_debugreg and write_debugreg 105 106 * - R5.5 107 - Macros expanding to their own name are allowed. 108 - Tagged as `deliberate` for ECLAIR. 109 110 * - R5.5 111 - Clashes between names of function-like macros and identifiers of 112 non-callable entities are allowed. 113 - Tagged as `deliberate` for ECLAIR. 114 115 * - R5.5 116 - Clashes between function names and macros are deliberate for string 117 handling functions since some architectures may want to use their own 118 arch-specific implementation. 119 - Tagged as `deliberate` for ECLAIR. 120 121 * - R5.5 122 - In libelf, clashes between macros and function names are deliberate and 123 needed to prevent the use of undecorated versions of memcpy, memset and 124 memmove. 125 - Tagged as `deliberate` for ECLAIR. 126 127 * - R5.6 128 - The type ret_t is deliberately defined multiple times depending on the 129 type of guest to service. 130 - Tagged as `deliberate` for ECLAIR. 131 132 * - R5.6 133 - On X86, some types are deliberately defined multiple times, depending on 134 the number of guest paging levels. 135 - Tagged as `deliberate` for ECLAIR. Such types are: 136 - guest_intpte_t 137 - guest_l[12]e_t 138 139 * - R5.6 140 - Some files are not subject to respect MISRA rules at 141 the moment, but, among these out-of-scope files, there are definitions 142 of typedef names that are already defined within in-scope files and 143 therefore, ECLAIR does report a violation since not all the files 144 involved in the violation are excluded from the analysis. 145 - Tagged as `deliberate` for ECLAIR. Such excluded files are: 146 - xen/include/efi/* 147 - xen/arch/*/include/asm/*/efibind.h 148 149 * - R7.1 150 - It is safe to use certain octal constants the way they are defined 151 in specifications, manuals, and algorithm descriptions. Such places 152 are marked safe with a /\* octal-ok \*/ in-code comment. 153 - Tagged as `safe` for ECLAIR. 154 155 * - R7.2 156 - Violations caused by __HYPERVISOR_VIRT_START are related to the 157 particular use of it done in xen_mk_ulong. 158 - Tagged as `deliberate` for ECLAIR. 159 160 * - R7.4 161 - Allow pointers of non-character type as long as the pointee is 162 const-qualified. 163 - ECLAIR has been configured to ignore these assignments. 164 165 * - R8.3 166 - The type ret_t is deliberately used and defined as int or long depending 167 on the architecture. 168 - Tagged as `deliberate` for ECLAIR. 169 170 * - R8.3 171 - Some files are not subject to respect MISRA rules at 172 the moment, but some entity from a file in scope is used; therefore 173 ECLAIR does report a violation, since not all the files involved in the 174 violation are excluded from the analysis. 175 - Tagged as `deliberate` for ECLAIR. Such excluded files are: 176 - xen/arch/x86/time.c 177 - xen/arch/x86/acpi/cpu_idle.c 178 - xen/arch/x86/mpparse.c 179 - xen/common/bunzip2.c 180 - xen/common/unlz4.c 181 - xen/common/unlzma.c 182 - xen/common/unlzo.c 183 - xen/common/unxz.c 184 - xen/common/unzstd.c 185 186 * - R8.3 187 - Parameter name "unused" (with an optional numeric suffix) is deliberate 188 and makes explicit the intention of not using such parameter within the 189 function. 190 - Tagged as `deliberate` for ECLAIR. 191 192 * - R8.4 193 - The definitions present in the files 'asm-offsets.c' for any architecture 194 are used to generate definitions for asm modules, and are not called by 195 C code. Therefore the absence of prior declarations is safe. 196 - Tagged as `safe` for ECLAIR. 197 198 * - R8.4 199 - The functions defined in the file xen/common/coverage/gcov_base.c are 200 meant to be called from gcc-generated code in a non-release build 201 configuration. Therefore, the absence of prior declarations is safe. 202 - Tagged as `safe` for ECLAIR. 203 204 * - R8.4 205 - Functions and variables used only by asm modules are marked with 206 the `asmlinkage` macro. Existing code may use a SAF-1-safe 207 textual deviation (see safe.json), but new code should not use 208 it. 209 - Tagged as `safe` for ECLAIR. 210 211 * - R8.4 212 - Some functions are excluded from non-debug build, therefore the absence 213 of declaration is safe. 214 - Tagged as `safe` for ECLAIR, such functions are: 215 - apei_read_mce() 216 - apei_check_mce() 217 - apei_clear_mce() 218 219 * - R8.4 220 - Given that bsearch and sort are defined with the attribute 'gnu_inline', 221 it's deliberate not to have a prior declaration. 222 See Section \"6.33.1 Common Function Attributes\" of \"GCC_MANUAL\" for 223 a full explanation of gnu_inline. 224 - Tagged as `deliberate` for ECLAIR. 225 226 * - R8.4 227 - first_valid_mfn is defined in this way because the current lack of NUMA 228 support in Arm and PPC requires it. 229 - Tagged as `deliberate` for ECLAIR. 230 231 * - R8.6 232 - The following variables are compiled in multiple translation units 233 belonging to different executables and therefore are safe. 234 235 - current_stack_pointer 236 - bsearch 237 - sort 238 - Tagged as `safe` for ECLAIR. 239 240 * - R8.6 241 - Declarations without definitions are allowed (specifically when the 242 definition is compiled-out or optimized-out by the compiler). 243 - Tagged as `deliberate` in ECLAIR. 244 245 * - R8.6 246 - The search procedure for Unix linkers is well defined, see ld(1) manual: 247 "The linker will search an archive only once, at the location where it 248 is specified on the command line. If the archive defines a symbol which 249 was undefined in some object which appeared before the archive on the 250 command line, the linker will include the appropriate file(s) from the 251 archive". 252 In Xen, thanks to the order in which file names appear in the build 253 commands, if arch-specific definitions are present, they get always 254 linked in before searching in the lib.a archive resulting from xen/lib. 255 - Tagged as `deliberate` for ECLAIR. 256 257 * - R8.10 258 - The gnu_inline attribute without static is deliberately allowed. 259 - Tagged as `deliberate` for ECLAIR. 260 261 * - R9.5 262 - The possibility of committing mistakes by specifying an explicit 263 dimension is higher than omitting the dimension, therefore all such 264 instances of violations are deviated. 265 - Project-wide deviation, tagged as `deliberate` for ECLAIR. 266 267 * - R10.1, R10.3, R10.4 268 - The value-preserving conversions of integer constants are safe. 269 - Tagged as `safe` for ECLAIR. 270 271 * - R10.1 272 - Shifting non-negative integers to the right is safe. 273 - Tagged as `safe` for ECLAIR. 274 275 * - R10.1 276 - Shifting non-negative integers to the left is safe if the result is still 277 non-negative. 278 - Tagged as `safe` for ECLAIR. 279 280 * - R10.1 281 - Bitwise logical operations on non-negative integers are safe. 282 - Tagged as `safe` for ECLAIR. 283 284 * - R10.1 285 - The implicit conversion to Boolean for logical operator arguments is 286 well-known to all Xen developers to be a comparison with 0. 287 - Tagged as `safe` for ECLAIR. 288 289 * - R10.1 290 - Xen only supports architectures where signed integers are representend 291 using two's complement and all the Xen developers are aware of this. For 292 this reason, bitwise operations are safe. 293 - Tagged as `safe` for ECLAIR. 294 295 * - R10.1 296 - Given the assumptions on the toolchain detailed in 297 docs/misra/C-language-toolchain.rst and the build flags used by the 298 project, it is deemed safe to use bitwise shift operators. 299 See automation/eclair_analysis/deviations.ecl for the full explanation. 300 - Tagged as `safe` for ECLAIR. 301 302 * - R10.1 303 - The macro ISOLATE_LSB encapsulates the well-known pattern (x & -x) 304 applied to unsigned integer values on 2's complement architectures 305 (i.e., all architectures supported by Xen), used to obtain a mask where 306 just the least significant nonzero bit of x is set. 307 If no bits are set, 0 is returned. 308 - Tagged as `safe` for ECLAIR. 309 310 * - R11.1 311 - The conversion from a function pointer to unsigned long or (void \*) does 312 not lose any information, provided that the target type has enough bits 313 to store it. 314 - Tagged as `safe` for ECLAIR. 315 316 * - R11.1 317 - The conversion from a function pointer to a boolean has a well-known 318 semantics that do not lead to unexpected behaviour. 319 - Tagged as `safe` for ECLAIR. 320 321 * - R11.2 322 - The conversion from a pointer to an incomplete type to unsigned long 323 does not lose any information, provided that the target type has enough 324 bits to store it. 325 - Tagged as `safe` for ECLAIR. 326 327 * - R11.3 328 - Conversions to object pointers that have a pointee type with a smaller 329 (i.e., less strict) alignment requirement are safe. 330 - Tagged as `safe` for ECLAIR. 331 332 * - R11.6 333 - Conversions from and to integral types are safe, in the assumption that 334 the target type has enough bits to store the value. 335 See also Section \"4.7 Arrays and Pointers\" of \"GCC_MANUAL\" 336 - Tagged as `safe` for ECLAIR. 337 338 * - R11.6 339 - The conversion from a pointer to a boolean has a well-known semantics 340 that do not lead to unexpected behaviour. 341 - Tagged as `safe` for ECLAIR. 342 343 * - R11.8 344 - Violations caused by container_of are due to pointer arithmetic operations 345 with the provided offset. The resulting pointer is then immediately cast back to its 346 original type, which preserves the qualifier. This use is deemed safe. 347 Fixing this violation would require to increase code complexity and lower readability. 348 - Tagged as `safe` for ECLAIR. 349 350 * - R11.9 351 - __ACCESS_ONCE uses an integer, which happens to be zero, as a 352 compile time check. The typecheck uses a cast. The usage of zero or other 353 integers for this purpose is allowed. 354 - Tagged as `deliberate` for ECLAIR. 355 356 * - R13.5 357 - All developers and reviewers can be safely assumed to be well aware of 358 the short-circuit evaluation strategy for logical operators. 359 - Project-wide deviation; tagged as `disapplied` for ECLAIR. 360 361 * - R13.6 362 - On x86, macros alternative_v?call[0-9] use sizeof and typeof to check 363 that the argument types match the corresponding parameter ones. 364 - Tagged as `deliberate` for ECLAIR. 365 366 * - R13.6 367 - Anything, no matter how complicated, inside the BUILD_BUG_ON macro is 368 subject to a compile-time evaluation without relevant side effects." 369 - Tagged as `safe` for ECLAIR. 370 371 * - R14.2 372 - The severe restrictions imposed by this rule on the use of 'for' 373 statements are not counterbalanced by the presumed facilitation of the 374 peer review activity. 375 - Project-wide deviation; tagged as `disapplied` for ECLAIR. 376 377 * - R14.3 378 - The Xen team relies on the fact that invariant conditions of 'if' 379 statements and conditional operators are deliberate. 380 - Tagged as `deliberate` for ECLAIR. 381 382 * - R14.3 383 - Switches having a 'sizeof' operator as the condition are deliberate and 384 have limited scope. 385 - Tagged as `deliberate` for ECLAIR. 386 387 * - R14.3 388 - The use of an invariant size argument in {put,get}_unsafe_size and 389 array_access_ok, as defined in arch/x86(_64)?/include/asm/uaccess.h is 390 deliberate and is deemed safe. 391 - Tagged as `deliberate` for ECLAIR. 392 393 * - R14.4 394 - A controlling expression of 'if' and iteration statements having 395 integer, character or pointer type has a semantics that is well-known to 396 all Xen developers. 397 - Tagged as `deliberate` for ECLAIR. 398 399 * - R14.4 400 - The XEN team relies on the fact that the enum is_dying has the 401 constant with assigned value 0 act as false and the other ones as true, 402 therefore have the same behavior of a boolean. 403 - Tagged as `deliberate` for ECLAIR. 404 405 * - R16.2 406 - Complying with the Rule would entail a lot of code duplication in the 407 implementation of the x86 emulator, therefore it is deemed better to 408 leave such files as is. 409 - Tagged as `deliberate` for ECLAIR. 410 411 * - R16.3 412 - Switch clauses ending with continue, goto, return statements are safe. 413 - Tagged as `safe` for ECLAIR. 414 415 * - R16.3 416 - Switch clauses ending with a call to a function that does not give 417 the control back (i.e., a function with attribute noreturn) are safe. 418 - Tagged as `safe` for ECLAIR. 419 420 * - R16.3 421 - Switch clauses ending with pseudo-keyword \"fallthrough\" are safe. 422 - Tagged as `safe` for ECLAIR. 423 424 * - R16.3 425 - Switch clauses ending with failure method \"BUG()\" are safe. 426 - Tagged as `safe` for ECLAIR. 427 428 * - R16.3 429 - Existing switch clauses not ending with the break statement are safe if 430 an explicit comment indicating the fallthrough intention is present. 431 However, the use of such comments in new code is deprecated: 432 the pseudo-keyword "fallthrough" shall be used. 433 - Tagged as `safe` for ECLAIR. The accepted comments are: 434 - /\* fall through \*/ 435 - /\* fall through. \*/ 436 - /\* fallthrough \*/ 437 - /\* fallthrough. \*/ 438 - /\* Fall through \*/ 439 - /\* Fall through. \*/ 440 - /\* Fallthrough \*/ 441 - /\* Fallthrough. \*/ 442 443 * - R16.4 444 - Switch statements having a controlling expression of enum type 445 deliberately do not have a default case: gcc -Wall enables -Wswitch 446 which warns (and breaks the build as we use -Werror) if one of the enum 447 labels is missing from the switch. 448 - Tagged as `deliberate` for ECLAIR. 449 450 * - R16.4 451 - A switch statement with a single switch clause and no default label may 452 be used in place of an equivalent if statement if it is considered to 453 improve readability. 454 - Tagged as `deliberate` for ECLAIR. 455 456 * - R16.6 457 - A switch statement with a single switch clause and no default label may 458 be used in place of an equivalent if statement if it is considered to 459 improve readability. 460 - Tagged as `deliberate` for ECLAIR. 461 462 * - R17.1 463 - printf()-like functions are allowed to use the variadic features provided 464 by `stdarg.h`. 465 - Tagged as `deliberate` for ECLAIR. 466 467 * - R17.7 468 - Not using the return value of a function does not endanger safety if it 469 coincides with an actual argument. 470 - Tagged as `safe` for ECLAIR. Such functions are: 471 - __builtin_memcpy() 472 - __builtin_memmove() 473 - __builtin_memset() 474 - cpumask_check() 475 476 * - R20.4 477 - The override of the keyword \"inline\" in xen/compiler.h is present so 478 that section contents checks pass when the compiler chooses not to 479 inline a particular function. 480 - Comment-based deviation. 481 482 * - R20.7 483 - Code violating Rule 20.7 is safe when macro parameters are used: 484 (1) as function arguments; 485 (2) as macro arguments; 486 (3) as array indices; 487 (4) as lhs in assignments; 488 (5) as initializers, possibly designated, in initalizer lists; 489 (6) as constant expressions of switch case labels. 490 - Tagged as `safe` for ECLAIR. 491 492 * - R20.7 493 - Violations due to the use of macros defined in files that are not 494 in scope for compliance are allowed, as that is imported code. 495 - Tagged as `safe` for ECLAIR. 496 497 * - R20.7 498 - To avoid compromising readability, the macros `alternative_(v)?call[0-9]` 499 are allowed not to parenthesize their arguments, as there are already 500 sanity checks in place. 501 - Tagged as `safe` for ECLAIR. 502 503 * - R20.7 504 - The macro `count_args_` is not compliant with the rule, but is not likely 505 to incur in the risk of being misused or lead to developer confusion, and 506 refactoring it to add parentheses breaks its functionality. 507 - Tagged as `safe` for ECLAIR. 508 509 * - R20.12 510 - Variadic macros that use token pasting often employ the gcc extension 511 `ext_paste_comma`, as detailed in `C-language-toolchain.rst`, which is 512 not easily replaceable; macros that in addition perform regular argument 513 expansion on the same argument subject to the # or ## operators violate 514 the Rule if the argument is a macro. 515 - Tagged as `deliberate` for ECLAIR. 516 517 * - R20.12 518 - Macros that are used for runtime or build-time assertions contain 519 deliberate uses of an argument as both a regular argument and a 520 stringification token, to provide useful diagnostic messages. 521 - Tagged as `deliberate` for ECLAIR. 522 523 * - R20.12 524 - GENERATE_CASE is a local helper macro that allows some selected switch 525 statements to be more compact and readable. As such, the risk of 526 developer confusion in using such macro is deemed negligible. This 527 construct is deviated only in Translation Units that present a violation 528 of the Rule due to uses of this macro. 529 - Tagged as `deliberate` for ECLAIR. 530 531 * - R21.9 532 - Xen does not use the `bsearch` and `qsort` functions provided by the C 533 Standard Library, but provides in source form its own implementation, 534 therefore any unspecified or undefined behavior associated to the 535 functions provided by the Standard Library does not apply. Any such 536 behavior that may exist in such functions is therefore under the 537 jurisdiction of other MISRA C rules. 538 - Project-wide deviation, tagged as `deliberate` for ECLAIR. 539 540 * - R21.10 541 - Xen does not use the facilities provided by the `\<time.h\>` provided by the C 542 Standard Library, but provides in source form its own implementation, 543 therefore any unspecified, undefined or implementation-defined behavior 544 associated to the functions provided by the Standard Library does not 545 apply. Any such behavior that may exist in such functions is therefore 546 under the jurisdiction of other MISRA C rules. 547 - Project-wide deviation, tagged as `deliberate` for ECLAIR. 548 549Other deviations: 550----------------- 551 552.. list-table:: 553 :header-rows: 1 554 555 * - Deviation 556 - Justification 557 558 * - do-while-0 and do-while-1 loops 559 - The do-while-0 and do-while-1 loops are well-recognized loop idioms used 560 by the Xen community and can therefore be used, even though they would 561 cause a number of violations in some instances. 562 563 * - while-0 and while-1 loops 564 - while-0 and while-1 are well-recognized loop idioms used by the Xen 565 community and can therefore be used, even though they would cause a 566 number of violations in some instances. 567