projects/linux·blob v5.13 · refs

755 lines · 22.0 KiB

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 <[email protected]>
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 **AVOID_BUG**
284 BUG() or BUG_ON() should be avoided totally.
285 Use WARN() and WARN_ON() instead, and handle the "impossible"
286 error condition as gracefully as possible.
287 See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
288
289 **CONSIDER_KSTRTO**
290 The simple_strtol(), simple_strtoll(), simple_strtoul(), and
291 simple_strtoull() functions explicitly ignore overflows, which
292 may lead to unexpected results in callers. The respective kstrtol(),
293 kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the
294 correct replacements.
295 See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
296
297 **LOCKDEP**
298 The lockdep_no_validate class was added as a temporary measure to
299 prevent warnings on conversion of device->sem to device->mutex.
300 It should not be used for any other purpose.
301 See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
302
303 **MALFORMED_INCLUDE**
304 The #include statement has a malformed path. This has happened
305 because the author has included a double slash "//" in the pathname
306 accidentally.
307
308 **USE_LOCKDEP**
309 lockdep_assert_held() annotations should be preferred over
310 assertions based on spin_is_locked()
311 See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
312
313 **UAPI_INCLUDE**
314 No #include statements in include/uapi should use a uapi/ path.
315
316
317Comment style
318-------------
319
320 **BLOCK_COMMENT_STYLE**
321 The comment style is incorrect. The preferred style for multi-
322 line comments is::
323
324 /*
325 * This is the preferred style
326 * for multi line comments.
327 */
328
329 The networking comment style is a bit different, with the first line
330 not empty like the former::
331
332 /* This is the preferred comment style
333 * for files in net/ and drivers/net/
334 */
335
336 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
337
338 **C99_COMMENTS**
339 C99 style single line comments (//) should not be used.
340 Prefer the block comment style instead.
341 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
342
343
344Commit message
345--------------
346
347 **BAD_SIGN_OFF**
348 The signed-off-by line does not fall in line with the standards
349 specified by the community.
350 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
351
352 **BAD_STABLE_ADDRESS_STYLE**
353 The email format for stable is incorrect.
354 Some valid options for stable address are::
355
356 1. [email protected]
357 2. [email protected]
358
359 For adding version info, the following comment style should be used::
360
361 [email protected] # version info
362
363 **COMMIT_COMMENT_SYMBOL**
364 Commit log lines starting with a '#' are ignored by git as
365 comments. To solve this problem addition of a single space
366 infront of the log line is enough.
367
368 **COMMIT_MESSAGE**
369 The patch is missing a commit description. A brief
370 description of the changes made by the patch should be added.
371 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
372
373 **MISSING_SIGN_OFF**
374 The patch is missing a Signed-off-by line. A signed-off-by
375 line should be added according to Developer's certificate of
376 Origin.
377 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
378
379 **NO_AUTHOR_SIGN_OFF**
380 The author of the patch has not signed off the patch. It is
381 required that a simple sign off line should be present at the
382 end of explanation of the patch to denote that the author has
383 written it or otherwise has the rights to pass it on as an open
384 source patch.
385 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
386
387 **DIFF_IN_COMMIT_MSG**
388 Avoid having diff content in commit message.
389 This causes problems when one tries to apply a file containing both
390 the changelog and the diff because patch(1) tries to apply the diff
391 which it found in the changelog.
392 See: https://lore.kernel.org/lkml/[email protected]/
393
394 **GERRIT_CHANGE_ID**
395 To be picked up by gerrit, the footer of the commit message might
396 have a Change-Id like::
397
398 Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
399 Signed-off-by: A. U. Thor <[email protected]>
400
401 The Change-Id line must be removed before submitting.
402
403 **GIT_COMMIT_ID**
404 The proper way to reference a commit id is:
405 commit <12+ chars of sha1> ("<title line>")
406
407 An example may be::
408
409 Commit e21d2170f36602ae2708 ("video: remove unnecessary
410 platform_set_drvdata()") removed the unnecessary
411 platform_set_drvdata(), but left the variable "dev" unused,
412 delete it.
413
414 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
415
416
417Comparison style
418----------------
419
420 **ASSIGN_IN_IF**
421 Do not use assignments in if condition.
422 Example::
423
424 if ((foo = bar(...)) < BAZ) {
425
426 should be written as::
427
428 foo = bar(...);
429 if (foo < BAZ) {
430
431 **BOOL_COMPARISON**
432 Comparisons of A to true and false are better written
433 as A and !A.
434 See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
435
436 **COMPARISON_TO_NULL**
437 Comparisons to NULL in the form (foo == NULL) or (foo != NULL)
438 are better written as (!foo) and (foo).
439
440 **CONSTANT_COMPARISON**
441 Comparisons with a constant or upper case identifier on the left
442 side of the test should be avoided.
443
444
445Macros, Attributes and Symbols
446------------------------------
447
448 **ARRAY_SIZE**
449 The ARRAY_SIZE(foo) macro should be preferred over
450 sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
451 array.
452
453 The macro is defined in include/linux/kernel.h::
454
455 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
456
457 **AVOID_EXTERNS**
458 Function prototypes don't need to be declared extern in .h
459 files. It's assumed by the compiler and is unnecessary.
460
461 **AVOID_L_PREFIX**
462 Local symbol names that are prefixed with `.L` should be avoided,
463 as this has special meaning for the assembler; a symbol entry will
464 not be emitted into the symbol table. This can prevent `objtool`
465 from generating correct unwind info.
466
467 Symbols with STB_LOCAL binding may still be used, and `.L` prefixed
468 local symbol names are still generally usable within a function,
469 but `.L` prefixed local symbol names should not be used to denote
470 the beginning or end of code regions via
471 `SYM_CODE_START_LOCAL`/`SYM_CODE_END`
472
473 **BIT_MACRO**
474 Defines like: 1 << <digit> could be BIT(digit).
475 The BIT() macro is defined in include/linux/bitops.h::
476
477 #define BIT(nr) (1UL << (nr))
478
479 **CONST_READ_MOSTLY**
480 When a variable is tagged with the __read_mostly annotation, it is a
481 signal to the compiler that accesses to the variable will be mostly
482 reads and rarely(but NOT never) a write.
483
484 const __read_mostly does not make any sense as const data is already
485 read-only. The __read_mostly annotation thus should be removed.
486
487 **DATE_TIME**
488 It is generally desirable that building the same source code with
489 the same set of tools is reproducible, i.e. the output is always
490 exactly the same.
491
492 The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
493 and enables warnings if they are used as they can lead to
494 non-deterministic builds.
495 See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
496
497 **DEFINE_ARCH_HAS**
498 The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong.
499
500 For big conceptual features use Kconfig symbols instead. And for
501 smaller things where we have compatibility fallback functions but
502 want architectures able to override them with optimized ones, we
503 should either use weak functions (appropriate for some cases), or
504 the symbol that protects them should be the same symbol we use.
505 See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/
506
507 **INIT_ATTRIBUTE**
508 Const init definitions should use __initconst instead of
509 __initdata.
510
511 Similarly init definitions without const require a separate
512 use of const.
513
514 **INLINE_LOCATION**
515 The inline keyword should sit between storage class and type.
516
517 For example, the following segment::
518
519 inline static int example_function(void)
520 {
521 ...
522 }
523
524 should be::
525
526 static inline int example_function(void)
527 {
528 ...
529 }
530
531 **MULTISTATEMENT_MACRO_USE_DO_WHILE**
532 Macros with multiple statements should be enclosed in a
533 do - while block. Same should also be the case for macros
534 starting with `if` to avoid logic defects::
535
536 #define macrofun(a, b, c) \
537 do { \
538 if (a == 5) \
539 do_this(b, c); \
540 } while (0)
541
542 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
543
544 **WEAK_DECLARATION**
545 Using weak declarations like __attribute__((weak)) or __weak
546 can have unintended link defects. Avoid using them.
547
548
549Functions and Variables
550-----------------------
551
552 **CAMELCASE**
553 Avoid CamelCase Identifiers.
554 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
555
556 **FUNCTION_WITHOUT_ARGS**
557 Function declarations without arguments like::
558
559 int foo()
560
561 should be::
562
563 int foo(void)
564
565 **GLOBAL_INITIALISERS**
566 Global variables should not be initialized explicitly to
567 0 (or NULL, false, etc.). Your compiler (or rather your
568 loader, which is responsible for zeroing out the relevant
569 sections) automatically does it for you.
570
571 **INITIALISED_STATIC**
572 Static variables should not be initialized explicitly to zero.
573 Your compiler (or rather your loader) automatically does
574 it for you.
575
576 **RETURN_PARENTHESES**
577 return is not a function and as such doesn't need parentheses::
578
579 return (bar);
580
581 can simply be::
582
583 return bar;
584
585
586Spacing and Brackets
587--------------------
588
589 **ASSIGNMENT_CONTINUATIONS**
590 Assignment operators should not be written at the start of a
591 line but should follow the operand at the previous line.
592
593 **BRACES**
594 The placement of braces is stylistically incorrect.
595 The preferred way is to put the opening brace last on the line,
596 and put the closing brace first::
597
598 if (x is true) {
599 we do y
600 }
601
602 This applies for all non-functional blocks.
603 However, there is one special case, namely functions: they have the
604 opening brace at the beginning of the next line, thus::
605
606 int function(int x)
607 {
608 body of function
609 }
610
611 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
612
613 **BRACKET_SPACE**
614 Whitespace before opening bracket '[' is prohibited.
615 There are some exceptions:
616
617 1. With a type on the left::
618
619 ;int [] a;
620
621 2. At the beginning of a line for slice initialisers::
622
623 [0...10] = 5,
624
625 3. Inside a curly brace::
626
627 = { [0...10] = 5 }
628
629 **CODE_INDENT**
630 Code indent should use tabs instead of spaces.
631 Outside of comments, documentation and Kconfig,
632 spaces are never used for indentation.
633 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
634
635 **CONCATENATED_STRING**
636 Concatenated elements should have a space in between.
637 Example::
638
639 printk(KERN_INFO"bar");
640
641 should be::
642
643 printk(KERN_INFO "bar");
644
645 **ELSE_AFTER_BRACE**
646 `else {` should follow the closing block `}` on the same line.
647 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
648
649 **LINE_SPACING**
650 Vertical space is wasted given the limited number of lines an
651 editor window can display when multiple blank lines are used.
652 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
653
654 **OPEN_BRACE**
655 The opening brace should be following the function definitions on the
656 next line. For any non-functional block it should be on the same line
657 as the last construct.
658 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
659
660 **POINTER_LOCATION**
661 When using pointer data or a function that returns a pointer type,
662 the preferred use of * is adjacent to the data name or function name
663 and not adjacent to the type name.
664 Examples::
665
666 char *linux_banner;
667 unsigned long long memparse(char *ptr, char **retptr);
668 char *match_strdup(substring_t *s);
669
670 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
671
672 **SPACING**
673 Whitespace style used in the kernel sources is described in kernel docs.
674 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
675
676 **SWITCH_CASE_INDENT_LEVEL**
677 switch should be at the same indent as case.
678 Example::
679
680 switch (suffix) {
681 case 'G':
682 case 'g':
683 mem <<= 30;
684 break;
685 case 'M':
686 case 'm':
687 mem <<= 20;
688 break;
689 case 'K':
690 case 'k':
691 mem <<= 10;
692 /* fall through */
693 default:
694 break;
695 }
696
697 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
698
699 **TRAILING_WHITESPACE**
700 Trailing whitespace should always be removed.
701 Some editors highlight the trailing whitespace and cause visual
702 distractions when editing files.
703 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
704
705 **WHILE_AFTER_BRACE**
706 while should follow the closing bracket on the same line::
707
708 do {
709 ...
710 } while(something);
711
712 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
713
714
715Others
716------
717
718 **CONFIG_DESCRIPTION**
719 Kconfig symbols should have a help text which fully describes
720 it.
721
722 **CORRUPTED_PATCH**
723 The patch seems to be corrupted or lines are wrapped.
724 Please regenerate the patch file before sending it to the maintainer.
725
726 **DOS_LINE_ENDINGS**
727 For DOS-formatted patches, there are extra ^M symbols at the end of
728 the line. These should be removed.
729
730 **EXECUTE_PERMISSIONS**
731 There is no reason for source files to be executable. The executable
732 bit can be removed safely.
733
734 **NON_OCTAL_PERMISSIONS**
735 Permission bits should use 4 digit octal permissions (like 0700 or 0444).
736 Avoid using any other base like decimal.
737
738 **NOT_UNIFIED_DIFF**
739 The patch file does not appear to be in unified-diff format. Please
740 regenerate the patch file before sending it to the maintainer.
741
742 **PRINTF_0XDECIMAL**
743 Prefixing 0x with decimal output is defective and should be corrected.
744
745 **TRAILING_STATEMENTS**
746 Trailing statements (for example after any conditional) should be
747 on the next line.
748 Like::
749
750 if (x == y) break;
751
752 should be::
753
754 if (x == y)
755 break;