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: +guards to prevent multiple inclusions. Guards need to be unique, and +this property is checked by static analysis. -- 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//include/asm/ collapses to - ASM____. +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 prefix. +The guard should be spelt in ALL CAPITALS, ending with _H. For example: -- Xen headers: XEN___H - - include/xen/something.h -> XEN__SOMETHING_H +- Xen headers: XEN__H + - include/xen/something.h -> XEN_SOMETHING_H -- asm-generic headers: ASM_GENERIC___H - - include/asm-generic/something.h -> ASM_GENERIC__SOMETHING_H +- arch-specific headers: __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_______H - - arch/x86/include/asm/something.h -> ASM__X86__SOMETHING_H +- Private headers: _PRIVATE_H + - common/something/private.h -> _PRIVATE_H + - drivers/foo/something.h -> _H -- Private headers: ___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. +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 ---------------------