Skip to contentSkip to conversation

docs/misra: new rules addition

PATCH Superseded Stefano Stabellini 2 participants 3 messages Jun 14, 2023 – Jun 15, 2023

v4 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v4 1/1 docs/misra: new rules addition

From: Stefano Stabellini <[email protected]>

For Dir 1.1, a document describing all implementation-defined behaviour (i.e. gcc-specific behavior) will be added to docs/misra, also including implementation-specific (gcc-specific) appropriate types for bit-field relevant to Rule 6.1.

Rule 21.21 is lacking an example on gitlab but the rule is
straightforward: we don't use stdlib at all in Xen.

---
Changes in v4:
- improve wording of the note in 6.1

Changes in v3:
- add all signed integer types to the Notes of 6.1
- clarify 7.2 in the Notes
- not added: marking "inapplicable" rules, to be a separate patch

Changes in v2:
- drop 5.6
- specify additional appropriate types for 6.1

---
 docs/misra/rules.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
docs/misra/rules.rst +50 -0
index d5a6ee8cb6..41a727ca98 100644
@@ -40,6 +40,12 @@ existing codebase are work-in-progress.
      - Summary
      - Notes
 
+   * - `Dir 1.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_01_01.c>`_
+     - Required
+     - Any implementation-defined behaviour on which the output of the
+       program depends shall be documented and understood
+     -
+
    * - `Dir 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_
      - Required
      - All source files shall compile without any compilation errors
@@ -57,6 +63,13 @@ existing codebase are work-in-progress.
        header file being included more than once
      -
 
+   * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
+     - Required
+     - The validity of values passed to library functions shall be checked
+     - We do not have libraries in Xen (libfdt and others are not
+       considered libraries from MISRA C point of view as they are
+       imported in source form)
+
    * - `Dir 4.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_14.c>`_
      - Required
      - The validity of values received from external sources shall be
@@ -133,6 +146,12 @@ existing codebase are work-in-progress.
        headers (xen/include/public/) are allowed to retain longer
        identifiers for backward compatibility.
 
+   * - `Rule 6.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_01.c>`_
+     - Required
+     - Bit-fields shall only be declared with an appropriate type
+     - In addition to the C99 types, we also consider appropriate types
+       enum and all explicitly signed / unsigned integer types.
+
    * - `Rule 6.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_02.c>`_
      - Required
      - Single-bit named bit fields shall not be of a signed type
@@ -143,6 +162,32 @@ existing codebase are work-in-progress.
      - Octal constants shall not be used
      -
 
+   * - `Rule 7.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_02.c>`_
+     - Required
+     - A "u" or "U" suffix shall be applied to all integer constants
+       that are represented in an unsigned type
+     - The rule asks that any integer literal that is implicitly
+       unsigned is made explicitly unsigned by using one of the
+       indicated suffixes.  As an example, on a machine where the int
+       type is 32-bit wide, 0x77777777 is signed whereas 0x80000000 is
+       (implicitly) unsigned. In order to comply with the rule, the
+       latter should be rewritten as either 0x80000000u or 0x80000000U.
+       Consistency considerations may suggest using the same suffix even
+       when not required by the rule. For instance, if one has:
+
+       Original: f(0x77777777); f(0x80000000);
+
+       one might prefer
+
+       Solution 1: f(0x77777777U); f(0x80000000U);
+
+       over
+
+       Solution 2: f(0x77777777); f(0x80000000U);
+
+       after having ascertained that "Solution 1" is compatible with the
+       intended semantics.
+
    * - `Rule 7.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_03.c>`_
      - Required
      - The lowercase character l shall not be used in a literal suffix
@@ -314,6 +359,11 @@ existing codebase are work-in-progress.
        used following a subsequent call to the same function
      -
 
+   * - Rule 21.21
+     - Required
+     - The Standard Library function system of <stdlib.h> shall not be used
+     -
+
    * - `Rule 22.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_22_02.c>`_
      - Mandatory
      - A block of memory shall only be freed if it was allocated by means of a
Signature · 1 line
2.25.1
Reviewed-by on v4 1/1
#1 lore raw

Hi Stefano,

Quoted 83 lines · Stefano Stabellini

From: Stefano Stabellini <[email protected]>

For Dir 1.1, a document describing all implementation-defined behaviour (i.e. gcc-specific behavior) will be added to docs/misra, also including implementation-specific (gcc-specific) appropriate types for bit-field relevant to Rule 6.1.

Rule 21.21 is lacking an example on gitlab but the rule is
straightforward: we don't use stdlib at all in Xen.

---
Changes in v4:
- improve wording of the note in 6.1

Changes in v3:
- add all signed integer types to the Notes of 6.1
- clarify 7.2 in the Notes
- not added: marking "inapplicable" rules, to be a separate patch

Changes in v2:
- drop 5.6
- specify additional appropriate types for 6.1

---
 docs/misra/rules.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
docs/misra/rules.rst +25 -0
index d5a6ee8cb6..41a727ca98 100644
@@ -40,6 +40,12 @@ existing codebase are work-in-progress.
      - Summary
      - Notes
 
+   * - `Dir 1.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_01_01.c>`_
+     - Required
+     - Any implementation-defined behaviour on which the output of the
+       program depends shall be documented and understood
+     -
+
    * - `Dir 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_
      - Required
      - All source files shall compile without any compilation errors
@@ -57,6 +63,13 @@ existing codebase are work-in-progress.
        header file being included more than once
      -
 
+   * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
+     - Required
+     - The validity of values passed to library functions shall be checked
+     - We do not have libraries in Xen (libfdt and others are not
+       considered libraries from MISRA C point of view as they are
+       imported in source form)
+
    * - `Dir 4.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_14.c>`_
      - Required
      - The validity of values received from external sources shall be
@@ -133,6 +146,12 @@ existing codebase are work-in-progress.
        headers (xen/include/public/) are allowed to retain longer
        identifiers for backward compatibility.
 
+   * - `Rule 6.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_01.c>`_
+     - Required
+     - Bit-fields shall only be declared with an appropriate type
+     - In addition to the C99 types, we also consider appropriate types
+       enum and all explicitly signed / unsigned integer types.
+
    * - `Rule 6.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_02.c>`_
      - Required
      - Single-bit named bit fields shall not be of a signed type
@@ -143,6 +162,32 @@ existing codebase are work-in-progress.
      - Octal constants shall not be used
      -
 
+   * - `Rule 7.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_02.c>`_
+     - Required
+     - A "u" or "U" suffix shall be applied to all integer constants
+       that are represented in an unsigned type
+     - The rule asks that any integer literal that is implicitly
+       unsigned is made explicitly unsigned by using one of the

docs/misra/rules.rst existing codebase are work-in-progress. · line 180

Quoted 10 lines
docs/misra/rules.rst +10 -0
+       indicated suffixes.  As an example, on a machine where the int
+       type is 32-bit wide, 0x77777777 is signed whereas 0x80000000 is
+       (implicitly) unsigned. In order to comply with the rule, the
+       latter should be rewritten as either 0x80000000u or 0x80000000U.
+       Consistency considerations may suggest using the same suffix even
+       when not required by the rule. For instance, if one has:
+
+       Original: f(0x77777777); f(0x80000000);
+
+       one might prefer

Shouldn't this be "one should do" in reference to Jan remark?

Quoted 14 lines
docs/misra/rules.rst +10 -0
+
+       Solution 1: f(0x77777777U); f(0x80000000U);
+
+       over
+
+       Solution 2: f(0x77777777); f(0x80000000U);
+
+       after having ascertained that "Solution 1" is compatible with the
+       intended semantics.
+
    * - `Rule 7.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_03.c>`_
      - Required
      - The lowercase character l shall not be used in a literal suffix

docs/misra/rules.rst existing codebase are work-in-progress. · line 362

Quoted 4 lines
docs/misra/rules.rst +1 -0
@@ -314,6 +359,11 @@ existing codebase are work-in-progress.
        used following a subsequent call to the same function
      -
 
+   * - Rule 21.21

This is incorrect as it should be surrounded by `` similar to other lines.
Otherwise it will not be taken into account by convert_misra_doc.py which converts this document into cppcheck rule list.

With that fixed (i.e. on commit):

~Michal

#2 lore raw
Quoted 89 lines · Michal Orzel

Hi Stefano,

Quoted 86 lines · Stefano Stabellini

From: Stefano Stabellini <[email protected]>

For Dir 1.1, a document describing all implementation-defined behaviour (i.e. gcc-specific behavior) will be added to docs/misra, also including implementation-specific (gcc-specific) appropriate types for bit-field relevant to Rule 6.1.

Rule 21.21 is lacking an example on gitlab but the rule is
straightforward: we don't use stdlib at all in Xen.

---
Changes in v4:
- improve wording of the note in 6.1

Changes in v3:
- add all signed integer types to the Notes of 6.1
- clarify 7.2 in the Notes
- not added: marking "inapplicable" rules, to be a separate patch

Changes in v2:
- drop 5.6
- specify additional appropriate types for 6.1

---
 docs/misra/rules.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
docs/misra/rules.rst +28 -0
index d5a6ee8cb6..41a727ca98 100644
@@ -40,6 +40,12 @@ existing codebase are work-in-progress.
      - Summary
      - Notes
 
+   * - `Dir 1.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_01_01.c>`_
+     - Required
+     - Any implementation-defined behaviour on which the output of the
+       program depends shall be documented and understood
+     -
+
    * - `Dir 2.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_02_01.c>`_
      - Required
      - All source files shall compile without any compilation errors
@@ -57,6 +63,13 @@ existing codebase are work-in-progress.
        header file being included more than once
      -
 
+   * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
+     - Required
+     - The validity of values passed to library functions shall be checked
+     - We do not have libraries in Xen (libfdt and others are not
+       considered libraries from MISRA C point of view as they are
+       imported in source form)
+
    * - `Dir 4.14 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_14.c>`_
      - Required
      - The validity of values received from external sources shall be
@@ -133,6 +146,12 @@ existing codebase are work-in-progress.
        headers (xen/include/public/) are allowed to retain longer
        identifiers for backward compatibility.
 
+   * - `Rule 6.1 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_01.c>`_
+     - Required
+     - Bit-fields shall only be declared with an appropriate type
+     - In addition to the C99 types, we also consider appropriate types
+       enum and all explicitly signed / unsigned integer types.
+
    * - `Rule 6.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_06_02.c>`_
      - Required
      - Single-bit named bit fields shall not be of a signed type
@@ -143,6 +162,32 @@ existing codebase are work-in-progress.
      - Octal constants shall not be used
      -
 
+   * - `Rule 7.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_02.c>`_
+     - Required
+     - A "u" or "U" suffix shall be applied to all integer constants
+       that are represented in an unsigned type
+     - The rule asks that any integer literal that is implicitly
+       unsigned is made explicitly unsigned by using one of the
+       indicated suffixes.  As an example, on a machine where the int
+       type is 32-bit wide, 0x77777777 is signed whereas 0x80000000 is
+       (implicitly) unsigned. In order to comply with the rule, the
Quoted 8 lines

docs/misra/rules.rst existing codebase are work-in-progress. · line 180

Quoted 7 lines
docs/misra/rules.rst +7 -0
+       latter should be rewritten as either 0x80000000u or 0x80000000U.
+       Consistency considerations may suggest using the same suffix even
+       when not required by the rule. For instance, if one has:
+
+       Original: f(0x77777777); f(0x80000000);
+
+       one might prefer

Shouldn't this be "one should do" in reference to Jan remark?

Yes OK

Quoted 17 lines
Quoted 17 lines
docs/misra/rules.rst +10 -0
+
+       Solution 1: f(0x77777777U); f(0x80000000U);
+
+       over
+
+       Solution 2: f(0x77777777); f(0x80000000U);
+
+       after having ascertained that "Solution 1" is compatible with the
+       intended semantics.
+
    * - `Rule 7.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_07_03.c>`_
      - Required
      - The lowercase character l shall not be used in a literal suffix
@@ -314,6 +359,11 @@ existing codebase are work-in-progress.
        used following a subsequent call to the same function
      -
 
Quoted 3 lines

docs/misra/rules.rst existing codebase are work-in-progress. · line 362

Quoted 1 line
docs/misra/rules.rst +1 -0
+   * - Rule 21.21

This is incorrect as it should be surrounded by `` similar to other lines.
Otherwise it will not be taken into account by convert_misra_doc.py which converts this document into cppcheck rule list.

As there is no example for 21.21 yet, I'll link the base directory with all the examples:
https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/

Quoted 2 lines

With that fixed (i.e. on commit):

Thanks, I'll add