1 .. SPDX-License-Identifier: GPL-2.0-only
7 Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial
8 style violations in patches and optionally corrects them. Checkpatch can
9 also be run on file contexts and without the kernel tree.
11 Checkpatch is not always right. Your judgement takes precedence over checkpatch
12 messages. If your code looks better with the violations, then its probably
19 This section will describe the options checkpatch can be run with.
23 ./scripts/checkpatch.pl [OPTION]... [FILE]...
32 Enable verbose mode. Additional verbose test descriptions are output
33 so as to provide information on why that particular message is shown.
37 Run checkpatch without the kernel tree.
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.
47 Signed-off-by: Random J Developer <random@developer.example.org>
49 Setting this flag effectively stops a message for a missing signed-off-by
50 line in a patch context.
54 Treat FILE as a patch. This is the default option and need not be
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
65 Output only one line per report.
69 Show the diffed file position instead of the input file position.
73 Treat FILE as a single commit or a git revision range.
81 Multiple commits with:
89 Treat FILE as a regular source file. This option must be used when running
90 checkpatch on source files in the kernel.
92 - --subjective, --strict
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.
99 Every message emitted by checkpatch has an associated TYPE. Add this flag
100 to display all the types in checkpatch.
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.
105 - --types TYPE(,TYPE2...)
107 Only display messages with the given types.
111 ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES
113 - --ignore TYPE(,TYPE2...)
115 Checkpatch will not emit messages for the specified types.
119 ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES
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.
126 - --max-line-length=n
128 Set the max line length (default 100). If a line exceeds the specified
129 length, a LONG_LINE message is emitted.
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.
136 - --min-conf-desc-length=n
138 Set the Kconfig entry minimum description length, if shorter, warn.
142 Set the number of spaces for tab (default 8).
146 PATH to the kernel tree root.
148 This option must be specified when invoking checkpatch from outside
153 Suppress the per file summary.
157 Only produce a report in case of Warnings or Errors. Milder Checks are
162 Include the filename in summary.
166 Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
167 'type', and 'attr' (default is all off).
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.
177 EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes.
179 DO NOT USE this flag unless you are absolutely sure and you have a backup
182 - --ignore-perl-version
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.
189 Use the codespell dictionary for checking spelling errors.
193 Use the specified codespell file.
194 Default is '/usr/share/codespell/dictionary.txt'.
198 Read additional types from this file.
202 Use colors 'always', 'never', or only when output is a terminal ('auto').
205 - --kconfig-prefix=WORD
207 Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
209 - -h, --help, --version
211 Display the help text.
216 Messages in checkpatch are divided into three levels. The levels of messages
217 in checkpatch denote the severity of the error. They are:
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.
226 This is the next stricter level. Messages of type WARNING requires a
227 more careful review. But it is milder than an ERROR.
231 This is the mildest level. These are things which may require some thought.
236 This section contains a description of all the message types in checkpatch.
238 .. Types in this section are also parsed by checkpatch.
239 .. The types are grouped into subsections based on use.
246 The first argument for kcalloc or kmalloc_array should be the
247 number of elements. sizeof() as the first argument is generally
249 See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
251 **ALLOC_SIZEOF_STRUCT**
252 The allocation style is bad. In general for family of
253 allocation functions using sizeof() to get memory size,
256 p = alloc(sizeof(struct foo), ...)
260 p = alloc(sizeof(*p), ...)
262 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory
264 **ALLOC_WITH_MULTIPLY**
265 Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
267 See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
274 Architecture specific defines should be avoided wherever
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/.
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
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
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/
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
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
314 No #include statements in include/uapi should use a uapi/ path.
320 **BLOCK_COMMENT_STYLE**
321 The comment style is incorrect. The preferred style for multi-
325 * This is the preferred style
326 * for multi line comments.
329 The networking comment style is a bit different, with the first line
330 not empty like the former::
332 /* This is the preferred comment style
333 * for files in net/ and drivers/net/
336 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
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
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
352 **BAD_STABLE_ADDRESS_STYLE**
353 The email format for stable is incorrect.
354 Some valid options for stable address are::
356 1. stable@vger.kernel.org
359 For adding version info, the following comment style should be used::
361 stable@vger.kernel.org # version info
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.
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
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
377 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
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
385 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
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/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/
395 To be picked up by gerrit, the footer of the commit message might
396 have a Change-Id like::
398 Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
399 Signed-off-by: A. U. Thor <author@example.com>
401 The Change-Id line must be removed before submitting.
404 The proper way to reference a commit id is:
405 commit <12+ chars of sha1> ("<title line>")
409 Commit e21d2170f36602ae2708 ("video: remove unnecessary
410 platform_set_drvdata()") removed the unnecessary
411 platform_set_drvdata(), but left the variable "dev" unused,
414 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
421 Do not use assignments in if condition.
424 if ((foo = bar(...)) < BAZ) {
426 should be written as::
432 Comparisons of A to true and false are better written
434 See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
436 **COMPARISON_TO_NULL**
437 Comparisons to NULL in the form (foo == NULL) or (foo != NULL)
438 are better written as (!foo) and (foo).
440 **CONSTANT_COMPARISON**
441 Comparisons with a constant or upper case identifier on the left
442 side of the test should be avoided.
445 Macros, Attributes and Symbols
446 ------------------------------
449 The ARRAY_SIZE(foo) macro should be preferred over
450 sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
453 The macro is defined in include/linux/kernel.h::
455 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
458 Function prototypes don't need to be declared extern in .h
459 files. It's assumed by the compiler and is unnecessary.
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.
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`
474 Defines like: 1 << <digit> could be BIT(digit).
475 The BIT() macro is defined in include/linux/bitops.h::
477 #define BIT(nr) (1UL << (nr))
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.
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.
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
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
498 The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong.
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/
508 Const init definitions should use __initconst instead of
511 Similarly init definitions without const require a separate
515 The inline keyword should sit between storage class and type.
517 For example, the following segment::
519 inline static int example_function(void)
526 static inline int example_function(void)
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::
536 #define macrofun(a, b, c) \
542 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
545 Using weak declarations like __attribute__((weak)) or __weak
546 can have unintended link defects. Avoid using them.
549 Functions and Variables
550 -----------------------
553 Avoid CamelCase Identifiers.
554 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
556 **FUNCTION_WITHOUT_ARGS**
557 Function declarations without arguments like::
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.
571 **INITIALISED_STATIC**
572 Static variables should not be initialized explicitly to zero.
573 Your compiler (or rather your loader) automatically does
576 **RETURN_PARENTHESES**
577 return is not a function and as such doesn't need parentheses::
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.
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::
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::
611 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
614 Whitespace before opening bracket '[' is prohibited.
615 There are some exceptions:
617 1. With a type on the left::
621 2. At the beginning of a line for slice initialisers::
625 3. Inside a curly brace::
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
635 **CONCATENATED_STRING**
636 Concatenated elements should have a space in between.
639 printk(KERN_INFO"bar");
643 printk(KERN_INFO "bar");
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
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
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
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.
667 unsigned long long memparse(char *ptr, char **retptr);
668 char *match_strdup(substring_t *s);
670 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
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
676 **SWITCH_CASE_INDENT_LEVEL**
677 switch should be at the same indent as case.
697 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
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
705 **WHILE_AFTER_BRACE**
706 while should follow the closing bracket on the same line::
712 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
718 **CONFIG_DESCRIPTION**
719 Kconfig symbols should have a help text which fully describes
723 The patch seems to be corrupted or lines are wrapped.
724 Please regenerate the patch file before sending it to the maintainer.
727 For DOS-formatted patches, there are extra ^M symbols at the end of
728 the line. These should be removed.
730 **EXECUTE_PERMISSIONS**
731 There is no reason for source files to be executable. The executable
732 bit can be removed safely.
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.
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.
743 Prefixing 0x with decimal output is defective and should be corrected.
745 **TRAILING_STATEMENTS**
746 Trailing statements (for example after any conditional) should be