[PATCH] coding-style: Clarify the expectations around bool

From: Jason Gunthorpe
Date: Fri Dec 21 2018 - 18:29:22 EST


There has been some confusion since checkpatch started warning about bool
use in structures, and people have been avoiding using it.

Many people feel there is still a legitimate place for bool in structures,
so provide some guidance on bool usage derived from the entire thread that
spawned the checkpatch warning.

Link: https://lkml.kernel.org/r/CA+55aFwVZk1OfB9T2v014PTAKFhtVan_Zj2dOjnCy3x6E4UJfA@xxxxxxxxxxxxxx
Signed-off-by: Joe Perches <joe@xxxxxxxxxxx>
Signed-off-by: Jason Gunthorpe <jgg@xxxxxxxxxxxx>
---
Documentation/process/coding-style.rst | 33 ++++++++++++++++++++++----
1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 4e7c0a1c427a9a..efdb1d32035fe1 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -918,7 +918,32 @@ result. Typical examples would be functions that return pointers; they use
NULL or the ERR_PTR mechanism to report failure.


-17) Don't re-invent the kernel macros
+17) Using bool
+--------------
+
+The Linux kernel uses the C11 standard for the bool type. bool values can only
+evaluate to 0 or 1, and implicit or explicit conversion to bool automatically
+converts the value to true or false. When using bool types the !! construction
+is not needed, which eliminates a class of bugs.
+
+When working with bool values the true and false labels should be used instead
+of 0 and 1.
+
+bool function return types, arguments and stack variables are always fine to
+use whenever appropriate. Use of bool is encouraged to improve readability and
+is often a better option than 'int' for storing boolean values.
+
+Do not use bool if cache line layout or size of the value matters, its size
+and alignment varies based on the compiled architecture. Structures that are
+optimized for alignment and size should not use bool.
+
+If a structure has many true/false values, consider consolidating them into a
+bitfield with 1 bit members, or using an appropriate fixed width type, such as
+u8.
+
+Otherwise limited use of bool in structures does improve readability.
+
+18) Don't re-invent the kernel macros
-------------------------------------

The header file include/linux/kernel.h contains a number of macros that
@@ -941,7 +966,7 @@ need them. Feel free to peruse that header file to see what else is already
defined that you shouldn't reproduce in your code.


-18) Editor modelines and other cruft
+19) Editor modelines and other cruft
------------------------------------

Some editors can interpret configuration information embedded in source files,
@@ -975,7 +1000,7 @@ own custom mode, or may have some other magic method for making indentation
work correctly.


-19) Inline assembly
+20) Inline assembly
-------------------

In architecture-specific code, you may need to use inline assembly to interface
@@ -1007,7 +1032,7 @@ the next instruction in the assembly output:
: /* outputs */ : /* inputs */ : /* clobbers */);


-20) Conditional Compilation
+21) Conditional Compilation
---------------------------

Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
--
2.19.2