Documentation/dev-tools/checkpatch.rst

1 .. SPDX-License-Identifier: GPL-2.0-only
13 best left alone.
27  - -q,  --quiet
31  - -v,  --verbose
35  - --no-tree
39  - --no-signoff
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
52  - --patch
57  - --emacs
63  - --terse
67  - --showfile
69    Show the diffed file position instead of the input file position.
71  - -g,  --git
73    Treat FILE as a single commit or a git revision range.
75    Single commit with:
77    - <rev>
78    - <rev>^
79    - <rev>~n
83    - <rev1>..<rev2>
84    - <rev1>...<rev2>
85    - <rev>-<count>
87  - -f,  --file
92  - --subjective,  --strict
97  - --list-types
102    Note that when this flag is active, checkpatch does not read the input FILE,
105  - --types TYPE(,TYPE2...)
111      ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES
113  - --ignore TYPE(,TYPE2...)
119      ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES
121  - --show-types
126  - --max-line-length=n
134    file contexts, the --strict flag must also be enabled.
136  - --min-conf-desc-length=n
140  - --tab-size=n
144  - --root=PATH
151  - --no-summary
155  - --mailback
160  - --summary-file
164  - --debug KEY=[0|1]
169  - --fix
172    <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
175  - --fix-inplace
177    EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes.
182  - --ignore-perl-version
187  - --codespell
191  - --codespellfile
196  - --typedefsfile
200  - --color[=WHEN]
205  - --kconfig-prefix=WORD
209  - -h, --help, --version
219  - ERROR
224  - WARNING
229  - CHECK
243 ----------------
250     See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
263     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory
269     See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
273 ---------
290     See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
299 …nel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple…
335     See: https://lore.kernel.org/lkml/1400106425.12666.6.camel@joe-AO725/
339     old flavourful RCU APIs by their new vanilla-RCU counterparts.
343     See: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis
347     flags added via commit f77bf01425b1 ("kbuild: introduce ccflags-y,
348     asflags-y and ldflags-y").
352       EXTRA_AFLAGS    ->  asflags-y
353       EXTRA_CFLAGS    ->  ccflags-y
354       EXTRA_CPPFLAGS  ->  cppflags-y
355       EXTRA_LDFLAGS   ->  ldflags-y
360       2. https://lore.kernel.org/lkml/1313384834-24433-12-git-send-email-lacombar@gmail.com/
361       3. https://www.kernel.org/doc/html/latest/kbuild/makefiles.html#compilation-flags
375     See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
384     See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
393     See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
402     See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
413       &zero     ->  SYSCTL_ZERO
414       &one      ->  SYSCTL_ONE
415       &int_max  ->  SYSCTL_INT_MAX
419       1. https://lore.kernel.org/lkml/20190430180111.10688-1-mcroce@redhat.com/
420       2. https://lore.kernel.org/lkml/20190531131422.14970-1-mcroce@redhat.com/
446     See: https://lore.kernel.org/lkml/20080320201723.b87b3732.akpm@linux-foundation.org/
450     prevent warnings on conversion of device->sem to device->mutex.
464     See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
473 …www.kernel.org/doc/html/latest/timers/timers-howto.html#delays-information-on-the-various-kernel-d…
477 --------
480     The comment style is incorrect.  The preferred style for multi-
495     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
498     C99 style single line comments (//) should not be used.
501     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
507     See: https://lore.kernel.org/lkml/20200401101714.44781-1-elver@google.com/
520 --------------
523     The signed-off-by line does not fall in line with the standards
526 …//www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin…
541     comments.  To solve this problem addition of a single space
548 …  See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
555 …  See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
558     The author's email does not match with that in the Signed-off-by:
564       - The email names do not match.
565       - The email addresses do not match.
566       - The email subaddresses do not match.
567       - The email comments do not match.
570     The patch is missing a Signed-off-by line.  A signed-off-by
574 ….kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certifi…
579     end of explanation of the patch to denote that the author has
583 ….kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certifi…
591     See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/
595     have a Change-Id like::
597       Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
598       Signed-off-by: A. U. Thor <author@example.com>
600     The Change-Id line must be removed before submitting.
610       platform_set_drvdata(), but left the variable "dev" unused,
613 …  See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
620 …  See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
624 ----------------
641     See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
648     Comparisons with a constant or upper case identifier on the left
653 ---------------------------
660     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
692     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
696     To use a different maximum line length, the --max-line-length=n option
700     ("checkpatch/coding-style: deprecate 80-column warning") increased the
704 …See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-stri…
708     To use a different maximum line length, the --max-line-length=n option
711 …See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-stri…
715     To use a different maximum line length, the --max-line-length=n option
718 …See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-stri…
727     A single dereferencing identifier spanned on multiple lines like::
729       struct_identifier->member[index].
742       member1->member2->member3.foo1;
743       member1->member2->member3.foo2;
745     then store the member1->member2->member3 part in a temporary variable.
751     on a single line.
767 ------------------------------
791     the beginning or end of code regions via
806     read-only.  The __read_mostly annotation thus should be removed.
815     non-deterministic builds.
817     See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
869     See: https://lore.kernel.org/lkml/1377655732.3619.19.camel@joe-AO722/
873     do - while block.  Same should also be the case for macros
882     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
889     Macro definition should not end with a semicolon. The macro
907     See: https://lore.kernel.org/lkml/1399671106.2912.21.camel@joe-AO725/
910     If function-like macros do not utilize a parameter, it might result
919       WARNING: Argument 'a' is not used in function-like macro.
921     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
924     For the multi-statement macros, it is necessary to use the do-while
925     loop to avoid unpredictable code paths. The do-while loop helps to
926     group the multiple statements into a single one so that a
927     function-like macro can be used as a function only.
929     But for the single statement macros, it is unnecessary to use the
930     do-while loop. Although the code is syntactically correct but using
931     the do-while loop is redundant. So remove the do-while loop for single
940 -----------------------
945     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
966     Note that this does not work with -f (--file) checkpatch option
1010     Multiple assignments on a single line makes the code unnecessarily
1011     complicated. So on a single line assign value to a single variable
1025 -----------
1029     Typically only three permissions are used - 0644 (RW), 0444 (RO)
1042     any local user to write arbitrary values into device registers - a
1045     See: https://lore.kernel.org/linux-arm-kernel/cover.1296818921.git.segoon@openwall.com/
1053     understand than their symbolic counterparts because many command-line
1060 …See: https://lore.kernel.org/lkml/CA+55aFw5v23T-zvDZp-MmD_EYxF8WbafwwB59934FV7g21uMGQ@mail.gmail.c…
1064 --------------------
1079     This applies for all non-functional blocks.
1088     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1094     1. With a type on the left::
1119     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1125     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1129     next line.  For any non-functional block it should be on the same line
1132     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1144     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1149     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1156     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1163           (foo->bar)();
1167           foo->bar();
1171           if ((foo->bar) && (foo->baz))
1176           if (foo->bar && foo->baz)
1179       3. addressof/dereference single Lvalues::
1181           &(foo->bar)
1182           *(foo->bar)
1186           &foo->bar
1187           *foo->bar
1196     See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1200 ------
1223     For DOS-formatted patches, there are extra ^M symbols at the end of
1227     DT bindings moved to a json-schema based format instead of
1230     See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html
1237     DT only tree created with git-filter-branch.
1239 …//www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters
1256     The patch file does not appear to be in unified-diff format.  Please
1267     See: https://www.kernel.org/doc/html/latest/process/license-rules.html