Skip to contentSkip to conversation

coding-style: Clarify the expectations around bool

PATCH In review Jason Gunthorpe 4 participants 7 messages Jan 10, 2019 – Jan 14, 2019

Subsystems (6)
lore
Share & tools
lore
#0 lore raw

PATCH v4 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(-)

v4:
- Describe true/false as definitions [Joe]
- Use clearer language for the _Bool explanation [Bart]
- Delete the checkpatch tests [Joe]

Documentation/process/coding-style.rst +34 -4
index b78dd680c03809..db3e030d0df908 100644
@@ -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 0 and 1.
+
+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, 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 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
index b737ca9d720441..d62abd032885a1 100755
@@ -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
Reviewed-by on v4 1/1
#1 lore raw
Quoted 6 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.

Hey Jason,

I very much agree that the bool expectations could be much clearer, and this patch is a nice step in that direction! Just a couple small nitpicks:

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 941

Quoted 3 lines
Documentation/process/coding-style.rst +3 -0
+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.

+Do not use bool if cache line layout or size of the value matters, as its size

                                                                    ^
                                                                    |

Adding an "as" makes the sentence flow a bit cleaner: --------------

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 949

Quoted 2 lines
Documentation/process/coding-style.rst +2 -0
+into a single bitwise 'flags' argument and 'flags' can often a more readable
+alternative if the call-sites have naked true/false constants.

+into a single bitwise 'flags' argument and 'flags' can often be a more readable

                                                              ^
                                                              |

Missing a "be" here: -----------------------------------------

Ack from me after those two corrections.

Signature · 2 lines
Cheers,
Joey Pabalinas
#2 lore raw
Quoted 26 lines · Joey Pabalinas
Quoted 6 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.

Hey Jason,

I very much agree that the bool expectations could be much clearer, and this patch is a nice step in that direction! Just a couple small nitpicks:

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 941

Quoted 3 lines
Documentation/process/coding-style.rst +3 -0
+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.

+Do not use bool if cache line layout or size of the value matters, as its size

                                                                    ^
                                                                    |

Adding an "as" makes the sentence flow a bit cleaner: --------------

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 949

Quoted 2 lines
Documentation/process/coding-style.rst +2 -0
+into a single bitwise 'flags' argument and 'flags' can often a more readable
+alternative if the call-sites have naked true/false constants.

+into a single bitwise 'flags' argument and 'flags' can often be a more readable

Quoted 7 lines
                                                              ^
                                                              |

Missing a "be" here: -----------------------------------------

Ack from me after those two corrections.

done, thanks

Jason

#3 lore raw
In reply to Jason Gunthorpe
Quoted 45 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.

Link:
https://lkml.kernel.org/r/CA+55aFwVZk1OfB9T2v014PTAKFhtVan_Zj2dOjnCy3x6E4UJfA@mail.gmail.com

---
 Documentation/process/coding-style.rst | 38 +++++++++++++++++++++++---
 scripts/checkpatch.pl                  | 13 ---------
 2 files changed, 34 insertions(+), 17 deletions(-)

v4:
- Describe true/false as definitions [Joe]
- Use clearer language for the _Bool explanation [Bart]
- Delete the checkpatch tests [Joe]

Documentation/process/coding-style.rst +0 -0
index b78dd680c03809..db3e030d0df908 100644
@@ -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
+--------------

Documentation/process/coding-style.rst +2 -0
+
+The Linux kernel bool type is an alias for the C99 _Bool type. bool 

values 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 bool 

types 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 be 
Quoted 2 lines

used
+instead of 0 and 1.

A very minor thing. I would suggest to keep consistent, in the statement, the mapping between definitions ("true and false [...]") and their correspondent integer values ("[...] instead of 1 and 0").

In few words, I propose to change "0 and 1" into "1 and 0".

Quoted 20 lines
Documentation/process/coding-style.rst +2 -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

Documentation/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, its 

size
+and alignment varies based on the compiled architecture. Structures that are

Documentation/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 them 

into a
+bitfield with 1 bit members, or using an appropriate fixed width type, such as

Documentation/process/coding-style.rst +3 -0
+u8.
+
+Similarly for function arguments, many true/false values can be 
Quoted 4 lines

consolidated
+into a single bitwise 'flags' argument and 'flags' can often a more readable
+alternative if the call-sites have naked true/false constants.

Of course, English is not my primary language, but it looks to me that here a "be" is missing: "[...] and 'flags' can often a more readable alternative [...]".

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 952

Quoted 3 lines
Documentation/process/coding-style.rst +3 -0
+
+Otherwise limited use of bool in structures and arguments can improve
+readability.

I'm going to update the Italian translations for this. Do you want me to contribute directly to this patch? Otherwise I will send a dedicated patch later when this one get accepted.

Thanks

Quoted 64 lines

+18) Don't re-invent the kernel macros
-------------------------------------

The header file include/linux/kernel.h contains a number of macros
that

Documentation/process/coding-style.rst +0 -0
@@ -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,

Documentation/process/coding-style.rst +0 -0
@@ -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

Documentation/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
index b737ca9d720441..d62abd032885a1 100755
@@ -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);

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/
#4 lore raw
Quoted 19 lines · Federico Vaga
Quoted 12 lines

-17) Don't re-invent the kernel macros
+17) Using bool
+--------------

(quoted diff) +2 -0
+
+The Linux kernel bool type is an alias for the C99 _Bool type. bool

values can

(quoted diff) +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 bool

types the
+!! construction is not needed, which eliminates a class of bugs.

(quoted diff) +2 -0
+
+When working with bool values the true and false definitions should be
Quoted 2 lines

used
+instead of 0 and 1.

A very minor thing. I would suggest to keep consistent, in the statement, the mapping between definitions ("true and false [...]") and their correspondent integer values ("[...] instead of 1 and 0").

Quoted 1 line

In few words, I propose to change "0 and 1" into "1 and 0".

Hm, sure, seems harmless

Quoted 9 lines
Quoted 5 lines

+Similarly for function arguments, many true/false values can be consolidated
+into a single bitwise 'flags' argument and 'flags' can often a more readable
+alternative if the call-sites have naked true/false constants.

Of course, English is not my primary language, but it looks to me that here a "be" is missing: "[...] and 'flags' can often a more readable alternative [...]".

yes, sthanks

Quoted 6 lines

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 952

Quoted 2 lines
Documentation/process/coding-style.rst +2 -0
+Otherwise limited use of bool in structures and arguments can improve
+readability.

I'm going to update the Italian translations for this. Do you want me to contribute directly to this patch? Otherwise I will send a dedicated patch later when this one get accepted.

I think you should send it as an update I guess? I don't really know the process for translations

Jason

#5 lore raw
In reply to Jason Gunthorpe

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 937

Quoted 11 lines · Jason Gunthorpe
Documentation/process/coding-style.rst +11 -0
+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 0 and 1.
+
+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.

It's awkward to start a sentence with a lower case letter. How about rephrasing this paragraph and the following one as:

Using bool as the return type of a function or as a variable is always fine when appropriate. It often improves readability and is a better option than int for storing boolean values. Using bool in data structures is more debatable; its size and alignment can vary between architectures.

Quoted 7 lines
Documentation/process/coding-style.rst +7 -0
+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.
#6 lore raw
Quoted 16 lines · Matthew Wilcox

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 937

Quoted 11 lines · Jason Gunthorpe
Documentation/process/coding-style.rst +11 -0
+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 0 and 1.
+
+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.

It's awkward to start a sentence with a lower case letter. How about rephrasing this paragraph and the following one as:

Quoted 4 lines

Using bool as the return type of a function or as a variable is always fine when appropriate. It often improves readability and is a better option than int for storing boolean values. Using bool in data structures is more debatable; its size and alignment can vary between architectures.

This is more concise, but I think if the coding style is not going to give a concrete advise then it should at least provide some general information so the reader can try and make an informed choice.

That is why I had it expand on some of the rationals a little bit, along with a concrete direction to not use bool in the cases Linus specifically called out.

Quoted 7 lines

Documentation/process/coding-style.rst result. Typical examples would be functions that return pointers; they use · line 945

Quoted 7 lines
Documentation/process/coding-style.rst +7 -0
+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.

JAson