Skip to contentSkip to conversation

docs/misra: add exceptions to rules

PATCH In review Stefano Stabellini 3 participants 8 messages Aug 22, 2023

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/1 docs/misra: add exceptions to rules

From: Stefano Stabellini <[email protected]>

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.

---
v2:
- remove autogenerated from D4.10
- remove R2.1
- remove R5.6
- remove R7.1
- reword R8.3

---
 docs/misra/rules.rst | 36 +++++++++++++++++++++++++++++-------
 1 file changed, 29 insertions(+), 7 deletions(-)
docs/misra/rules.rst +11 -5
index 8f0e4d3f25..62bd4620fd 100644
@@ -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
 
    * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
      - Required
@@ -117,7 +131,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
@@ -239,13 +256,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 maybe be deliberately used and defined as int or
+       long depending on the type of guest to service
 
    * - `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 +389,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
Signature · 1 line
2.25.1
Acked-by on v2 1/1
#1 lore raw
Quoted 3 lines · Stefano Stabellini

From: Stefano Stabellini <[email protected]>

During the discussions that led to the acceptable of the Rules, we

Nit: acceptance

Quoted 14 lines

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.

docs/misra/rules.rst +1 -1
@@ -239,13 +256,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 maybe be deliberately used and defined as int or

docs/misra/rules.rst maintainers if you want to suggest a change. · line 268

Quoted 10 lines
docs/misra/rules.rst +4 -1
+       long depending on the type of guest to service
 
    * - `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)

Doesn't this want to be

- Allowed exceptions: asm-offsets.c, definitions for asm modules not called from C code, and gcov_base.c (definitions only used in non-release builds)

? As to coverage: Why "only used in non-release builds"? COVERAGE doesn't depend on DEBUG, and people may actually want to enable it for release builds. Just likely not for production ones.

If you agree with and make respective adjustments:

Jan

#3 lore raw
In reply to Stefano Stabellini

Hi Stefano,

Quoted 26 lines · Stefano Stabellini

From: Stefano Stabellini <[email protected]>

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.

---
v2:
- remove autogenerated from D4.10
- remove R2.1
- remove R5.6
- remove R7.1
- reword R8.3

---
  docs/misra/rules.rst | 36 +++++++++++++++++++++++++++++-------
  1 file changed, 29 insertions(+), 7 deletions(-)
docs/misra/rules.rst +0 -0
index 8f0e4d3f25..62bd4620fd 100644

docs/misra/rules.rst maintainers if you want to suggest a change. · line 62

Quoted 4 lines
docs/misra/rules.rst +0 -1
@@ -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
-     -

It is not clear to me why this line is removed. Was it added by mistake in a previous commit?

Quoted 44 lines
docs/misra/rules.rst +11 -4
+     - Files that are intended to be included more than once do not need to
+       conform to the directive
 
     * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
       - Required
@@ -117,7 +131,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
@@ -239,13 +256,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 maybe be deliberately used and defined as int or
+       long depending on the type of guest to service
 
     * - `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 +389,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
Signature · 1 line
Julien Grall
#4 lore raw
Quoted 11 lines · Julien Grall

docs/misra/rules.rst maintainers if you want to suggest a change. · line 62

Quoted 7 lines · Stefano Stabellini
docs/misra/rules.rst +0 -1
@@ -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
-     -

It is not clear to me why this line is removed. Was it added by mistake in a previous commit?

The patch is replacing an empty comment ...

Quoted 2 lines

docs/misra/rules.rst maintainers if you want to suggest a change. · line 63

Quoted 2 lines
docs/misra/rules.rst +2 -0
+     - Files that are intended to be included more than once do not need to
+       conform to the directive

... with a non-empty one.

Jan

#5 lore raw

Hi Jan,

Quoted 13 lines · Jan Beulich
Quoted 11 lines · Julien Grall

docs/misra/rules.rst maintainers if you want to suggest a change. · line 62

Quoted 7 lines · Stefano Stabellini
docs/misra/rules.rst +0 -1
@@ -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
-     -

It is not clear to me why this line is removed. Was it added by mistake in a previous commit?

Quoted 6 lines

The patch is replacing an empty comment ...

Quoted 2 lines

docs/misra/rules.rst maintainers if you want to suggest a change. · line 63

Quoted 2 lines
docs/misra/rules.rst +2 -0
+     - Files that are intended to be included more than once do not need to
+       conform to the directive

... with a non-empty one.

I understand that... My question is more related to why we originally added one? If this was done on purpose, then why are we removing it?

Cheers,

Signature · 1 line
Julien Grall
#6 lore raw
Quoted 18 lines · Julien Grall

Hi Jan,

Quoted 15 lines · Jan Beulich
Quoted 11 lines · Julien Grall

docs/misra/rules.rst maintainers if you want to suggest a change. · line 62

Quoted 7 lines · Stefano Stabellini
docs/misra/rules.rst +0 -1
@@ -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
-     -

It is not clear to me why this line is removed. Was it added by mistake in a previous commit?

The patch is replacing an empty comment ...

Quoted 7 lines
Quoted 4 lines
Quoted 2 lines

docs/misra/rules.rst maintainers if you want to suggest a change. · line 63

Quoted 2 lines
docs/misra/rules.rst +2 -0
+     - Files that are intended to be included more than once do not need to
+       conform to the directive

... with a non-empty one.

I understand that... My question is more related to why we originally added one? If this was done on purpose, then why are we removing it?

I think the goal is for the file to be easily machine readable, and hence the same number of sub-items want to appear for every main item.

Jan

#7 lore raw
Quoted 22 lines · Jan Beulich
Quoted 21 lines · Julien Grall

Hi Jan,

Quoted 18 lines · Jan Beulich
Quoted 11 lines · Julien Grall

docs/misra/rules.rst maintainers if you want to suggest a change. · line 62

Quoted 7 lines · Stefano Stabellini
docs/misra/rules.rst +0 -1
@@ -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
-     -

It is not clear to me why this line is removed. Was it added by mistake in a previous commit?

The patch is replacing an empty comment ...

Quoted 2 lines
Quoted 2 lines
docs/misra/rules.rst +2 -0
+     - Files that are intended to be included more than once do not need to
+       conform to the directive
Quoted 7 lines
Quoted 4 lines
Quoted 1 line

... with a non-empty one.

I understand that... My question is more related to why we originally added one? If this was done on purpose, then why are we removing it?

I think the goal is for the file to be easily machine readable, and hence the same number of sub-items want to appear for every main item.

Yes, it is to respect the RST table format so that gets rendered as a table in HTML/PDF/etc.

#2 lore raw
In reply to Jan Beulich
Quoted 38 lines · Jan Beulich
Quoted 3 lines · Stefano Stabellini

From: Stefano Stabellini <[email protected]>

During the discussions that led to the acceptable of the Rules, we

Nit: acceptance

Quoted 14 lines

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.

docs/misra/rules.rst +1 -1
@@ -239,13 +256,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 maybe be deliberately used and defined as int or

docs/misra/rules.rst maintainers if you want to suggest a change. · line 268

Quoted 10 lines
docs/misra/rules.rst +4 -1
+       long depending on the type of guest to service
 
    * - `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)

Doesn't this want to be

- Allowed exceptions: asm-offsets.c, definitions for asm modules not called from C code, and gcov_base.c (definitions only used in non-release builds)

Quoted 6 lines

? As to coverage: Why "only used in non-release builds"? COVERAGE doesn't depend on DEBUG, and people may actually want to enable it for release builds. Just likely not for production ones.

If you agree with and make respective adjustments:

Yes I agree to the changes and I made them on commit