[01/17] misra: add deviation for headers that explicitly avoid guards

Commit Message

Alessandro Zucchelli July 1, 2024, 11:10 a.m. UTC

From: Simone Ballarin <[e-mail]>

Some headers, under specific circumstances (documented in a comment at
the beginning of the file), explicitly avoid inclusion guards: the caller
is responsible for including them correctly.

These files are not supposed to comply with Directive 4.10:
"Precautions shall be taken in order to prevent the contents of a header
file being included more than once"

This patch adds deviation cooments for headers that avoid guards.

Signed-off-by: Simone Ballarin <[e-mail]>
Signed-off-by: Nicola Vetrini <[e-mail]>
Signed-off-by: Alessandro Zucchelli <[e-mail]>

---
Changes in v4:
- rebased against current staging tree
Changes in v3:
- fix inconsistent deviation ID
- change comment-based deviation text
Changes in v2:
- use the format introduced with doc/misra/safe.json instead of
  a generic text-based deviation
---
 docs/misra/safe.json                        | 8 ++++++++
 xen/include/public/arch-x86/cpufeatureset.h | 1 +
 xen/include/public/errno.h                  | 1 +
 3 files changed, 10 insertions(+)

Comments

Jan Beulich July 3, 2024, 12:46 p.m. UTC | #1

On 01.07.2024 13:10, Alessandro Zucchelli wrote:
> --- a/docs/misra/safe.json
> +++ b/docs/misra/safe.json
> @@ -68,6 +68,14 @@
>          },
>          {
>              "id": "SAF-8-safe",
> +            "analyser": {
> +                "eclair": "MC3R1.D4.10"
> +            },
> +            "name": "Dir 4.10: headers that leave it up to the caller to include them correctly",
> +            "text": "Headers that deliberatively avoid inclusion guards explicitly leaving responsibility to the caller are allowed."
> +        },
> +        {
> +            "id": "SAF-9-safe",
>              "analyser": {},
>              "name": "Sentinel",
>              "text": "Next ID to be used"

Patch 10 adds another entry here, targeted at headers which are intended to be
possible to include more than once. Both headers here also fit that criteria,
even if right now they aren't used that way (iirc). Do we really need two
SAF-* markers for effectively all the same kind of headers?

> --- a/xen/include/public/arch-x86/cpufeatureset.h
> +++ b/xen/include/public/arch-x86/cpufeatureset.h
> @@ -23,6 +23,7 @@
>   * their XEN_CPUFEATURE() being appropriate in the included context.
>   */
>  
> +/* SAF-8-safe omitted inclusion guard */
>  #ifndef XEN_CPUFEATURE
>  
>  /*
> diff --git a/xen/include/public/errno.h b/xen/include/public/errno.h
> index 5a78a7607c..ccd5023c3a 100644
> --- a/xen/include/public/errno.h
> +++ b/xen/include/public/errno.h
> @@ -17,6 +17,7 @@
>   * will unilaterally #undef XEN_ERRNO().
>   */
>  
> +/* SAF-8-safe omitted inclusion guard */
>  #ifndef XEN_ERRNO
>  
>  /*

Further both of these headers have guards (to cover the default case), so
"omitted" certainly isn't correct. Much like the "name" line in the SAF
entry also isn't quite correct, as in the common case it's not left to
the use sites.

Jan

Patch

diff --git a/docs/misra/safe.json b/docs/misra/safe.json
index 3f18ef401c..b865caac73 100644
--- a/docs/misra/safe.json
+++ b/docs/misra/safe.json
@@ -68,6 +68,14 @@ 
         },
         {
             "id": "SAF-8-safe",
+            "analyser": {
+                "eclair": "MC3R1.D4.10"
+            },
+            "name": "Dir 4.10: headers that leave it up to the caller to include them correctly",
+            "text": "Headers that deliberatively avoid inclusion guards explicitly leaving responsibility to the caller are allowed."
+        },
+        {
+            "id": "SAF-9-safe",
             "analyser": {},
             "name": "Sentinel",
             "text": "Next ID to be used"
diff --git a/xen/include/public/arch-x86/cpufeatureset.h b/xen/include/public/arch-x86/cpufeatureset.h
index d9eba5e9a7..0d2adfdc3a 100644
--- a/xen/include/public/arch-x86/cpufeatureset.h
+++ b/xen/include/public/arch-x86/cpufeatureset.h
@@ -23,6 +23,7 @@ 
  * their XEN_CPUFEATURE() being appropriate in the included context.
  */
 
+/* SAF-8-safe omitted inclusion guard */
 #ifndef XEN_CPUFEATURE
 
 /*
diff --git a/xen/include/public/errno.h b/xen/include/public/errno.h
index 5a78a7607c..ccd5023c3a 100644
--- a/xen/include/public/errno.h
+++ b/xen/include/public/errno.h
@@ -17,6 +17,7 @@ 
  * will unilaterally #undef XEN_ERRNO().
  */
 
+/* SAF-8-safe omitted inclusion guard */
 #ifndef XEN_ERRNO
 
 /*