1.. _coding_guidelines: 2 3Coding Guidelines 4################# 5 6The project TSC and the Safety Committee of the project agreed to implement 7a staged and incremental approach for complying with a set of coding rules (AKA 8Coding Guidelines) to improve quality and consistency of the code base. Below 9are the agreed upon stages and the approximate timelines: 10 11Stage I 12 Coding guideline rules are available to be followed and referenced, 13 but not enforced. Rules are not yet enforced in CI and pull-requests cannot be 14 blocked by reviewers/approvers due to violations. 15 16Stage II 17 Begin enforcement on a limited scope of the code base. Initially, this would be 18 the safety certification scope. For rules easily applied across codebase, we 19 should not limit compliance to initial scope. This step requires tooling, 20 CI setup and an enforcement strategy. 21 22Stage III 23 Revisit the coding guideline rules and based on experience from previous 24 stages, refine/iterate on selected rules. 25 26Stage IV 27 Expand enforcement to the wider codebase. Exceptions may be granted on some 28 areas of the codebase with a proper justification. Exception would require 29 TSC approval. 30 31.. note:: 32 33 Coding guideline rules may be removed/changed at any time by filing a 34 GH issue/RFC. 35 36Main rules 37********** 38 39The coding guideline rules are based on MISRA-C 2012 and are a subset of MISRA-C. 40The subset is listed in the table below with a summary of the rules, its 41severity and the equivalent rules from other standards for reference. 42 43.. note:: 44 45 For existing Zephyr maintainers and collaborators, if you are unable to 46 obtain a copy through your employer, a limited number of copies will be made 47 available through the project. If you need a copy of MISRA-C 2012, please 48 send email to safety@lists.zephyrproject.org and provide details on reason 49 why you can't obtain one through other options and expected contributions 50 once you have one. The safety committee will review all requests. 51 52 53.. list-table:: Main rules 54 :header-rows: 1 55 :widths: 17 14 43 12 14 56 57 * - MISRA C 2012 58 - Severity 59 - Description 60 - CERT C 61 - Example 62 63 .. _MisraC_Dir_1_1: 64 * - Dir 1.1 65 - Required 66 - Any implementation-defined behaviour on which the output of the program depends shall be documented and understood 67 - `MSC09-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC09-C.+Character+encoding%3A+Use+subset+of+ASCII+for+safety>`_ 68 - `Dir 1.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_01_01.c>`_ 69 70 .. _MisraC_Dir_2_1: 71 * - Dir 2.1 72 - Required 73 - All source files shall compile without any compilation errors 74 - N/A 75 - `Dir 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_ 76 77 .. _MisraC_Dir_3_1: 78 * - Dir 3.1 79 - Required 80 - All code shall be traceable to documented requirements 81 - N/A 82 - `Dir 3.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_03_01.c>`_ 83 84 .. _MisraC_Dir_4_1: 85 * - Dir 4.1 86 - Required 87 - Run-time failures shall be minimized 88 - N/A 89 - `Dir 4.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_01.c>`_ 90 91 .. _MisraC_Dir_4_2: 92 * - Dir 4.2 93 - Advisory 94 - All usage of assembly language should be documented 95 - N/A 96 - `Dir 4.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_02.c>`_ 97 98 .. _MisraC_Dir_4_4: 99 * - Dir 4.4 100 - Advisory 101 - Sections of code should not be “commented out” 102 - `MSC04-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC04-C.+Use+comments+consistently+and+in+a+readable+fashion>`_ 103 - `Dir 4.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_04.c>`_ 104 105 .. _MisraC_Dir_4_5: 106 * - Dir 4.5 107 - Advisory 108 - Identifiers in the same name space with overlapping visibility should be typographically unambiguous 109 - `DCL02-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL02-C.+Use+visually+distinct+identifiers>`_ 110 - `Dir 4.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_05.c>`_ 111 112 .. _MisraC_Dir_4_6: 113 * - Dir 4.6 114 - Advisory 115 - typedefs that indicate size and signedness should be used in place of the basic numerical types 116 - N/A 117 - `Dir 4.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_06.c>`_ 118 119 .. _MisraC_Dir_4_7: 120 * - Dir 4.7 121 - Required 122 - If a function returns error information, then that error information shall be tested 123 - N/A 124 - `Dir 4.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_07.c>`_ 125 126 .. _MisraC_Dir_4_8: 127 * - Dir 4.8 128 - Advisory 129 - If a pointer to a structure or union is never dereferenced within a translation unit, then the implementation of the object should be hidden 130 - `DCL12-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL12-C.+Implement+abstract+data+types+using+opaque+types>`_ 131 - | `Dir 4.8 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_08_1.c>`_ 132 | `Dir 4.8 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_08_2.c>`_ 133 134 .. _MisraC_Dir_4_9: 135 * - Dir 4.9 136 - Advisory 137 - A function should be used in preference to a function-like macro where they are interchangeable 138 - `PRE00-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE00-C.+Prefer+inline+or+static+functions+to+function-like+macros>`_ 139 - `Dir 4.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_09.c>`_ 140 141 .. _MisraC_Dir_4_10: 142 * - Dir 4.10 143 - Required 144 - Precautions shall be taken in order to prevent the contents of a header file being included more than once 145 - `PRE06-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE06-C.+Enclose+header+files+in+an+include+guard>`_ 146 - `Dir 4.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_10.c>`_ 147 148 .. _MisraC_Dir_4_11: 149 * - Dir 4.11 150 - Required 151 - The validity of values passed to library functions shall be checked 152 - N/A 153 - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_ 154 155 .. _MisraC_Dir_4_12: 156 * - Dir 4.12 157 - Required 158 - Dynamic memory allocation shall not be used 159 - `STR01-C <https://wiki.sei.cmu.edu/confluence/display/c/STR01-C.+Adopt+and+implement+a+consistent+plan+for+managing+strings>`_ 160 - `Dir 4.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_12.c>`_ 161 162 .. _MisraC_Dir_4_13: 163 * - Dir 4.13 164 - Advisory 165 - Functions which are designed to provide operations on a resource should be called in an appropriate sequence 166 - N/A 167 - `Dir 4.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_13.c>`_ 168 169 .. _MisraC_Dir_4_14: 170 * - Dir 4.14 171 - Required 172 - The validity of values received from external sources shall be checked 173 174 - N/A 175 - `Dir 4.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_14.c>`_ 176 177 .. _MisraC_Rule_1_2: 178 * - Rule 1.2 179 - Advisory 180 - Language extensions should not be used 181 - `MSC04-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC04-C.+Use+comments+consistently+and+in+a+readable+fashion>`_ 182 - `Rule 1.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_01_02.c>`_ 183 184 .. _MisraC_Rule_1_3: 185 * - Rule 1.3 186 - Required 187 - There shall be no occurrence of undefined or critical unspecified behaviour 188 - N/A 189 - `Rule 1.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_01_03.c>`_ 190 191 .. _MisraC_Rule_2_1: 192 * - Rule 2.1 193 - Required 194 - A project shall not contain unreachable code 195 - `MSC07-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC07-C.+Detect+and+remove+dead+code>`_ 196 - | `Rule 2.1 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_01_1.c>`_ 197 | `Rule 2.1 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_01_2.c>`_ 198 199 .. _MisraC_Rule_2_2: 200 * - Rule 2.2 201 - Required 202 - There shall be no dead code 203 - `MSC12-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC12-C.+Detect+and+remove+code+that+has+no+effect+or+is+never+executed>`_ 204 - `Rule 2.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_02.c>`_ 205 206 .. _MisraC_Rule_2_3: 207 * - Rule 2.3 208 - Advisory 209 - A project should not contain unused type declarations 210 - N/A 211 - `Rule 2.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_03.c>`_ 212 213 .. _MisraC_Rule_2_6: 214 * - Rule 2.6 215 - Advisory 216 - A function should not contain unused label declarations 217 - N/A 218 - `Rule 2.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_06.c>`_ 219 220 .. _MisraC_Rule_2_7: 221 * - Rule 2.7 222 - Advisory 223 - There should be no unused parameters in functions 224 - N/A 225 - `Rule 2.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_07.c>`_ 226 227 .. _MisraC_Rule_3_1: 228 * - Rule 3.1 229 - Required 230 - The character sequences /* and // shall not be used within a comment 231 - `MSC04-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC04-C.+Use+comments+consistently+and+in+a+readable+fashion>`_ 232 - `Rule 3.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_01.c>`_ 233 234 .. _MisraC_Rule_3_2: 235 * - Rule 3.2 236 - Required 237 - Line-splicing shall not be used in // comments 238 - N/A 239 - `Rule 3.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_02.c>`_ 240 241 .. _MisraC_Rule_4_1: 242 * - Rule 4.1 243 - Required 244 - Octal and hexadecimal escape sequences shall be terminated 245 - `MSC09-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC09-C.+Character+encoding%3A+Use+subset+of+ASCII+for+safety>`_ 246 - `Rule 4.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_04_01.c>`_ 247 248 .. _MisraC_Rule_4_2: 249 * - Rule 4.2 250 - Advisory 251 - Trigraphs should not be used 252 - `PRE07-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE07-C.+Avoid+using+repeated+question+marks>`_ 253 - `Rule 4.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_04_02.c>`_ 254 255 .. _MisraC_Rule_5_1: 256 * - Rule 5.1 257 - Required 258 - External identifiers shall be distinct 259 - `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_ 260 - | `Rule 5.1 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_01_1.c>`_ 261 | `Rule 5.1 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_01_2.c>`_ 262 263 .. _MisraC_Rule_5_2: 264 * - Rule 5.2 265 - Required 266 - Identifiers declared in the same scope and name space shall be distinct 267 - `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_ 268 - `Rule 5.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_02.c>`_ 269 270 .. _MisraC_Rule_5_3: 271 * - Rule 5.3 272 - Required 273 - An identifier declared in an inner scope shall not hide an identifier declared in an outer scope 274 - `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_ 275 - `Rule 5.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_03.c>`_ 276 277 .. _MisraC_Rule_5_4: 278 * - Rule 5.4 279 - Required 280 - Macro identifiers shall be distinct 281 - `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_ 282 - `Rule 5.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_04.c>`_ 283 284 .. _MisraC_Rule_5_5: 285 * - Rule 5.5 286 - Required 287 - Identifiers shall be distinct from macro names 288 - `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_ 289 - `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_ 290 291 .. _MisraC_Rule_5_6: 292 * - Rule 5.6 293 - Required 294 - A typedef name shall be a unique identifier 295 - N/A 296 - `Rule 5.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_06.c>`_ 297 298 .. _MisraC_Rule_5_7: 299 * - Rule 5.7 300 - Required 301 - A tag name shall be a unique identifier 302 - N/A 303 - `Rule 5.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_07.c>`_ 304 305 .. _MisraC_Rule_5_8: 306 * - Rule 5.8 307 - Required 308 - Identifiers that define objects or functions with external linkage shall be unique 309 - N/A 310 - | `Rule 5.8 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_08_1.c>`_ 311 | `Rule 5.8 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_08_2.c>`_ 312 313 .. _MisraC_Rule_5_9: 314 * - Rule 5.9 315 - Advisory 316 - Identifiers that define objects or functions with internal linkage should be unique 317 - N/A 318 - | `Rule 5.9 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_09_1.c>`_ 319 | `Rule 5.9 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_09_2.c>`_ 320 321 .. _MisraC_Rule_6_1: 322 * - Rule 6.1 323 - Required 324 - Bit-fields shall only be declared with an appropriate type 325 - `INT14-C <https://wiki.sei.cmu.edu/confluence/display/c/INT14-C.+Avoid+performing+bitwise+and+arithmetic+operations+on+the+same+data>`_ 326 - `Rule 6.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_01.c>`_ 327 328 .. _MisraC_Rule_6_2: 329 * - Rule 6.2 330 - Required 331 - Single-bit named bit fields shall not be of a signed type 332 - `INT14-C <https://wiki.sei.cmu.edu/confluence/display/c/INT14-C.+Avoid+performing+bitwise+and+arithmetic+operations+on+the+same+data>`_ 333 - `Rule 6.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_02.c>`_ 334 335 .. _MisraC_Rule_7_1: 336 * - Rule 7.1 337 - Required 338 - Octal constants shall not be used 339 - `DCL18-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL18-C.+Do+not+begin+integer+constants+with+0+when+specifying+a+decimal+value>`_ 340 - `Rule 7.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_01.c>`_ 341 342 .. _MisraC_Rule_7_2: 343 * - Rule 7.2 344 - Required 345 - A u or U suffix shall be applied to all integer constants that are represented in an unsigned type 346 - N/A 347 - `Rule 7.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_02.c>`_ 348 349 .. _MisraC_Rule_7_3: 350 * - Rule 7.3 351 - Required 352 - The lowercase character l shall not be used in a literal suffix 353 - `DCL16-C <https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152241>`_ 354 - `Rule 7.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_03.c>`_ 355 356 .. _MisraC_Rule_7_4: 357 * - Rule 7.4 358 - Required 359 - A string literal shall not be assigned to an object unless the objects type is pointer to const-qualified char 360 - N/A 361 - `Rule 7.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_04.c>`_ 362 363 .. _MisraC_Rule_8_1: 364 * - Rule 8.1 365 - Required 366 - Types shall be explicitly specified 367 - N/A 368 - `Rule 8.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_01.c>`_ 369 370 .. _MisraC_Rule_8_2: 371 * - Rule 8.2 372 - Required 373 - Function types shall be in prototype form with named parameters 374 - `DCL20-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL20-C.+Explicitly+specify+void+when+a+function+accepts+no+arguments>`_ 375 - `Rule 8.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_02.c>`_ 376 377 .. _MisraC_Rule_8_3: 378 * - Rule 8.3 379 - Required 380 - All declarations of an object or function shall use the same names and type qualifiers 381 - N/A 382 - `Rule 8.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_03.c>`_ 383 384 .. _MisraC_Rule_8_4: 385 * - Rule 8.4 386 - Required 387 - A compatible declaration shall be visible when an object or function with external linkage is defined 388 - N/A 389 - `Rule 8.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_04.c>`_ 390 391 .. _MisraC_Rule_8_5: 392 * - Rule 8.5 393 - Required 394 - An external object or function shall be declared once in one and only one file 395 - N/A 396 - | `Rule 8.5 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_05_1.c>`_ 397 | `Rule 8.5 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_05_2.c>`_ 398 399 .. _MisraC_Rule_8_6: 400 * - Rule 8.6 401 - Required 402 - An identifier with external linkage shall have exactly one external definition 403 - N/A 404 - | `Rule 8.6 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_06_1.c>`_ 405 | `Rule 8.6 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_06_2.c>`_ 406 407 .. _MisraC_Rule_8_8: 408 * - Rule 8.8 409 - Required 410 - The static storage class specifier shall be used in all declarations of objects and functions that have internal linkage 411 - `DCL15-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL15-C.+Declare+file-scope+objects+or+functions+that+do+not+need+external+linkage+as+static>`_ 412 - `Rule 8.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_08.c>`_ 413 414 .. _MisraC_Rule_8_9: 415 * - Rule 8.9 416 - Advisory 417 - An object should be defined at block scope if its identifier only appears in a single function 418 - `DCL19-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL19-C.+Minimize+the+scope+of+variables+and+functions>`_ 419 - `Rule 8.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_09.c>`_ 420 421 .. _MisraC_Rule_8_10: 422 * - Rule 8.10 423 - Required 424 - An inline function shall be declared with the static storage class 425 - N/A 426 - `Rule 8.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_10.c>`_ 427 428 .. _MisraC_Rule_8_12: 429 * - Rule 8.12 430 - Required 431 - Within an enumerator list, the value of an implicitly-specified enumeration constant shall be unique 432 - `INT09-C <https://wiki.sei.cmu.edu/confluence/display/c/INT09-C.+Ensure+enumeration+constants+map+to+unique+values>`_ 433 - `Rule 8.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_12.c>`_ 434 435 .. _MisraC_Rule_8_14: 436 * - Rule 8.14 437 - Required 438 - The restrict type qualifier shall not be used 439 - N/A 440 - `Rule 8.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_14.c>`_ 441 442 .. _MisraC_Rule_9_1: 443 * - Rule 9.1 444 - Mandatory 445 - The value of an object with automatic storage duration shall not be read before it has been set 446 - N/A 447 - `Rule 9.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_01.c>`_ 448 449 .. _MisraC_Rule_9_2: 450 * - Rule 9.2 451 - Required 452 - The initializer for an aggregate or union shall be enclosed in braces 453 - N/A 454 - `Rule 9.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_02.c>`_ 455 456 .. _MisraC_Rule_9_3: 457 * - Rule 9.3 458 - Required 459 - Arrays shall not be partially initialized 460 - N/A 461 - `Rule 9.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_03.c>`_ 462 463 .. _MisraC_Rule_9_4: 464 * - Rule 9.4 465 - Required 466 - An element of an object shall not be initialized more than once 467 - N/A 468 - `Rule 9.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_04.c>`_ 469 470 .. _MisraC_Rule_9_5: 471 * - Rule 9.5 472 - Required 473 - Where designated initializers are used to initialize an array object the size of the array shall be specified explicitly 474 - N/A 475 - `Rule 9.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_05.c>`_ 476 477 .. _MisraC_Rule_10_1: 478 * - Rule 10.1 479 - Required 480 - Operands shall not be of an inappropriate essential type 481 - `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_ 482 - `Rule 10.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_01.c>`_ 483 484 .. _MisraC_Rule_10_2: 485 * - Rule 10.2 486 - Required 487 - Expressions of essentially character type shall not be used inappropriately in addition and subtraction operations 488 - `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_ 489 - `Rule 10.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_02.c>`_ 490 491 .. _MisraC_Rule_10_3: 492 * - Rule 10.3 493 - Required 494 - The value of an expression shall not be assigned to an object with a narrower essential type or of a different essential type category 495 - `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_ 496 - `Rule 10.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_03.c>`_ 497 498 .. _MisraC_Rule_10_4: 499 * - Rule 10.4 500 - Required 501 - Both operands of an operator in which the usual arithmetic conversions are performed shall have the same essential type category 502 - `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_ 503 - `Rule 10.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_04.c>`_ 504 505 .. _MisraC_Rule_10_5: 506 * - Rule 10.5 507 - Advisory 508 - The value of an expression should not be cast to an inappropriate essential type 509 - N/A 510 - `Rule 10.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_05.c>`_ 511 512 .. _MisraC_Rule_10_6: 513 * - Rule 10.6 514 - Required 515 - The value of a composite expression shall not be assigned to an object with wider essential type 516 - `INT02-C <https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules>`_ 517 - `Rule 10.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_06.c>`_ 518 519 .. _MisraC_Rule_10_7: 520 * - Rule 10.7 521 - Required 522 - If a composite expression is used as one operand of an operator in which the usual arithmetic conversions are performed then the other operand shall not have wider essential type 523 - `INT02-C <https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules>`_ 524 - `Rule 10.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_07.c>`_ 525 526 .. _MisraC_Rule_10_8: 527 * - Rule 10.8 528 - Required 529 - The value of a composite expression shall not be cast to a different essential type category or a wider essential type 530 - `INT02-C <https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules>`_ 531 - `Rule 10.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_08.c>`_ 532 533 .. _MisraC_Rule_11_2: 534 * - Rule 11.2 535 - Required 536 - Conversions shall not be performed between a pointer to an incomplete type and any other type 537 - N/A 538 - `Rule 11.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_02.c>`_ 539 540 .. _MisraC_Rule_11_6: 541 * - Rule 11.6 542 - Required 543 - A cast shall not be performed between pointer to void and an arithmetic type 544 - N/A 545 - `Rule 11.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_06.c>`_ 546 547 .. _MisraC_Rule_11_7: 548 * - Rule 11.7 549 - Required 550 - A cast shall not be performed between pointer to object and a noninteger arithmetic type 551 - N/A 552 - `Rule 11.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_07.c>`_ 553 554 .. _MisraC_Rule_11_8: 555 * - Rule 11.8 556 - Required 557 - A cast shall not remove any const or volatile qualification from the type pointed to by a pointer 558 - `EXP05-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP05-C.+Do+not+cast+away+a+const+qualification>`_ 559 - `Rule 11.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_08.c>`_ 560 561 .. _MisraC_Rule_11_9: 562 * - Rule 11.9 563 - Required 564 - The macro NULL shall be the only permitted form of integer null pointer constant 565 - N/A 566 - `Rule 11.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_09.c>`_ 567 568 .. _MisraC_Rule_12_1: 569 * - Rule 12.1 570 - Advisory 571 - The precedence of operators within expressions should be made explicit 572 - `EXP00-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP00-C.+Use+parentheses+for+precedence+of+operation>`_ 573 - `Rule 12.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_01.c>`_ 574 575 .. _MisraC_Rule_12_2: 576 * - Rule 12.2 577 - Required 578 - The right hand operand of a shift operator shall lie in the range zero to one less than the width in bits of the essential type of the left hand operand 579 - N/A 580 - `Rule 12.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_02.c>`_ 581 582 .. _MisraC_Rule_12_4: 583 * - Rule 12.4 584 - Advisory 585 - Evaluation of constant expressions should not lead to unsigned integer wrap-around 586 - N/A 587 - `Rule 12.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_04.c>`_ 588 589 .. _MisraC_Rule_12_5: 590 * - Rule 12.5 591 - Mandatory 592 - The sizeof operator shall not have an operand which is a function parameter declared as “array of type” 593 - N/A 594 - `Rule 12.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_05.c>`_ 595 596 .. _MisraC_Rule_13_1: 597 * - Rule 13.1 598 - Required 599 - Initializer lists shall not contain persistent side effects 600 - N/A 601 - | `Rule 13.1 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_01_1.c>`_ 602 | `Rule 13.1 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_01_2.c>`_ 603 604 .. _MisraC_Rule_13_2: 605 * - Rule 13.2 606 - Required 607 - The value of an expression and its persistent side effects shall be the same under all permitted evaluation orders 608 - N/A 609 - `Rule 13.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_02.c>`_ 610 611 .. _MisraC_Rule_13_3: 612 * - Rule 13.3 613 - Advisory 614 - A full expression containing an increment (++) or decrement (--) operator should have no other potential side effects other than that caused by the increment or decrement operator 615 - N/A 616 - `Rule 13.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_03.c>`_ 617 618 .. _MisraC_Rule_13_4: 619 * - Rule 13.4 620 - Advisory 621 - The result of an assignment operator should not be used 622 - N/A 623 - `Rule 13.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_04.c>`_ 624 625 .. _MisraC_Rule_13_5: 626 * - Rule 13.5 627 - Required 628 - The right hand operand of a logical && or || operator shall not contain persistent side effects 629 - `EXP10-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP10-C.+Do+not+depend+on+the+order+of+evaluation+of+subexpressions+or+the+order+in+which+side+effects+take+place>`_ 630 - | `Rule 13.5 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_05_1.c>`_ 631 | `Rule 13.5 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_05_2.c>`_ 632 633 .. _MisraC_Rule_13_6: 634 * - Rule 13.6 635 - Mandatory 636 - The operand of the sizeof operator shall not contain any expression which has potential side effects 637 - N/A 638 - `Rule 13.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_06.c>`_ 639 640 .. _MisraC_Rule_14_1: 641 * - Rule 14.1 642 - Required 643 - A loop counter shall not have essentially floating type 644 - N/A 645 - `Rule 14.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_01.c>`_ 646 647 .. _MisraC_Rule_14_2: 648 * - Rule 14.2 649 - Required 650 - A for loop shall be well-formed 651 - N/A 652 - `Rule 14.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_02.c>`_ 653 654 .. _MisraC_Rule_14_3: 655 * - Rule 14.3 656 - Required 657 - Controlling expressions shall not be invariant 658 - N/A 659 - `Rule 14.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_03.c>`_ 660 661 .. _MisraC_Rule_14_4: 662 * - Rule 14.4 663 - Required 664 - The controlling expression of an if statement and the controlling expression of an iteration-statement shall have essentially Boolean type 665 - N/A 666 - `Rule 14.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_04.c>`_ 667 668 .. _MisraC_Rule_15_2: 669 * - Rule 15.2 670 - Required 671 - The goto statement shall jump to a label declared later in the same function 672 - N/A 673 - `Rule 15.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_02.c>`_ 674 675 .. _MisraC_Rule_15_3: 676 * - Rule 15.3 677 - Required 678 - Any label referenced by a goto statement shall be declared in the same block, or in any block enclosing the goto statement 679 - N/A 680 - `Rule 15.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_03.c>`_ 681 682 .. _MisraC_Rule_15_6: 683 * - Rule 15.6 684 - Required 685 - The body of an iteration-statement or a selection-statement shall be a compound-statement 686 - `EXP19-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP19-C.+Use+braces+for+the+body+of+an+if%2C+for%2C+or+while+statement>`_ 687 - `Rule 15.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_06.c>`_ 688 689 .. _MisraC_Rule_15_7: 690 * - Rule 15.7 691 - Required 692 - All if else if constructs shall be terminated with an else statement 693 - N/A 694 - `Rule 15.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_07.c>`_ 695 696 .. _MisraC_Rule_16_1: 697 * - Rule 16.1 698 - Required 699 - All switch statements shall be well-formed 700 - N/A 701 - `Rule 16.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_01.c>`_ 702 703 .. _MisraC_Rule_16_2: 704 * - Rule 16.2 705 - Required 706 - A switch label shall only be used when the most closely-enclosing compound statement is the body of a switch statement 707 - `MSC20-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC20-C.+Do+not+use+a+switch+statement+to+transfer+control+into+a+complex+block>`_ 708 - `Rule 16.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_02.c>`_ 709 710 .. _MisraC_Rule_16_3: 711 * - Rule 16.3 712 - Required 713 - An unconditional break statement shall terminate every switch-clause 714 - N/A 715 - `Rule 16.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_03.c>`_ 716 717 .. _MisraC_Rule_16_4: 718 * - Rule 16.4 719 - Required 720 - Every switch statement shall have a default label 721 - N/A 722 - `Rule 16.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_04.c>`_ 723 724 .. _MisraC_Rule_16_5: 725 * - Rule 16.5 726 - Required 727 - A default label shall appear as either the first or the last switch label of a switch statement 728 - N/A 729 - `Rule 16.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_05.c>`_ 730 731 .. _MisraC_Rule_16_6: 732 * - Rule 16.6 733 - Required 734 - Every switch statement shall have at least two switch-clauses 735 - N/A 736 - `Rule 16.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_06.c>`_ 737 738 .. _MisraC_Rule_16_7: 739 * - Rule 16.7 740 - Required 741 - A switch-expression shall not have essentially Boolean type 742 - N/A 743 - `Rule 16.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_07.c>`_ 744 745 .. _MisraC_Rule_17_1: 746 * - Rule 17.1 747 - Required 748 - The features of <stdarg.h> shall not be used 749 - `ERR00-C <https://wiki.sei.cmu.edu/confluence/display/c/ERR00-C.+Adopt+and+implement+a+consistent+and+comprehensive+error-handling+policy>`_ 750 - `Rule 17.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_01.c>`_ 751 752 .. _MisraC_Rule_17_2: 753 * - Rule 17.2 754 - Required 755 - Functions shall not call themselves, either directly or indirectly 756 - `MEM05-C <https://wiki.sei.cmu.edu/confluence/display/c/MEM05-C.+Avoid+large+stack+allocations>`_ 757 - `Rule 17.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_02.c>`_ 758 759 .. _MisraC_Rule_17_3: 760 * - Rule 17.3 761 - Mandatory 762 - A function shall not be declared implicitly 763 - N/A 764 - `Rule 17.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_03.c>`_ 765 766 .. _MisraC_Rule_17_4: 767 * - Rule 17.4 768 - Mandatory 769 - All exit paths from a function with non-void return type shall have an explicit return statement with an expression 770 - N/A 771 - `Rule 17.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_04.c>`_ 772 773 .. _MisraC_Rule_17_5: 774 * - Rule 17.5 775 - Advisory 776 - The function argument corresponding to a parameter declared to have an array type shall have an appropriate number of elements 777 - N/A 778 - `Rule 17.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_05.c>`_ 779 780 .. _MisraC_Rule_17_6: 781 * - Rule 17.6 782 - Mandatory 783 - The declaration of an array parameter shall not contain the static keyword between the [ ] 784 - N/A 785 - `Rule 17.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_06.c>`_ 786 787 .. _MisraC_Rule_17_7: 788 * - Rule 17.7 789 - Required 790 - The value returned by a function having non-void return type shall be used 791 - N/A 792 - `Rule 17.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_07.c>`_ 793 794 .. _MisraC_Rule_18_1: 795 * - Rule 18.1 796 - Required 797 - A pointer resulting from arithmetic on a pointer operand shall address an element of the same array as that pointer operand 798 - `EXP08-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP08-C.+Ensure+pointer+arithmetic+is+used+correctly>`_ 799 - `Rule 18.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_01.c>`_ 800 801 .. _MisraC_Rule_18_2: 802 * - Rule 18.2 803 - Required 804 - Subtraction between pointers shall only be applied to pointers that address elements of the same array 805 - `EXP08-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP08-C.+Ensure+pointer+arithmetic+is+used+correctly>`_ 806 - `Rule 18.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_02.c>`_ 807 808 .. _MisraC_Rule_18_3: 809 * - Rule 18.3 810 - Required 811 - The relational operators >, >=, < and <= shall not be applied to objects of pointer type except where they point into the same object 812 - `EXP08-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP08-C.+Ensure+pointer+arithmetic+is+used+correctly>`_ 813 - `Rule 18.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_03.c>`_ 814 815 .. _MisraC_Rule_18_5: 816 * - Rule 18.5 817 - Advisory 818 - Declarations should contain no more than two levels of pointer nesting 819 - N/A 820 - `Rule 18.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_05.c>`_ 821 822 .. _MisraC_Rule_18_6: 823 * - Rule 18.6 824 - Required 825 - The address of an object with automatic storage shall not be copied to another object that persists after the first object has ceased to exist 826 - N/A 827 - | `Rule 18.6 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_06_1.c>`_ 828 | `Rule 18.6 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_06_2.c>`_ 829 830 .. _MisraC_Rule_18_8: 831 * - Rule 18.8 832 - Required 833 - Variable-length array types shall not be used 834 - N/A 835 - `Rule 18.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_08.c>`_ 836 837 .. _MisraC_Rule_19_1: 838 * - Rule 19.1 839 - Mandatory 840 - An object shall not be assigned or copied to an overlapping object 841 - N/A 842 - `Rule 19.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_19_01.c>`_ 843 844 .. _MisraC_Rule_20_2: 845 * - Rule 20.2 846 - Required 847 - The ', or \ characters and the /* or // character sequences shall not occur in a header file name" 848 - N/A 849 - `Rule 20.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_02.c>`_ 850 851 .. _MisraC_Rule_20_3: 852 * - Rule 20.3 853 - Required 854 - The #include directive shall be followed by either a <filename> or "filename" sequence 855 - N/A 856 - `Rule 20.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_03.c>`_ 857 858 .. _MisraC_Rule_20_4: 859 * - Rule 20.4 860 - Required 861 - A macro shall not be defined with the same name as a keyword 862 - N/A 863 - `Rule 20.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_04.c>`_ 864 865 .. _MisraC_Rule_20_7: 866 * - Rule 20.7 867 - Required 868 - Expressions resulting from the expansion of macro parameters shall be enclosed in parentheses 869 - `PRE01-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE01-C.+Use+parentheses+within+macros+around+parameter+names>`_ 870 - `Rule 20.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_07.c>`_ 871 872 .. _MisraC_Rule_20_8: 873 * - Rule 20.8 874 - Required 875 - The controlling expression of a #if or #elif preprocessing directive shall evaluate to 0 or 1 876 - N/A 877 - `Rule 20.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_08.c>`_ 878 879 .. _MisraC_Rule_20_9: 880 * - Rule 20.9 881 - Required 882 - All identifiers used in the controlling expression of #if or #elif preprocessing directives shall be #defined before evaluation 883 - N/A 884 - `Rule 20.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_09.c>`_ 885 886 .. _MisraC_Rule_20_11: 887 * - Rule 20.11 888 - Required 889 - A macro parameter immediately following a # operator shall not immediately be followed by a ## operator 890 - N/A 891 - `Rule 20.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_11.c>`_ 892 893 .. _MisraC_Rule_20_12: 894 * - Rule 20.12 895 - Required 896 - A macro parameter used as an operand to the # or ## operators, which is itself subject to further macro replacement, shall only be used as an operand to these operators 897 - N/A 898 - `Rule 20.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_12.c>`_ 899 900 .. _MisraC_Rule_20_13: 901 * - Rule 20.13 902 - Required 903 - A line whose first token is # shall be a valid preprocessing directive 904 - N/A 905 - `Rule 20.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_13.c>`_ 906 907 .. _MisraC_Rule_20_14: 908 * - Rule 20.14 909 - Required 910 - All #else, #elif and #endif preprocessor directives shall reside in the same file as the #if, #ifdef or #ifndef directive to which they are related 911 - N/A 912 - `Rule 20.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_14.c>`_ 913 914 .. _MisraC_Rule_21_1: 915 * - Rule 21.1 916 - Required 917 - #define and #undef shall not be used on a reserved identifier or reserved macro name 918 - N/A 919 - `Rule 21.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_01.c>`_ 920 921 .. _MisraC_Rule_21_2: 922 * - Rule 21.2 923 - Required 924 - A reserved identifier or macro name shall not be declared 925 - N/A 926 - `Rule 21.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_02.c>`_ 927 928 .. _MisraC_Rule_21_3: 929 * - Rule 21.3 930 - Required 931 - The memory allocation and deallocation functions of <stdlib.h> shall not be used 932 - `MSC24-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC24-C.+Do+not+use+deprecated+or+obsolescent+functions>`_ 933 - `Rule 21.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_03.c>`_ 934 935 .. _MisraC_Rule_21_4: 936 * - Rule 21.4 937 - Required 938 - The standard header file <setjmp.h> shall not be used 939 - N/A 940 - `Rule 21.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_04.c>`_ 941 942 .. _MisraC_Rule_21_6: 943 * - Rule 21.6 944 - Required 945 - The Standard Library input/output functions shall not be used 946 - N/A 947 - `Rule 21.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_06.c>`_ 948 949 .. _MisraC_Rule_21_7: 950 * - Rule 21.7 951 - Required 952 - The atof, atoi, atol and atoll functions of <stdlib.h> shall not be used 953 - N/A 954 - `Rule 21.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_07.c>`_ 955 956 .. _MisraC_Rule_21_9: 957 * - Rule 21.9 958 - Required 959 - The library functions bsearch and qsort of <stdlib.h> shall not be used 960 - N/A 961 - `Rule 21.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_09.c>`_ 962 963 .. _MisraC_Rule_21_11: 964 * - Rule 21.11 965 - Required 966 - The standard header file <tgmath.h> shall not be used 967 - N/A 968 - `Rule 21.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_11.c>`_ 969 970 .. _MisraC_Rule_21_12: 971 * - Rule 21.12 972 - Advisory 973 - The exception handling features of <fenv.h> should not be used 974 - N/A 975 - `Rule 21.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_12.c>`_ 976 977 .. _MisraC_Rule_21_13: 978 * - Rule 21.13 979 - Mandatory 980 - Any value passed to a function in <ctype.h> shall be representable as an unsigned char or be the value EO 981 - N/A 982 - `Rule 21.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_13.c>`_ 983 984 .. _MisraC_Rule_21_14: 985 * - Rule 21.14 986 - Required 987 - The Standard Library function memcmp shall not be used to compare null terminated strings 988 - N/A 989 - `Rule 21.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_14.c>`_ 990 991 .. _MisraC_Rule_21_15: 992 * - Rule 21.15 993 - Required 994 - The pointer arguments to the Standard Library functions memcpy, memmove and memcmp shall be pointers to qualified or unqualified versions of compatible types 995 - N/A 996 - `Rule 21.15 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_15.c>`_ 997 998 .. _MisraC_Rule_21_16: 999 * - Rule 21.16 1000 - Required 1001 - The pointer arguments to the Standard Library function memcmp shall point to either a pointer type, an essentially signed type, an essentially unsigned type, an essentially Boolean type or an essentially enum type 1002 - N/A 1003 - `Rule 21.16 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_16.c>`_ 1004 1005 .. _MisraC_Rule_21_17: 1006 * - Rule 21.17 1007 - Mandatory 1008 - Use of the string handling functions from <string.h> shall not result in accesses beyond the bounds of the objects referenced by their pointer parameters 1009 - N/A 1010 - `Rule 21.17 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_17.c>`_ 1011 1012 .. _MisraC_Rule_21_18: 1013 * - Rule 21.18 1014 - Mandatory 1015 - The size_t argument passed to any function in <string.h> shall have an appropriate value 1016 - N/A 1017 - `Rule 21.18 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_18.c>`_ 1018 1019 .. _MisraC_Rule_21_19: 1020 * - Rule 21.19 1021 - Mandatory 1022 - The pointers returned by the Standard Library functions localeconv, getenv, setlocale or, strerror shall only be used as if they have pointer to const-qualified type 1023 - N/A 1024 - `Rule 21.19 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_19.c>`_ 1025 1026 .. _MisraC_Rule_21_20: 1027 * - Rule 21.20 1028 - Mandatory 1029 - The pointer returned by the Standard Library functions asctime, ctime, gmtime, localtime, localeconv, getenv, setlocale or strerror shall not be used following a subsequent call to the same function 1030 - N/A 1031 - `Rule 21.20 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_20.c>`_ 1032 1033 .. _MisraC_Rule_22_1: 1034 * - Rule 22.1 1035 - Required 1036 - All resources obtained dynamically by means of Standard Library functions shall be explicitly released 1037 - N/A 1038 - `Rule 22.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_01.c>`_ 1039 1040 .. _MisraC_Rule_22_2: 1041 * - Rule 22.2 1042 - Mandatory 1043 - A block of memory shall only be freed if it was allocated by means of a Standard Library function 1044 - N/A 1045 - `Rule 22.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_02.c>`_ 1046 1047 .. _MisraC_Rule_22_3: 1048 * - Rule 22.3 1049 - Required 1050 - The same file shall not be open for read and write access at the same time on different streams 1051 - N/A 1052 - `Rule 22.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_03.c>`_ 1053 1054 .. _MisraC_Rule_22_4: 1055 * - Rule 22.4 1056 - Mandatory 1057 - There shall be no attempt to write to a stream which has been opened as read-only 1058 - N/A 1059 - `Rule 22.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_04.c>`_ 1060 1061 .. _MisraC_Rule_22_5: 1062 * - Rule 22.5 1063 - Mandatory 1064 - A pointer to a FILE object shall not be dereferenced 1065 - N/A 1066 - `Rule 22.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_05.c>`_ 1067 1068 .. _MisraC_Rule_22_6: 1069 * - Rule 22.6 1070 - Mandatory 1071 - The value of a pointer to a FILE shall not be used after the associated stream has been closed 1072 - N/A 1073 - `Rule 22.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_06.c>`_ 1074 1075 .. _MisraC_Rule_22_7: 1076 * - Rule 22.7 1077 - Required 1078 - The macro EOF shall only be compared with the unmodified return value from any Standard Library function capable of returning EOF 1079 - N/A 1080 - `Rule 22.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_07.c>`_ 1081 1082 .. _MisraC_Rule_22_8: 1083 * - Rule 22.8 1084 - Required 1085 - The value of errno shall be set to zero prior to a call to an errno-setting-function 1086 - N/A 1087 - `Rule 22.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_08.c>`_ 1088 1089 .. _MisraC_Rule_22_9: 1090 * - Rule 22.9 1091 - Required 1092 - The value of errno shall be tested against zero after calling an errno-setting-function 1093 - N/A 1094 - `Rule 22.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_09.c>`_ 1095 1096 .. _MisraC_Rule_22_10: 1097 * - Rule 22.10 1098 - Required 1099 - The value of errno shall only be tested when the last function to be called was an errno-setting-function 1100 - N/A 1101 - `Rule 22.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_10.c>`_ 1102 1103Additional rules 1104**************** 1105 1106Rule A.1: Conditional Compilation 1107================================= 1108 1109Severity 1110-------- 1111 1112Required 1113 1114Description 1115----------- 1116 1117Do not conditionally compile function declarations in header files. Do not 1118conditionally compile structure declarations in header files. You may 1119conditionally exclude fields within structure definitions to avoid wasting 1120memory when the feature they support is not enabled. 1121 1122Rationale 1123--------- 1124 1125Excluding declarations from the header based on compile-time options may prevent 1126their documentation from being generated. Their absence also prevents use of 1127``if (IS_ENABLED(CONFIG_FOO)) {}`` as an alternative to preprocessor 1128conditionals when the code path should change based on the selected options. 1129 1130.. _coding_guideline_inclusive_language: 1131 1132Rule A.2: Inclusive Language 1133============================ 1134 1135Severity 1136-------- 1137 1138Required 1139 1140Description 1141----------- 1142 1143Do not introduce new usage of offensive terms listed below. This rule applies 1144but is not limited to source code, comments, documentation, and branch names. 1145Replacement terms may vary by area or subsystem, but should aim to follow 1146updated industry standards when possible. 1147 1148Exceptions are allowed for maintaining existing implementations or adding new 1149implementations of industry standard specifications governed externally to the 1150Zephyr Project. 1151 1152Existing usage is recommended to change as soon as updated industry standard 1153specifications become available or new terms are publicly announced by the 1154governing body, or immediately if no specifications apply. 1155 1156.. list-table:: 1157 :header-rows: 1 1158 1159 * - Offensive Terms 1160 - Recommended Replacements 1161 1162 * - ``{master,leader} / slave`` 1163 - - ``{primary,main} / {secondary,replica}`` 1164 - ``{initiator,requester} / {target,responder}`` 1165 - ``{controller,host} / {device,worker,proxy,target}`` 1166 - ``director / performer`` 1167 - ``central / peripheral`` 1168 1169 * - ``blacklist / whitelist`` 1170 - * ``denylist / allowlist`` 1171 * ``blocklist / allowlist`` 1172 * ``rejectlist / acceptlist`` 1173 1174 * - ``grandfather policy`` 1175 - * ``legacy`` 1176 1177 * - ``sanity`` 1178 - * ``coherence`` 1179 * ``confidence`` 1180 1181 1182Rationale 1183--------- 1184 1185Offensive terms do not create an inclusive community environment and therefore 1186violate the Zephyr Project `Code of Conduct`_. This coding rule was inspired by 1187a similar rule in `Linux`_. 1188 1189.. _Code of Conduct: https://github.com/zephyrproject-rtos/zephyr/blob/main/CODE_OF_CONDUCT.md 1190.. _Linux: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb 1191 1192Status 1193------ 1194 1195Related GitHub Issues and Pull Requests are tagged with the `Inclusive Language Label`_. 1196 1197.. list-table:: 1198 :header-rows: 1 1199 1200 * - Area 1201 - Selected Replacements 1202 - Status 1203 1204 * - :ref:`bluetooth_api` 1205 - See `Bluetooth Appropriate Language Mapping Tables`_ 1206 - 1207 1208 * - CAN 1209 - This `CAN in Automation Inclusive Language news post`_ has a list of general 1210 recommendations. See `CAN in Automation Inclusive Language`_ for terms to 1211 be used in specification document updates. 1212 - 1213 1214 * - eSPI 1215 - * ``master / slave`` => TBD 1216 - 1217 1218 * - gPTP 1219 - * ``master / slave`` => TBD 1220 - 1221 1222 * - :ref:`i2c_api` 1223 - * ``master / slave`` => TBD 1224 - NXP publishes the `I2C Specification`_ and has selected ``controller / 1225 target`` as replacement terms, but the timing to publish an announcement 1226 or new specification is TBD. Zephyr will update I2C when replacement 1227 terminology is confirmed by a public announcement or updated 1228 specification. 1229 1230 See :github:`Zephyr issue 27033 <27033>`. 1231 1232 * - :ref:`i2s_api` 1233 - * ``master / slave`` => TBD 1234 - 1235 1236 * - SMP/AMP 1237 - * ``master / slave`` => TBD 1238 - 1239 1240 * - :ref:`spi_api` 1241 - * ``master / slave`` => ``controller / peripheral`` 1242 * ``MOSI / MISO / SS`` => ``SDO / SDI / CS`` 1243 - The Open Source Hardware Association has selected these replacement 1244 terms. See `OSHWA Resolution to Redefine SPI Signal Names`_ 1245 1246 * - :ref:`twister_script` 1247 - * ``platform_whitelist`` => ``platform_allow`` 1248 * ``sanitycheck`` => ``twister`` 1249 - 1250 1251.. _Inclusive Language Label: https://github.com/zephyrproject-rtos/zephyr/issues?q=label%3A%22Inclusive+Language%22 1252.. _I2C Specification: https://www.nxp.com/docs/en/user-guide/UM10204.pdf 1253.. _Bluetooth Appropriate Language Mapping Tables: https://btprodspecificationrefs.blob.core.windows.net/language-mapping/Appropriate_Language_Mapping_Table.pdf 1254.. _OSHWA Resolution to Redefine SPI Signal Names: https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names/ 1255.. _CAN in Automation Inclusive Language news post: https://www.can-cia.org/news/archive/view/?tx_news_pi1%5Bnews%5D=699&tx_news_pi1%5Bday%5D=6&tx_news_pi1%5Bmonth%5D=12&tx_news_pi1%5Byear%5D=2020&cHash=784e79eb438141179386cf7c29ed9438 1256.. _CAN in Automation Inclusive Language: https://can-newsletter.org/canopen/categories/ 1257 1258 1259Rule A.3: Macro name collisions 1260=============================== 1261 1262Severity 1263-------- 1264 1265Required 1266 1267Description 1268----------- 1269 1270Macros with commonly used names such as ``MIN``, ``MAX``, ``ARRAY_SIZE``, must 1271not be modified or protected to avoid name collisions with other 1272implementations. In particular, they must not be prefixed to place them in a 1273Zephyr-specific namespace, re-defined using ``#undef``, or conditionally 1274excluded from compilation using ``#ifndef``. Instead, if a conflict arises with 1275an existing definition originating from a :ref:`module <modules>`, the module's 1276code itself needs to be modified (ideally upstream, alternatively via a change 1277in Zephyr's own fork). 1278This rule applies to Zephyr as a project in general, regardless of the time of 1279introduction of the macro or its current name in the tree. If a macro name is 1280commonly used in several other well-known open source projects then the 1281implementation in Zephyr should use that name. While there is a subjective and 1282non-measurable component to what "commonly used" means, the ultimate goal is 1283to offer users familiar macros. 1284Finally, this rule applies to inter-module name collisions as well: in that case 1285both modules, prior to their inclusion, should be modified to use 1286module-specific versions of the macro name that collides. 1287 1288Rationale 1289--------- 1290 1291Zephyr is an RTOS that comes with additional functionality and dependencies in 1292the form of modules. Those modules are typically independent projects that may 1293use macro names that can conflict with other modules or with Zephyr itself. 1294Since, in the context of this documentation, Zephyr is considered the central or 1295main project, it should implement the non-namespaced versions of the 1296macros. Given that Zephyr uses a fork of the corresponding upstream for each 1297module, it is always possible to patch the macro implementation in each module 1298to avoid collisions. 1299 1300.. _coding_guideline_libc_usage_restrictions_in_zephyr_kernel: 1301 1302Rule A.4: C Standard Library Usage Restrictions in Zephyr Kernel 1303================================================================ 1304 1305Severity 1306-------- 1307 1308Required 1309 1310Description 1311----------- 1312 1313The use of the C standard library functions and macros in the Zephyr kernel 1314shall be limited to the following functions and macros from the ISO/IEC 13159899:2011 standard, also known as C11, and their extensions: 1316 1317.. csv-table:: List of allowed libc functions and macros in the Zephyr kernel 1318 :header: Function,Source 1319 :widths: auto 1320 1321 abort(),ISO/IEC 9899:2011 1322 abs(),ISO/IEC 9899:2011 1323 aligned_alloc(),ISO/IEC 9899:2011 1324 assert(),ISO/IEC 9899:2011 1325 atoi(),ISO/IEC 9899:2011 1326 bsearch(),ISO/IEC 9899:2011 1327 calloc(),ISO/IEC 9899:2011 1328 exit(),ISO/IEC 9899:2011 1329 fprintf(),ISO/IEC 9899:2011 1330 fputc(),ISO/IEC 9899:2011 1331 fputs(),ISO/IEC 9899:2011 1332 free(),ISO/IEC 9899:2011 1333 fwrite(),ISO/IEC 9899:2011 1334 gmtime(),ISO/IEC 9899:2011 1335 isalnum(),ISO/IEC 9899:2011 1336 isalpha(),ISO/IEC 9899:2011 1337 iscntrl(),ISO/IEC 9899:2011 1338 isdigit(),ISO/IEC 9899:2011 1339 isgraph(),ISO/IEC 9899:2011 1340 isprint(),ISO/IEC 9899:2011 1341 isspace(),ISO/IEC 9899:2011 1342 isupper(),ISO/IEC 9899:2011 1343 isxdigit(),ISO/IEC 9899:2011 1344 labs(),ISO/IEC 9899:2011 1345 llabs(),ISO/IEC 9899:2011 1346 malloc(),ISO/IEC 9899:2011 1347 memchr(),ISO/IEC 9899:2011 1348 memcmp(),ISO/IEC 9899:2011 1349 memcpy(),ISO/IEC 9899:2011 1350 memmove(),ISO/IEC 9899:2011 1351 memset(),ISO/IEC 9899:2011 1352 perror(),ISO/IEC 9899:2011 1353 printf(),ISO/IEC 9899:2011 1354 putc(),ISO/IEC 9899:2011 1355 putchar(),ISO/IEC 9899:2011 1356 puts(),ISO/IEC 9899:2011 1357 qsort(),ISO/IEC 9899:2011 1358 rand(),ISO/IEC 9899:2011 1359 realloc(),ISO/IEC 9899:2011 1360 snprintf(),ISO/IEC 9899:2011 1361 sprintf(),ISO/IEC 9899:2011 1362 sqrt(),ISO/IEC 9899:2011 1363 sqrtf(),ISO/IEC 9899:2011 1364 srand(),ISO/IEC 9899:2011 1365 strcat(),ISO/IEC 9899:2011 1366 strchr(),ISO/IEC 9899:2011 1367 strcmp(),ISO/IEC 9899:2011 1368 strcpy(),ISO/IEC 9899:2011 1369 strcspn(),ISO/IEC 9899:2011 1370 strerror(),ISO/IEC 9899:2011 1371 strlen(),ISO/IEC 9899:2011 1372 strncat(),ISO/IEC 9899:2011 1373 strncmp(),ISO/IEC 9899:2011 1374 strncpy(),ISO/IEC 9899:2011 1375 `strnlen()`_,POSIX.1-2008 1376 strrchr(),ISO/IEC 9899:2011 1377 strspn(),ISO/IEC 9899:2011 1378 strstr(),ISO/IEC 9899:2011 1379 strtol(),ISO/IEC 9899:2011 1380 strtoll(),ISO/IEC 9899:2011 1381 strtoul(),ISO/IEC 9899:2011 1382 strtoull(),ISO/IEC 9899:2011 1383 time(),ISO/IEC 9899:2011 1384 tolower(),ISO/IEC 9899:2011 1385 toupper(),ISO/IEC 9899:2011 1386 vfprintf(),ISO/IEC 9899:2011 1387 vprintf(),ISO/IEC 9899:2011 1388 vsnprintf(),ISO/IEC 9899:2011 1389 vsprintf(),ISO/IEC 9899:2011 1390 1391All of the functions listed above must be implemented by the 1392:ref:`minimal libc <c_library_minimal>` to ensure that the Zephyr kernel can 1393build with the minimal libc. 1394 1395In addition, any functions from the above list that are not part of the 1396ISO/IEC 9899:2011 standard must be implemented by the 1397:ref:`common libc <c_library_common>` to ensure their availability across 1398multiple C standard libraries. 1399 1400Introducing new C standard library functions to the Zephyr kernel is allowed 1401with justification given that the above requirements are satisfied. 1402 1403Note that the use of the functions listed above are subject to secure and safe 1404coding practices and it should not be assumed that their use in the Zephyr 1405kernel is unconditionally permitted by being listed in this rule. 1406 1407The "Zephyr kernel" in this context consists of the following components: 1408 1409* Kernel (:file:`kernel`) 1410* OS Library (:file:`lib/os`) 1411* Architecture Port (:file:`arch`) 1412* Logging Subsystem (:file:`subsys/logging`) 1413 1414Rationale 1415--------- 1416 1417Zephyr kernel must be able to build with the 1418:ref:`minimal libc <c_library_minimal>`, a limited C standard library 1419implementation that is part of the Zephyr RTOS and maintained by the Zephyr 1420Project, to allow self-contained testing and verification of the kernel and 1421core OS services. 1422 1423In order to ensure that the Zephyr kernel can build with the minimal libc, it 1424is necessary to restrict the use of the C standard library functions and macros 1425in the Zephyr kernel to the functions and macros that are available as part of 1426the minimal libc. 1427 1428Rule A.5: C Standard Library Usage Restrictions in Zephyr Codebase 1429================================================================== 1430 1431Severity 1432-------- 1433 1434Required 1435 1436Description 1437----------- 1438 1439The use of the C standard library functions and macros in the Zephyr codebase 1440shall be limited to the functions, excluding the Annex K "Bounds-checking 1441interfaces", from the ISO/IEC 9899:2011 standard, also known as C11, unless 1442exempted by this rule. 1443 1444The "Zephyr codebase" in this context refers to all source code files committed 1445to the `main Zephyr repository`_, except the Zephyr kernel as defined by the 1446:ref:`coding_guideline_libc_usage_restrictions_in_zephyr_kernel`. 1447 1448The following non-ISO 9899:2011, hereinafter referred to as non-standard, 1449functions and macros are exempt from this rule and allowed to be used in the 1450Zephyr codebase: 1451 1452.. csv-table:: List of allowed non-standard libc functions 1453 :header: Function,Source 1454 :widths: auto 1455 1456 `strnlen()`_,POSIX.1-2008 1457 `strtok_r()`_,POSIX.1-2001 1458 1459All non-standard functions and macros listed above must be implemented by the 1460:ref:`common libc <c_library_common>` in order to make sure that these 1461functions can be made available when using a C standard library that does not 1462implement these functions. 1463 1464Adding a new non-standard function from common C standard libraries to the 1465above list is allowed with justification, given that the above requirement is 1466satisfied. However, when there exists a standard function that is functionally 1467equivalent, the standard function shall be used. 1468 1469Rationale 1470--------- 1471 1472Some C standard libraries, such as Newlib and Picolibc, include additional 1473functions and macros that are defined by the standards and de-facto standards 1474that extend the ISO C standard (e.g. POSIX, Linux). 1475 1476The ISO/IEC 9899:2011 standard does not require C compiler toolchains to 1477include the support for these non-standard functions, and therefore using 1478these functions can lead to compatibility issues with the third-party 1479toolchains that come with their own C standard libraries. 1480 1481.. _main Zephyr repository: https://github.com/zephyrproject-rtos/zephyr 1482.. _strnlen(): https://pubs.opengroup.org/onlinepubs/9699919799/functions/strlen.html 1483.. _strtok_r(): https://pubs.opengroup.org/onlinepubs/9699919799/functions/strtok.html 1484 1485Parasoft Codescan Tool 1486********************** 1487 1488Parasoft Codescan is an official static code analysis tool used by the Zephyr 1489project. It is used to automate compliance with a range of coding and security 1490standards. 1491The tool is currently set to the MISRA-C:2012 Coding Standard because the Zephyr 1492:ref:`coding_guidelines` are based on that standard. 1493It is used together with the Coverity Scan tool to achieve the best code health 1494and precision in bug findings. 1495 1496Violations fixing process 1497========================= 1498 1499Step 1 1500 Any Zephyr Project member, company or a developer can request access 1501 to the Parasoft reporting centre if they wish to get involved in fixing 1502 violations by submitting issues. 1503 1504Step 2 1505 A developer starts to review violations. 1506 1507Step 3 1508 A developer submits a Github PR with the fix. Commit messages should follow 1509 the same guidelines as other PRs in the Zephyr project. Please add a comment 1510 that your fix was found by a static coding scanning tool. 1511 Developers should follow and refer to the Zephyr :ref:`coding_guidelines` 1512 as basic rules for coding. These rules are based on the MISRA-C standard. 1513 1514 Below you can find an example of a recommended commit message:: 1515 1516 lib: os: add braces to 'if' statements 1517 1518 An 'if' (expression) construct shall be followed by a compound statement. 1519 Add braces to improve readability and maintainability. 1520 1521 Found as a coding guideline violation (Rule 15.6) by static 1522 coding scanning tool. 1523 1524 Signed-off-by: Johnny Developer <johnny.developer@company.com> 1525 1526Step 4 1527 If a violation is a false positive, the developer should mark it for the Codescan 1528 tool just like they would do for the Coverity tool. 1529 The developer should also add a comment to the code explaining that 1530 the violation raised by the static code analysis tool should be considered a 1531 false positive. 1532 1533Step 5 1534 If the developer has found a real violation that the community decided to ignore, 1535 the developer must submit a PR with a suppression tag 1536 and a comment explaining why the violation has been deviated. 1537 The template structure of the comment and tag in the code should be:: 1538 1539 /* Explain why that part of the code doesn't follow the standard, 1540 * explain why it is a deliberate deviation from the standard. 1541 * Don't refer to the Parasoft tool here, just mention that static code 1542 * analysis tool raised a violation in the line below. 1543 */ 1544 code_line_with_a_violation /* parasoft-suppress Rule ID */ 1545 1546 Below you can find an example of a recommended commit message:: 1547 1548 testsuite: suppress usage of setjmp in a testcode (rule 21.4) 1549 1550 According to the Rule 21.4 the standard header file <setjmp.h> shall not 1551 be used. We will suppress this violation because it is in 1552 test code. Tag suppresses reporting of the violation for the 1553 line where the violation is located. 1554 This is a deliberate deviation. 1555 1556 Found as a coding guideline violation (Rule 21.4) by static coding 1557 scanning tool. 1558 1559 Signed-off-by: Johnny Developer <johnny.developer@company.com> 1560 1561 The example below demonstrates how deviations can be suppressed in the code:: 1562 1563 /* Static code analysis tool can raise a violation that the standard 1564 * header <setjmp.h> shall not be used. 1565 * Since this violation is in test code, we will suppress it. 1566 * Deliberate deviation. 1567 */ 1568 #include <setjmp.h> /* parasoft-suppress MISRAC2012-RULE_21_4-a MISRAC2012-RULE_21_4-b */ 1569 1570 This variant above suppresses item ``MISRAC2012-RULE_21_4-a`` and ``MISRAC2012-RULE_21_4-b`` 1571 on the line with "setjump" header include. You can add as many rules to suppress you want - 1572 just make sure to keep the Parasoft tag on one line and separate rules with a space. 1573 To read more about suppressing findings in the Parasoft tool, refer to the 1574 official Parasoft `documentation`_ 1575 1576 .. _documentation: https://docs.parasoft.com/display/CPPTEST1031/Suppressing+Findings 1577 1578Step 6 1579 After a PR is submitted, the developer should add the ``Coding guidelines`` 1580 and ``MISRA-C`` Github labels so their PR can be easily tracked by maintainers. 1581 If you have any concerns about what your PR should look like, you can search 1582 on Github using those tags and refer to similar PRs that have already been merged. 1583
