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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

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@xxxxxxx>
> >>>>>>>>>> ---
> >>>>>>>>>>      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);