From ca935d1107ccc3ba77cc6915360f17f38e2f328d Mon Sep 17 00:00:00 2001 From: Julius Werner Date: Tue, 2 Feb 2021 16:27:57 -0800 Subject: [PATCH] Documentation: Codify some guidelines for headers and chain-including MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There has been some repeated discussion about how header includes should be formatted, specifically on the topic of chain-including. The coding style currently doesn't say anything about the topic but clearly people have some basic assumptions. This patch tries to codify some common ground rules that are supposed to reflect the existing practice. Signed-off-by: Julius Werner Change-Id: Ibbcde306a814f52b3a41b58c7a33bdd99b0187e0 Reviewed-on: https://review.coreboot.org/c/coreboot/+/50247 Tested-by: build bot (Jenkins) Reviewed-by: Kyösti Mälkki Reviewed-by: HAOUAS Elyes Reviewed-by: Angel Pons --- Documentation/coding_style.md | 49 ++++++++++++++++++++++++++++------- 1 file changed, 39 insertions(+), 10 deletions(-) diff --git a/Documentation/coding_style.md b/Documentation/coding_style.md index ac0de4ea9d..ca45096744 100644 --- a/Documentation/coding_style.md +++ b/Documentation/coding_style.md @@ -834,22 +834,51 @@ subject to this rule. Generally they indicate failure by returning some out-of-range result. Typical examples would be functions that return pointers; they use NULL or the ERR_PTR mechanism to report failure. -Don't re-invent the kernel macros ----------------------------------- +Headers and includes +--------------- -The header file include/linux/kernel.h contains a number of macros that -you should use, rather than explicitly coding some variant of them -yourself. For example, if you need to calculate the length of an array, -take advantage of the macro +Headers should always be included at the top of the file, preferrably in +alphabetical order. Includes should always use the `#include ` +notation, except for rare cases where a file in the same directory that +is not part of a normal include path gets included (e.g. local headers +in mainboard directories), which should use `#include "file.h"`. Headers +that can be included from both assembly files and .c files should keep +all C code wrapped in `#ifndef __ASSEMBLER__` blocks, including includes +to other headers that don't follow that provision. + +Files should generally include every header they need a definition from +directly (and not include any unnecessary extra headers). Excepted from +this are certain headers that intentionally chain-include other headers +which logically belong to them and are just factored out into a separate +location for implementation or organizatory reasons. This could be +because part of the definitions is generic and part SoC-specific (e.g. +`` chain-including ``), architecture-specific (e.g. +`` chain-including ``), separated out into +commonlib[/bsd] for sharing/license reasons (e.g. `` +chain-including ``) or just split out +to make organizing subunits of a larger header easier. This can also +happen when certain definitions need to be in a specific header for +legacy POSIX reasons but we would like to logically group them together +(e.g. `uintptr_t` is in `` and `size_t` in ``, but +it's nicer to be able to just include `` and get all the common +type and helper function stuff we need everywhere). + +The headers ``, `` and `` +are always automatically included in all compilation units by the build +system and should not be included manually. + +Don't re-invent common macros +----------------------------- + +The header file `src/commonlib/bsd/include/commonlib/bsd/helpers.h` +contains a number of macros that you should use, rather than explicitly +coding some variant of them yourself. For example, if you need to +calculate the length of an array, take advantage of the macro ```c #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) ``` -There are also min() and max() macros that do strict type checking if -you need them. Feel free to peruse that header file to see what else is -already defined that you shouldn't reproduce in your code. - Editor modelines and other cruft --------------------------------