* [PATCH v3] coding-style: Clarify the expectations around bool
@ 2019-01-07 21:11 Jason Gunthorpe
2019-01-07 22:10 ` Joe Perches
0 siblings, 1 reply; 6+ messages in thread
From: Jason Gunthorpe @ 2019-01-07 21:11 UTC (permalink / raw)
To: Gal Pressman
Cc: Joe Perches, Bart Van Assche, Stephen Warren, Tariq Toukan,
xavier.huwei, netdev, linux-rdma, Doug Ledford, Stephen Warren,
Christoph Hellwig, Andrew Morton, Linus Torvalds,
Jonathan Corbet, linux-kernel
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
Signed-off-by: Joe Perches <joe@perches.com>
Signed-off-by: Jason Gunthorpe <jgg@mellanox.com>
---
Documentation/process/coding-style.rst | 38 +++++++++++++++++++++++---
1 file changed, 34 insertions(+), 4 deletions(-)
There hasn't been any negative feedback on the first thread that
spawned this discussion, so here is a cleanuped up patch, ready to be
applied. Acks?
v2:
- Revise Joe's original suggestion with background and more details
v3:
- s/C11/C99/ [Al Viro]
- Add some remarks on the use of bool in function arguments [GalP]
I'm not sure what tree this should go through - Jonathan would you
pick it up?
Thanks,
Jason
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index b78dd680c03809..cbe6b01b05fa66 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -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 uses the C99 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 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
--
2.20.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH v3] coding-style: Clarify the expectations around bool
2019-01-07 21:11 [PATCH v3] coding-style: Clarify the expectations around bool Jason Gunthorpe
@ 2019-01-07 22:10 ` Joe Perches
2019-01-07 22:50 ` Bart Van Assche
2019-01-07 23:25 ` Jason Gunthorpe
0 siblings, 2 replies; 6+ messages in thread
From: Joe Perches @ 2019-01-07 22:10 UTC (permalink / raw)
To: Jason Gunthorpe, Gal Pressman
Cc: Bart Van Assche, Stephen Warren, Tariq Toukan, xavier.huwei,
netdev, linux-rdma, Doug Ledford, Stephen Warren,
Christoph Hellwig, Andrew Morton, Linus Torvalds,
Jonathan Corbet, linux-kernel
On Mon, 2019-01-07 at 14:11 -0700, Jason Gunthorpe 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.
Thanks Jason.
It'd be nice to combine this with some better
checkpatch warning or even a removal of that
misleading warning from checkpatch altogether.
With a couple minor nits below and and Ack if
you want one:
Acked-by: Joe Perches <joe@perches.com>
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
[]
> @@ -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 uses the C99 standard for the bool type. bool values can only
Maybe
The Linux kernel bool type is the C99 _Bool type.
> +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
true and false are not labels but #defines
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v3] coding-style: Clarify the expectations around bool
2019-01-07 22:10 ` Joe Perches
@ 2019-01-07 22:50 ` Bart Van Assche
2019-01-07 23:25 ` Jason Gunthorpe
1 sibling, 0 replies; 6+ messages in thread
From: Bart Van Assche @ 2019-01-07 22:50 UTC (permalink / raw)
To: Joe Perches, Jason Gunthorpe, Gal Pressman
Cc: Stephen Warren, Tariq Toukan, xavier.huwei, netdev, linux-rdma,
Doug Ledford, Stephen Warren, Christoph Hellwig, Andrew Morton,
Linus Torvalds, Jonathan Corbet, linux-kernel
On Mon, 2019-01-07 at 14:10 -0800, Joe Perches wrote:
> On Mon, 2019-01-07 at 14:11 -0700, Jason Gunthorpe 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.
>
> Thanks Jason.
>
> It'd be nice to combine this with some better
> checkpatch warning or even a removal of that
> misleading warning from checkpatch altogether.
>
> With a couple minor nits below and and Ack if
> you want one:
>
> Acked-by: Joe Perches <joe@perches.com>
>
> > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
>
> []
> > @@ -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 uses the C99 standard for the bool type. bool values can only
>
> Maybe
>
> The Linux kernel bool type is the C99 _Bool type.
Or maybe "The Linux kernel bool type is an alias for the C99 _Bool type."
> > +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
>
> true and false are not labels but #defines
With these refinements, feel free to add:
Reviewed-by: Bart Van Assche <bvanassche@acm.org>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v3] coding-style: Clarify the expectations around bool
2019-01-07 22:10 ` Joe Perches
2019-01-07 22:50 ` Bart Van Assche
@ 2019-01-07 23:25 ` Jason Gunthorpe
2019-01-08 0:38 ` Joe Perches
1 sibling, 1 reply; 6+ messages in thread
From: Jason Gunthorpe @ 2019-01-07 23:25 UTC (permalink / raw)
To: Joe Perches
Cc: Gal Pressman, Bart Van Assche, Stephen Warren, Tariq Toukan,
xavier.huwei, netdev, linux-rdma, Doug Ledford, Stephen Warren,
Christoph Hellwig, Andrew Morton, Linus Torvalds,
Jonathan Corbet, linux-kernel
On Mon, Jan 07, 2019 at 02:10:22PM -0800, Joe Perches wrote:
> On Mon, 2019-01-07 at 14:11 -0700, Jason Gunthorpe 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.
>
> Thanks Jason.
>
> It'd be nice to combine this with some better checkpatch warning or
> even a removal of that misleading warning from checkpatch
> altogether.
Okay, do you have a preference?
> With a couple minor nits below and and Ack if
> you want one:
>
> Acked-by: Joe Perches <joe@perches.com>
Thanks, I made the revisions with Bart's extra words. I'll send a v4
in a few days.
Jason
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v3] coding-style: Clarify the expectations around bool
2019-01-07 23:25 ` Jason Gunthorpe
@ 2019-01-08 0:38 ` Joe Perches
2019-01-08 3:21 ` Jason Gunthorpe
0 siblings, 1 reply; 6+ messages in thread
From: Joe Perches @ 2019-01-08 0:38 UTC (permalink / raw)
To: Jason Gunthorpe
Cc: Gal Pressman, Bart Van Assche, Stephen Warren, Tariq Toukan,
xavier.huwei, netdev, linux-rdma, Doug Ledford, Stephen Warren,
Christoph Hellwig, Andrew Morton, Linus Torvalds,
Jonathan Corbet, linux-kernel
On Mon, 2019-01-07 at 16:25 -0700, Jason Gunthorpe wrote:
> On Mon, Jan 07, 2019 at 02:10:22PM -0800, Joe Perches wrote:
> > On Mon, 2019-01-07 at 14:11 -0700, Jason Gunthorpe 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.
> >
> > Thanks Jason.
> >
> > It'd be nice to combine this with some better checkpatch warning or
> > even a removal of that misleading warning from checkpatch
> > altogether.
>
> Okay, do you have a preference?
Yes.
---
scripts/checkpatch.pl | 13 -------------
1 file changed, 13 deletions(-)
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 155fa9305166..cfe0396c9845 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -6370,19 +6370,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",
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH v3] coding-style: Clarify the expectations around bool
2019-01-08 0:38 ` Joe Perches
@ 2019-01-08 3:21 ` Jason Gunthorpe
0 siblings, 0 replies; 6+ messages in thread
From: Jason Gunthorpe @ 2019-01-08 3:21 UTC (permalink / raw)
To: Joe Perches
Cc: Gal Pressman, Bart Van Assche, Stephen Warren, Tariq Toukan,
xavier.huwei, netdev, linux-rdma, Doug Ledford, Stephen Warren,
Christoph Hellwig, Andrew Morton, Linus Torvalds,
Jonathan Corbet, linux-kernel
On Mon, Jan 07, 2019 at 04:38:50PM -0800, Joe Perches wrote:
> On Mon, 2019-01-07 at 16:25 -0700, Jason Gunthorpe wrote:
> > On Mon, Jan 07, 2019 at 02:10:22PM -0800, Joe Perches wrote:
> > > On Mon, 2019-01-07 at 14:11 -0700, Jason Gunthorpe 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.
> > >
> > > Thanks Jason.
> > >
> > > It'd be nice to combine this with some better checkpatch warning or
> > > even a removal of that misleading warning from checkpatch
> > > altogether.
> >
> > Okay, do you have a preference?
>
> Yes.
Great, done, thanks
Jason
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2019-01-08 3:21 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-01-07 21:11 [PATCH v3] coding-style: Clarify the expectations around bool Jason Gunthorpe
2019-01-07 22:10 ` Joe Perches
2019-01-07 22:50 ` Bart Van Assche
2019-01-07 23:25 ` Jason Gunthorpe
2019-01-08 0:38 ` Joe Perches
2019-01-08 3:21 ` Jason Gunthorpe
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.