[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


  • To: Stefano Stabellini <sstabellini@xxxxxxxxxx>
  • From: Jan Beulich <jbeulich@xxxxxxxx>
  • Date: Mon, 30 Sep 2024 10:58:37 +0200
  • Autocrypt: addr=jbeulich@xxxxxxxx; keydata= xsDiBFk3nEQRBADAEaSw6zC/EJkiwGPXbWtPxl2xCdSoeepS07jW8UgcHNurfHvUzogEq5xk hu507c3BarVjyWCJOylMNR98Yd8VqD9UfmX0Hb8/BrA+Hl6/DB/eqGptrf4BSRwcZQM32aZK 7Pj2XbGWIUrZrd70x1eAP9QE3P79Y2oLrsCgbZJfEwCgvz9JjGmQqQkRiTVzlZVCJYcyGGsD /0tbFCzD2h20ahe8rC1gbb3K3qk+LpBtvjBu1RY9drYk0NymiGbJWZgab6t1jM7sk2vuf0Py O9Hf9XBmK0uE9IgMaiCpc32XV9oASz6UJebwkX+zF2jG5I1BfnO9g7KlotcA/v5ClMjgo6Gl MDY4HxoSRu3i1cqqSDtVlt+AOVBJBACrZcnHAUSuCXBPy0jOlBhxPqRWv6ND4c9PH1xjQ3NP nxJuMBS8rnNg22uyfAgmBKNLpLgAGVRMZGaGoJObGf72s6TeIqKJo/LtggAS9qAUiuKVnygo 3wjfkS9A3DRO+SpU7JqWdsveeIQyeyEJ/8PTowmSQLakF+3fote9ybzd880fSmFuIEJldWxp Y2ggPGpiZXVsaWNoQHN1c2UuY29tPsJgBBMRAgAgBQJZN5xEAhsDBgsJCAcDAgQVAggDBBYC AwECHgECF4AACgkQoDSui/t3IH4J+wCfQ5jHdEjCRHj23O/5ttg9r9OIruwAn3103WUITZee e7Sbg12UgcQ5lv7SzsFNBFk3nEQQCACCuTjCjFOUdi5Nm244F+78kLghRcin/awv+IrTcIWF hUpSs1Y91iQQ7KItirz5uwCPlwejSJDQJLIS+QtJHaXDXeV6NI0Uef1hP20+y8qydDiVkv6l IreXjTb7DvksRgJNvCkWtYnlS3mYvQ9NzS9PhyALWbXnH6sIJd2O9lKS1Mrfq+y0IXCP10eS FFGg+Av3IQeFatkJAyju0PPthyTqxSI4lZYuJVPknzgaeuJv/2NccrPvmeDg6Coe7ZIeQ8Yj t0ARxu2xytAkkLCel1Lz1WLmwLstV30g80nkgZf/wr+/BXJW/oIvRlonUkxv+IbBM3dX2OV8 AmRv1ySWPTP7AAMFB/9PQK/VtlNUJvg8GXj9ootzrteGfVZVVT4XBJkfwBcpC/XcPzldjv+3 HYudvpdNK3lLujXeA5fLOH+Z/G9WBc5pFVSMocI71I8bT8lIAzreg0WvkWg5V2WZsUMlnDL9 mpwIGFhlbM3gfDMs7MPMu8YQRFVdUvtSpaAs8OFfGQ0ia3LGZcjA6Ik2+xcqscEJzNH+qh8V m5jjp28yZgaqTaRbg3M/+MTbMpicpZuqF4rnB0AQD12/3BNWDR6bmh+EkYSMcEIpQmBM51qM EKYTQGybRCjpnKHGOxG0rfFY1085mBDZCH5Kx0cl0HVJuQKC+dV2ZY5AqjcKwAxpE75MLFkr wkkEGBECAAkFAlk3nEQCGwwACgkQoDSui/t3IH7nnwCfcJWUDUFKdCsBH/E5d+0ZnMQi+G0A nAuWpQkjM1ASeQwSHEeAWPgskBQL
  • Cc: Alessandro Zucchelli <alessandro.zucchelli@xxxxxxxxxxx>, consulting@xxxxxxxxxxx, Andrew Cooper <andrew.cooper3@xxxxxxxxxx>, Julien Grall <julien@xxxxxxx>, xen-devel@xxxxxxxxxxxxxxxxxxxx
  • Delivery-date: Mon, 30 Sep 2024 08:58:49 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>

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.
- 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



 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.