[xen master] CODING_STYLE: header file guard naming rules

[patchbot@xxxxxxx]

commit a7201c021174efc908d939079db5bb2f89962a0d
Author:     Jan Beulich <jbeulich@xxxxxxxx>
AuthorDate: Mon Oct 7 11:10:05 2024 +0200
Commit:     Jan Beulich <jbeulich@xxxxxxxx>
CommitDate: Mon Oct 7 11:10:05 2024 +0200

    CODING_STYLE: header file guard naming rules
    
    Provide a (small) set of rules on how header guard identifiers ought to
    be spelled and what precautions ought to be taken to avoid name
    collisions.
    
    Signed-off-by: Jan Beulich <jbeulich@xxxxxxxx>
    Acked-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
---
 CODING_STYLE | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/CODING_STYLE b/CODING_STYLE
index 7f6e9ad065..554c69a16a 100644
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -153,6 +153,48 @@ E.g. timer-works.
 Note that some of the options and filenames are using '_'. This is now
 deprecated.
 
+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.
+- Certain directory components are omitted, to keep identifier length
+  bounded:
+  - the top level include/,
+  - architecture-specific private files' arch/,
+  - any architecture's arch/<arch>/include/asm/ collapses to
+    ASM__<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 other 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
+adding a new subdirectory, check the rules to prevent any potential
+collisions.
+
 Emacs local variables
 ---------------------
 
--
generated by git-patchbot for /home/xen/git/xen.git#master