[xen staging] CODING_STYLE: Updated header guard recommendations

[patchbot@xxxxxxx]

commit 7abea85c9f128556da2fdb08dd74c7e2489da7ea
Author:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
AuthorDate: Fri May 16 15:20:31 2025 +0100
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Fri May 16 23:54:05 2025 +0100

    CODING_STYLE: Updated header guard recommendations
    
    Despite the best intentions at the time, the current recommendation
    lead to very long identifiers, bordering on the max limit we've chosen
    for certification.
    
    One observation is that we do have static analysis which will
    highlight if duplicate guards are created accidentally.
    
    Therefore, relax the recommendations and in particular remove the
    specific tie to the directory structure.  This has the other advantage
    of being more similar to other projects.
    
    This will hopefully mean there's less churn getting the tree in shape,
    and a random contributor is more likely to pick an appropriate guard
    given no specific knowledge of Xen.
    
    As always, it's something reviewers and maintainers should be aware
    of, and to advise on.
    
    Reviewed-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
    Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
---
 CODING_STYLE | 49 ++++++++++++++++++-------------------------------
 1 file changed, 18 insertions(+), 31 deletions(-)

diff --git a/CODING_STYLE b/CODING_STYLE
index e3b1da6048..5644f1697f 100644
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -157,43 +157,30 @@ 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>__.
+guards to prevent multiple inclusions.  Guards need to be unique, and
+this property is checked by static analysis.
 
-For example:
+Guards should be chosen based on the logical area, with enough
+disambiguation when the same filename exits in multiple locations in
+the source tree.  Commonly there should be a XEN or <arch> prefix.
+The guard should be spelt in ALL CAPITALS, ending with _H.
 
-- Xen headers: XEN__<filename>_H
-  - include/xen/something.h -> XEN__SOMETHING_H
+For example:
 
-- asm-generic headers: ASM_GENERIC__<filename>_H
-  - include/asm-generic/something.h -> ASM_GENERIC__SOMETHING_H
+- Xen headers: XEN_<something>_H
+  - include/xen/something.h -> XEN_SOMETHING_H
 
-- arch-specific headers: ASM__<architecture>__<subdir>__<filename>_H
-  - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H
+- arch-specific headers: <arch>_<something>_H
+  - arch/x86/include/asm/something.h -> X86_SOMETHING_H
+  - arch/x86/include/asm/hvm/something.h -> X86_HVM_SOMETHING_H
+  - arch/x86/include/asm/pv/something.h -> X86_PV_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
+- Private headers: <something>_PRIVATE_H
+  - common/something/private.h -> <SOMETHING>_PRIVATE_H
+  - drivers/foo/something.h -> <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.
+A good choice of guard is one that wont become stale if the
+driver/subsystem/etc is shuffled around the source tree.
 
 Emacs local variables
 ---------------------
--
generated by git-patchbot for /home/xen/git/xen.git#staging