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@kernel.org>
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

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
+guards to prevent multiple inclusions.  Guards need to be unique, and
-apply:
+this property is checked by static analysis.
 
-- Guard names are derived from directory path underneath xen/ and the
+Guards should be chosen based on the logical area, with enough
-  actual file name.  Path components are separated by double
+disambiguation when the same filename exits in multiple locations in
-  underscores.  Alphabetic characters are converted to upper case.  Non-
+the source tree.  Commonly there should be a XEN or <arch> prefix.
-  alphanumeric characters are replaced by single underscores.
+The guard should be spelt in ALL CAPITALS, ending with _H.
-- 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
+- Xen headers: XEN_<something>_H
-  - include/xen/something.h -> XEN__SOMETHING_H
+  - include/xen/something.h -> XEN_SOMETHING_H
 
-- asm-generic headers: ASM_GENERIC__<filename>_H
+- arch-specific headers: <arch>_<something>_H
-  - include/asm-generic/something.h -> ASM_GENERIC__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
 
-- arch-specific headers: ASM__<architecture>__<subdir>__<filename>_H
+- Private headers: <something>_PRIVATE_H
-  - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H
+  - common/something/private.h -> <SOMETHING>_PRIVATE_H
+  - drivers/foo/something.h -> <SOMETHING>_H
 
-- Private headers: <dir>__<filename>_H
+A good choice of guard is one that wont become stale if the
-  - arch/arm/arm64/lib/something.h -> ARM__ARM64__LIB__SOMETHING_H
+driver/subsystem/etc is shuffled around the source tree.
-  - 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
 ---------------------