Re: [XEN PATCH] docs/misra: document the C dialect and translation toolchain assumptions.

[Roberto Bagnara <roberto.bagnara@xxxxxxxxxxx>]

On 16/06/23 01:26, Stefano Stabellini wrote:
> On Thu, 15 Jun 2023, Roberto Bagnara wrote:
> > This document specifies the C language dialect used by Xen and
> > the assumptions Xen makes on the translation toolchain.
> >
> > Signed-off-by: Roberto Bagnara <roberto.bagnara@xxxxxxxxxxx>
> Thanks Roberto for the amazing work of research and archaeology.
>
> I have a few comments below, mostly to clarify the description of some
> of the less documented GCC extensions, for the purpose of having all
> community members be able to understand what they can and cannot use.
> > +   * - Arithmetic operator on void type
> > +     - ARM64, X86_64
> > +     - See Section "6.24 Arithmetic on void- and Function-Pointers" of 
> > GCC_MANUAL."
> > +
> > +   * - GNU statement expression
> "GNU statement expression" is not very clear, at least for me. I would
> call it "Statements and Declarations in Expressions".
Agreed.

> > +   * - Empty declaration
> > +     - ARM64, X86_64
> > +     - Non-documented GCC extension.
> For the non-documented GCC extensions, would it be possible to add a
> very brief example or a couple of words in the "References" sections?
> Otherwise I think people might not understand what we are talking about.
Ok.

> > +   * - Incomplete enum declaration
> > +     - ARM64
> > +     - Non-documented GCC extension.
> Is this 6.49 of the GCC manual perhaps?
Indeed, on a second reading, I think that section covers also the case
of an enum declaration that is never completed in the course of the
translation unit.

> > +   * - Implicit conversion from a pointer to an incompatible pointer
> > +     - ARM64, X86_64
> > +     - Non-documented GCC extension.
> Is this related to -Wincompatible-pointer-types?
In my opinion, this does not specify what the result of the
conversion is.

> > +   * - Pointer to a function is converted to a pointer to an object or a 
> > pointer to an object is converted to a pointer to a function
> > +     - X86_64
> > +     - Non-documented GCC extension.
> Is this J.5.7 of n1570?
> https://www.iso-9899.info/n1570.html
This says that function pointer casts are a common extension.
What we need here is documentation for GCC that assures us
that the extension is implemented and what its semantics is.

> Or maybe we should link https://gcc.gnu.org/bugzilla/show_bug.cgi?id=83584
My opinion is that this might not be accepted by an assessor:
if I was an assessor, I would not accept it.

> > +   * - Ill-formed source detected by the parser
> As we are documenting compiler extensions that we are using, I am a bit
> confused by the name of this category of compiler extensions, and the
> reason why they are bundled together. After all, they are all separate
> compiler extensions? Should each of them have their own row?
Agreed.

> > +     - ARM64, X86_64
> > +     - token pasting of ',' and __VA_ARGS__ is a GNU extension:
> > +          see Section "6.21 Macros with a Variable Number of Arguments" of 
> > GCC_MANUAL.
> > +       must specify at least one argument for '...' parameter of variadic 
> > macro:
> > +          see Section "6.21 Macros with a Variable Number of Arguments" of 
> > GCC_MANUAL.
> > +       void function should not return void expression:
> I understand that GCC does a poor job at documenting several of these
> extensions. In fact a few of them are not even documented at all.
> However, if they are extensions, they should be described for what they
> do, not for the rule they violate. What do you think?
The point is that we don't know what they do.  We might make observations,
and our observations might substantiate what we believe they do.
But this would not allow us to generalize them.

> For example, in this case maybe we should say "void function can return
> a void expression" ?
We can certainly say that, but this might not convince an assessor.
One possibility would be to submit patches to the GCC manual and see
whether they are accepted.

> > +          see the documentation for -Wreturn-type in Section "3.8 Options to 
> > Request or Suppress Warnings" of GCC_MANUAL.
> > +       use of GNU statement expression extension from macro expansion:
> > +          see Section "6.1 Statements and Declarations in Expressions" of 
> > GCC_MANUAL.
> > +       invalid application of sizeof to a void type:
> > +          see Section "6.24 Arithmetic on void- and Function-Pointers" of 
> > GCC_MANUAL.
> > +       redeclaration of already-defined enum is a GNU extension:
> > +          see Section "6.49 Incomplete enum Types" of GCC_MANUAL.
> > +       static function is used in an inline function with external linkage:
> > +          non-documented GCC extension.
> I am not sure if I follow about this one. Did you mean "static is used
> in an inline function with external linkage" ?
An inline function with external linkage can be inlined everywhere.
If that calls a static functions, which is not available everywhere,
the behavior is not defined.

> > +       struct may not be nested in a struct due to flexible array member:
> > +          see Section "6.18 Arrays of Length Zero" of GCC_MANUAL.
> > +       struct may not be used as an array element due to flexible array member:
> > +          see Section "6.18 Arrays of Length Zero" of GCC_MANUAL.
> > +       ISO C restricts enumerator values to the range of int:
> > +          non-documented GCC extension.
> Should we call it instead "enumerator values can be larger than int" ?
Yes, I have rephrased that entry.

> > +   * - Unspecified escape sequence is encountered in a character constant or a 
> > string literal token
> > +     - X86_64
> > +     - \\m:
> > +          non-documented GCC extension.
> Are you saying that we are using \m and \m is not allowed by the C
> standard?
The C standard does not specify that escape sequence, so what is
done with it, in particular by the preprocessor, is not specified.

> > +   * - Non-standard type
> Should we call it "128-bit Integers" ?
I have rephrased this as suggested by Jan.

Thanks for your review.  I will submit a revised patch
on Monday.
Kind regards,

    Roberto