.. _coding_guidelines:

Coding Guidelines
#################

The project TSC and the Safety Committee of the project agreed to implement
a staged and incremental approach for complying with a set of coding rules (AKA
Coding Guidelines) to improve quality and consistency of the code base. Below
are the agreed upon stages and the approximate timelines:

Stage I
  Coding guideline rules are available to be followed and referenced,
  but not enforced. Rules are not yet enforced in CI and pull-requests cannot be
  blocked by reviewers/approvers due to violations.

Stage II
  Begin enforcement on a limited scope of the code base. Initially, this would be
  the safety certification scope. For rules easily applied across codebase, we
  should not limit compliance to initial scope. This step requires tooling,
  CI setup and an enforcement strategy.

Stage III
  Revisit the coding guideline rules and based on experience from previous
  stages, refine/iterate on selected rules.

Stage IV
   Expand enforcement to the wider codebase. Exceptions may be granted on some
   areas of the codebase with a proper justification. Exception would require
   TSC approval.

.. note::

    Coding guideline rules may be removed/changed at any time by filing a
    GH issue/RFC.

Main rules
**********

The coding guideline rules are based on MISRA-C 2012 and are a subset of MISRA-C.
The subset is listed in the table below with a summary of the rules, its
severity and the equivalent rules from other standards for reference.

.. note::

    For existing Zephyr maintainers and collaborators, if you are unable to
    obtain a copy through your employer, a limited number of copies will be made
    available through the project. If you need a copy of MISRA-C 2012, please
    send email to safety@lists.zephyrproject.org and provide details on reason
    why you can't obtain one through other options and expected contributions
    once you have one.  The safety committee will review all requests.


.. list-table:: Main rules
    :header-rows: 1
    :widths: 17 14 43 12 14

    * -  MISRA C 2012
      -  Severity
      -  Description
      -  CERT C
      -  Example

         .. _MisraC_Dir_1_1:
    * -  Dir 1.1
      -  Required
      -  Any implementation-defined behaviour on which the output of the program depends shall be documented and understood
      -  `MSC09-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC09-C.+Character+encoding%3A+Use+subset+of+ASCII+for+safety>`_
      -  `Dir 1.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_01_01.c>`_

         .. _MisraC_Dir_2_1:
    * -  Dir 2.1
      -  Required
      -  All source files shall compile without any compilation errors
      -  N/A
      -  `Dir 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_

         .. _MisraC_Dir_3_1:
    * -  Dir 3.1
      -  Required
      -  All code shall be traceable to documented requirements
      -  N/A
      -  `Dir 3.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_03_01.c>`_

         .. _MisraC_Dir_4_1:
    * -  Dir 4.1
      -  Required
      -  Run-time failures shall be minimized
      -  N/A
      -  `Dir 4.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_01.c>`_

         .. _MisraC_Dir_4_2:
    * -  Dir 4.2
      -  Advisory
      -  All usage of assembly language should be documented
      -  N/A
      -  `Dir 4.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_02.c>`_

         .. _MisraC_Dir_4_4:
    * -  Dir 4.4
      -  Advisory
      -  Sections of code should not be “commented out”
      -  `MSC04-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC04-C.+Use+comments+consistently+and+in+a+readable+fashion>`_
      -  `Dir 4.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_04.c>`_

         .. _MisraC_Dir_4_5:
    * -  Dir 4.5
      -  Advisory
      -  Identifiers in the same name space with overlapping visibility should be typographically unambiguous
      -  `DCL02-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL02-C.+Use+visually+distinct+identifiers>`_
      -  `Dir 4.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_05.c>`_

         .. _MisraC_Dir_4_6:
    * -  Dir 4.6
      -  Advisory
      -  typedefs that indicate size and signedness should be used in place of the basic numerical types
      -  N/A
      -  `Dir 4.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_06.c>`_

         .. _MisraC_Dir_4_7:
    * -  Dir 4.7
      -  Required
      -  If a function returns error information, then that error information shall be tested
      -  N/A
      -  `Dir 4.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_07.c>`_

         .. _MisraC_Dir_4_8:
    * -  Dir 4.8
      -  Advisory
      -  If a pointer to a structure or union is never dereferenced within a translation unit, then the implementation of the object should be hidden
      -  `DCL12-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL12-C.+Implement+abstract+data+types+using+opaque+types>`_
      -  | `Dir 4.8 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_08_1.c>`_
         | `Dir 4.8 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_08_2.c>`_

         .. _MisraC_Dir_4_9:
    * -  Dir 4.9
      -  Advisory
      -  A function should be used in preference to a function-like macro where they are interchangeable
      -  `PRE00-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE00-C.+Prefer+inline+or+static+functions+to+function-like+macros>`_
      -  `Dir 4.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_09.c>`_

         .. _MisraC_Dir_4_10:
    * -  Dir 4.10
      -  Required
      -  Precautions shall be taken in order to prevent the contents of a header file being included more than once
      -  `PRE06-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE06-C.+Enclose+header+files+in+an+include+guard>`_
      -  `Dir 4.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_10.c>`_

         .. _MisraC_Dir_4_11:
    * -  Dir 4.11
      -  Required
      -  The validity of values passed to library functions shall be checked
      -  N/A
      -  `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_

         .. _MisraC_Dir_4_12:
    * -  Dir 4.12
      -  Required
      -  Dynamic memory allocation shall not be used
      -  `STR01-C <https://wiki.sei.cmu.edu/confluence/display/c/STR01-C.+Adopt+and+implement+a+consistent+plan+for+managing+strings>`_
      -  `Dir 4.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_12.c>`_

         .. _MisraC_Dir_4_13:
    * -  Dir 4.13
      -  Advisory
      -  Functions which are designed to provide operations on a resource should be called in an appropriate sequence
      -  N/A
      -  `Dir 4.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_13.c>`_

         .. _MisraC_Dir_4_14:
    * -  Dir 4.14
      -  Required
      -  The validity of values received from external sources shall be checked

      -  N/A
      -  `Dir 4.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_14.c>`_

         .. _MisraC_Rule_1_2:
    * -  Rule 1.2
      -  Advisory
      -  Language extensions should not be used
      -  `MSC04-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC04-C.+Use+comments+consistently+and+in+a+readable+fashion>`_
      -  `Rule 1.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_01_02.c>`_

         .. _MisraC_Rule_1_3:
    * -  Rule 1.3
      -  Required
      -  There shall be no occurrence of undefined or critical unspecified behaviour
      -  N/A
      -  `Rule 1.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_01_03.c>`_

         .. _MisraC_Rule_2_1:
    * -  Rule 2.1
      -  Required
      -  A project shall not contain unreachable code
      -  `MSC07-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC07-C.+Detect+and+remove+dead+code>`_
      -  | `Rule 2.1 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_01_1.c>`_
         | `Rule 2.1 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_01_2.c>`_

         .. _MisraC_Rule_2_2:
    * -  Rule 2.2
      -  Required
      -  There shall be no dead code
      -  `MSC12-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC12-C.+Detect+and+remove+code+that+has+no+effect+or+is+never+executed>`_
      -  `Rule 2.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_02.c>`_

         .. _MisraC_Rule_2_3:
    * -  Rule 2.3
      -  Advisory
      -  A project should not contain unused type declarations
      -  N/A
      -  `Rule 2.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_03.c>`_

         .. _MisraC_Rule_2_6:
    * -  Rule 2.6
      -  Advisory
      -  A function should not contain unused label declarations
      -  N/A
      -  `Rule 2.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_06.c>`_

         .. _MisraC_Rule_2_7:
    * -  Rule 2.7
      -  Advisory
      -  There should be no unused parameters in functions
      -  N/A
      -  `Rule 2.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_07.c>`_

         .. _MisraC_Rule_3_1:
    * -  Rule 3.1
      -  Required
      -  The character sequences /* and // shall not be used within a comment
      -  `MSC04-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC04-C.+Use+comments+consistently+and+in+a+readable+fashion>`_
      -  `Rule 3.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_01.c>`_

         .. _MisraC_Rule_3_2:
    * -  Rule 3.2
      -  Required
      -  Line-splicing shall not be used in // comments
      -  N/A
      -  `Rule 3.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_02.c>`_

         .. _MisraC_Rule_4_1:
    * -  Rule 4.1
      -  Required
      -  Octal and hexadecimal escape sequences shall be terminated
      -  `MSC09-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC09-C.+Character+encoding%3A+Use+subset+of+ASCII+for+safety>`_
      -  `Rule 4.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_04_01.c>`_

         .. _MisraC_Rule_4_2:
    * -  Rule 4.2
      -  Advisory
      -  Trigraphs should not be used
      -  `PRE07-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE07-C.+Avoid+using+repeated+question+marks>`_
      -  `Rule 4.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_04_02.c>`_

         .. _MisraC_Rule_5_1:
    * -  Rule 5.1
      -  Required
      -  External identifiers shall be distinct
      -  `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_
      -  | `Rule 5.1 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_01_1.c>`_
         | `Rule 5.1 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_01_2.c>`_

         .. _MisraC_Rule_5_2:
    * -  Rule 5.2
      -  Required
      -  Identifiers declared in the same scope and name space shall be distinct
      -  `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_
      -  `Rule 5.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_02.c>`_

         .. _MisraC_Rule_5_3:
    * -  Rule 5.3
      -  Required
      -  An identifier declared in an inner scope shall not hide an identifier declared in an outer scope
      -  `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_
      -  `Rule 5.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_03.c>`_

         .. _MisraC_Rule_5_4:
    * -  Rule 5.4
      -  Required
      -  Macro identifiers shall be distinct
      -  `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_
      -  `Rule 5.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_04.c>`_

         .. _MisraC_Rule_5_5:
    * -  Rule 5.5
      -  Required
      -  Identifiers shall be distinct from macro names
      -  `DCL23-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL23-C.+Guarantee+that+mutually+visible+identifiers+are+unique>`_
      -  `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_

         .. _MisraC_Rule_5_6:
    * -  Rule 5.6
      -  Required
      -  A typedef name shall be a unique identifier
      -  N/A
      -  `Rule 5.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_06.c>`_

         .. _MisraC_Rule_5_7:
    * -  Rule 5.7
      -  Required
      -  A tag name shall be a unique identifier
      -  N/A
      -  `Rule 5.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_07.c>`_

         .. _MisraC_Rule_5_8:
    * -  Rule 5.8
      -  Required
      -  Identifiers that define objects or functions with external linkage shall be unique
      -  N/A
      -  | `Rule 5.8 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_08_1.c>`_
         | `Rule 5.8 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_08_2.c>`_

         .. _MisraC_Rule_5_9:
    * -  Rule 5.9
      -  Advisory
      -  Identifiers that define objects or functions with internal linkage should be unique
      -  N/A
      -  | `Rule 5.9 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_09_1.c>`_
         | `Rule 5.9 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_09_2.c>`_

         .. _MisraC_Rule_6_1:
    * -  Rule 6.1
      -  Required
      -  Bit-fields shall only be declared with an appropriate type
      -  `INT14-C <https://wiki.sei.cmu.edu/confluence/display/c/INT14-C.+Avoid+performing+bitwise+and+arithmetic+operations+on+the+same+data>`_
      -  `Rule 6.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_01.c>`_

         .. _MisraC_Rule_6_2:
    * -  Rule 6.2
      -  Required
      -  Single-bit named bit fields shall not be of a signed type
      -  `INT14-C <https://wiki.sei.cmu.edu/confluence/display/c/INT14-C.+Avoid+performing+bitwise+and+arithmetic+operations+on+the+same+data>`_
      -  `Rule 6.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_02.c>`_

         .. _MisraC_Rule_7_1:
    * -  Rule 7.1
      -  Required
      -  Octal constants shall not be used
      -  `DCL18-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL18-C.+Do+not+begin+integer+constants+with+0+when+specifying+a+decimal+value>`_
      -  `Rule 7.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_01.c>`_

         .. _MisraC_Rule_7_2:
    * -  Rule 7.2
      -  Required
      -  A u or U suffix shall be applied to all integer constants that are represented in an unsigned type
      -  N/A
      -  `Rule 7.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_02.c>`_

         .. _MisraC_Rule_7_3:
    * -  Rule 7.3
      -  Required
      -  The lowercase character l shall not be used in a literal suffix
      -  `DCL16-C <https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152241>`_
      -  `Rule 7.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_03.c>`_

         .. _MisraC_Rule_7_4:
    * -  Rule 7.4
      -  Required
      -  A string literal shall not be assigned to an object unless the objects type is pointer to const-qualified char
      -  N/A
      -  `Rule 7.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_04.c>`_

         .. _MisraC_Rule_8_1:
    * -  Rule 8.1
      -  Required
      -  Types shall be explicitly specified
      -  N/A
      -  `Rule 8.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_01.c>`_

         .. _MisraC_Rule_8_2:
    * -  Rule 8.2
      -  Required
      -  Function types shall be in prototype form with named parameters
      -  `DCL20-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL20-C.+Explicitly+specify+void+when+a+function+accepts+no+arguments>`_
      -  `Rule 8.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_02.c>`_

         .. _MisraC_Rule_8_3:
    * -  Rule 8.3
      -  Required
      -  All declarations of an object or function shall use the same names and type qualifiers
      -  N/A
      -  `Rule 8.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_03.c>`_

         .. _MisraC_Rule_8_4:
    * -  Rule 8.4
      -  Required
      -  A compatible declaration shall be visible when an object or function with external linkage is defined
      -  N/A
      -  `Rule 8.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_04.c>`_

         .. _MisraC_Rule_8_5:
    * -  Rule 8.5
      -  Required
      -  An external object or function shall be declared once in one and only one file
      -  N/A
      -  | `Rule 8.5 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_05_1.c>`_
         | `Rule 8.5 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_05_2.c>`_

         .. _MisraC_Rule_8_6:
    * -  Rule 8.6
      -  Required
      -  An identifier with external linkage shall have exactly one external definition
      -  N/A
      -  | `Rule 8.6 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_06_1.c>`_
         | `Rule 8.6 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_06_2.c>`_

         .. _MisraC_Rule_8_8:
    * -  Rule 8.8
      -  Required
      -  The static storage class specifier shall be used in all declarations of objects and functions that have internal linkage
      -  `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>`_
      -  `Rule 8.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_08.c>`_

         .. _MisraC_Rule_8_9:
    * -  Rule 8.9
      -  Advisory
      -  An object should be defined at block scope if its identifier only appears in a single function
      -  `DCL19-C <https://wiki.sei.cmu.edu/confluence/display/c/DCL19-C.+Minimize+the+scope+of+variables+and+functions>`_
      -  `Rule 8.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_09.c>`_

         .. _MisraC_Rule_8_10:
    * -  Rule 8.10
      -  Required
      -  An inline function shall be declared with the static storage class
      -  N/A
      -  `Rule 8.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_10.c>`_

         .. _MisraC_Rule_8_12:
    * -  Rule 8.12
      -  Required
      -  Within an enumerator list, the value of an implicitly-specified enumeration constant shall be unique
      -  `INT09-C <https://wiki.sei.cmu.edu/confluence/display/c/INT09-C.+Ensure+enumeration+constants+map+to+unique+values>`_
      -  `Rule 8.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_12.c>`_

         .. _MisraC_Rule_8_14:
    * -  Rule 8.14
      -  Required
      -  The restrict type qualifier shall not be used
      -  N/A
      -  `Rule 8.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_14.c>`_

         .. _MisraC_Rule_9_1:
    * -  Rule 9.1
      -  Mandatory
      -  The value of an object with automatic storage duration shall not be read before it has been set
      -  N/A
      -  `Rule 9.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_01.c>`_

         .. _MisraC_Rule_9_2:
    * -  Rule 9.2
      -  Required
      -  The initializer for an aggregate or union shall be enclosed in braces
      -  N/A
      -  `Rule 9.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_02.c>`_

         .. _MisraC_Rule_9_3:
    * -  Rule 9.3
      -  Required
      -  Arrays shall not be partially initialized
      -  N/A
      -  `Rule 9.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_03.c>`_

         .. _MisraC_Rule_9_4:
    * -  Rule 9.4
      -  Required
      -  An element of an object shall not be initialized more than once
      -  N/A
      -  `Rule 9.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_04.c>`_

         .. _MisraC_Rule_9_5:
    * -  Rule 9.5
      -  Required
      -  Where designated initializers are used to initialize an array object the size of the array shall be specified explicitly
      -  N/A
      -  `Rule 9.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_09_05.c>`_

         .. _MisraC_Rule_10_1:
    * -  Rule 10.1
      -  Required
      -  Operands shall not be of an inappropriate essential type
      -  `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_
      -  `Rule 10.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_01.c>`_

         .. _MisraC_Rule_10_2:
    * -  Rule 10.2
      -  Required
      -  Expressions of essentially character type shall not be used inappropriately in addition and subtraction operations
      -  `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_
      -  `Rule 10.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_02.c>`_

         .. _MisraC_Rule_10_3:
    * -  Rule 10.3
      -  Required
      -  The value of an expression shall not be assigned to an object with a narrower essential type or of a different essential type category
      -  `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_
      -  `Rule 10.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_03.c>`_

         .. _MisraC_Rule_10_4:
    * -  Rule 10.4
      -  Required
      -  Both operands of an operator in which the usual arithmetic conversions are performed shall have the same essential type category
      -  `STR04-C <https://wiki.sei.cmu.edu/confluence/display/c/STR04-C.+Use+plain+char+for+characters+in+the+basic+character+set>`_
      -  `Rule 10.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_04.c>`_

         .. _MisraC_Rule_10_5:
    * -  Rule 10.5
      -  Advisory
      -  The value of an expression should not be cast to an inappropriate essential type
      -  N/A
      -  `Rule 10.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_05.c>`_

         .. _MisraC_Rule_10_6:
    * -  Rule 10.6
      -  Required
      -  The value of a composite expression shall not be assigned to an object with wider essential type
      -  `INT02-C <https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules>`_
      -  `Rule 10.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_06.c>`_

         .. _MisraC_Rule_10_7:
    * -  Rule 10.7
      -  Required
      -  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
      -  `INT02-C <https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules>`_
      -  `Rule 10.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_07.c>`_

         .. _MisraC_Rule_10_8:
    * -  Rule 10.8
      -  Required
      -  The value of a composite expression shall not be cast to a different essential type category or a wider essential type
      -  `INT02-C <https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules>`_
      -  `Rule 10.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_10_08.c>`_

         .. _MisraC_Rule_11_2:
    * -  Rule 11.2
      -  Required
      -  Conversions shall not be performed between a pointer to an incomplete type and any other type
      -  N/A
      -  `Rule 11.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_02.c>`_

         .. _MisraC_Rule_11_6:
    * -  Rule 11.6
      -  Required
      -  A cast shall not be performed between pointer to void and an arithmetic type
      -  N/A
      -  `Rule 11.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_06.c>`_

         .. _MisraC_Rule_11_7:
    * -  Rule 11.7
      -  Required
      -  A cast shall not be performed between pointer to object and a noninteger arithmetic type
      -  N/A
      -  `Rule 11.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_07.c>`_

         .. _MisraC_Rule_11_8:
    * -  Rule 11.8
      -  Required
      -  A cast shall not remove any const or volatile qualification from the type pointed to by a pointer
      -  `EXP05-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP05-C.+Do+not+cast+away+a+const+qualification>`_
      -  `Rule 11.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_08.c>`_

         .. _MisraC_Rule_11_9:
    * -  Rule 11.9
      -  Required
      -  The macro NULL shall be the only permitted form of integer null pointer constant
      -  N/A
      -  `Rule 11.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_09.c>`_

         .. _MisraC_Rule_12_1:
    * -  Rule 12.1
      -  Advisory
      -  The precedence of operators within expressions should be made explicit
      -  `EXP00-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP00-C.+Use+parentheses+for+precedence+of+operation>`_
      -  `Rule 12.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_01.c>`_

         .. _MisraC_Rule_12_2:
    * -  Rule 12.2
      -  Required
      -  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
      -  N/A
      -  `Rule 12.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_02.c>`_

         .. _MisraC_Rule_12_4:
    * -  Rule 12.4
      -  Advisory
      -  Evaluation of constant expressions should not lead to unsigned integer wrap-around
      -  N/A
      -  `Rule 12.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_04.c>`_

         .. _MisraC_Rule_12_5:
    * -  Rule 12.5
      -  Mandatory
      -  The sizeof operator shall not have an operand which is a function parameter declared as “array of type”
      -  N/A
      -  `Rule 12.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_12_05.c>`_

         .. _MisraC_Rule_13_1:
    * -  Rule 13.1
      -  Required
      -  Initializer lists shall not contain persistent side effects
      -  N/A
      -  | `Rule 13.1 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_01_1.c>`_
         | `Rule 13.1 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_01_2.c>`_

         .. _MisraC_Rule_13_2:
    * -  Rule 13.2
      -  Required
      -  The value of an expression and its persistent side effects shall be the same under all permitted evaluation orders
      -  N/A
      -  `Rule 13.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_02.c>`_

         .. _MisraC_Rule_13_3:
    * -  Rule 13.3
      -  Advisory
      -  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
      -  N/A
      -  `Rule 13.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_03.c>`_

         .. _MisraC_Rule_13_4:
    * -  Rule 13.4
      -  Advisory
      -  The result of an assignment operator should not be used
      -  N/A
      -  `Rule 13.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_04.c>`_

         .. _MisraC_Rule_13_5:
    * -  Rule 13.5
      -  Required
      -  The right hand operand of a logical && or || operator shall not contain persistent side effects
      -  `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>`_
      -  | `Rule 13.5 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_05_1.c>`_
         | `Rule 13.5 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_05_2.c>`_

         .. _MisraC_Rule_13_6:
    * -  Rule 13.6
      -  Mandatory
      -  The operand of the sizeof operator shall not contain any expression which has potential side effects
      -  N/A
      -  `Rule 13.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_13_06.c>`_

         .. _MisraC_Rule_14_1:
    * -  Rule 14.1
      -  Required
      -  A loop counter shall not have essentially floating type
      -  N/A
      -  `Rule 14.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_01.c>`_

         .. _MisraC_Rule_14_2:
    * -  Rule 14.2
      -  Required
      -  A for loop shall be well-formed
      -  N/A
      -  `Rule 14.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_02.c>`_

         .. _MisraC_Rule_14_3:
    * -  Rule 14.3
      -  Required
      -  Controlling expressions shall not be invariant
      -  N/A
      -  `Rule 14.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_03.c>`_

         .. _MisraC_Rule_14_4:
    * -  Rule 14.4
      -  Required
      -  The controlling expression of an if statement and the controlling expression of an iteration-statement shall have essentially Boolean type
      -  N/A
      -  `Rule 14.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_04.c>`_

         .. _MisraC_Rule_15_2:
    * -  Rule 15.2
      -  Required
      -  The goto statement shall jump to a label declared later in the same function
      -  N/A
      -  `Rule 15.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_02.c>`_

         .. _MisraC_Rule_15_3:
    * -  Rule 15.3
      -  Required
      -  Any label referenced by a goto statement shall be declared in the same block, or in any block enclosing the goto statement
      -  N/A
      -  `Rule 15.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_03.c>`_

         .. _MisraC_Rule_15_6:
    * -  Rule 15.6
      -  Required
      -  The body of an iteration-statement or a selection-statement shall be a compound-statement
      -  `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>`_
      -  `Rule 15.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_06.c>`_

         .. _MisraC_Rule_15_7:
    * -  Rule 15.7
      -  Required
      -  All if else if constructs shall be terminated with an else statement
      -  N/A
      -  `Rule 15.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_15_07.c>`_

         .. _MisraC_Rule_16_1:
    * -  Rule 16.1
      -  Required
      -  All switch statements shall be well-formed
      -  N/A
      -  `Rule 16.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_01.c>`_

         .. _MisraC_Rule_16_2:
    * -  Rule 16.2
      -  Required
      -  A switch label shall only be used when the most closely-enclosing compound statement is the body of a switch statement
      -  `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>`_
      -  `Rule 16.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_02.c>`_

         .. _MisraC_Rule_16_3:
    * -  Rule 16.3
      -  Required
      -  An unconditional break statement shall terminate every switch-clause
      -  N/A
      -  `Rule 16.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_03.c>`_

         .. _MisraC_Rule_16_4:
    * -  Rule 16.4
      -  Required
      -  Every switch statement shall have a default label
      -  N/A
      -  `Rule 16.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_04.c>`_

         .. _MisraC_Rule_16_5:
    * -  Rule 16.5
      -  Required
      -  A default label shall appear as either the first or the last switch label of a switch statement
      -  N/A
      -  `Rule 16.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_05.c>`_

         .. _MisraC_Rule_16_6:
    * -  Rule 16.6
      -  Required
      -  Every switch statement shall have at least two switch-clauses
      -  N/A
      -  `Rule 16.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_06.c>`_

         .. _MisraC_Rule_16_7:
    * -  Rule 16.7
      -  Required
      -  A switch-expression shall not have essentially Boolean type
      -  N/A
      -  `Rule 16.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_07.c>`_

         .. _MisraC_Rule_17_1:
    * -  Rule 17.1
      -  Required
      -  The features of <stdarg.h> shall not be used
      -  `ERR00-C <https://wiki.sei.cmu.edu/confluence/display/c/ERR00-C.+Adopt+and+implement+a+consistent+and+comprehensive+error-handling+policy>`_
      -  `Rule 17.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_01.c>`_

         .. _MisraC_Rule_17_2:
    * -  Rule 17.2
      -  Required
      -  Functions shall not call themselves, either directly or indirectly
      -  `MEM05-C <https://wiki.sei.cmu.edu/confluence/display/c/MEM05-C.+Avoid+large+stack+allocations>`_
      -  `Rule 17.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_02.c>`_

         .. _MisraC_Rule_17_3:
    * -  Rule 17.3
      -  Mandatory
      -  A function shall not be declared implicitly
      -  N/A
      -  `Rule 17.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_03.c>`_

         .. _MisraC_Rule_17_4:
    * -  Rule 17.4
      -  Mandatory
      -  All exit paths from a function with non-void return type shall have an explicit return statement with an expression
      -  N/A
      -  `Rule 17.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_04.c>`_

         .. _MisraC_Rule_17_5:
    * -  Rule 17.5
      -  Advisory
      -  The function argument corresponding to a parameter declared to have an array type shall have an appropriate number of elements
      -  N/A
      -  `Rule 17.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_05.c>`_

         .. _MisraC_Rule_17_6:
    * -  Rule 17.6
      -  Mandatory
      -  The declaration of an array parameter shall not contain the static keyword between the [ ]
      -  N/A
      -  `Rule 17.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_06.c>`_

         .. _MisraC_Rule_17_7:
    * -  Rule 17.7
      -  Required
      -  The value returned by a function having non-void return type shall be used
      -  N/A
      -  `Rule 17.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_17_07.c>`_

         .. _MisraC_Rule_18_1:
    * -  Rule 18.1
      -  Required
      -  A pointer resulting from arithmetic on a pointer operand shall address an element of the same array as that pointer operand
      -  `EXP08-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP08-C.+Ensure+pointer+arithmetic+is+used+correctly>`_
      -  `Rule 18.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_01.c>`_

         .. _MisraC_Rule_18_2:
    * -  Rule 18.2
      -  Required
      -  Subtraction between pointers shall only be applied to pointers that address elements of the same array
      -  `EXP08-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP08-C.+Ensure+pointer+arithmetic+is+used+correctly>`_
      -  `Rule 18.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_02.c>`_

         .. _MisraC_Rule_18_3:
    * -  Rule 18.3
      -  Required
      -  The relational operators >, >=, < and <= shall not be applied to objects of pointer type except where they point into the same object
      -  `EXP08-C <https://wiki.sei.cmu.edu/confluence/display/c/EXP08-C.+Ensure+pointer+arithmetic+is+used+correctly>`_
      -  `Rule 18.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_03.c>`_

         .. _MisraC_Rule_18_5:
    * -  Rule 18.5
      -  Advisory
      -  Declarations should contain no more than two levels of pointer nesting
      -  N/A
      -  `Rule 18.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_05.c>`_

         .. _MisraC_Rule_18_6:
    * -  Rule 18.6
      -  Required
      -  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
      -  N/A
      -  | `Rule 18.6 example 1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_06_1.c>`_
         | `Rule 18.6 example 2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_06_2.c>`_

         .. _MisraC_Rule_18_8:
    * -  Rule 18.8
      -  Required
      -  Variable-length array types shall not be used
      -  N/A
      -  `Rule 18.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_18_08.c>`_

         .. _MisraC_Rule_19_1:
    * -  Rule 19.1
      -  Mandatory
      -  An object shall not be assigned or copied to an overlapping object
      -  N/A
      -  `Rule 19.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_19_01.c>`_

         .. _MisraC_Rule_20_2:
    * -  Rule 20.2
      -  Required
      -  The ', or \ characters and the /* or // character sequences shall not occur in a header file name"
      -  N/A
      -  `Rule 20.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_02.c>`_

         .. _MisraC_Rule_20_3:
    * -  Rule 20.3
      -  Required
      -  The #include directive shall be followed by either a <filename> or "filename" sequence
      -  N/A
      -  `Rule 20.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_03.c>`_

         .. _MisraC_Rule_20_4:
    * -  Rule 20.4
      -  Required
      -  A macro shall not be defined with the same name as a keyword
      -  N/A
      -  `Rule 20.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_04.c>`_

         .. _MisraC_Rule_20_7:
    * -  Rule 20.7
      -  Required
      -  Expressions resulting from the expansion of macro parameters shall be enclosed in parentheses
      -  `PRE01-C <https://wiki.sei.cmu.edu/confluence/display/c/PRE01-C.+Use+parentheses+within+macros+around+parameter+names>`_
      -  `Rule 20.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_07.c>`_

         .. _MisraC_Rule_20_8:
    * -  Rule 20.8
      -  Required
      -  The controlling expression of a #if or #elif preprocessing directive shall evaluate to 0 or 1
      -  N/A
      -  `Rule 20.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_08.c>`_

         .. _MisraC_Rule_20_9:
    * -  Rule 20.9
      -  Required
      -  All identifiers used in the controlling expression of #if or #elif preprocessing directives shall be #defined before evaluation
      -  N/A
      -  `Rule 20.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_09.c>`_

         .. _MisraC_Rule_20_11:
    * -  Rule 20.11
      -  Required
      -  A macro parameter immediately following a # operator shall not immediately be followed by a ## operator
      -  N/A
      -  `Rule 20.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_11.c>`_

         .. _MisraC_Rule_20_12:
    * -  Rule 20.12
      -  Required
      -  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
      -  N/A
      -  `Rule 20.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_12.c>`_

         .. _MisraC_Rule_20_13:
    * -  Rule 20.13
      -  Required
      -  A line whose first token is # shall be a valid preprocessing directive
      -  N/A
      -  `Rule 20.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_13.c>`_

         .. _MisraC_Rule_20_14:
    * -  Rule 20.14
      -  Required
      -  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
      -  N/A
      -  `Rule 20.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_14.c>`_

         .. _MisraC_Rule_21_1:
    * -  Rule 21.1
      -  Required
      -  #define and #undef shall not be used on a reserved identifier or reserved macro name
      -  N/A
      -  `Rule 21.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_01.c>`_

         .. _MisraC_Rule_21_2:
    * -  Rule 21.2
      -  Required
      -  A reserved identifier or macro name shall not be declared
      -  N/A
      -  `Rule 21.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_02.c>`_

         .. _MisraC_Rule_21_3:
    * -  Rule 21.3
      -  Required
      -  The memory allocation and deallocation functions of <stdlib.h> shall not be used
      -  `MSC24-C <https://wiki.sei.cmu.edu/confluence/display/c/MSC24-C.+Do+not+use+deprecated+or+obsolescent+functions>`_
      -  `Rule 21.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_03.c>`_

         .. _MisraC_Rule_21_4:
    * -  Rule 21.4
      -  Required
      -  The standard header file <setjmp.h> shall not be used
      -  N/A
      -  `Rule 21.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_04.c>`_

         .. _MisraC_Rule_21_6:
    * -  Rule 21.6
      -  Required
      -  The Standard Library input/output functions shall not be used
      -  N/A
      -  `Rule 21.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_06.c>`_

         .. _MisraC_Rule_21_7:
    * -  Rule 21.7
      -  Required
      -  The atof, atoi, atol and atoll functions of <stdlib.h> shall not be used
      -  N/A
      -  `Rule 21.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_07.c>`_

         .. _MisraC_Rule_21_9:
    * -  Rule 21.9
      -  Required
      -  The library functions bsearch and qsort of <stdlib.h> shall not be used
      -  N/A
      -  `Rule 21.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_09.c>`_

         .. _MisraC_Rule_21_11:
    * -  Rule 21.11
      -  Required
      -  The standard header file <tgmath.h> shall not be used
      -  N/A
      -  `Rule 21.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_11.c>`_

         .. _MisraC_Rule_21_12:
    * -  Rule 21.12
      -  Advisory
      -  The exception handling features of <fenv.h> should not be used
      -  N/A
      -  `Rule 21.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_12.c>`_

         .. _MisraC_Rule_21_13:
    * -  Rule 21.13
      -  Mandatory
      -  Any value passed to a function in <ctype.h> shall be representable as an unsigned char or be the value EO
      -  N/A
      -  `Rule 21.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_13.c>`_

         .. _MisraC_Rule_21_14:
    * -  Rule 21.14
      -  Required
      -  The Standard Library function memcmp shall not be used to compare null terminated strings
      -  N/A
      -  `Rule 21.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_14.c>`_

         .. _MisraC_Rule_21_15:
    * -  Rule 21.15
      -  Required
      -  The pointer arguments to the Standard Library functions memcpy, memmove and memcmp shall be pointers to qualified or unqualified versions of compatible types
      -  N/A
      -  `Rule 21.15 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_15.c>`_

         .. _MisraC_Rule_21_16:
    * -  Rule 21.16
      -  Required
      -  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
      -  N/A
      -  `Rule 21.16 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_16.c>`_

         .. _MisraC_Rule_21_17:
    * -  Rule 21.17
      -  Mandatory
      -  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
      -  N/A
      -  `Rule 21.17 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_17.c>`_

         .. _MisraC_Rule_21_18:
    * -  Rule 21.18
      -  Mandatory
      -  The size_t argument passed to any function in <string.h> shall have an appropriate value
      -  N/A
      -  `Rule 21.18 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_18.c>`_

         .. _MisraC_Rule_21_19:
    * -  Rule 21.19
      -  Mandatory
      -  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
      -  N/A
      -  `Rule 21.19 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_19.c>`_

         .. _MisraC_Rule_21_20:
    * -  Rule 21.20
      -  Mandatory
      -  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
      -  N/A
      -  `Rule 21.20 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_21_20.c>`_

         .. _MisraC_Rule_22_1:
    * -  Rule 22.1
      -  Required
      -  All resources obtained dynamically by means of Standard Library functions shall be explicitly released
      -  N/A
      -  `Rule 22.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_01.c>`_

         .. _MisraC_Rule_22_2:
    * -  Rule 22.2
      -  Mandatory
      -  A block of memory shall only be freed if it was allocated by means of a Standard Library function
      -  N/A
      -  `Rule 22.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_02.c>`_

         .. _MisraC_Rule_22_3:
    * -  Rule 22.3
      -  Required
      -  The same file shall not be open for read and write access at the same time on different streams
      -  N/A
      -  `Rule 22.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_03.c>`_

         .. _MisraC_Rule_22_4:
    * -  Rule 22.4
      -  Mandatory
      -  There shall be no attempt to write to a stream which has been opened as read-only
      -  N/A
      -  `Rule 22.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_04.c>`_

         .. _MisraC_Rule_22_5:
    * -  Rule 22.5
      -  Mandatory
      -  A pointer to a FILE object shall not be dereferenced
      -  N/A
      -  `Rule 22.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_05.c>`_

         .. _MisraC_Rule_22_6:
    * -  Rule 22.6
      -  Mandatory
      -  The value of a pointer to a FILE shall not be used after the associated stream has been closed
      -  N/A
      -  `Rule 22.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_06.c>`_

         .. _MisraC_Rule_22_7:
    * -  Rule 22.7
      -  Required
      -  The macro EOF shall only be compared with the unmodified return value from any Standard Library function capable of returning EOF
      -  N/A
      -  `Rule 22.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_07.c>`_

         .. _MisraC_Rule_22_8:
    * -  Rule 22.8
      -  Required
      -  The value of errno shall be set to zero prior to a call to an errno-setting-function
      -  N/A
      -  `Rule 22.8 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_08.c>`_

         .. _MisraC_Rule_22_9:
    * -  Rule 22.9
      -  Required
      -  The value of errno shall be tested against zero after calling an errno-setting-function
      -  N/A
      -  `Rule 22.9 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_09.c>`_

         .. _MisraC_Rule_22_10:
    * -  Rule 22.10
      -  Required
      -  The value of errno shall only be tested when the last function to be called was an errno-setting-function
      -  N/A
      -  `Rule 22.10 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_10.c>`_

Additional rules
****************

Rule A.1: Conditional Compilation
=================================

Severity
--------

Required

Description
-----------

Do not conditionally compile function declarations in header files.  Do not
conditionally compile structure declarations in header files.  You may
conditionally exclude fields within structure definitions to avoid wasting
memory when the feature they support is not enabled.

Rationale
---------

Excluding declarations from the header based on compile-time options may prevent
their documentation from being generated. Their absence also prevents use of
``if (IS_ENABLED(CONFIG_FOO)) {}`` as an alternative to preprocessor
conditionals when the code path should change based on the selected options.

.. _coding_guideline_inclusive_language:

Rule A.2: Inclusive Language
============================

Severity
--------

Required

Description
-----------

Do not introduce new usage of offensive terms listed below. This rule applies
but is not limited to source code, comments, documentation, and branch names.
Replacement terms may vary by area or subsystem, but should aim to follow
updated industry standards when possible.

Exceptions are allowed for maintaining existing implementations or adding new
implementations of industry standard specifications governed externally to the
Zephyr Project.

Existing usage is recommended to change as soon as updated industry standard
specifications become available or new terms are publicly announced by the
governing body, or immediately if no specifications apply.

.. list-table::
   :header-rows: 1

   * - Offensive Terms
     - Recommended Replacements

   * - ``{master,leader} / slave``
     - - ``{primary,main} / {secondary,replica}``
       - ``{initiator,requester} / {target,responder}``
       - ``{controller,host} / {device,worker,proxy,target}``
       - ``director / performer``
       - ``central / peripheral``

   * - ``blacklist / whitelist``
     - * ``denylist / allowlist``
       * ``blocklist / allowlist``
       * ``rejectlist / acceptlist``

   * - ``grandfather policy``
     - * ``legacy``

   * - ``sanity``
     - * ``coherence``
       * ``confidence``


Rationale
---------

Offensive terms do not create an inclusive community environment and therefore
violate the Zephyr Project `Code of Conduct`_. This coding rule was inspired by
a similar rule in `Linux`_.

.. _Code of Conduct: https://github.com/zephyrproject-rtos/zephyr/blob/main/CODE_OF_CONDUCT.md
.. _Linux: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb

Status
------

Related GitHub Issues and Pull Requests are tagged with the `Inclusive Language Label`_.

.. list-table::
   :header-rows: 1

   * - Area
     - Selected Replacements
     - Status

   * - :ref:`bluetooth_api`
     - See `Bluetooth Appropriate Language Mapping Tables`_
     -

   * - CAN
     - This `CAN in Automation Inclusive Language news post`_ has a list of general
       recommendations. See `CAN in Automation Inclusive Language`_ for terms to
       be used in specification document updates.
     -

   * - eSPI
     - * ``master / slave`` => TBD
     -

   * - gPTP
     - * ``master / slave`` => TBD
     -

   * - :ref:`i2c_api`
     - * ``master / slave`` => TBD
     - NXP publishes the `I2C Specification`_ and has selected ``controller /
       target`` as replacement terms, but the timing to publish an announcement
       or new specification is TBD. Zephyr will update I2C when replacement
       terminology is confirmed by a public announcement or updated
       specification.

       See :github:`Zephyr issue 27033 <27033>`.

   * - :ref:`i2s_api`
     - * ``master / slave`` => TBD
     -

   * - SMP/AMP
     - * ``master / slave`` => TBD
     -

   * - :ref:`spi_api`
     - * ``master / slave`` => ``controller / peripheral``
       * ``MOSI / MISO / SS`` => ``SDO / SDI / CS``
     - The Open Source Hardware Association has selected these replacement
       terms. See `OSHWA Resolution to Redefine SPI Signal Names`_

   * - :ref:`twister_script`
     - * ``platform_whitelist`` => ``platform_allow``
       * ``sanitycheck`` => ``twister``
     -

.. _Inclusive Language Label: https://github.com/zephyrproject-rtos/zephyr/issues?q=label%3A%22Inclusive+Language%22
.. _I2C Specification: https://www.nxp.com/docs/en/user-guide/UM10204.pdf
.. _Bluetooth Appropriate Language Mapping Tables: https://specificationrefs.bluetooth.com/language-mapping/Appropriate_Language_Mapping_Table.pdf
.. _OSHWA Resolution to Redefine SPI Signal Names: https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names/
.. _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
.. _CAN in Automation Inclusive Language: https://can-newsletter.org/canopen/categories/


Rule A.3: Macro name collisions
===============================

Severity
--------

Required

Description
-----------

Macros with commonly used names such as  ``MIN``, ``MAX``, ``ARRAY_SIZE``, must
not be modified or protected to avoid name collisions with other
implementations. In particular, they must not be prefixed to place them in a
Zephyr-specific namespace, re-defined using ``#undef``, or conditionally
excluded from compilation using ``#ifndef``.  Instead, if a conflict arises with
an existing definition originating from a :ref:`module <modules>`, the module's
code itself needs to be modified (ideally upstream, alternatively via a change
in Zephyr's own fork).
This rule applies to Zephyr as a project in general, regardless of the time of
introduction of the macro or its current name in the tree. If a macro name is
commonly used in several other well-known open source projects then the
implementation in Zephyr should use that name. While there is a subjective and
non-measurable component to what "commonly used" means, the ultimate goal is
to offer users familiar macros.
Finally, this rule applies to inter-module name collisions as well: in that case
both modules, prior to their inclusion, should be modified to use
module-specific versions of the macro name that collides.

Rationale
---------

Zephyr is an RTOS that comes with additional functionality and dependencies in
the form of modules. Those modules are typically independent projects that may
use macro names that can conflict with other modules or with Zephyr itself.
Since, in the context of this documentation, Zephyr is considered the central or
main project, it should implement the non-namespaced versions of the
macros. Given that Zephyr uses a fork of the corresponding upstream for each
module, it is always possible to patch the macro implementation in each module
to avoid collisions.

.. _coding_guideline_libc_usage_restrictions_in_zephyr_kernel:

Rule A.4: C Standard Library Usage Restrictions in Zephyr Kernel
================================================================

Severity
--------

Required

Description
-----------

The use of the C standard library functions and macros in the Zephyr kernel
shall be limited to the following functions and macros from the ISO/IEC
9899:2011 standard, also known as C11, and their extensions:

.. csv-table:: List of allowed libc functions and macros in the Zephyr kernel
   :header: Function,Source
   :widths: auto

   abort(),ISO/IEC 9899:2011
   abs(),ISO/IEC 9899:2011
   aligned_alloc(),ISO/IEC 9899:2011
   assert(),ISO/IEC 9899:2011
   atoi(),ISO/IEC 9899:2011
   bsearch(),ISO/IEC 9899:2011
   calloc(),ISO/IEC 9899:2011
   exit(),ISO/IEC 9899:2011
   fprintf(),ISO/IEC 9899:2011
   fputc(),ISO/IEC 9899:2011
   fputs(),ISO/IEC 9899:2011
   free(),ISO/IEC 9899:2011
   fwrite(),ISO/IEC 9899:2011
   gmtime(),ISO/IEC 9899:2011
   isalnum(),ISO/IEC 9899:2011
   isalpha(),ISO/IEC 9899:2011
   iscntrl(),ISO/IEC 9899:2011
   isdigit(),ISO/IEC 9899:2011
   isgraph(),ISO/IEC 9899:2011
   isprint(),ISO/IEC 9899:2011
   isspace(),ISO/IEC 9899:2011
   isupper(),ISO/IEC 9899:2011
   isxdigit(),ISO/IEC 9899:2011
   labs(),ISO/IEC 9899:2011
   llabs(),ISO/IEC 9899:2011
   malloc(),ISO/IEC 9899:2011
   memchr(),ISO/IEC 9899:2011
   memcmp(),ISO/IEC 9899:2011
   memcpy(),ISO/IEC 9899:2011
   memmove(),ISO/IEC 9899:2011
   memset(),ISO/IEC 9899:2011
   perror(),ISO/IEC 9899:2011
   printf(),ISO/IEC 9899:2011
   putc(),ISO/IEC 9899:2011
   putchar(),ISO/IEC 9899:2011
   puts(),ISO/IEC 9899:2011
   qsort(),ISO/IEC 9899:2011
   rand(),ISO/IEC 9899:2011
   realloc(),ISO/IEC 9899:2011
   snprintf(),ISO/IEC 9899:2011
   sprintf(),ISO/IEC 9899:2011
   sqrt(),ISO/IEC 9899:2011
   sqrtf(),ISO/IEC 9899:2011
   srand(),ISO/IEC 9899:2011
   strcat(),ISO/IEC 9899:2011
   strchr(),ISO/IEC 9899:2011
   strcmp(),ISO/IEC 9899:2011
   strcpy(),ISO/IEC 9899:2011
   strcspn(),ISO/IEC 9899:2011
   strerror(),ISO/IEC 9899:2011
   strlen(),ISO/IEC 9899:2011
   strncat(),ISO/IEC 9899:2011
   strncmp(),ISO/IEC 9899:2011
   strncpy(),ISO/IEC 9899:2011
   `strnlen()`_,POSIX.1-2008
   strrchr(),ISO/IEC 9899:2011
   strspn(),ISO/IEC 9899:2011
   strstr(),ISO/IEC 9899:2011
   strtol(),ISO/IEC 9899:2011
   strtoll(),ISO/IEC 9899:2011
   strtoul(),ISO/IEC 9899:2011
   strtoull(),ISO/IEC 9899:2011
   time(),ISO/IEC 9899:2011
   tolower(),ISO/IEC 9899:2011
   toupper(),ISO/IEC 9899:2011
   vfprintf(),ISO/IEC 9899:2011
   vprintf(),ISO/IEC 9899:2011
   vsnprintf(),ISO/IEC 9899:2011
   vsprintf(),ISO/IEC 9899:2011

All of the functions listed above must be implemented by the
:ref:`minimal libc <c_library_minimal>` to ensure that the Zephyr kernel can
build with the minimal libc.

In addition, any functions from the above list that are not part of the
ISO/IEC 9899:2011 standard must be implemented by the
:ref:`common libc <c_library_common>` to ensure their availability across
multiple C standard libraries.

Introducing new C standard library functions to the Zephyr kernel is allowed
with justification given that the above requirements are satisfied.

Note that the use of the functions listed above are subject to secure and safe
coding practices and it should not be assumed that their use in the Zephyr
kernel is unconditionally permitted by being listed in this rule.

The "Zephyr kernel" in this context consists of the following components:

* Kernel (:file:`kernel`)
* OS Library (:file:`lib/os`)
* Architecture Port (:file:`arch`)
* Logging Subsystem (:file:`subsys/logging`)

Rationale
---------

Zephyr kernel must be able to build with the
:ref:`minimal libc <c_library_minimal>`, a limited C standard library
implementation that is part of the Zephyr RTOS and maintained by the Zephyr
Project, to allow self-contained testing and verification of the kernel and
core OS services.

In order to ensure that the Zephyr kernel can build with the minimal libc, it
is necessary to restrict the use of the C standard library functions and macros
in the Zephyr kernel to the functions and macros that are available as part of
the minimal libc.

Rule A.5: C Standard Library Usage Restrictions in Zephyr Codebase
==================================================================

Severity
--------

Required

Description
-----------

The use of the C standard library functions and macros in the Zephyr codebase
shall be limited to the functions, excluding the Annex K "Bounds-checking
interfaces", from the ISO/IEC 9899:2011 standard, also known as C11, unless
exempted by this rule.

The "Zephyr codebase" in this context refers to all embedded source code files committed
to the `main Zephyr repository`_, except the Zephyr kernel as defined by the
:ref:`coding_guideline_libc_usage_restrictions_in_zephyr_kernel`.
With embedded source code we refer to code which is meant to be executed in embedded
targets, and therefore excludes host tooling, and code specific for the
:ref:`native <boards_posix>` test targets.

The following non-ISO 9899:2011, hereinafter referred to as non-standard,
functions and macros are exempt from this rule and allowed to be used in the
Zephyr codebase:

.. csv-table:: List of allowed non-standard libc functions
   :header: Function,Source
   :widths: auto

   `gmtime_r()`_,POSIX.1-2001
   `strnlen()`_,POSIX.1-2008
   `strtok_r()`_,POSIX.1-2001

All non-standard functions and macros listed above must be implemented by the
:ref:`common libc <c_library_common>` in order to make sure that these
functions can be made available when using a C standard library that does not
implement these functions.

Adding a new non-standard function from common C standard libraries to the
above list is allowed with justification, given that the above requirement is
satisfied. However, when there exists a standard function that is functionally
equivalent, the standard function shall be used.

Rationale
---------

Some C standard libraries, such as Newlib and Picolibc, include additional
functions and macros that are defined by the standards and de-facto standards
that extend the ISO C standard (e.g. POSIX, Linux).

The ISO/IEC 9899:2011 standard does not require C compiler toolchains to
include the support for these non-standard functions, and therefore using
these functions can lead to compatibility issues with the third-party
toolchains that come with their own C standard libraries.

.. _main Zephyr repository: https://github.com/zephyrproject-rtos/zephyr
.. _gmtime_r(): https://pubs.opengroup.org/onlinepubs/9699919799/functions/gmtime_r.html
.. _strnlen(): https://pubs.opengroup.org/onlinepubs/9699919799/functions/strlen.html
.. _strtok_r(): https://pubs.opengroup.org/onlinepubs/9699919799/functions/strtok.html