coding-style: Clarify the expectations around bool
Subsystems (6)
PATCH v5 1/1 coding-style: Clarify the expectations around bool
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.
--- Documentation/process/coding-style.rst | 38 +++++++++++++++++++++++--- scripts/checkpatch.pl | 13 --------- 2 files changed, 34 insertions(+), 17 deletions(-)
v5:
- Wording updates from JoeyP, MatthewW, FedericoV
Documentation/process/coding-style.rst +34 -4
@@ -921,7 +921,37 @@ 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 bool type is an alias for the C99 _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 definitions should be used +instead of 1 and 0. + +bool function return types 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, as 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. + +Similarly for function arguments, many true/false values can be consolidated +into a single bitwise 'flags' argument and 'flags' can often be a more +readable alternative if the call-sites have naked true/false constants. + +Otherwise limited use of bool in structures and arguments can improve +readability. + +18) Don't re-invent the kernel macros ------------------------------------- The header file include/linux/kernel.h contains a number of macros that
@@ -944,7 +974,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,
@@ -978,7 +1008,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
@@ -1010,7 +1040,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
scripts/checkpatch.pl +0 -13
@@ -6368,19 +6368,6 @@ sub process { } } -# check for bool bitfields - if ($sline =~ /^.\s+bool\s*$Ident\s*:\s*\d+\s*;/) { - WARN("BOOL_BITFIELD", - "Avoid using bool as bitfield. Prefer bool bitfields as unsigned int or u<8|16|32>\n" . $herecurr); - } - -# check for bool use in .h files - if ($realfile =~ /\.h$/ && - $sline =~ /^.\s+bool\s*$Ident\s*(?::\s*d+\s*)?;/) { - CHK("BOOL_MEMBER", - "Avoid using bool structure members because of possible alignment issues - see: https://lkml.org/lkml/2017/11/21/384\n" . $herecurr); - } - # check for semaphores initialized locked if ($line =~ /^.\s*sema_init.+,\W?0\W?\)/) { WARN("CONSIDER_COMPLETION",
Signature · 1 line
2.20.1
Quoted 7 lines · Jason Gunthorpe
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.
Quoted 8 lines
Link:
https://lkml.kernel.org/r/CA+55aFwVZk1OfB9T2v014PTAKFhtVan_Zj2dOjnCy3x6E4UJfA@mail.gmail.comSigned-off-by Joe Perches <[email protected]>Acked-by Joe Perches <[email protected]>Reviewed-by Bart Van Assche <[email protected]>Acked-by Jani Nikula <[email protected]>Reviewed-by Joey Pabalinas <[email protected]>Signed-off-by Jason Gunthorpe <[email protected]>
Quoted 124 lines
--- Documentation/process/coding-style.rst | 38 +++++++++++++++++++++++--- scripts/checkpatch.pl | 13 --------- 2 files changed, 34 insertions(+), 17 deletions(-)v5:
- Wording updates from JoeyP, MatthewW, FedericoVDocumentation/process/coding-style.rst +0
-0@@ -921,7 +921,37 @@ result. Typical examples would be functions thatreturn pointers; they use
NULL or theERR_PTRmechanism to report failure.-17) Don't re-invent the kernel macros
+17) Using bool
+--------------Documentation/process/coding-style.rst +2
-0+ +The Linux kernel bool type is an alias for the C99 _Bool type. boolvalues can
Documentation/process/coding-style.rst +2
-0+only evaluate to 0 or 1, and implicit or explicit conversion to bool +automatically converts the value to true or false. When using booltypes the
+!! construction is not needed, which eliminates a class of bugs.Documentation/process/coding-style.rst +2
-0+ +When working with bool values the true and false definitions should beused
Documentation/process/coding-style.rst +3
-0+instead of 1 and 0. + +bool function return types and stack variables are always fine to usewhenever
+appropriate. Use of bool is encouraged to improve readability and is often aDocumentation/process/coding-style.rst +3
-0+better option than 'int' for storing boolean values. + +Do not use bool if cache line layout or size of the value matters, asits size
+and alignment varies based on the compiled architecture. Structures that areDocumentation/process/coding-style.rst +3
-0+optimized for alignment and size should not use bool. + +If a structure has many true/false values, consider consolidating theminto a
+bitfield with 1 bit members, or using an appropriate fixed width type, such asDocumentation/process/coding-style.rst +3
-0+u8. + +Similarly for function arguments, many true/false values can beconsolidated
Documentation/process/coding-style.rst +2
-0+into a single bitwise 'flags' argument and 'flags' can often be a more +readable alternative if the call-sites have naked true/falseconstants.
Documentation/process/coding-style.rst +5
-0+ +Otherwise limited use of bool in structures and arguments can improve +readability. + +18) Don't re-invent the kernel macros ------------------------------------- The header file include/linux/kernel.h contains a number of macrosthat
Documentation/process/coding-style.rst +0
-0@@ -944,7 +974,7 @@ need them. Feel free to peruse that header fileto 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,Documentation/process/coding-style.rst +0
-0@@ -978,7 +1008,7 @@ own custom mode, or may have some other magicmethod for making indentation
work correctly.-19) Inline assembly
+20) Inline assembly
-------------------In architecture-specific code, you may need to use inline assembly to
interfaceDocumentation/process/coding-style.rst +1
-1@@ -1010,7 +1040,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
scripts/checkpatch.pl +0
-11@@ -6368,19 +6368,6 @@ sub process { } } -# check for bool bitfields - if ($sline =~ /^.\s+bool\s*$Ident\s*:\s*\d+\s*;/) { - WARN("BOOL_BITFIELD", - "Avoid using bool as bitfield. Prefer bool bitfields as unsigned int or u<8|16|32>\n" . $herecurr); - } - -# check for bool use in .h files - if ($realfile =~ /\.h$/ && - $sline =~ /^.\s+bool\s*$Ident\s*(?::\s*d+\s*)?;/) { - CHK("BOOL_MEMBER", - "Avoid using bool structure members because of possiblealignment issues - see: https://lkml.org/lkml/2017/11/21/384\n" . $herecurr);
scripts/checkpatch.pl +0
-2- } - # check for semaphores initialized locked if ($line =~ /^.\s*sema_init.+,\W?0\W?\)/) { WARN("CONSIDER_COMPLETION",
Signature · 2 lines
Federico Vaga http://www.federicovaga.it/
Jonathan Corbet
maintainerQuoted 7 lines · On Fri, 18 Jan 2019 15:50:47 -0700 Jason Gunthorpe <[email protected]> wrote:
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.
Quoted 7 lines
Link https://lkml.kernel.org/r/CA+55aFwVZk1OfB9T2v014PTAKFhtVan_Zj2dOjnCy3x6E4UJfA@mail.gmail.com open hereSigned-off-by Joe Perches <[email protected]>Acked-by Joe Perches <[email protected]>Reviewed-by Bart Van Assche <[email protected]>Acked-by Jani Nikula <[email protected]>Reviewed-by Joey Pabalinas <[email protected]>Signed-off-by Jason Gunthorpe <[email protected]>
So this seems ready; I've applied it.
Thanks,
jon