1.. SPDX-License-Identifier: CC-BY-4.0 2 3MISRA C rules for Xen 4===================== 5 6.. note:: 7 8 **IMPORTANT** All MISRA C rules, text, and examples are copyrighted 9 by the MISRA Consortium Limited and used with permission. 10 11 Please refer to https://www.misra.org.uk/ to obtain a copy of MISRA 12 C, or for licensing options for other use of the rules. 13 14The following is the list of MISRA C rules that apply to the Xen 15hypervisor. 16 17It is possible that in specific circumstances it is best not to follow a 18rule because it is not possible or because the alternative leads to 19better code quality. Those cases are called "deviations". They are 20permissible as long as they are documented. For details, please refer to 21docs/misra/documenting-violations.rst and docs/misra/deviations.rst 22 23Other documentation mechanisms are work-in-progress. 24 25The existing codebase is not 100% compliant with the rules. Some of the 26violations are meant to be documented as deviations, while some others 27should be fixed. Both compliance and documenting deviations on the 28existing codebase are work-in-progress. 29 30The list below might need to be updated over time. Reach out to THE REST 31maintainers if you want to suggest a change. 32 33.. list-table:: 34 :header-rows: 1 35 36 * - Dir number 37 - Severity 38 - Summary 39 - Notes 40 41 * - `Dir 1.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_01_01.c>`_ 42 - Required 43 - Any implementation-defined behaviour on which the output of the 44 program depends shall be documented and understood 45 - 46 47 * - `Dir 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_ 48 - Required 49 - All source files shall compile without any compilation errors 50 - 51 52 * - `Dir 4.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_01.c>`_ 53 - Required 54 - Run-time failures shall be minimized 55 - The strategies adopted by Xen to prevent certain classes of runtime 56 failures is documented by 57 `C-runtime-failures.rst <docs/misra/C-runtime-failures.rst>`_ 58 59 * - `Dir 4.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_07.c>`_ 60 - Required 61 - If a function returns error information then that error 62 information shall be tested 63 - 64 65 * - `Dir 4.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_10.c>`_ 66 - Required 67 - Precautions shall be taken in order to prevent the contents of a 68 header file being included more than once 69 - Files that are intended to be included more than once do not need to 70 conform to the directive 71 72 * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_ 73 - Required 74 - The validity of values passed to library functions shall be checked 75 - We do not have libraries in Xen (libfdt and others are not 76 considered libraries from MISRA C point of view as they are 77 imported in source form) 78 79 * - `Dir 4.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_14.c>`_ 80 - Required 81 - The validity of values received from external sources shall be 82 checked 83 - 84 85.. list-table:: 86 :header-rows: 1 87 88 * - Rule number 89 - Severity 90 - Summary 91 - Notes 92 93 * - `Rule 1.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_01_01.c>`_ 94 - Required 95 - The program shall contain no violations of the standard C syntax 96 and constraints, and shall not exceed the implementation's 97 translation limits 98 - We make use of several compiler extensions as documented by 99 `C-language-toolchain.rst <docs/misra/C-language-toolchain.rst>`_ 100 101 * - `Rule 1.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_01_03.c>`_ 102 - Required 103 - There shall be no occurrence of undefined or critical unspecified 104 behaviour 105 - 106 107 * - `Rule 1.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/>`_ 108 - Required 109 - Emergent language features shall not be used 110 - Emergent language features, such as C11 features, should not be 111 confused with similar compiler extensions, which we use. When the 112 time comes to adopt C11, this rule will be revisited. 113 114 * - `Rule 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_01_1.c>`_ 115 - Required 116 - A project shall not contain unreachable code 117 - The following are allowed: 118 - Invariantly constant conditions, e.g. if(IS_ENABLED(CONFIG_HVM)) { S; } 119 - Switch with a controlling value statically determined not to 120 match one or more case statements 121 - Functions that are intended to be referenced only from 122 assembly code (e.g. 'do_trap_fiq') 123 - asm-offsets.c, as they are not linked deliberately, because 124 they are used to generate definitions for asm modules 125 - Declarations without initializer are safe, as they are not 126 executed 127 128 * - `Rule 2.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_06.c>`_ 129 - Advisory 130 - A function should not contain unused label declarations 131 - 132 133 * - `Rule 3.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_01.c>`_ 134 - Required 135 - The character sequences /* and // shall not be used within a 136 comment 137 - Comments containing hyperlinks inside C-style block comments are safe 138 139 * - `Rule 3.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_02.c>`_ 140 - Required 141 - Line-splicing shall not be used in // comments 142 - 143 144 * - `Rule 4.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_04_01.c>`_ 145 - Required 146 - Octal and hexadecimal escape sequences shall be terminated 147 - 148 149 * - `Rule 4.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_04_02.c>`_ 150 - Advisory 151 - Trigraphs should not be used 152 - 153 154 * - `Rule 5.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_01_2.c>`_ 155 - Required 156 - External identifiers shall be distinct 157 - The Xen characters limit for identifiers is 40. Public headers 158 (xen/include/public/) are allowed to retain longer identifiers 159 for backward compatibility. 160 161 * - `Rule 5.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_02.c>`_ 162 - Required 163 - Identifiers declared in the same scope and name space shall be 164 distinct 165 - The Xen characters limit for identifiers is 40. Public headers 166 (xen/include/public/) are allowed to retain longer identifiers 167 for backward compatibility. 168 169 * - `Rule 5.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_03.c>`_ 170 - Required 171 - An identifier declared in an inner scope shall not hide an 172 identifier declared in an outer scope 173 - Using macros as macro parameters at invocation time is allowed 174 even if both macros use identically named local variables, e.g. 175 max(var0, min(var1, var2)) 176 177 * - `Rule 5.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_04.c>`_ 178 - Required 179 - Macro identifiers shall be distinct 180 - The Xen characters limit for macro identifiers is 40. Public 181 headers (xen/include/public/) are allowed to retain longer 182 identifiers for backward compatibility. 183 184 * - `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_ 185 - Required 186 - Identifiers shall be distinct from macro names 187 - Macros expanding to their own name are allowed, e.g.:: 188 189 #define x x 190 191 Clashes between names of function-like macros and identifiers of 192 non-callable entities are allowed. Callable entities having an 193 identifier that is the same of the name of a 194 function-like macro are not allowed. Example (not allowed):: 195 196 #define f(x, y) f(x, y) 197 void f(int x, int y); 198 199 * - `Rule 5.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_06.c>`_ 200 - Required 201 - A typedef name shall be a unique identifier 202 - 203 204 * - `Rule 6.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_01.c>`_ 205 - Required 206 - Bit-fields shall only be declared with an appropriate type 207 - In addition to the C99 types, we also consider appropriate types 208 enum and all explicitly signed / unsigned integer types. 209 210 * - `Rule 6.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_02.c>`_ 211 - Required 212 - Single-bit named bit fields shall not be of a signed type 213 - 214 215 * - `Rule 7.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_01.c>`_ 216 - Required 217 - Octal constants shall not be used 218 - 219 220 * - `Rule 7.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_02.c>`_ 221 - Required 222 - A "u" or "U" suffix shall be applied to all integer constants 223 that are represented in an unsigned type 224 - The rule asks that any integer literal that is implicitly 225 unsigned is made explicitly unsigned by using one of the 226 indicated suffixes. As an example, on a machine where the int 227 type is 32-bit wide, 0x77777777 is signed whereas 0x80000000 is 228 (implicitly) unsigned. In order to comply with the rule, the 229 latter should be rewritten as either 0x80000000u or 0x80000000U. 230 Consistency considerations may suggest using the same suffix even 231 when not required by the rule. For instance, if one has: 232 233 Original: f(0x77777777); f(0x80000000); 234 235 one should do 236 237 Solution 1: f(0x77777777U); f(0x80000000U); 238 239 over 240 241 Solution 2: f(0x77777777); f(0x80000000U); 242 243 after having ascertained that "Solution 1" is compatible with the 244 intended semantics. 245 246 * - `Rule 7.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_03.c>`_ 247 - Required 248 - The lowercase character l shall not be used in a literal suffix 249 - 250 251 * - `Rule 7.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_04.c>`_ 252 - Required 253 - A string literal shall not be assigned to an object unless the 254 object type is pointer to const-qualified char 255 - All "character types" are permitted, as long as the string 256 element type and the character type match. (There should be no 257 casts.) Assigning a string literal to any object with type 258 "pointer to const-qualified void" is allowed. 259 260 * - `Rule 8.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_01.c>`_ 261 - Required 262 - Types shall be explicitly specified 263 - 264 265 * - `Rule 8.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_02.c>`_ 266 - Required 267 - Function types shall be in prototype form with named parameters 268 - Clarification: both function and function pointers types shall 269 have named parameters. 270 271 * - `Rule 8.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_03.c>`_ 272 - Required 273 - All declarations of an object or function shall use the same 274 names and type qualifiers 275 - The type ret_t maybe be deliberately used and defined as int or 276 long depending on the type of guest to service 277 278 * - `Rule 8.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_04.c>`_ 279 - Required 280 - A compatible declaration shall be visible when an object or 281 function with external linkage is defined 282 - Allowed exceptions: asm-offsets.c, definitions for asm modules 283 not called from C code, gcov_base.c 284 285 * - `Rule 8.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_05_2.c>`_ 286 - Required 287 - An external object or function shall be declared once in one and only one file 288 - 289 290 * - `Rule 8.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_06_2.c>`_ 291 - Required 292 - An identifier with external linkage shall have exactly one 293 external definition 294 - Declarations without definitions are allowed (specifically when 295 the definition is compiled-out or optimized-out by the compiler) 296 297 * - `Rule 8.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_08.c>`_ 298 - Required 299 - The static storage class specifier shall be used in all 300 declarations of objects and functions that have internal linkage 301 - 302 303 * - `Rule 8.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_10.c>`_ 304 - Required 305 - An inline function shall be declared with the static storage class 306 - gnu_inline (without static) is allowed. 307 308 * - `Rule 8.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_12.c>`_ 309 - Required 310 - Within an enumerator list the value of an implicitly-specified 311 enumeration constant shall be unique 312 - 313 314 * - `Rule 8.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_14.c>`_ 315 - Required 316 - The restrict type qualifier shall not be used 317 - 318 319 * - `Rule 9.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_01.c>`_ 320 - Mandatory 321 - The value of an object with automatic storage duration shall not 322 be read before it has been set 323 - Rule clarification: do not use variables before they are 324 initialized. An explicit initializer is not necessarily required. 325 Try reducing the scope of the variable. If an explicit 326 initializer is added, consider initializing the variable to a 327 poison value. 328 329 * - `Rule 9.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_02.c>`_ 330 - Required 331 - The initializer for an aggregate or union shall be enclosed in 332 braces 333 - 334 335 * - `Rule 9.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_03.c>`_ 336 - Required 337 - Arrays shall not be partially initialized 338 - {} is also allowed to specify explicit zero-initialization 339 340 * - `Rule 9.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_04.c>`_ 341 - Required 342 - An element of an object shall not be initialized more than once 343 - 344 345 * - `Rule 10.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_01.c>`_ 346 - Required 347 - Operands shall not be of an inappropriate essential type 348 - The following are allowed: 349 - Value-preserving conversions of integer constants 350 - Bitwise and, or, xor, one's complement, bitwise and assignment, 351 bitwise or assignment, bitwise xor assignment (bitwise and, or, xor 352 are safe on non-negative integers; also Xen assumes two's complement 353 representation) 354 - Left shift, right shift, left shift assignment, right shift 355 assignment (see C-language-toolchain.rst for uses of 356 compilers' extensions) 357 - Implicit conversions to boolean for conditionals (?: if while 358 for) and logical operators (! || &&) 359 - The essential type model allows the constants defined by anonymous 360 enums (e.g., enum { A, B, C }) to be used as operands to arithmetic 361 operators, as they have a signed essential type. 362 363 * - `Rule 10.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_02.c>`_ 364 - Required 365 - Expressions of essentially character type shall not be used 366 inappropriately in addition and subtraction operations 367 - 368 369 * - `Rule 10.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_03.c>`_ 370 - Required 371 - The value of an expression shall not be assigned to an object 372 with a narrower essential type or of a different essential type 373 category 374 - Please beware that this rule has many violations in the Xen 375 codebase today, and its adoption is aspirational. However, when 376 submitting new patches please try to decrease the number of 377 violations when possible. 378 379 gcc has a helpful warning that can help you spot and remove 380 violations of this kind: conversion. For instance, you can use 381 it as follows: 382 383 CFLAGS="-Wconversion -Wno-error=sign-conversion -Wno-error=conversion" make -C xen 384 385 * - `Rule 10.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_04.c>`_ 386 - Required 387 - Both operands of an operator in which the usual arithmetic 388 conversions are performed shall have the same essential type 389 category 390 - Please beware that this rule has many violations in the Xen 391 codebase today, and its adoption is aspirational. However, when 392 submitting new patches please try to decrease the number of 393 violations when possible. 394 395 gcc has a helpful warning that can help you spot and remove 396 violations of this kind: arith-conversion. For instance, you 397 can use it as follows: 398 399 CFLAGS="-Warith-conversion -Wno-error=arith-conversion" make -C xen 400 401 * - `Rule 11.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_01.c>`_ 402 - Required 403 - Conversions shall not be performed between a pointer to a 404 function and any other type 405 - All conversions to integer types are permitted if the destination 406 type has enough bits to hold the entire value. Conversions to 407 bool and void* are permitted. 408 409 * - `Rule 11.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_02.c>`_ 410 - Required 411 - Conversions shall not be performed between a pointer to an 412 incomplete type and any other type 413 - All conversions to integer types are permitted if the destination 414 type has enough bits to hold the entire value. Conversions to 415 bool and void* are permitted. 416 417 * - `Rule 11.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_03.c>`_ 418 - Required 419 - A cast shall not be performed between a pointer to object type 420 and a pointer to a different object type 421 - 422 423 * - `Rule 11.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_06.c>`_ 424 - Required 425 - A cast shall not be performed between pointer to void and an 426 arithmetic type 427 - All conversions to integer types are permitted if the destination 428 type has enough bits to hold the entire value. Conversions to 429 bool are permitted. 430 431 * - `Rule 11.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_07.c>`_ 432 - Required 433 - A cast shall not be performed between pointer to object and a noninteger arithmetic type 434 - 435 436 * - `Rule 11.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_08.c>`_ 437 - Required 438 - A cast shall not remove any const or volatile qualification from the type pointed to by a pointer 439 - 440 441 * - `Rule 11.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_09.c>`_ 442 - Required 443 - The macro NULL shall be the only permitted form of null pointer constant 444 - 445 446 * - `Rule 12.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_05.c>`_ 447 - Mandatory 448 - The sizeof operator shall not have an operand which is a function 449 parameter declared as "array of type" 450 - 451 452 * - `Rule 13.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_01_1.c>`_ 453 - Required 454 - Initializer lists shall not contain persistent side effects 455 - 456 457 * - `Rule 13.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_06.c>`_ 458 - Required 459 - The operand of the sizeof operator shall not contain any 460 expression which has potential side effects 461 - In addition to sizeof, we also want to apply the rule to typeof 462 and alignof 463 464 * - `Rule 14.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_01.c>`_ 465 - Required 466 - A loop counter shall not have essentially floating type 467 - 468 469 * - `Rule 14.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_03.c>`_ 470 - Required 471 - Controlling expressions shall not be invariant 472 - Due to the extensive usage of IS_ENABLED, sizeof compile-time 473 checks, and other constructs that are detected as errors by MISRA 474 C scanners, managing the configuration of a MISRA C scanner for 475 this rule would be unmanageable. Thus, this rule is adopted with 476 a project-wide deviation on if, ?:, switch(sizeof(...)), and 477 switch(offsetof(...)) statements. 478 479 while(0) and while(1) and alike are allowed. 480 481 * - `Rule 14.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_04.c>`_ 482 - Required 483 - The controlling expression of an if-statement and the controlling 484 expression of an iteration-statement shall have essentially 485 Boolean type 486 - Automatic conversions of integer types to bool are permitted. 487 Automatic conversions of pointer types to bool are permitted. 488 This rule still applies to enum types. 489 490 * - `Rule 16.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_03.c>`_ 491 - Required 492 - An unconditional break statement shall terminate every switch-clause_ 493 - In addition to break, also other unconditional flow control statements 494 such as continue, return, goto are allowed. 495 496 * - `Rule 16.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_04.c>`_ 497 - Required 498 - Every switch statement shall have a default label 499 - Switch statements with enums as controlling expression don't need 500 a default label as gcc -Wall enables -Wswitch which warns (and 501 breaks the build as we use -Werror) if one of the enum labels is 502 missing from the switch. 503 504 Switch statements with integer types as controlling expression 505 should have a default label: 506 507 - if the switch is expected to handle all possible cases 508 explicitly, then a default label shall be added to handle 509 unexpected error conditions, using BUG(), ASSERT(), WARN(), 510 domain_crash(), or other appropriate methods; 511 512 - if the switch is expected to handle a subset of all possible 513 cases, then an empty default label shall be added with an 514 in-code comment on top of the default label with a reason and 515 when possible a more detailed explanation. Example:: 516 517 default: 518 /* Notifier pattern */ 519 break; 520 521 * - `Rule 16.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_02.c>`_ 522 - Required 523 - A switch label shall only be used when the most closely-enclosing 524 compound statement is the body of a switch statement 525 - The x86 emulator (xen/arch/x86/x86_emulate*) is exempt from 526 compliance with this rule. Efforts to make the x86 emulator 527 adhere to Rule 16.2 would result in increased complexity and 528 maintenance difficulty, and could potentially introduce bugs. 529 530 * - `Rule 16.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_06.c>`_ 531 - Required 532 - Every switch statement shall have at least two switch-clauses 533 - Single-clause switches are allowed when they do not involve a 534 default label. 535 536 * - `Rule 16.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_07.c>`_ 537 - Required 538 - A switch-expression shall not have essentially Boolean type 539 - 540 541 * - `Rule 17.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_01.c>`_ 542 - Required 543 - The features of <stdarg.h> shall not be used 544 - 545 546 * - `Rule 17.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_03.c>`_ 547 - Mandatory 548 - A function shall not be declared implicitly 549 - 550 551 * - `Rule 17.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_04.c>`_ 552 - Mandatory 553 - All exit paths from a function with non-void return type shall 554 have an explicit return statement with an expression 555 - 556 557 * - `Rule 17.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_05.c>`_ 558 - Advisory 559 - The function argument corresponding to a parameter declared to 560 have an array type shall have an appropriate number of elements 561 - 562 563 * - `Rule 17.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_06.c>`_ 564 - Mandatory 565 - The declaration of an array parameter shall not contain the 566 static keyword between the [ ] 567 - 568 569 * - `Rule 17.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_07.c>`_ 570 - Required 571 - The value returned by a function having non-void return type 572 shall be used 573 - Please beware that this rule has many violations in the Xen 574 codebase today, and its adoption is aspirational. However, when 575 submitting new patches please try to decrease the number of 576 violations when possible. 577 578 * - `Rule 18.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_03.c>`_ 579 - Required 580 - The relational operators > >= < and <= shall not be applied to objects of pointer type except where they point into the same object 581 - 582 583 * - `Rule 19.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_19_01.c>`_ 584 - Mandatory 585 - An object shall not be assigned or copied to an overlapping 586 object 587 - Be aware that the static analysis tool Eclair might report 588 several findings for Rule 19.1 of type "caution". These are 589 instances where Eclair is unable to verify that the code is valid 590 in regard to Rule 19.1. Caution reports are not violations. 591 592 * - `Rule 20.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_04.c>`_ 593 - Required 594 - A macro shall not be defined with the same name as a keyword 595 - 596 597 * - `Rule 20.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_07.c>`_ 598 - Required 599 - Expressions resulting from the expansion of macro parameters 600 shall be enclosed in parentheses 601 - Extra parentheses are not required when macro parameters are used 602 as function arguments, as macro arguments, array indices, lhs in 603 assignments or as initializers in initalizer lists. 604 605 * - `Rule 20.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_09.c>`_ 606 - Required 607 - All identifiers used in the controlling expression of #if or 608 #elif preprocessing directives shall be #define'd before 609 evaluation 610 - 611 612 * - `Rule 20.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_12.c>`_ 613 - Required 614 - A macro parameter used as an operand to the # or ## operators, 615 which is itself subject to further macro replacement, shall only 616 be used as an operand to these operators 617 - Variadic macros are allowed to violate the rule. 618 619 * - `Rule 20.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_13.c>`_ 620 - Required 621 - A line whose first token is # shall be a valid preprocessing 622 directive 623 - 624 625 * - `Rule 20.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_14.c>`_ 626 - Required 627 - All #else #elif and #endif preprocessor directives shall reside 628 in the same file as the #if #ifdef or #ifndef directive to which 629 they are related 630 - 631 632 * - `Rule 21.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_01.c>`_ 633 - Required 634 - #define and #undef shall not be used on a reserved identifier or 635 reserved macro name 636 - Identifiers starting with an underscore followed by another underscore 637 or an upper-case letter are reserved. Today Xen uses many, such as 638 header guards and bitwise manipulation functions. Upon analysis it turns 639 out Xen identifiers do not clash with the identifiers used by modern 640 GCC, but that is not a guarantee that there won't be a naming clash in 641 the future or with another compiler. For these reasons we discourage 642 the introduction of new reserved identifiers in Xen, and we see it as 643 positive the reduction of reserved identifiers. At the same time, 644 certain identifiers starting with two underscores are also commonly used 645 in Linux (e.g. __set_bit) and we don't think it would be an improvement 646 to rename them. 647 648 * - `Rule 21.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_02.c>`_ 649 - Required 650 - A reserved identifier or reserved macro name shall not be 651 declared 652 - See comment for Rule 21.1 653 654 * - `Rule 21.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_06.c>`_ 655 - Required 656 - The Standard Library input/output routines shall not be used 657 - Xen doesn't provide, use, or link against a Standard Library [#xen-stdlib]_ 658 659 * - `Rule 21.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_09.c>`_ 660 - Required 661 - The library functions bsearch and qsort of <stdlib.h> shall not be used 662 - Xen doesn't provide, use, or link against a Standard Library [#xen-stdlib]_ 663 664 * - `Rule 21.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_10.c>`_ 665 - Required 666 - The Standard Library time and date routines shall not be used 667 - Xen doesn't provide, use, or link against a Standard Library [#xen-stdlib]_ 668 669 * - `Rule 21.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_13.c>`_ 670 - Mandatory 671 - Any value passed to a function in <ctype.h> shall be representable as an 672 unsigned char or be the value EOF 673 - 674 675 * - `Rule 21.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_14.c>`_ 676 - Required 677 - The Standard Library function memcmp shall not be used to compare 678 null terminated strings 679 - 680 681 * - `Rule 21.15 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_15.c>`_ 682 - Required 683 - The pointer arguments to the Standard Library functions memcpy, 684 memmove and memcmp shall be pointers to qualified or unqualified 685 versions of compatible types 686 - 687 688 * - `Rule 21.16 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_16.c>`_ 689 - Required 690 - The pointer arguments to the Standard Library function memcmp 691 shall point to either a pointer type, an essentially signed type, 692 an essentially unsigned type, an essentially Boolean type or an 693 essentially enum type 694 - void* arguments are allowed 695 696 * - `Rule 21.17 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_17.c>`_ 697 - Mandatory 698 - Use of the string handling functions from <string.h> shall not result in 699 accesses beyond the bounds of the objects referenced by their pointer 700 parameters 701 - 702 703 * - `Rule 21.18 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_18.c>`_ 704 - Mandatory 705 - The size_t argument passed to any function in <string.h> shall have an 706 appropriate value 707 - 708 709 * - `Rule 21.19 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_19.c>`_ 710 - Mandatory 711 - The pointers returned by the Standard Library functions localeconv, 712 getenv, setlocale or, strerror shall only be used as if they have 713 pointer to const-qualified type 714 - 715 716 * - `Rule 21.20 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_20.c>`_ 717 - Mandatory 718 - The pointer returned by the Standard Library functions asctime ctime 719 gmtime localtime localeconv getenv setlocale or strerror shall not be 720 used following a subsequent call to the same function 721 - 722 723 * - `Rule 21.21 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/>`_ 724 - Required 725 - The Standard Library function system of <stdlib.h> shall not be used 726 - 727 728 * - `Rule 22.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_02.c>`_ 729 - Mandatory 730 - A block of memory shall only be freed if it was allocated by means of a 731 Standard Library function 732 - 733 734 * - `Rule 22.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_04.c>`_ 735 - Mandatory 736 - There shall be no attempt to write to a stream which has been opened as 737 read-only 738 - 739 740 * - `Rule 22.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_05.c>`_ 741 - Mandatory 742 - A pointer to a FILE object shall not be dereferenced 743 - 744 745 * - `Rule 22.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_06.c>`_ 746 - Mandatory 747 - The value of a pointer to a FILE shall not be used after the associated 748 stream has been closed 749 - 750 751Terms & Definitions 752------------------- 753 754.. _switch-clause: 755 756A *switch clause* can be defined as: 757"the non-empty list of statements which follows a non-empty list of 758case/default labels". 759A formal definition is available within the amplification of MISRA C:2012 760Rule 16.1. 761 762.. rubric:: Footnotes 763 764.. [#xen-stdlib] Xen implements itself a few functions with names that match 765 the corresponding function names of the Standard Library for developers' 766 convenience. These functions are part of the Xen code and subject to 767 analysis. 768