[PATCH] docs/misra: add exceptions to rules

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

From: Stefano Stabellini <stefano.stabellini@xxxxxxx>

During the discussions that led to the acceptable of the Rules, we
decided on a few exceptions that were not properly recorded in
rules.rst. Other times, the exceptions were decided later when it came
to enabling a rule in ECLAIR.

Either way, update rules.rst with appropriate notes.

Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxx>
---
Note that there might be more to add, but the below look correct to me
---
 docs/misra/rules.rst | 41 +++++++++++++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index 8f0e4d3f25..ecbb04da96 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -59,7 +59,8 @@ maintainers if you want to suggest a change.
      - Required
      - Precautions shall be taken in order to prevent the contents of a
        header file being included more than once
-     -
+     - Files that are intended to be included more than once do not need to
+       conform to the directive (e.g. autogenerated or empty header files)
 
    * - `Dir 4.11 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
      - Required
@@ -106,7 +107,23 @@ maintainers if you want to suggest a change.
    * - `Rule 2.1 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_01_1.c>`_
      - Required
      - A project shall not contain unreachable code
-     -
+     - The following are allowed:
+         - Invariantly constant conditions (e.g. while(0) { S; })
+         - Switch with a controlling value incompatible with labeled
+           statements
+         - Functions that are intended to be never referenced from C
+           code, or are referenced in builds not under analysis (e.g.
+           'do_trap_fiq' for the former and 'check_for_unexpected_msi'
+           for the latter)
+         - Unreachability caused by the following macros/functions is
+           deliberate: BUG, assert_failed, ERROR_EXIT, ERROR_EXIT_DOM,
+           PIN_FAIL, __builtin_unreachable, panic, do_unexpected_trap,
+           machine_halt, machine_restart, machine_reboot,
+           ASSERT_UNREACHABLE
+         - asm-offsets.c, as they are not linked deliberately, because
+           they are used to generate definitions for asm modules
+         - pure declarations (i.e. declarations without
+           initialization) are safe, as they are not executed
 
    * - `Rule 2.6 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_02_06.c>`_
      - Advisory
@@ -117,7 +134,7 @@ maintainers if you want to suggest a change.
      - Required
      - The character sequences /* and // shall not be used within a
        comment
-     -
+     - Comments containing hyperlinks inside C-style block comments are safe
 
    * - `Rule 3.2 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_02.c>`_
      - Required
@@ -167,7 +184,7 @@ maintainers if you want to suggest a change.
    * - `Rule 5.6 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_06.c>`_
      - Required
      - A typedef name shall be a unique identifier
-     -
+     - BOOLEAN, UINT{8,32,64} and INT{8,32,64} are allowed
 
    * - `Rule 6.1 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_01.c>`_
      - Required
@@ -183,7 +200,10 @@ maintainers if you want to suggest a change.
    * - `Rule 7.1 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_01.c>`_
      - Required
      - Octal constants shall not be used
-     -
+     - Usage of the following constants is safe, since they are given
+       as-is in the inflate algorithm specification and there is
+       therefore no risk of them being interpreted as decimal constants:
+       ^0(007|37|070|213|236|300|321|330|331|332|333|334|335|337|371)$
 
    * - `Rule 7.2 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_02.c>`_
      - Required
@@ -239,13 +259,16 @@ maintainers if you want to suggest a change.
      - Required
      - All declarations of an object or function shall use the same
        names and type qualifiers
-     -
+     - The type ret_t is deliberately used and defined as int or long
+       depending on the architecture
 
    * - `Rule 8.4 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_04.c>`_
      - Required
      - A compatible declaration shall be visible when an object or
        function with external linkage is defined
-     -
+     - Allowed exceptions: asm-offsets.c (definitions for asm modules
+       not called from C code), gcov_base.c (definitions only used in
+       non-release builds)
 
    * - `Rule 8.5 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_08_05_2.c>`_
      - Required
@@ -369,7 +392,9 @@ maintainers if you want to suggest a change.
      - Required
      - Expressions resulting from the expansion of macro parameters
        shall be enclosed in parentheses
-     -
+     - Extra parentheses are not required when macro parameters are used
+       as function arguments, as macro arguments, array indices, lhs in
+       assignments
 
    * - `Rule 20.13 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_13.c>`_
      - Required
-- 
2.25.1