Re: [XEN PATCH v6] CODING_STYLE: Add a section on header guards naming conventions

[Frediano Ziglio <frediano.ziglio@xxxxxxxxx>]

On Mon, Sep 30, 2024 at 9:58 AM Jan Beulich <jbeulich@xxxxxxxx> wrote:
>
> On 12.09.2024 03:13, Stefano Stabellini wrote:
> > Hi Jan, we have gone back and forth on this a few times, but neither
> > Alessandro nor I fully understand your perspective. To help streamline
> > the process and save time for everyone, I suggest you provide an example
> > of the rules written in the style you believe is appropriate. Once you
> > set the initial direction, Alessandro and I can continue and complete
> > the rest in that preferred style.
>
> Header inclusion guards
> -----------------------
>
> Unless otherwise specified, all header files should include proper
> guards to prevent multiple inclusions. The following naming conventions
> apply:
>
> - Guard names are derived from directory path underneath xen/ and the
>   actual file name.  Path components are separated by double underscores.
>   Alphabetic characters are converted to upper case.  Non-alphanumeric
>   characters are replaced by single underscores.

Possibly there should be no cases; but about "Non-alphanumeric
characters are replaced by single underscores" are we talking about
sequences or single entities? I would say sequences so
"Non-alphanumeric character sequences are replaced by single
underscores".
For instance "foo--bar.h" -> "FOO_BAR_H" and not "foo--bar.h" -> "FOO__BAR_H".

Another maybe not supported case is no ASCII characters in name. As
far as I can see they are not supported. Is it written somewhere?

> - Certain directory components are omitted, to keep identifier length
>   bounded:
>   - The top level include/,
>   - Any architecture's arch/<arch>/include/asm/ collapses to
>     ASM__<ARCH>__,
>   - Architecture-specific private files' arch/.
>
> For example:
>
> - Xen headers: XEN__<filename>_H
>   - include/xen/something.h -> XEN__SOMETHING_H
>
> - asm-generic headers: ASM_GENERIC__<filename>_H
>   - include/asm-generic/something.h -> ASM_GENERIC__SOMETHING_H
>
> - arch-specific headers: ASM__<architecture>__<subdir>__<filename>_H
>   - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H
>
> - Private headers: <dir>__<filename>_H
>   - arch/arm/arm64/lib/something.h -> ARM__ARM64__LIB__SOMETHING_H
>   - arch/x86/lib/something.h -> X86__LIB__SOMETHING_H
>   - common/something.h -> COMMON__SOMETHING_H
>
> Note that this requires some discipline on the naming of future new
> sub-directories: There shouldn't be any random asm/ one anywhere, for
> example.  Nor should any new ports be named the same as top-level (within
> xen/) directories.  Which may in turn require some care if any new top-
> level directories were to be added.  Rule of thumb: Whenever a new sub-
> directory is added, check the rules for no collisions to result.
>
> Jan
>

Thanks for taking time to get to a proposal.

Frediano