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

[Federico Serafini <federico.serafini@xxxxxxxxxxx>]

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.
+
    * - `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)