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 a deviation for all headers that contain the following
in a comment text:
"In this case, no inclusion guards apply and the caller is responsible"

Signed-off-by: Simone Ballarin <simone.ballarin@bugseng.com>
---
 automation/eclair_analysis/ECLAIR/deviations.ecl | 4 ++++
 docs/misra/rules.rst                             | 3 ++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl b/automation/eclair_analysis/ECLAIR/deviations.ecl
index d8170106b4..5f068377fa 100644
--- a/automation/eclair_analysis/ECLAIR/deviations.ecl
+++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
@@ -91,6 +91,10 @@ conform to the directive."
 -config=MC3R1.D4.10,reports+={safe, "first_area(text(^/\\* Generated file, do not edit! \\*/$, begin-3))"}
 -doc_end
 
+-doc_begin="Some headers, under specific circumstances, explicitly avoid inclusion guards."
+-config=MC3R1.D4.10,reports+={safe, "first_area(text(^ \\* In this case, no inclusion guards apply and the caller is responsible.*\\*/$, begin-1))"}
+-doc_end
+
 #
 # Series 5.
 #
diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index db30632b93..4b1a7b02b6 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -60,7 +60,8 @@ maintainers if you want to suggest a change.
      - 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
+       conform to the directive. Files that explicitly avoid inclusion guards
+       under specific circumstances do not need to conform the directive.
 
    * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
      - Required
-- 
2.34.1

On 28.08.2023 15:19, Simone Ballarin wrote:
> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -60,7 +60,8 @@ maintainers if you want to suggest a change.
>       - 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
> +       conform to the directive. Files that explicitly avoid inclusion guards
> +       under specific circumstances do not need to conform the directive.

Nit: There's a "to" missing near the end of the added sentence. Can likely
be taken care of while committing, since Stefano has already ack-ed this,
but I'd like to still raise the question of the utility of this statement:
How is one to know whether omission of guards is intentional?

Jan

On 29/08/23 08:33, Jan Beulich wrote:
> On 28.08.2023 15:19, Simone Ballarin wrote:
>> --- a/docs/misra/rules.rst
>> +++ b/docs/misra/rules.rst
>> @@ -60,7 +60,8 @@ maintainers if you want to suggest a change.
>>        - 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
>> +       conform to the directive. Files that explicitly avoid inclusion guards
>> +       under specific circumstances do not need to conform the directive.
> 
> Nit: There's a "to" missing near the end of the added sentence. Can likely
> be taken care of while committing, since Stefano has already ack-ed this,
> but I'd like to still raise the question of the utility of this statement:
> How is one to know whether omission of guards is intentional?

As suggested by Stefano, this kind of deviation should be done using
the format specified in safe.json, and I will follow his suggestion in 
the next submission. The statement will disappear.

> 
> Jan
> 
> 
> 

-- 
Simone Ballarin, M.Sc.

Field Application Engineer, BUGSENG (https://bugseng.com)

On Mon, 28 Aug 2023, 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 a deviation for all headers that contain the following
> in a comment text:
> "In this case, no inclusion guards apply and the caller is responsible"
> 
> Signed-off-by: Simone Ballarin <simone.ballarin@bugseng.com>

Acked-by: Stefano Stabellini <sstabellini@kernel.org>


> ---
>  automation/eclair_analysis/ECLAIR/deviations.ecl | 4 ++++
>  docs/misra/rules.rst                             | 3 ++-
>  2 files changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl b/automation/eclair_analysis/ECLAIR/deviations.ecl
> index d8170106b4..5f068377fa 100644
> --- a/automation/eclair_analysis/ECLAIR/deviations.ecl
> +++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
> @@ -91,6 +91,10 @@ conform to the directive."
>  -config=MC3R1.D4.10,reports+={safe, "first_area(text(^/\\* Generated file, do not edit! \\*/$, begin-3))"}
>  -doc_end
>  
> +-doc_begin="Some headers, under specific circumstances, explicitly avoid inclusion guards."
> +-config=MC3R1.D4.10,reports+={safe, "first_area(text(^ \\* In this case, no inclusion guards apply and the caller is responsible.*\\*/$, begin-1))"}
> +-doc_end
> +
>  #
>  # Series 5.
>  #
> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> index db30632b93..4b1a7b02b6 100644
> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -60,7 +60,8 @@ maintainers if you want to suggest a change.
>       - 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
> +       conform to the directive. Files that explicitly avoid inclusion guards
> +       under specific circumstances do not need to conform the directive.
>  
>     * - `Dir 4.11 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/D_04_11.c>`_
>       - Required
> -- 
> 2.34.1
>

On Mon, 28 Aug 2023, Stefano Stabellini wrote:
> On Mon, 28 Aug 2023, 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 a deviation for all headers that contain the following
> > in a comment text:
> > "In this case, no inclusion guards apply and the caller is responsible"
> > 
> > Signed-off-by: Simone Ballarin <simone.ballarin@bugseng.com>
> 
> Acked-by: Stefano Stabellini <sstabellini@kernel.org>

Actually one question


> > ---
> >  automation/eclair_analysis/ECLAIR/deviations.ecl | 4 ++++
> >  docs/misra/rules.rst                             | 3 ++-
> >  2 files changed, 6 insertions(+), 1 deletion(-)
> > 
> > diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl b/automation/eclair_analysis/ECLAIR/deviations.ecl
> > index d8170106b4..5f068377fa 100644
> > --- a/automation/eclair_analysis/ECLAIR/deviations.ecl
> > +++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
> > @@ -91,6 +91,10 @@ conform to the directive."
> >  -config=MC3R1.D4.10,reports+={safe, "first_area(text(^/\\* Generated file, do not edit! \\*/$, begin-3))"}
> >  -doc_end
> >  
> > +-doc_begin="Some headers, under specific circumstances, explicitly avoid inclusion guards."
> > +-config=MC3R1.D4.10,reports+={safe, "first_area(text(^ \\* In this case, no inclusion guards apply and the caller is responsible.*\\*/$, begin-1))"}
> > +-doc_end

Is this supposed to match with any files starting with "In this case,
no inclusion..." ?

We should use the format introduced by safe.json instead

On 29/08/23 00:32, Stefano Stabellini wrote:
> On Mon, 28 Aug 2023, Stefano Stabellini wrote:
>> On Mon, 28 Aug 2023, 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 a deviation for all headers that contain the following
>>> in a comment text:
>>> "In this case, no inclusion guards apply and the caller is responsible"
>>>
>>> Signed-off-by: Simone Ballarin <simone.ballarin@bugseng.com>
>>
>> Acked-by: Stefano Stabellini <sstabellini@kernel.org>
> 
> Actually one question
> 
> 
>>> ---
>>>   automation/eclair_analysis/ECLAIR/deviations.ecl | 4 ++++
>>>   docs/misra/rules.rst                             | 3 ++-
>>>   2 files changed, 6 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/automation/eclair_analysis/ECLAIR/deviations.ecl b/automation/eclair_analysis/ECLAIR/deviations.ecl
>>> index d8170106b4..5f068377fa 100644
>>> --- a/automation/eclair_analysis/ECLAIR/deviations.ecl
>>> +++ b/automation/eclair_analysis/ECLAIR/deviations.ecl
>>> @@ -91,6 +91,10 @@ conform to the directive."
>>>   -config=MC3R1.D4.10,reports+={safe, "first_area(text(^/\\* Generated file, do not edit! \\*/$, begin-3))"}
>>>   -doc_end
>>>   
>>> +-doc_begin="Some headers, under specific circumstances, explicitly avoid inclusion guards."
>>> +-config=MC3R1.D4.10,reports+={safe, "first_area(text(^ \\* In this case, no inclusion guards apply and the caller is responsible.*\\*/$, begin-1))"}
>>> +-doc_end
> 
> Is this supposed to match with any files starting with "In this case,
> no inclusion..." ?
> 
> We should use the format introduced by safe.json instead
> 

I agree, I will do it in the next submission.

-- 
Simone Ballarin, M.Sc.

Field Application Engineer, BUGSENG (https://bugseng.com)