[PATCH v2] docs/misra/rules.rst update

[PATCH v2] docs/misra/rules.rst update

[Stefano Stabellini]

Hi all,

Update docs/misra/rules.rst to reflect the MISRA C rules accepted in the
last couple of months.

Cheers,

Stefano

[PATCH v2 1/3] docs/misra/rules.rst: add rule 16.6 and 20.12

[Stefano Stabellini]

Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
---
 docs/misra/rules.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index 182331089d..c185366966 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -478,6 +478,12 @@ maintainers if you want to suggest a change.
        adhere to Rule 16.2 would result in increased complexity and
        maintenance difficulty, and could potentially introduce bugs. 
 
+   * - `Rule 16.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_06.c>`_
+     - Required
+     - Every switch statement shall have at least two switch-clauses
+     - Single-clause switches are allowed when they do not involve a
+       default label.
+
    * - `Rule 16.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_07.c>`_
      - Required
      - A switch-expression shall not have essentially Boolean type
@@ -554,6 +560,13 @@ maintainers if you want to suggest a change.
        evaluation
      -
 
+   * - `Rule 20.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_12.c>`_
+     - A macro parameter used as an operand to the # or ## operators,
+       which is itself subject to further macro replacement, shall only
+       be used as an operand to these operators
+     - Required
+     - Variadic macros are allowed to violate the rule.
+
    * - `Rule 20.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_13.c>`_
      - Required
      - A line whose first token is # shall be a valid preprocessing
-- 
2.25.1

[PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Stefano Stabellini]

Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
---
 docs/misra/rules.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index c185366966..931158b354 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
        headers (xen/include/public/) are allowed to retain longer
        identifiers for backward compatibility.
 
+   * - `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
+     - Required
+     - Identifiers shall be distinct from macro names
+     - Clashes between function-like macros and non-callable entities
+       are allowed. The pattern #define x x is also allowed.
+
    * - `Rule 5.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_06.c>`_
      - Required
      - A typedef name shall be a unique identifier
-- 
2.25.1

[PATCH v2 3/3] docs/misra/rules.rst: add rule 14.4

[Stefano Stabellini]

Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
---
 docs/misra/rules.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index 931158b354..3e6f94d7bd 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -468,6 +468,15 @@ maintainers if you want to suggest a change.
 
        while(0) and while(1) and alike are allowed.
 
+   * - `Rule 14.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_04.c>`_
+     - Required
+     - The controlling expression of an if-statement and the controlling
+       expression of an iteration-statement shall have essentially
+       Boolean type
+     - Automatic conversions of integer types to bool are permitted.
+       Automatic conversions of pointer types to bool are permitted.
+       This rule still applies to enum types.
+
    * - `Rule 16.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_03.c>`_
      - Required
      - An unconditional break statement shall terminate every
-- 
2.25.1

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Jan Beulich]

On 13.02.2024 23:33, Stefano Stabellini wrote:
> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
> ---
>  docs/misra/rules.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> index c185366966..931158b354 100644
> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>         headers (xen/include/public/) are allowed to retain longer
>         identifiers for backward compatibility.
>  
> +   * - `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
> +     - Required
> +     - Identifiers shall be distinct from macro names
> +     - Clashes between function-like macros and non-callable entities
> +       are allowed. The pattern #define x x is also allowed.

Just for me to know what exactly is covered (hence also a question
to Roberto as to [to be] implemented Eclair behavior): Even when
the above would be sufficient (and imo better) people frequently
write

#define a(x, y) b(x, y)

which, transformed to the specific case here, would then be

#define a(x, y) a(x, y)

I'd assume such ought to also be covered, but that's not clear
from the spelling above.

Jan

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Federico Serafini]

On 14/02/24 09:28, Jan Beulich wrote:
> On 13.02.2024 23:33, Stefano Stabellini wrote:
>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>> ---
>>   docs/misra/rules.rst | 6 ++++++
>>   1 file changed, 6 insertions(+)
>>
>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>> index c185366966..931158b354 100644
>> --- a/docs/misra/rules.rst
>> +++ b/docs/misra/rules.rst
>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>          headers (xen/include/public/) are allowed to retain longer
>>          identifiers for backward compatibility.
>>   
>> +   * - `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>> +     - Required
>> +     - Identifiers shall be distinct from macro names
>> +     - Clashes between function-like macros and non-callable entities
>> +       are allowed. The pattern #define x x is also allowed.
> 
> Just for me to know what exactly is covered (hence also a question
> to Roberto as to [to be] implemented Eclair behavior): Even when
> the above would be sufficient (and imo better) people frequently
> write
> 
> #define a(x, y) b(x, y)
> 
> which, transformed to the specific case here, would then be
> 
> #define a(x, y) a(x, y)
> 
> I'd assume such ought to also be covered, but that's not clear
> from the spelling above.

I list what happens in some different situations,
then we can find the right words for the documentation and/or
refine the configuration:

If you
#define x x
and then use `x' as identifier,
the resulting violation is deviated (allowed pattern).

If you
#define a(x, y) a(x, y)
and then use `a' as identifier for a non-callable entity,
the resulting violation is deviated (no clash with non-callable
entities).
If you use identifier `a' for a callable entity, the resulting violation
is reported: the allowed pattern covers only macros expanding to their
own name, in this case the macro name is considered to be
`a' only, not a(x, y).

If you
#define a(x, y) b(x, y)
and then use `a' as identifier for a non-callable entity,
the resulting violation is deviated (no clash with non-callable
entities).
If you use `a' as identifier for a callable entity,
this is not a violation because after the preprocessing phase,
identifier `a' no longer exists.

As far as I know, this is what was agreed upon in one of the recent
MISRA meetings.

-- 
Federico Serafini, M.Sc.

Software Engineer, BUGSENG (http://bugseng.com)

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Jan Beulich]

On 14.02.2024 12:27, Federico Serafini wrote:
> On 14/02/24 09:28, Jan Beulich wrote:
>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>> ---
>>>   docs/misra/rules.rst | 6 ++++++
>>>   1 file changed, 6 insertions(+)
>>>
>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>> index c185366966..931158b354 100644
>>> --- a/docs/misra/rules.rst
>>> +++ b/docs/misra/rules.rst
>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>          headers (xen/include/public/) are allowed to retain longer
>>>          identifiers for backward compatibility.
>>>   
>>> +   * - `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>> +     - Required
>>> +     - Identifiers shall be distinct from macro names
>>> +     - Clashes between function-like macros and non-callable entities
>>> +       are allowed. The pattern #define x x is also allowed.
>>
>> Just for me to know what exactly is covered (hence also a question
>> to Roberto as to [to be] implemented Eclair behavior): Even when
>> the above would be sufficient (and imo better) people frequently
>> write
>>
>> #define a(x, y) b(x, y)
>>
>> which, transformed to the specific case here, would then be
>>
>> #define a(x, y) a(x, y)
>>
>> I'd assume such ought to also be covered, but that's not clear
>> from the spelling above.
> 
> I list what happens in some different situations,
> then we can find the right words for the documentation and/or
> refine the configuration:
> 
> If you
> #define x x
> and then use `x' as identifier,
> the resulting violation is deviated (allowed pattern).
> 
> If you
> #define a(x, y) a(x, y)
> and then use `a' as identifier for a non-callable entity,
> the resulting violation is deviated (no clash with non-callable
> entities).
> If you use identifier `a' for a callable entity, the resulting violation
> is reported: the allowed pattern covers only macros expanding to their
> own name, in this case the macro name is considered to be
> `a' only, not a(x, y).
> 
> If you
> #define a(x, y) b(x, y)
> and then use `a' as identifier for a non-callable entity,
> the resulting violation is deviated (no clash with non-callable
> entities).

I'm afraid I don't see what violation there is in this case, to
deviate. As a result I'm also not sure I correctly understand the
rest of your reply.

> If you use `a' as identifier for a callable entity,
> this is not a violation because after the preprocessing phase,
> identifier `a' no longer exists.
> 
> As far as I know, this is what was agreed upon in one of the recent
> MISRA meetings.

That was my fear (of being what I'd call a wrong [insufficient]
interpretation of what was meant).

Jan

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Federico Serafini]

On 14/02/24 14:15, Jan Beulich wrote:
> On 14.02.2024 12:27, Federico Serafini wrote:
>> On 14/02/24 09:28, Jan Beulich wrote:
>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>> ---
>>>>    docs/misra/rules.rst | 6 ++++++
>>>>    1 file changed, 6 insertions(+)
>>>>
>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>> index c185366966..931158b354 100644
>>>> --- a/docs/misra/rules.rst
>>>> +++ b/docs/misra/rules.rst
>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>           headers (xen/include/public/) are allowed to retain longer
>>>>           identifiers for backward compatibility.
>>>>    
>>>> +   * - `Rule 5.5 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>> +     - Required
>>>> +     - Identifiers shall be distinct from macro names
>>>> +     - Clashes between function-like macros and non-callable entities
>>>> +       are allowed. The pattern #define x x is also allowed.
>>>
>>> Just for me to know what exactly is covered (hence also a question
>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>> the above would be sufficient (and imo better) people frequently
>>> write
>>>
>>> #define a(x, y) b(x, y)
>>>
>>> which, transformed to the specific case here, would then be
>>>
>>> #define a(x, y) a(x, y)
>>>
>>> I'd assume such ought to also be covered, but that's not clear
>>> from the spelling above.
>>
>> I list what happens in some different situations,
>> then we can find the right words for the documentation and/or
>> refine the configuration:
>>
>> If you
>> #define x x
>> and then use `x' as identifier,
>> the resulting violation is deviated (allowed pattern).
>>
>> If you
>> #define a(x, y) a(x, y)
>> and then use `a' as identifier for a non-callable entity,
>> the resulting violation is deviated (no clash with non-callable
>> entities).
>> If you use identifier `a' for a callable entity, the resulting violation
>> is reported: the allowed pattern covers only macros expanding to their
>> own name, in this case the macro name is considered to be
>> `a' only, not a(x, y).
>>
>> If you
>> #define a(x, y) b(x, y)
>> and then use `a' as identifier for a non-callable entity,
>> the resulting violation is deviated (no clash with non-callable
>> entities).
> 
> I'm afraid I don't see what violation there is in this case, to
> deviate. As a result I'm also not sure I correctly understand the
> rest of your reply.

#define a(x, y) b(x, y)

int a; // Violation of Rule 5.5.

The macro name `a' that exist before the preprocessing phase,
still exists after the preprocessing phase as identifier for the integer
variable and this is a violation.

>> If you use `a' as identifier for a callable entity,
>> this is not a violation because after the preprocessing phase,
>> identifier `a' no longer exists.
I correct myself:
if you use `a' as identifier for a *function*,
it is not a violation because after the preprocessing phase
the identifier `a' no longer exists, for example:

#define a(x, y) b(x, y)

void a(int x, int y); // Ok.

-- 
Federico Serafini, M.Sc.

Software Engineer, BUGSENG (http://bugseng.com)

Re: [PATCH v2 1/3] docs/misra/rules.rst: add rule 16.6 and 20.12

[Julien Grall]

Hi Stefano,

On 13/02/2024 22:33, Stefano Stabellini wrote:
> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>

Acked-by: Julien Grall <jgrall@amazon.com>

Cheers,

-- 
Julien Grall

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Stefano Stabellini]

On Wed, 14 Feb 2024, Federico Serafini wrote:
> On 14/02/24 14:15, Jan Beulich wrote:
> > On 14.02.2024 12:27, Federico Serafini wrote:
> > > On 14/02/24 09:28, Jan Beulich wrote:
> > > > On 13.02.2024 23:33, Stefano Stabellini wrote:
> > > > > Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
> > > > > ---
> > > > >    docs/misra/rules.rst | 6 ++++++
> > > > >    1 file changed, 6 insertions(+)
> > > > > 
> > > > > diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> > > > > index c185366966..931158b354 100644
> > > > > --- a/docs/misra/rules.rst
> > > > > +++ b/docs/misra/rules.rst
> > > > > @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
> > > > >           headers (xen/include/public/) are allowed to retain longer
> > > > >           identifiers for backward compatibility.
> > > > >    +   * - `Rule 5.5
> > > > > <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
> > > > > +     - Required
> > > > > +     - Identifiers shall be distinct from macro names
> > > > > +     - Clashes between function-like macros and non-callable entities
> > > > > +       are allowed. The pattern #define x x is also allowed.
> > > > 
> > > > Just for me to know what exactly is covered (hence also a question
> > > > to Roberto as to [to be] implemented Eclair behavior): Even when
> > > > the above would be sufficient (and imo better) people frequently
> > > > write
> > > > 
> > > > #define a(x, y) b(x, y)
> > > > 
> > > > which, transformed to the specific case here, would then be
> > > > 
> > > > #define a(x, y) a(x, y)
> > > > 
> > > > I'd assume such ought to also be covered, but that's not clear
> > > > from the spelling above.
> > > 
> > > I list what happens in some different situations,
> > > then we can find the right words for the documentation and/or
> > > refine the configuration:
> > > 
> > > If you
> > > #define x x
> > > and then use `x' as identifier,
> > > the resulting violation is deviated (allowed pattern).
> > > 
> > > If you
> > > #define a(x, y) a(x, y)
> > > and then use `a' as identifier for a non-callable entity,
> > > the resulting violation is deviated (no clash with non-callable
> > > entities).
> > > If you use identifier `a' for a callable entity, the resulting violation
> > > is reported: the allowed pattern covers only macros expanding to their
> > > own name, in this case the macro name is considered to be
> > > `a' only, not a(x, y).
> > > 
> > > If you
> > > #define a(x, y) b(x, y)
> > > and then use `a' as identifier for a non-callable entity,
> > > the resulting violation is deviated (no clash with non-callable
> > > entities).
> > 
> > I'm afraid I don't see what violation there is in this case, to
> > deviate. As a result I'm also not sure I correctly understand the
> > rest of your reply.
> 
> #define a(x, y) b(x, y)
> 
> int a; // Violation of Rule 5.5.
> 
> The macro name `a' that exist before the preprocessing phase,
> still exists after the preprocessing phase as identifier for the integer
> variable and this is a violation.
> 
> > > If you use `a' as identifier for a callable entity,
> > > this is not a violation because after the preprocessing phase,
> > > identifier `a' no longer exists.
> I correct myself:
> if you use `a' as identifier for a *function*,
> it is not a violation because after the preprocessing phase
> the identifier `a' no longer exists, for example:
> 
> #define a(x, y) b(x, y)
> 
> void a(int x, int y); // Ok.

Federico, do you have a better wording suggestion for this rule?

Jan, any further requests here? What would you like to see as next step?

Re: [PATCH v2 1/3] docs/misra/rules.rst: add rule 16.6 and 20.12

[Stefano Stabellini]

Hi all,

This patch broke gitlab-ci. The jobs failing are the cppcheck jobs.

xen/scripts/xen-analysis.py --run-cppcheck --cppcheck-misra -- -j80
No summary for rule 20.12
WARNING: Can't open /builds/xen-project/hardware/xen/xen/drivers/video/font_8x14.c: 'utf-8' codec can't decode byte 0x9f in position 7228: invalid start byte
WARNING: Can't open /builds/xen-project/hardware/xen/xen/drivers/video/font_8x16.c: 'utf-8' codec can't decode byte 0x80 in position 5436: invalid start byte
WARNING: Can't open /builds/xen-project/hardware/xen/xen/drivers/video/font_8x8.c: 'utf-8' codec can't decode byte 0x80 in position 4410: invalid start byte
ERROR: An error occured when running:
/builds/xen-project/hardware/xen/xen/tools/convert_misra_doc.py -i /builds/xen-project/hardware/xen/docs/misra/rules.rst -o /builds/xen-project/hardware/xen/xen/cppcheck-misra.txt -j /builds/xen-project/hardware/xen/xen/cppcheck-misra.json 

I'll look into it as soon as possible.


On Tue, 13 Feb 2024, Stefano Stabellini wrote:
> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
> ---
>  docs/misra/rules.rst | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> index 182331089d..c185366966 100644
> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -478,6 +478,12 @@ maintainers if you want to suggest a change.
>         adhere to Rule 16.2 would result in increased complexity and
>         maintenance difficulty, and could potentially introduce bugs. 
>  
> +   * - `Rule 16.6 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_06.c>`_
> +     - Required
> +     - Every switch statement shall have at least two switch-clauses
> +     - Single-clause switches are allowed when they do not involve a
> +       default label.
> +
>     * - `Rule 16.7 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_07.c>`_
>       - Required
>       - A switch-expression shall not have essentially Boolean type
> @@ -554,6 +560,13 @@ maintainers if you want to suggest a change.
>         evaluation
>       -
>  
> +   * - `Rule 20.12 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_12.c>`_
> +     - A macro parameter used as an operand to the # or ## operators,
> +       which is itself subject to further macro replacement, shall only
> +       be used as an operand to these operators
> +     - Required
> +     - Variadic macros are allowed to violate the rule.
> +
>     * - `Rule 20.13 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_13.c>`_
>       - Required
>       - A line whose first token is # shall be a valid preprocessing
> -- 
> 2.25.1
> 
> 

Re: [PATCH v2 3/3] docs/misra/rules.rst: add rule 14.4

[Bertrand Marquis]

Hi Stefano,


> On 13 Feb 2024, at 23:33, Stefano Stabellini <stefano.stabellini@amd.com> wrote:
> 
> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>

Coherent with what was discussed during the Misra meeting so:

Acked-by: Bertrand Marquis <bertrand.marquis@arm.com>

Cheers
Bertrand

> ---
> docs/misra/rules.rst | 9 +++++++++
> 1 file changed, 9 insertions(+)
> 
> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> index 931158b354..3e6f94d7bd 100644
> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -468,6 +468,15 @@ maintainers if you want to suggest a change.
> 
>        while(0) and while(1) and alike are allowed.
> 
> +   * - `Rule 14.4 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_14_04.c>`_
> +     - Required
> +     - The controlling expression of an if-statement and the controlling
> +       expression of an iteration-statement shall have essentially
> +       Boolean type
> +     - Automatic conversions of integer types to bool are permitted.
> +       Automatic conversions of pointer types to bool are permitted.
> +       This rule still applies to enum types.
> +
>    * - `Rule 16.3 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_03.c>`_
>      - Required
>      - An unconditional break statement shall terminate every
> -- 
> 2.25.1
> 
> 

Re: [PATCH v2 1/3] docs/misra/rules.rst: add rule 16.6 and 20.12

[Nicola Vetrini]

On 2024-03-01 02:56, Stefano Stabellini wrote:
> Hi all,
> 
> This patch broke gitlab-ci. The jobs failing are the cppcheck jobs.
> 
> xen/scripts/xen-analysis.py --run-cppcheck --cppcheck-misra -- -j80
> No summary for rule 20.12
> WARNING: Can't open 
> /builds/xen-project/hardware/xen/xen/drivers/video/font_8x14.c: 'utf-8' 
> codec can't decode byte 0x9f in position 7228: invalid start byte
> WARNING: Can't open 
> /builds/xen-project/hardware/xen/xen/drivers/video/font_8x16.c: 'utf-8' 
> codec can't decode byte 0x80 in position 5436: invalid start byte
> WARNING: Can't open 
> /builds/xen-project/hardware/xen/xen/drivers/video/font_8x8.c: 'utf-8' 
> codec can't decode byte 0x80 in position 4410: invalid start byte
> ERROR: An error occured when running:
> /builds/xen-project/hardware/xen/xen/tools/convert_misra_doc.py -i 
> /builds/xen-project/hardware/xen/docs/misra/rules.rst -o 
> /builds/xen-project/hardware/xen/xen/cppcheck-misra.txt -j 
> /builds/xen-project/hardware/xen/xen/cppcheck-misra.json
> 
> I'll look into it as soon as possible.
> 
> 
> On Tue, 13 Feb 2024, Stefano Stabellini wrote:
>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>> ---
>>  docs/misra/rules.rst | 13 +++++++++++++
>>  1 file changed, 13 insertions(+)
>> 
>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>> index 182331089d..c185366966 100644
>> --- a/docs/misra/rules.rst
>> +++ b/docs/misra/rules.rst
>> @@ -478,6 +478,12 @@ maintainers if you want to suggest a change.
>>         adhere to Rule 16.2 would result in increased complexity and
>>         maintenance difficulty, and could potentially introduce bugs.
>> 
>> +   * - `Rule 16.6 
>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_06.c>`_
>> +     - Required
>> +     - Every switch statement shall have at least two switch-clauses
>> +     - Single-clause switches are allowed when they do not involve a
>> +       default label.
>> +
>>     * - `Rule 16.7 
>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_16_07.c>`_
>>       - Required
>>       - A switch-expression shall not have essentially Boolean type
>> @@ -554,6 +560,13 @@ maintainers if you want to suggest a change.
>>         evaluation
>>       -
>> 
>> +   * - `Rule 20.12 
>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_12.c>`_
>> +     - A macro parameter used as an operand to the # or ## operators,
>> +       which is itself subject to further macro replacement, shall 
>> only
>> +       be used as an operand to these operators
>> +     - Required
>> +     - Variadic macros are allowed to violate the rule.
>> +

I think here it wants the strictness "Required" first, and then the 
headline second "A macro parameter..."

>>     * - `Rule 20.13 
>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_20_13.c>`_
>>       - Required
>>       - A line whose first token is # shall be a valid preprocessing
>> --
>> 2.25.1
>> 
>> 

-- 
Nicola Vetrini, BSc
Software Engineer, BUGSENG srl (https://bugseng.com)

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Jan Beulich]

On 01.03.2024 00:28, Stefano Stabellini wrote:
> On Wed, 14 Feb 2024, Federico Serafini wrote:
>> On 14/02/24 14:15, Jan Beulich wrote:
>>> On 14.02.2024 12:27, Federico Serafini wrote:
>>>> On 14/02/24 09:28, Jan Beulich wrote:
>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>>>> ---
>>>>>>    docs/misra/rules.rst | 6 ++++++
>>>>>>    1 file changed, 6 insertions(+)
>>>>>>
>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>>> index c185366966..931158b354 100644
>>>>>> --- a/docs/misra/rules.rst
>>>>>> +++ b/docs/misra/rules.rst
>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>>>           headers (xen/include/public/) are allowed to retain longer
>>>>>>           identifiers for backward compatibility.
>>>>>>    +   * - `Rule 5.5
>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>>> +     - Required
>>>>>> +     - Identifiers shall be distinct from macro names
>>>>>> +     - Clashes between function-like macros and non-callable entities
>>>>>> +       are allowed. The pattern #define x x is also allowed.
>>>>>
>>>>> Just for me to know what exactly is covered (hence also a question
>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>>>> the above would be sufficient (and imo better) people frequently
>>>>> write
>>>>>
>>>>> #define a(x, y) b(x, y)
>>>>>
>>>>> which, transformed to the specific case here, would then be
>>>>>
>>>>> #define a(x, y) a(x, y)
>>>>>
>>>>> I'd assume such ought to also be covered, but that's not clear
>>>>> from the spelling above.
>>>>
>>>> I list what happens in some different situations,
>>>> then we can find the right words for the documentation and/or
>>>> refine the configuration:
>>>>
>>>> If you
>>>> #define x x
>>>> and then use `x' as identifier,
>>>> the resulting violation is deviated (allowed pattern).
>>>>
>>>> If you
>>>> #define a(x, y) a(x, y)
>>>> and then use `a' as identifier for a non-callable entity,
>>>> the resulting violation is deviated (no clash with non-callable
>>>> entities).
>>>> If you use identifier `a' for a callable entity, the resulting violation
>>>> is reported: the allowed pattern covers only macros expanding to their
>>>> own name, in this case the macro name is considered to be
>>>> `a' only, not a(x, y).
>>>>
>>>> If you
>>>> #define a(x, y) b(x, y)
>>>> and then use `a' as identifier for a non-callable entity,
>>>> the resulting violation is deviated (no clash with non-callable
>>>> entities).
>>>
>>> I'm afraid I don't see what violation there is in this case, to
>>> deviate. As a result I'm also not sure I correctly understand the
>>> rest of your reply.
>>
>> #define a(x, y) b(x, y)
>>
>> int a; // Violation of Rule 5.5.
>>
>> The macro name `a' that exist before the preprocessing phase,
>> still exists after the preprocessing phase as identifier for the integer
>> variable and this is a violation.
>>
>>>> If you use `a' as identifier for a callable entity,
>>>> this is not a violation because after the preprocessing phase,
>>>> identifier `a' no longer exists.
>> I correct myself:
>> if you use `a' as identifier for a *function*,
>> it is not a violation because after the preprocessing phase
>> the identifier `a' no longer exists, for example:
>>
>> #define a(x, y) b(x, y)
>>
>> void a(int x, int y); // Ok.
> 
> Federico, do you have a better wording suggestion for this rule?
> 
> Jan, any further requests here? What would you like to see as next step?

A more concise wording proposal would probably help.

Jan

Re: [PATCH v2 1/3] docs/misra/rules.rst: add rule 16.6 and 20.12

[Michal Orzel]

On 01/03/2024 02:56, Stefano Stabellini wrote:
> 
> 
> Hi all,
> 
> This patch broke gitlab-ci. The jobs failing are the cppcheck jobs.
> 
> xen/scripts/xen-analysis.py --run-cppcheck --cppcheck-misra -- -j80
> No summary for rule 20.12
This is the error message. For rule 20.12, the summary and severity are in reverse order.
I'll send a patch shortly.

~Michal

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Federico Serafini]

On 01/03/24 09:06, Jan Beulich wrote:
> On 01.03.2024 00:28, Stefano Stabellini wrote:
>> On Wed, 14 Feb 2024, Federico Serafini wrote:
>>> On 14/02/24 14:15, Jan Beulich wrote:
>>>> On 14.02.2024 12:27, Federico Serafini wrote:
>>>>> On 14/02/24 09:28, Jan Beulich wrote:
>>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>>>>> ---
>>>>>>>     docs/misra/rules.rst | 6 ++++++
>>>>>>>     1 file changed, 6 insertions(+)
>>>>>>>
>>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>>>> index c185366966..931158b354 100644
>>>>>>> --- a/docs/misra/rules.rst
>>>>>>> +++ b/docs/misra/rules.rst
>>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>>>>            headers (xen/include/public/) are allowed to retain longer
>>>>>>>            identifiers for backward compatibility.
>>>>>>>     +   * - `Rule 5.5
>>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>>>> +     - Required
>>>>>>> +     - Identifiers shall be distinct from macro names
>>>>>>> +     - Clashes between function-like macros and non-callable entities
>>>>>>> +       are allowed. The pattern #define x x is also allowed.
>>>>>>
>>>>>> Just for me to know what exactly is covered (hence also a question
>>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>>>>> the above would be sufficient (and imo better) people frequently
>>>>>> write
>>>>>>
>>>>>> #define a(x, y) b(x, y)
>>>>>>
>>>>>> which, transformed to the specific case here, would then be
>>>>>>
>>>>>> #define a(x, y) a(x, y)
>>>>>>
>>>>>> I'd assume such ought to also be covered, but that's not clear
>>>>>> from the spelling above.
>>>>>
>>>>> I list what happens in some different situations,
>>>>> then we can find the right words for the documentation and/or
>>>>> refine the configuration:
>>>>>
>>>>> If you
>>>>> #define x x
>>>>> and then use `x' as identifier,
>>>>> the resulting violation is deviated (allowed pattern).
>>>>>
>>>>> If you
>>>>> #define a(x, y) a(x, y)
>>>>> and then use `a' as identifier for a non-callable entity,
>>>>> the resulting violation is deviated (no clash with non-callable
>>>>> entities).
>>>>> If you use identifier `a' for a callable entity, the resulting violation
>>>>> is reported: the allowed pattern covers only macros expanding to their
>>>>> own name, in this case the macro name is considered to be
>>>>> `a' only, not a(x, y).
>>>>>
>>>>> If you
>>>>> #define a(x, y) b(x, y)
>>>>> and then use `a' as identifier for a non-callable entity,
>>>>> the resulting violation is deviated (no clash with non-callable
>>>>> entities).
>>>>
>>>> I'm afraid I don't see what violation there is in this case, to
>>>> deviate. As a result I'm also not sure I correctly understand the
>>>> rest of your reply.
>>>
>>> #define a(x, y) b(x, y)
>>>
>>> int a; // Violation of Rule 5.5.
>>>
>>> The macro name `a' that exist before the preprocessing phase,
>>> still exists after the preprocessing phase as identifier for the integer
>>> variable and this is a violation.
>>>
>>>>> If you use `a' as identifier for a callable entity,
>>>>> this is not a violation because after the preprocessing phase,
>>>>> identifier `a' no longer exists.
>>> I correct myself:
>>> if you use `a' as identifier for a *function*,
>>> it is not a violation because after the preprocessing phase
>>> the identifier `a' no longer exists, for example:
>>>
>>> #define a(x, y) b(x, y)
>>>
>>> void a(int x, int y); // Ok.
>>
>> Federico, do you have a better wording suggestion for this rule?
>>
>> Jan, any further requests here? What would you like to see as next step?
> 
> A more concise wording proposal would probably help.

What do you think about:

diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index 1e134ccebc..a975b9a85f 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -181,6 +181,13 @@ maintainers if you want to suggest a change.
         headers (xen/include/public/) are allowed to retain longer
         identifiers for backward compatibility.

+   * - `Rule 5.5 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
+     - Required
+     - Identifiers shall be distinct from macro names
+     - Macros expanding to their own name are allowed (e.g., #define x x).
+       Clashes between names of function-like macros and identifiers of
+       non-callable entities are allowed.
+
     * - `Rule 5.6 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_06.c>`_
       - Required
       - A typedef name shall be a unique identifier

-- 
Federico Serafini, M.Sc.

Software Engineer, BUGSENG (http://bugseng.com)

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Jan Beulich]

On 04.03.2024 14:31, Federico Serafini wrote:
> On 01/03/24 09:06, Jan Beulich wrote:
>> On 01.03.2024 00:28, Stefano Stabellini wrote:
>>> On Wed, 14 Feb 2024, Federico Serafini wrote:
>>>> On 14/02/24 14:15, Jan Beulich wrote:
>>>>> On 14.02.2024 12:27, Federico Serafini wrote:
>>>>>> On 14/02/24 09:28, Jan Beulich wrote:
>>>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>>>>>> ---
>>>>>>>>     docs/misra/rules.rst | 6 ++++++
>>>>>>>>     1 file changed, 6 insertions(+)
>>>>>>>>
>>>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>>>>> index c185366966..931158b354 100644
>>>>>>>> --- a/docs/misra/rules.rst
>>>>>>>> +++ b/docs/misra/rules.rst
>>>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>>>>>            headers (xen/include/public/) are allowed to retain longer
>>>>>>>>            identifiers for backward compatibility.
>>>>>>>>     +   * - `Rule 5.5
>>>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>>>>> +     - Required
>>>>>>>> +     - Identifiers shall be distinct from macro names
>>>>>>>> +     - Clashes between function-like macros and non-callable entities
>>>>>>>> +       are allowed. The pattern #define x x is also allowed.
>>>>>>>
>>>>>>> Just for me to know what exactly is covered (hence also a question
>>>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>>>>>> the above would be sufficient (and imo better) people frequently
>>>>>>> write
>>>>>>>
>>>>>>> #define a(x, y) b(x, y)
>>>>>>>
>>>>>>> which, transformed to the specific case here, would then be
>>>>>>>
>>>>>>> #define a(x, y) a(x, y)
>>>>>>>
>>>>>>> I'd assume such ought to also be covered, but that's not clear
>>>>>>> from the spelling above.
>>>>>>
>>>>>> I list what happens in some different situations,
>>>>>> then we can find the right words for the documentation and/or
>>>>>> refine the configuration:
>>>>>>
>>>>>> If you
>>>>>> #define x x
>>>>>> and then use `x' as identifier,
>>>>>> the resulting violation is deviated (allowed pattern).
>>>>>>
>>>>>> If you
>>>>>> #define a(x, y) a(x, y)
>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>> entities).
>>>>>> If you use identifier `a' for a callable entity, the resulting violation
>>>>>> is reported: the allowed pattern covers only macros expanding to their
>>>>>> own name, in this case the macro name is considered to be
>>>>>> `a' only, not a(x, y).
>>>>>>
>>>>>> If you
>>>>>> #define a(x, y) b(x, y)
>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>> entities).
>>>>>
>>>>> I'm afraid I don't see what violation there is in this case, to
>>>>> deviate. As a result I'm also not sure I correctly understand the
>>>>> rest of your reply.
>>>>
>>>> #define a(x, y) b(x, y)
>>>>
>>>> int a; // Violation of Rule 5.5.
>>>>
>>>> The macro name `a' that exist before the preprocessing phase,
>>>> still exists after the preprocessing phase as identifier for the integer
>>>> variable and this is a violation.
>>>>
>>>>>> If you use `a' as identifier for a callable entity,
>>>>>> this is not a violation because after the preprocessing phase,
>>>>>> identifier `a' no longer exists.
>>>> I correct myself:
>>>> if you use `a' as identifier for a *function*,
>>>> it is not a violation because after the preprocessing phase
>>>> the identifier `a' no longer exists, for example:
>>>>
>>>> #define a(x, y) b(x, y)
>>>>
>>>> void a(int x, int y); // Ok.
>>>
>>> Federico, do you have a better wording suggestion for this rule?
>>>
>>> Jan, any further requests here? What would you like to see as next step?
>>
>> A more concise wording proposal would probably help.
> 
> What do you think about:
> 
> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> index 1e134ccebc..a975b9a85f 100644
> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -181,6 +181,13 @@ maintainers if you want to suggest a change.
>          headers (xen/include/public/) are allowed to retain longer
>          identifiers for backward compatibility.
> 
> +   * - `Rule 5.5 
> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
> +     - Required
> +     - Identifiers shall be distinct from macro names
> +     - Macros expanding to their own name are allowed (e.g., #define x x).
> +       Clashes between names of function-like macros and identifiers of
> +       non-callable entities are allowed.

Imo that still leaves open e.g. the

#define a(x, y) a(x, y)

case: Permitted ("own name") or not permitted ("a" pretty clearly is expected
to be a callable entity here, besides being a function-like macro)?

Jan

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Federico Serafini]

On 04/03/24 15:17, Jan Beulich wrote:
> On 04.03.2024 14:31, Federico Serafini wrote:
>> On 01/03/24 09:06, Jan Beulich wrote:
>>> On 01.03.2024 00:28, Stefano Stabellini wrote:
>>>> On Wed, 14 Feb 2024, Federico Serafini wrote:
>>>>> On 14/02/24 14:15, Jan Beulich wrote:
>>>>>> On 14.02.2024 12:27, Federico Serafini wrote:
>>>>>>> On 14/02/24 09:28, Jan Beulich wrote:
>>>>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>>>>>>> ---
>>>>>>>>>      docs/misra/rules.rst | 6 ++++++
>>>>>>>>>      1 file changed, 6 insertions(+)
>>>>>>>>>
>>>>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>>>>>> index c185366966..931158b354 100644
>>>>>>>>> --- a/docs/misra/rules.rst
>>>>>>>>> +++ b/docs/misra/rules.rst
>>>>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>>>>>>             headers (xen/include/public/) are allowed to retain longer
>>>>>>>>>             identifiers for backward compatibility.
>>>>>>>>>      +   * - `Rule 5.5
>>>>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>>>>>> +     - Required
>>>>>>>>> +     - Identifiers shall be distinct from macro names
>>>>>>>>> +     - Clashes between function-like macros and non-callable entities
>>>>>>>>> +       are allowed. The pattern #define x x is also allowed.
>>>>>>>>
>>>>>>>> Just for me to know what exactly is covered (hence also a question
>>>>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>>>>>>> the above would be sufficient (and imo better) people frequently
>>>>>>>> write
>>>>>>>>
>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>
>>>>>>>> which, transformed to the specific case here, would then be
>>>>>>>>
>>>>>>>> #define a(x, y) a(x, y)
>>>>>>>>
>>>>>>>> I'd assume such ought to also be covered, but that's not clear
>>>>>>>> from the spelling above.
>>>>>>>
>>>>>>> I list what happens in some different situations,
>>>>>>> then we can find the right words for the documentation and/or
>>>>>>> refine the configuration:
>>>>>>>
>>>>>>> If you
>>>>>>> #define x x
>>>>>>> and then use `x' as identifier,
>>>>>>> the resulting violation is deviated (allowed pattern).
>>>>>>>
>>>>>>> If you
>>>>>>> #define a(x, y) a(x, y)
>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>> entities).
>>>>>>> If you use identifier `a' for a callable entity, the resulting violation
>>>>>>> is reported: the allowed pattern covers only macros expanding to their
>>>>>>> own name, in this case the macro name is considered to be
>>>>>>> `a' only, not a(x, y).
>>>>>>>
>>>>>>> If you
>>>>>>> #define a(x, y) b(x, y)
>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>> entities).
>>>>>>
>>>>>> I'm afraid I don't see what violation there is in this case, to
>>>>>> deviate. As a result I'm also not sure I correctly understand the
>>>>>> rest of your reply.
>>>>>
>>>>> #define a(x, y) b(x, y)
>>>>>
>>>>> int a; // Violation of Rule 5.5.
>>>>>
>>>>> The macro name `a' that exist before the preprocessing phase,
>>>>> still exists after the preprocessing phase as identifier for the integer
>>>>> variable and this is a violation.
>>>>>
>>>>>>> If you use `a' as identifier for a callable entity,
>>>>>>> this is not a violation because after the preprocessing phase,
>>>>>>> identifier `a' no longer exists.
>>>>> I correct myself:
>>>>> if you use `a' as identifier for a *function*,
>>>>> it is not a violation because after the preprocessing phase
>>>>> the identifier `a' no longer exists, for example:
>>>>>
>>>>> #define a(x, y) b(x, y)
>>>>>
>>>>> void a(int x, int y); // Ok.
>>>>
>>>> Federico, do you have a better wording suggestion for this rule?
>>>>
>>>> Jan, any further requests here? What would you like to see as next step?
>>>
>>> A more concise wording proposal would probably help.
>>
>> What do you think about:
>>
>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>> index 1e134ccebc..a975b9a85f 100644
>> --- a/docs/misra/rules.rst
>> +++ b/docs/misra/rules.rst
>> @@ -181,6 +181,13 @@ maintainers if you want to suggest a change.
>>           headers (xen/include/public/) are allowed to retain longer
>>           identifiers for backward compatibility.
>>
>> +   * - `Rule 5.5
>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>> +     - Required
>> +     - Identifiers shall be distinct from macro names
>> +     - Macros expanding to their own name are allowed (e.g., #define x x).
>> +       Clashes between names of function-like macros and identifiers of
>> +       non-callable entities are allowed.
> 
> Imo that still leaves open e.g. the
> 
> #define a(x, y) a(x, y)
> 
> case: Permitted ("own name") or not permitted ("a" pretty clearly is expected
> to be a callable entity here, besides being a function-like macro)?

I would not consider your example as a macro that expands to its own
name, the macro name is considered to be `a' only.

Rather, you example can be used to trigger the "callable-noncallable"
part of the deviation, for example:

#define a(x, y) a(x, y)

void a(int x, int y); /* Not permitted (callable entity 'a'). */

void foo(int a);      /* Permitted (non-callable entity `a'). */

-- 
Federico Serafini, M.Sc.

Software Engineer, BUGSENG (http://bugseng.com)

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Jan Beulich]

On 04.03.2024 16:39, Federico Serafini wrote:
> On 04/03/24 15:17, Jan Beulich wrote:
>> On 04.03.2024 14:31, Federico Serafini wrote:
>>> On 01/03/24 09:06, Jan Beulich wrote:
>>>> On 01.03.2024 00:28, Stefano Stabellini wrote:
>>>>> On Wed, 14 Feb 2024, Federico Serafini wrote:
>>>>>> On 14/02/24 14:15, Jan Beulich wrote:
>>>>>>> On 14.02.2024 12:27, Federico Serafini wrote:
>>>>>>>> On 14/02/24 09:28, Jan Beulich wrote:
>>>>>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>>>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>>>>>>>> ---
>>>>>>>>>>      docs/misra/rules.rst | 6 ++++++
>>>>>>>>>>      1 file changed, 6 insertions(+)
>>>>>>>>>>
>>>>>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>>>>>>> index c185366966..931158b354 100644
>>>>>>>>>> --- a/docs/misra/rules.rst
>>>>>>>>>> +++ b/docs/misra/rules.rst
>>>>>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>>>>>>>             headers (xen/include/public/) are allowed to retain longer
>>>>>>>>>>             identifiers for backward compatibility.
>>>>>>>>>>      +   * - `Rule 5.5
>>>>>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>>>>>>> +     - Required
>>>>>>>>>> +     - Identifiers shall be distinct from macro names
>>>>>>>>>> +     - Clashes between function-like macros and non-callable entities
>>>>>>>>>> +       are allowed. The pattern #define x x is also allowed.
>>>>>>>>>
>>>>>>>>> Just for me to know what exactly is covered (hence also a question
>>>>>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>>>>>>>> the above would be sufficient (and imo better) people frequently
>>>>>>>>> write
>>>>>>>>>
>>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>>
>>>>>>>>> which, transformed to the specific case here, would then be
>>>>>>>>>
>>>>>>>>> #define a(x, y) a(x, y)
>>>>>>>>>
>>>>>>>>> I'd assume such ought to also be covered, but that's not clear
>>>>>>>>> from the spelling above.
>>>>>>>>
>>>>>>>> I list what happens in some different situations,
>>>>>>>> then we can find the right words for the documentation and/or
>>>>>>>> refine the configuration:
>>>>>>>>
>>>>>>>> If you
>>>>>>>> #define x x
>>>>>>>> and then use `x' as identifier,
>>>>>>>> the resulting violation is deviated (allowed pattern).
>>>>>>>>
>>>>>>>> If you
>>>>>>>> #define a(x, y) a(x, y)
>>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>>> entities).
>>>>>>>> If you use identifier `a' for a callable entity, the resulting violation
>>>>>>>> is reported: the allowed pattern covers only macros expanding to their
>>>>>>>> own name, in this case the macro name is considered to be
>>>>>>>> `a' only, not a(x, y).
>>>>>>>>
>>>>>>>> If you
>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>>> entities).
>>>>>>>
>>>>>>> I'm afraid I don't see what violation there is in this case, to
>>>>>>> deviate. As a result I'm also not sure I correctly understand the
>>>>>>> rest of your reply.
>>>>>>
>>>>>> #define a(x, y) b(x, y)
>>>>>>
>>>>>> int a; // Violation of Rule 5.5.
>>>>>>
>>>>>> The macro name `a' that exist before the preprocessing phase,
>>>>>> still exists after the preprocessing phase as identifier for the integer
>>>>>> variable and this is a violation.
>>>>>>
>>>>>>>> If you use `a' as identifier for a callable entity,
>>>>>>>> this is not a violation because after the preprocessing phase,
>>>>>>>> identifier `a' no longer exists.
>>>>>> I correct myself:
>>>>>> if you use `a' as identifier for a *function*,
>>>>>> it is not a violation because after the preprocessing phase
>>>>>> the identifier `a' no longer exists, for example:
>>>>>>
>>>>>> #define a(x, y) b(x, y)
>>>>>>
>>>>>> void a(int x, int y); // Ok.
>>>>>
>>>>> Federico, do you have a better wording suggestion for this rule?
>>>>>
>>>>> Jan, any further requests here? What would you like to see as next step?
>>>>
>>>> A more concise wording proposal would probably help.
>>>
>>> What do you think about:
>>>
>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>> index 1e134ccebc..a975b9a85f 100644
>>> --- a/docs/misra/rules.rst
>>> +++ b/docs/misra/rules.rst
>>> @@ -181,6 +181,13 @@ maintainers if you want to suggest a change.
>>>           headers (xen/include/public/) are allowed to retain longer
>>>           identifiers for backward compatibility.
>>>
>>> +   * - `Rule 5.5
>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>> +     - Required
>>> +     - Identifiers shall be distinct from macro names
>>> +     - Macros expanding to their own name are allowed (e.g., #define x x).
>>> +       Clashes between names of function-like macros and identifiers of
>>> +       non-callable entities are allowed.
>>
>> Imo that still leaves open e.g. the
>>
>> #define a(x, y) a(x, y)
>>
>> case: Permitted ("own name") or not permitted ("a" pretty clearly is expected
>> to be a callable entity here, besides being a function-like macro)?
> 
> I would not consider your example as a macro that expands to its own
> name, the macro name is considered to be `a' only.

That's what I was assuming, and hence my asking back. I think the
above ought to be permitted just like "#define x x", and hence the
suggested text would need expanding, to ...

> Rather, you example can be used to trigger the "callable-noncallable"
> part of the deviation, for example:
> 
> #define a(x, y) a(x, y)
> 
> void a(int x, int y); /* Not permitted (callable entity 'a'). */

... prevent this ("not permitted") from happening. I'm pretty sure
you've already found instances of this pattern in our code base.

Jan

> void foo(int a);      /* Permitted (non-callable entity `a'). */
> 

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Stefano Stabellini]

On Mon, 4 Mar 2024, Jan Beulich wrote:
> On 04.03.2024 16:39, Federico Serafini wrote:
> > On 04/03/24 15:17, Jan Beulich wrote:
> >> On 04.03.2024 14:31, Federico Serafini wrote:
> >>> On 01/03/24 09:06, Jan Beulich wrote:
> >>>> On 01.03.2024 00:28, Stefano Stabellini wrote:
> >>>>> On Wed, 14 Feb 2024, Federico Serafini wrote:
> >>>>>> On 14/02/24 14:15, Jan Beulich wrote:
> >>>>>>> On 14.02.2024 12:27, Federico Serafini wrote:
> >>>>>>>> On 14/02/24 09:28, Jan Beulich wrote:
> >>>>>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
> >>>>>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
> >>>>>>>>>> ---
> >>>>>>>>>>      docs/misra/rules.rst | 6 ++++++
> >>>>>>>>>>      1 file changed, 6 insertions(+)
> >>>>>>>>>>
> >>>>>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> >>>>>>>>>> index c185366966..931158b354 100644
> >>>>>>>>>> --- a/docs/misra/rules.rst
> >>>>>>>>>> +++ b/docs/misra/rules.rst
> >>>>>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
> >>>>>>>>>>             headers (xen/include/public/) are allowed to retain longer
> >>>>>>>>>>             identifiers for backward compatibility.
> >>>>>>>>>>      +   * - `Rule 5.5
> >>>>>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
> >>>>>>>>>> +     - Required
> >>>>>>>>>> +     - Identifiers shall be distinct from macro names
> >>>>>>>>>> +     - Clashes between function-like macros and non-callable entities
> >>>>>>>>>> +       are allowed. The pattern #define x x is also allowed.
> >>>>>>>>>
> >>>>>>>>> Just for me to know what exactly is covered (hence also a question
> >>>>>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
> >>>>>>>>> the above would be sufficient (and imo better) people frequently
> >>>>>>>>> write
> >>>>>>>>>
> >>>>>>>>> #define a(x, y) b(x, y)
> >>>>>>>>>
> >>>>>>>>> which, transformed to the specific case here, would then be
> >>>>>>>>>
> >>>>>>>>> #define a(x, y) a(x, y)
> >>>>>>>>>
> >>>>>>>>> I'd assume such ought to also be covered, but that's not clear
> >>>>>>>>> from the spelling above.
> >>>>>>>>
> >>>>>>>> I list what happens in some different situations,
> >>>>>>>> then we can find the right words for the documentation and/or
> >>>>>>>> refine the configuration:
> >>>>>>>>
> >>>>>>>> If you
> >>>>>>>> #define x x
> >>>>>>>> and then use `x' as identifier,
> >>>>>>>> the resulting violation is deviated (allowed pattern).
> >>>>>>>>
> >>>>>>>> If you
> >>>>>>>> #define a(x, y) a(x, y)
> >>>>>>>> and then use `a' as identifier for a non-callable entity,
> >>>>>>>> the resulting violation is deviated (no clash with non-callable
> >>>>>>>> entities).
> >>>>>>>> If you use identifier `a' for a callable entity, the resulting violation
> >>>>>>>> is reported: the allowed pattern covers only macros expanding to their
> >>>>>>>> own name, in this case the macro name is considered to be
> >>>>>>>> `a' only, not a(x, y).
> >>>>>>>>
> >>>>>>>> If you
> >>>>>>>> #define a(x, y) b(x, y)
> >>>>>>>> and then use `a' as identifier for a non-callable entity,
> >>>>>>>> the resulting violation is deviated (no clash with non-callable
> >>>>>>>> entities).
> >>>>>>>
> >>>>>>> I'm afraid I don't see what violation there is in this case, to
> >>>>>>> deviate. As a result I'm also not sure I correctly understand the
> >>>>>>> rest of your reply.
> >>>>>>
> >>>>>> #define a(x, y) b(x, y)
> >>>>>>
> >>>>>> int a; // Violation of Rule 5.5.
> >>>>>>
> >>>>>> The macro name `a' that exist before the preprocessing phase,
> >>>>>> still exists after the preprocessing phase as identifier for the integer
> >>>>>> variable and this is a violation.
> >>>>>>
> >>>>>>>> If you use `a' as identifier for a callable entity,
> >>>>>>>> this is not a violation because after the preprocessing phase,
> >>>>>>>> identifier `a' no longer exists.
> >>>>>> I correct myself:
> >>>>>> if you use `a' as identifier for a *function*,
> >>>>>> it is not a violation because after the preprocessing phase
> >>>>>> the identifier `a' no longer exists, for example:
> >>>>>>
> >>>>>> #define a(x, y) b(x, y)
> >>>>>>
> >>>>>> void a(int x, int y); // Ok.
> >>>>>
> >>>>> Federico, do you have a better wording suggestion for this rule?
> >>>>>
> >>>>> Jan, any further requests here? What would you like to see as next step?
> >>>>
> >>>> A more concise wording proposal would probably help.
> >>>
> >>> What do you think about:
> >>>
> >>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
> >>> index 1e134ccebc..a975b9a85f 100644
> >>> --- a/docs/misra/rules.rst
> >>> +++ b/docs/misra/rules.rst
> >>> @@ -181,6 +181,13 @@ maintainers if you want to suggest a change.
> >>>           headers (xen/include/public/) are allowed to retain longer
> >>>           identifiers for backward compatibility.
> >>>
> >>> +   * - `Rule 5.5
> >>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
> >>> +     - Required
> >>> +     - Identifiers shall be distinct from macro names
> >>> +     - Macros expanding to their own name are allowed (e.g., #define x x).
> >>> +       Clashes between names of function-like macros and identifiers of
> >>> +       non-callable entities are allowed.
> >>
> >> Imo that still leaves open e.g. the
> >>
> >> #define a(x, y) a(x, y)
> >>
> >> case: Permitted ("own name") or not permitted ("a" pretty clearly is expected
> >> to be a callable entity here, besides being a function-like macro)?
> > 
> > I would not consider your example as a macro that expands to its own
> > name, the macro name is considered to be `a' only.
> 
> That's what I was assuming, and hence my asking back. I think the
> above ought to be permitted just like "#define x x", and hence the
> suggested text would need expanding, to ...
> 
> > Rather, you example can be used to trigger the "callable-noncallable"
> > part of the deviation, for example:
> > 
> > #define a(x, y) a(x, y)
> > 
> > void a(int x, int y); /* Not permitted (callable entity 'a'). */
> 
> ... prevent this ("not permitted") from happening. I'm pretty sure
> you've already found instances of this pattern in our code base.

Sorry Jan, purely asking as a clarification because I couldn't
understand what you wrote.

You are asking for a clarification in the wording so that the following
is explicitly allowed, right?

#define a(x, y) a(x, y)
void a(int x, int y);

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Jan Beulich]

On 05.03.2024 02:49, Stefano Stabellini wrote:
> On Mon, 4 Mar 2024, Jan Beulich wrote:
>> On 04.03.2024 16:39, Federico Serafini wrote:
>>> On 04/03/24 15:17, Jan Beulich wrote:
>>>> On 04.03.2024 14:31, Federico Serafini wrote:
>>>>> On 01/03/24 09:06, Jan Beulich wrote:
>>>>>> On 01.03.2024 00:28, Stefano Stabellini wrote:
>>>>>>> On Wed, 14 Feb 2024, Federico Serafini wrote:
>>>>>>>> On 14/02/24 14:15, Jan Beulich wrote:
>>>>>>>>> On 14.02.2024 12:27, Federico Serafini wrote:
>>>>>>>>>> On 14/02/24 09:28, Jan Beulich wrote:
>>>>>>>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>>>>>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>>>>>>>>>> ---
>>>>>>>>>>>>      docs/misra/rules.rst | 6 ++++++
>>>>>>>>>>>>      1 file changed, 6 insertions(+)
>>>>>>>>>>>>
>>>>>>>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>>>>>>>>> index c185366966..931158b354 100644
>>>>>>>>>>>> --- a/docs/misra/rules.rst
>>>>>>>>>>>> +++ b/docs/misra/rules.rst
>>>>>>>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>>>>>>>>>             headers (xen/include/public/) are allowed to retain longer
>>>>>>>>>>>>             identifiers for backward compatibility.
>>>>>>>>>>>>      +   * - `Rule 5.5
>>>>>>>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>>>>>>>>> +     - Required
>>>>>>>>>>>> +     - Identifiers shall be distinct from macro names
>>>>>>>>>>>> +     - Clashes between function-like macros and non-callable entities
>>>>>>>>>>>> +       are allowed. The pattern #define x x is also allowed.
>>>>>>>>>>>
>>>>>>>>>>> Just for me to know what exactly is covered (hence also a question
>>>>>>>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>>>>>>>>>> the above would be sufficient (and imo better) people frequently
>>>>>>>>>>> write
>>>>>>>>>>>
>>>>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>>>>
>>>>>>>>>>> which, transformed to the specific case here, would then be
>>>>>>>>>>>
>>>>>>>>>>> #define a(x, y) a(x, y)
>>>>>>>>>>>
>>>>>>>>>>> I'd assume such ought to also be covered, but that's not clear
>>>>>>>>>>> from the spelling above.
>>>>>>>>>>
>>>>>>>>>> I list what happens in some different situations,
>>>>>>>>>> then we can find the right words for the documentation and/or
>>>>>>>>>> refine the configuration:
>>>>>>>>>>
>>>>>>>>>> If you
>>>>>>>>>> #define x x
>>>>>>>>>> and then use `x' as identifier,
>>>>>>>>>> the resulting violation is deviated (allowed pattern).
>>>>>>>>>>
>>>>>>>>>> If you
>>>>>>>>>> #define a(x, y) a(x, y)
>>>>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>>>>> entities).
>>>>>>>>>> If you use identifier `a' for a callable entity, the resulting violation
>>>>>>>>>> is reported: the allowed pattern covers only macros expanding to their
>>>>>>>>>> own name, in this case the macro name is considered to be
>>>>>>>>>> `a' only, not a(x, y).
>>>>>>>>>>
>>>>>>>>>> If you
>>>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>>>>> entities).
>>>>>>>>>
>>>>>>>>> I'm afraid I don't see what violation there is in this case, to
>>>>>>>>> deviate. As a result I'm also not sure I correctly understand the
>>>>>>>>> rest of your reply.
>>>>>>>>
>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>
>>>>>>>> int a; // Violation of Rule 5.5.
>>>>>>>>
>>>>>>>> The macro name `a' that exist before the preprocessing phase,
>>>>>>>> still exists after the preprocessing phase as identifier for the integer
>>>>>>>> variable and this is a violation.
>>>>>>>>
>>>>>>>>>> If you use `a' as identifier for a callable entity,
>>>>>>>>>> this is not a violation because after the preprocessing phase,
>>>>>>>>>> identifier `a' no longer exists.
>>>>>>>> I correct myself:
>>>>>>>> if you use `a' as identifier for a *function*,
>>>>>>>> it is not a violation because after the preprocessing phase
>>>>>>>> the identifier `a' no longer exists, for example:
>>>>>>>>
>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>
>>>>>>>> void a(int x, int y); // Ok.
>>>>>>>
>>>>>>> Federico, do you have a better wording suggestion for this rule?
>>>>>>>
>>>>>>> Jan, any further requests here? What would you like to see as next step?
>>>>>>
>>>>>> A more concise wording proposal would probably help.
>>>>>
>>>>> What do you think about:
>>>>>
>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>> index 1e134ccebc..a975b9a85f 100644
>>>>> --- a/docs/misra/rules.rst
>>>>> +++ b/docs/misra/rules.rst
>>>>> @@ -181,6 +181,13 @@ maintainers if you want to suggest a change.
>>>>>           headers (xen/include/public/) are allowed to retain longer
>>>>>           identifiers for backward compatibility.
>>>>>
>>>>> +   * - `Rule 5.5
>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>> +     - Required
>>>>> +     - Identifiers shall be distinct from macro names
>>>>> +     - Macros expanding to their own name are allowed (e.g., #define x x).
>>>>> +       Clashes between names of function-like macros and identifiers of
>>>>> +       non-callable entities are allowed.
>>>>
>>>> Imo that still leaves open e.g. the
>>>>
>>>> #define a(x, y) a(x, y)
>>>>
>>>> case: Permitted ("own name") or not permitted ("a" pretty clearly is expected
>>>> to be a callable entity here, besides being a function-like macro)?
>>>
>>> I would not consider your example as a macro that expands to its own
>>> name, the macro name is considered to be `a' only.
>>
>> That's what I was assuming, and hence my asking back. I think the
>> above ought to be permitted just like "#define x x", and hence the
>> suggested text would need expanding, to ...
>>
>>> Rather, you example can be used to trigger the "callable-noncallable"
>>> part of the deviation, for example:
>>>
>>> #define a(x, y) a(x, y)
>>>
>>> void a(int x, int y); /* Not permitted (callable entity 'a'). */
>>
>> ... prevent this ("not permitted") from happening. I'm pretty sure
>> you've already found instances of this pattern in our code base.
> 
> Sorry Jan, purely asking as a clarification because I couldn't
> understand what you wrote.
> 
> You are asking for a clarification in the wording so that the following
> is explicitly allowed, right?
> 
> #define a(x, y) a(x, y)
> void a(int x, int y);

Yes. (Or, less desirable, unambiguously disallowed.)

Jan

Re: [PATCH v2 2/3] docs/misra/rules.rst: add rule 5.5

[Jan Beulich]

On 04.03.2024 17:36, Jan Beulich wrote:
> On 04.03.2024 16:39, Federico Serafini wrote:
>> On 04/03/24 15:17, Jan Beulich wrote:
>>> On 04.03.2024 14:31, Federico Serafini wrote:
>>>> On 01/03/24 09:06, Jan Beulich wrote:
>>>>> On 01.03.2024 00:28, Stefano Stabellini wrote:
>>>>>> On Wed, 14 Feb 2024, Federico Serafini wrote:
>>>>>>> On 14/02/24 14:15, Jan Beulich wrote:
>>>>>>>> On 14.02.2024 12:27, Federico Serafini wrote:
>>>>>>>>> On 14/02/24 09:28, Jan Beulich wrote:
>>>>>>>>>> On 13.02.2024 23:33, Stefano Stabellini wrote:
>>>>>>>>>>> Signed-off-by: Stefano Stabellini <stefano.stabellini@amd.com>
>>>>>>>>>>> ---
>>>>>>>>>>>      docs/misra/rules.rst | 6 ++++++
>>>>>>>>>>>      1 file changed, 6 insertions(+)
>>>>>>>>>>>
>>>>>>>>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>>>>>>>>> index c185366966..931158b354 100644
>>>>>>>>>>> --- a/docs/misra/rules.rst
>>>>>>>>>>> +++ b/docs/misra/rules.rst
>>>>>>>>>>> @@ -181,6 +181,12 @@ maintainers if you want to suggest a change.
>>>>>>>>>>>             headers (xen/include/public/) are allowed to retain longer
>>>>>>>>>>>             identifiers for backward compatibility.
>>>>>>>>>>>      +   * - `Rule 5.5
>>>>>>>>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>>>>>>>>> +     - Required
>>>>>>>>>>> +     - Identifiers shall be distinct from macro names
>>>>>>>>>>> +     - Clashes between function-like macros and non-callable entities
>>>>>>>>>>> +       are allowed. The pattern #define x x is also allowed.
>>>>>>>>>>
>>>>>>>>>> Just for me to know what exactly is covered (hence also a question
>>>>>>>>>> to Roberto as to [to be] implemented Eclair behavior): Even when
>>>>>>>>>> the above would be sufficient (and imo better) people frequently
>>>>>>>>>> write
>>>>>>>>>>
>>>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>>>
>>>>>>>>>> which, transformed to the specific case here, would then be
>>>>>>>>>>
>>>>>>>>>> #define a(x, y) a(x, y)
>>>>>>>>>>
>>>>>>>>>> I'd assume such ought to also be covered, but that's not clear
>>>>>>>>>> from the spelling above.
>>>>>>>>>
>>>>>>>>> I list what happens in some different situations,
>>>>>>>>> then we can find the right words for the documentation and/or
>>>>>>>>> refine the configuration:
>>>>>>>>>
>>>>>>>>> If you
>>>>>>>>> #define x x
>>>>>>>>> and then use `x' as identifier,
>>>>>>>>> the resulting violation is deviated (allowed pattern).
>>>>>>>>>
>>>>>>>>> If you
>>>>>>>>> #define a(x, y) a(x, y)
>>>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>>>> entities).
>>>>>>>>> If you use identifier `a' for a callable entity, the resulting violation
>>>>>>>>> is reported: the allowed pattern covers only macros expanding to their
>>>>>>>>> own name, in this case the macro name is considered to be
>>>>>>>>> `a' only, not a(x, y).
>>>>>>>>>
>>>>>>>>> If you
>>>>>>>>> #define a(x, y) b(x, y)
>>>>>>>>> and then use `a' as identifier for a non-callable entity,
>>>>>>>>> the resulting violation is deviated (no clash with non-callable
>>>>>>>>> entities).
>>>>>>>>
>>>>>>>> I'm afraid I don't see what violation there is in this case, to
>>>>>>>> deviate. As a result I'm also not sure I correctly understand the
>>>>>>>> rest of your reply.
>>>>>>>
>>>>>>> #define a(x, y) b(x, y)
>>>>>>>
>>>>>>> int a; // Violation of Rule 5.5.
>>>>>>>
>>>>>>> The macro name `a' that exist before the preprocessing phase,
>>>>>>> still exists after the preprocessing phase as identifier for the integer
>>>>>>> variable and this is a violation.
>>>>>>>
>>>>>>>>> If you use `a' as identifier for a callable entity,
>>>>>>>>> this is not a violation because after the preprocessing phase,
>>>>>>>>> identifier `a' no longer exists.
>>>>>>> I correct myself:
>>>>>>> if you use `a' as identifier for a *function*,
>>>>>>> it is not a violation because after the preprocessing phase
>>>>>>> the identifier `a' no longer exists, for example:
>>>>>>>
>>>>>>> #define a(x, y) b(x, y)
>>>>>>>
>>>>>>> void a(int x, int y); // Ok.
>>>>>>
>>>>>> Federico, do you have a better wording suggestion for this rule?
>>>>>>
>>>>>> Jan, any further requests here? What would you like to see as next step?
>>>>>
>>>>> A more concise wording proposal would probably help.
>>>>
>>>> What do you think about:
>>>>
>>>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>>>> index 1e134ccebc..a975b9a85f 100644
>>>> --- a/docs/misra/rules.rst
>>>> +++ b/docs/misra/rules.rst
>>>> @@ -181,6 +181,13 @@ maintainers if you want to suggest a change.
>>>>           headers (xen/include/public/) are allowed to retain longer
>>>>           identifiers for backward compatibility.
>>>>
>>>> +   * - `Rule 5.5
>>>> <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_05_05.c>`_
>>>> +     - Required
>>>> +     - Identifiers shall be distinct from macro names
>>>> +     - Macros expanding to their own name are allowed (e.g., #define x x).
>>>> +       Clashes between names of function-like macros and identifiers of
>>>> +       non-callable entities are allowed.
>>>
>>> Imo that still leaves open e.g. the
>>>
>>> #define a(x, y) a(x, y)
>>>
>>> case: Permitted ("own name") or not permitted ("a" pretty clearly is expected
>>> to be a callable entity here, besides being a function-like macro)?
>>
>> I would not consider your example as a macro that expands to its own
>> name, the macro name is considered to be `a' only.
> 
> That's what I was assuming, and hence my asking back. I think the
> above ought to be permitted just like "#define x x", and hence the
> suggested text would need expanding, to ...
> 
>> Rather, you example can be used to trigger the "callable-noncallable"
>> part of the deviation, for example:
>>
>> #define a(x, y) a(x, y)
>>
>> void a(int x, int y); /* Not permitted (callable entity 'a'). */
> 
> ... prevent this ("not permitted") from happening. I'm pretty sure
> you've already found instances of this pattern in our code base.

And btw, see https://lists.xen.org/archives/html/xen-devel/2024-03/msg00159.html
for yet another slightly different pattern that I'd rather not see becoming
"forbidden".

Jan