Re: [XEN PATCH v2 01/10] misra: add deviation for headers that explicitly avoid guards

[Jan Beulich <jbeulich@xxxxxxxx>]

On 12.09.2023 11:36, Simone Ballarin wrote:
> 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 <simone.ballarin@xxxxxxxxxxx>
> 
> ---
> 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(+)
> 
> diff --git a/docs/misra/safe.json b/docs/misra/safe.json
> index 39c5c056c7..db438c9770 100644
> --- a/docs/misra/safe.json
> +++ b/docs/misra/safe.json
> @@ -20,6 +20,14 @@
>          },
>          {
>              "id": "SAF-2-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."
> +        },

With this ...

> +        {
> +            "id": "SAF-3-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 6b6ce2745c..eac1ae4b2a 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-1-safe header that leaves it up to the caller to include them 
> correctly */
>  #ifndef XEN_CPUFEATURE
>  
>  /*
> diff --git a/xen/include/public/errno.h b/xen/include/public/errno.h
> index 5a78a7607c..8b60ac74ae 100644
> --- a/xen/include/public/errno.h
> +++ b/xen/include/public/errno.h
> @@ -17,6 +17,7 @@
>   * will unilaterally #undef XEN_ERRNO().
>   */
>  
> +/* SAF-1-safe header that leaves it up to the caller to include them 
> correctly */
>  #ifndef XEN_ERRNO
>  
>  /*

... you mean SAF-2-safe in both code comments. I did point out the problem
with the sequential numbering (and resulting rebasing mistakes) when the
scheme was introduced.

I also think the comments are too verbose. I don't mind them having an
indication what specific issue they are about, but it shouldn't be more
than a couple of words. Here maybe "omitted inclusion guard".

Jan