1.. SPDX-License-Identifier: GPL-2.0-only
2
3==========
4Checkpatch
5==========
6
7Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial
8style violations in patches and optionally corrects them.  Checkpatch can
9also be run on file contexts and without the kernel tree.
10
11Checkpatch is not always right. Your judgement takes precedence over checkpatch
12messages.  If your code looks better with the violations, then its probably
13best left alone.
14
15
16Options
17=======
18
19This section will describe the options checkpatch can be run with.
20
21Usage::
22
23  ./scripts/checkpatch.pl [OPTION]... [FILE]...
24
25Available options:
26
27 - -q,  --quiet
28
29   Enable quiet mode.
30
31 - -v,  --verbose
32   Enable verbose mode.  Additional verbose test descriptions are output
33   so as to provide information on why that particular message is shown.
34
35 - --no-tree
36
37   Run checkpatch without the kernel tree.
38
39 - --no-signoff
40
41   Disable the 'Signed-off-by' line check.  The sign-off is a simple line at
42   the end of the explanation for the patch, which certifies that you wrote it
43   or otherwise have the right to pass it on as an open-source patch.
44
45   Example::
46
47	 Signed-off-by: Random J Developer <random@developer.example.org>
48
49   Setting this flag effectively stops a message for a missing signed-off-by
50   line in a patch context.
51
52 - --patch
53
54   Treat FILE as a patch.  This is the default option and need not be
55   explicitly specified.
56
57 - --emacs
58
59   Set output to emacs compile window format.  This allows emacs users to jump
60   from the error in the compile window directly to the offending line in the
61   patch.
62
63 - --terse
64
65   Output only one line per report.
66
67 - --showfile
68
69   Show the diffed file position instead of the input file position.
70
71 - -g,  --git
72
73   Treat FILE as a single commit or a git revision range.
74
75   Single commit with:
76
77   - <rev>
78   - <rev>^
79   - <rev>~n
80
81   Multiple commits with:
82
83   - <rev1>..<rev2>
84   - <rev1>...<rev2>
85   - <rev>-<count>
86
87 - -f,  --file
88
89   Treat FILE as a regular source file.  This option must be used when running
90   checkpatch on source files in the kernel.
91
92 - --subjective,  --strict
93
94   Enable stricter tests in checkpatch.  By default the tests emitted as CHECK
95   do not activate by default.  Use this flag to activate the CHECK tests.
96
97 - --list-types
98
99   Every message emitted by checkpatch has an associated TYPE.  Add this flag
100   to display all the types in checkpatch.
101
102   Note that when this flag is active, checkpatch does not read the input FILE,
103   and no message is emitted.  Only a list of types in checkpatch is output.
104
105 - --types TYPE(,TYPE2...)
106
107   Only display messages with the given types.
108
109   Example::
110
111     ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES
112
113 - --ignore TYPE(,TYPE2...)
114
115   Checkpatch will not emit messages for the specified types.
116
117   Example::
118
119     ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES
120
121 - --show-types
122
123   By default checkpatch doesn't display the type associated with the messages.
124   Set this flag to show the message type in the output.
125
126 - --max-line-length=n
127
128   Set the max line length (default 100).  If a line exceeds the specified
129   length, a LONG_LINE message is emitted.
130
131
132   The message level is different for patch and file contexts.  For patches,
133   a WARNING is emitted.  While a milder CHECK is emitted for files.  So for
134   file contexts, the --strict flag must also be enabled.
135
136 - --min-conf-desc-length=n
137
138   Set the Kconfig entry minimum description length, if shorter, warn.
139
140 - --tab-size=n
141
142   Set the number of spaces for tab (default 8).
143
144 - --root=PATH
145
146   PATH to the kernel tree root.
147
148   This option must be specified when invoking checkpatch from outside
149   the kernel root.
150
151 - --no-summary
152
153   Suppress the per file summary.
154
155 - --mailback
156
157   Only produce a report in case of Warnings or Errors.  Milder Checks are
158   excluded from this.
159
160 - --summary-file
161
162   Include the filename in summary.
163
164 - --debug KEY=[0|1]
165
166   Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
167   'type', and 'attr' (default is all off).
168
169 - --fix
170
171   This is an EXPERIMENTAL feature.  If correctable errors exists, a file
172   <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
173   automatically fixable errors corrected.
174
175 - --fix-inplace
176
177   EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes.
178
179   DO NOT USE this flag unless you are absolutely sure and you have a backup
180   in place.
181
182 - --ignore-perl-version
183
184   Override checking of perl version.  Runtime errors maybe encountered after
185   enabling this flag if the perl version does not meet the minimum specified.
186
187 - --codespell
188
189   Use the codespell dictionary for checking spelling errors.
190
191 - --codespellfile
192
193   Use the specified codespell file.
194   Default is '/usr/share/codespell/dictionary.txt'.
195
196 - --typedefsfile
197
198   Read additional types from this file.
199
200 - --color[=WHEN]
201
202   Use colors 'always', 'never', or only when output is a terminal ('auto').
203   Default is 'auto'.
204
205 - --kconfig-prefix=WORD
206
207   Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
208
209 - -h, --help, --version
210
211   Display the help text.
212
213Message Levels
214==============
215
216Messages in checkpatch are divided into three levels. The levels of messages
217in checkpatch denote the severity of the error. They are:
218
219 - ERROR
220
221   This is the most strict level.  Messages of type ERROR must be taken
222   seriously as they denote things that are very likely to be wrong.
223
224 - WARNING
225
226   This is the next stricter level.  Messages of type WARNING requires a
227   more careful review.  But it is milder than an ERROR.
228
229 - CHECK
230
231   This is the mildest level.  These are things which may require some thought.
232
233Type Descriptions
234=================
235
236This section contains a description of all the message types in checkpatch.
237
238.. Types in this section are also parsed by checkpatch.
239.. The types are grouped into subsections based on use.
240
241
242Allocation style
243----------------
244
245  **ALLOC_ARRAY_ARGS**
246    The first argument for kcalloc or kmalloc_array should be the
247    number of elements.  sizeof() as the first argument is generally
248    wrong.
249    See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
250
251  **ALLOC_SIZEOF_STRUCT**
252    The allocation style is bad.  In general for family of
253    allocation functions using sizeof() to get memory size,
254    constructs like::
255
256      p = alloc(sizeof(struct foo), ...)
257
258    should be::
259
260      p = alloc(sizeof(*p), ...)
261
262    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory
263
264  **ALLOC_WITH_MULTIPLY**
265    Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
266    sizeof multiply.
267    See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
268
269
270API usage
271---------
272
273  **ARCH_DEFINES**
274    Architecture specific defines should be avoided wherever
275    possible.
276
277  **ARCH_INCLUDE_LINUX**
278    Whenever asm/file.h is included and linux/file.h exists, a
279    conversion can be made when linux/file.h includes asm/file.h.
280    However this is not always the case (See signal.h).
281    This message type is emitted only for includes from arch/.
282
283  **ARRAY_SIZE**
284    The ARRAY_SIZE(foo) macro should be preferred over
285    sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
286    array.
287
288    The macro is defined in include/linux/kernel.h::
289
290      #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
291
292  **AVOID_BUG**
293    BUG() or BUG_ON() should be avoided totally.
294    Use WARN() and WARN_ON() instead, and handle the "impossible"
295    error condition as gracefully as possible.
296    See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
297
298  **AVOID_EXTERNS**
299    Function prototypes don't need to be declared extern in .h
300    files.  It's assumed by the compiler and is unnecessary.
301
302  **AVOID_L_PREFIX**
303    Local symbol names that are prefixed with `.L` should be avoided,
304    as this has special meaning for the assembler; a symbol entry will
305    not be emitted into the symbol table.  This can prevent `objtool`
306    from generating correct unwind info.
307
308    Symbols with STB_LOCAL binding may still be used, and `.L` prefixed
309    local symbol names are still generally usable within a function,
310    but `.L` prefixed local symbol names should not be used to denote
311    the beginning or end of code regions via
312    `SYM_CODE_START_LOCAL`/`SYM_CODE_END`
313
314  **BIT_MACRO**
315    Defines like: 1 << <digit> could be BIT(digit).
316    The BIT() macro is defined in include/linux/bitops.h::
317
318      #define BIT(nr)         (1UL << (nr))
319
320  **CONSIDER_KSTRTO**
321    The simple_strtol(), simple_strtoll(), simple_strtoul(), and
322    simple_strtoull() functions explicitly ignore overflows, which
323    may lead to unexpected results in callers.  The respective kstrtol(),
324    kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the
325    correct replacements.
326    See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
327
328
329Comment style
330-------------
331
332  **BLOCK_COMMENT_STYLE**
333    The comment style is incorrect.  The preferred style for multi-
334    line comments is::
335
336      /*
337      * This is the preferred style
338      * for multi line comments.
339      */
340
341    The networking comment style is a bit different, with the first line
342    not empty like the former::
343
344      /* This is the preferred comment style
345      * for files in net/ and drivers/net/
346      */
347
348    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
349
350  **C99_COMMENTS**
351    C99 style single line comments (//) should not be used.
352    Prefer the block comment style instead.
353    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
354
355
356
357Commit message
358--------------
359
360  **BAD_SIGN_OFF**
361    The signed-off-by line does not fall in line with the standards
362    specified by the community.
363    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
364
365  **BAD_STABLE_ADDRESS_STYLE**
366    The email format for stable is incorrect.
367    Some valid options for stable address are::
368
369      1. stable@vger.kernel.org
370      2. stable@kernel.org
371
372    For adding version info, the following comment style should be used::
373
374      stable@vger.kernel.org # version info
375
376  **COMMIT_COMMENT_SYMBOL**
377    Commit log lines starting with a '#' are ignored by git as
378    comments.  To solve this problem addition of a single space
379    infront of the log line is enough.
380
381  **COMMIT_MESSAGE**
382    The patch is missing a commit description.  A brief
383    description of the changes made by the patch should be added.
384    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
385
386  **MISSING_SIGN_OFF**
387    The patch is missing a Signed-off-by line.  A signed-off-by
388    line should be added according to Developer's certificate of
389    Origin.
390    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
391
392  **NO_AUTHOR_SIGN_OFF**
393    The author of the patch has not signed off the patch.  It is
394    required that a simple sign off line should be present at the
395    end of explanation of the patch to denote that the author has
396    written it or otherwise has the rights to pass it on as an open
397    source patch.
398    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
399
400
401Comparison style
402----------------
403
404  **ASSIGN_IN_IF**
405    Do not use assignments in if condition.
406    Example::
407
408      if ((foo = bar(...)) < BAZ) {
409
410    should be written as::
411
412      foo = bar(...);
413      if (foo < BAZ) {
414
415  **BOOL_COMPARISON**
416    Comparisons of A to true and false are better written
417    as A and !A.
418    See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
419
420  **COMPARISON_TO_NULL**
421    Comparisons to NULL in the form (foo == NULL) or (foo != NULL)
422    are better written as (!foo) and (foo).
423
424  **CONSTANT_COMPARISON**
425    Comparisons with a constant or upper case identifier on the left
426    side of the test should be avoided.
427
428
429Spacing and Brackets
430--------------------
431
432  **ASSIGNMENT_CONTINUATIONS**
433    Assignment operators should not be written at the start of a
434    line but should follow the operand at the previous line.
435
436  **BRACES**
437    The placement of braces is stylistically incorrect.
438    The preferred way is to put the opening brace last on the line,
439    and put the closing brace first::
440
441      if (x is true) {
442        we do y
443      }
444
445    This applies for all non-functional blocks.
446    However, there is one special case, namely functions: they have the
447    opening brace at the beginning of the next line, thus::
448
449      int function(int x)
450      {
451        body of function
452      }
453
454    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
455
456  **BRACKET_SPACE**
457    Whitespace before opening bracket '[' is prohibited.
458    There are some exceptions:
459
460    1. With a type on the left::
461
462        ;int [] a;
463
464    2. At the beginning of a line for slice initialisers::
465
466        [0...10] = 5,
467
468    3. Inside a curly brace::
469
470        = { [0...10] = 5 }
471
472  **CODE_INDENT**
473    Code indent should use tabs instead of spaces.
474    Outside of comments, documentation and Kconfig,
475    spaces are never used for indentation.
476    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
477
478  **CONCATENATED_STRING**
479    Concatenated elements should have a space in between.
480    Example::
481
482      printk(KERN_INFO"bar");
483
484    should be::
485
486      printk(KERN_INFO "bar");
487
488  **LINE_SPACING**
489    Vertical space is wasted given the limited number of lines an
490    editor window can display when multiple blank lines are used.
491    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
492
493  **SPACING**
494    Whitespace style used in the kernel sources is described in kernel docs.
495    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
496
497  **TRAILING_WHITESPACE**
498    Trailing whitespace should always be removed.
499    Some editors highlight the trailing whitespace and cause visual
500    distractions when editing files.
501    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
502
503
504Others
505------
506
507  **CAMELCASE**
508    Avoid CamelCase Identifiers.
509    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
510
511  **CONFIG_DESCRIPTION**
512    Kconfig symbols should have a help text which fully describes
513    it.
514