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
250    See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
251
252  **ALLOC_SIZEOF_STRUCT**
253    The allocation style is bad.  In general for family of
254    allocation functions using sizeof() to get memory size,
255    constructs like::
256
257      p = alloc(sizeof(struct foo), ...)
258
259    should be::
260
261      p = alloc(sizeof(*p), ...)
262
263    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory
264
265  **ALLOC_WITH_MULTIPLY**
266    Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
267    sizeof multiply.
268
269    See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
270
271
272API usage
273---------
274
275  **ARCH_DEFINES**
276    Architecture specific defines should be avoided wherever
277    possible.
278
279  **ARCH_INCLUDE_LINUX**
280    Whenever asm/file.h is included and linux/file.h exists, a
281    conversion can be made when linux/file.h includes asm/file.h.
282    However this is not always the case (See signal.h).
283    This message type is emitted only for includes from arch/.
284
285  **AVOID_BUG**
286    BUG() or BUG_ON() should be avoided totally.
287    Use WARN() and WARN_ON() instead, and handle the "impossible"
288    error condition as gracefully as possible.
289
290    See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
291
292  **CONSIDER_KSTRTO**
293    The simple_strtol(), simple_strtoll(), simple_strtoul(), and
294    simple_strtoull() functions explicitly ignore overflows, which
295    may lead to unexpected results in callers.  The respective kstrtol(),
296    kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the
297    correct replacements.
298
299    See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
300
301  **CONSTANT_CONVERSION**
302    Use of __constant_<foo> form is discouraged for the following functions::
303
304      __constant_cpu_to_be[x]
305      __constant_cpu_to_le[x]
306      __constant_be[x]_to_cpu
307      __constant_le[x]_to_cpu
308      __constant_htons
309      __constant_ntohs
310
311    Using any of these outside of include/uapi/ is not preferred as using the
312    function without __constant_ is identical when the argument is a
313    constant.
314
315    In big endian systems, the macros like __constant_cpu_to_be32(x) and
316    cpu_to_be32(x) expand to the same expression::
317
318      #define __constant_cpu_to_be32(x) ((__force __be32)(__u32)(x))
319      #define __cpu_to_be32(x)          ((__force __be32)(__u32)(x))
320
321    In little endian systems, the macros __constant_cpu_to_be32(x) and
322    cpu_to_be32(x) expand to __constant_swab32 and __swab32.  __swab32
323    has a __builtin_constant_p check::
324
325      #define __swab32(x)				\
326        (__builtin_constant_p((__u32)(x)) ?	\
327        ___constant_swab32(x) :			\
328        __fswab32(x))
329
330    So ultimately they have a special case for constants.
331    Similar is the case with all of the macros in the list.  Thus
332    using the __constant_... forms are unnecessarily verbose and
333    not preferred outside of include/uapi.
334
335    See: https://lore.kernel.org/lkml/1400106425.12666.6.camel@joe-AO725/
336
337  **DEPRECATED_API**
338    Usage of a deprecated RCU API is detected.  It is recommended to replace
339    old flavourful RCU APIs by their new vanilla-RCU counterparts.
340
341    The full list of available RCU APIs can be viewed from the kernel docs.
342
343    See: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis
344
345  **DEPRECATED_VARIABLE**
346    EXTRA_{A,C,CPP,LD}FLAGS are deprecated and should be replaced by the new
347    flags added via commit f77bf01425b1 ("kbuild: introduce ccflags-y,
348    asflags-y and ldflags-y").
349
350    The following conversion scheme maybe used::
351
352      EXTRA_AFLAGS    ->  asflags-y
353      EXTRA_CFLAGS    ->  ccflags-y
354      EXTRA_CPPFLAGS  ->  cppflags-y
355      EXTRA_LDFLAGS   ->  ldflags-y
356
357    See:
358
359      1. https://lore.kernel.org/lkml/20070930191054.GA15876@uranus.ravnborg.org/
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
362
363  **DEVICE_ATTR_FUNCTIONS**
364    The function names used in DEVICE_ATTR is unusual.
365    Typically, the store and show functions are used with <attr>_store and
366    <attr>_show, where <attr> is a named attribute variable of the device.
367
368    Consider the following examples::
369
370      static DEVICE_ATTR(type, 0444, type_show, NULL);
371      static DEVICE_ATTR(power, 0644, power_show, power_store);
372
373    The function names should preferably follow the above pattern.
374
375    See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
376
377  **DEVICE_ATTR_RO**
378    The DEVICE_ATTR_RO(name) helper macro can be used instead of
379    DEVICE_ATTR(name, 0444, name_show, NULL);
380
381    Note that the macro automatically appends _show to the named
382    attribute variable of the device for the show method.
383
384    See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
385
386  **DEVICE_ATTR_RW**
387    The DEVICE_ATTR_RW(name) helper macro can be used instead of
388    DEVICE_ATTR(name, 0644, name_show, name_store);
389
390    Note that the macro automatically appends _show and _store to the
391    named attribute variable of the device for the show and store methods.
392
393    See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
394
395  **DEVICE_ATTR_WO**
396    The DEVICE_AATR_WO(name) helper macro can be used instead of
397    DEVICE_ATTR(name, 0200, NULL, name_store);
398
399    Note that the macro automatically appends _store to the
400    named attribute variable of the device for the store method.
401
402    See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
403
404  **DUPLICATED_SYSCTL_CONST**
405    Commit d91bff3011cf ("proc/sysctl: add shared variables for range
406    check") added some shared const variables to be used instead of a local
407    copy in each source file.
408
409    Consider replacing the sysctl range checking value with the shared
410    one in include/linux/sysctl.h.  The following conversion scheme may
411    be used::
412
413      &zero     ->  SYSCTL_ZERO
414      &one      ->  SYSCTL_ONE
415      &int_max  ->  SYSCTL_INT_MAX
416
417    See:
418
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/
421
422  **ENOSYS**
423    ENOSYS means that a nonexistent system call was called.
424    Earlier, it was wrongly used for things like invalid operations on
425    otherwise valid syscalls.  This should be avoided in new code.
426
427    See: https://lore.kernel.org/lkml/5eb299021dec23c1a48fa7d9f2c8b794e967766d.1408730669.git.luto@amacapital.net/
428
429  **ENOTSUPP**
430    ENOTSUPP is not a standard error code and should be avoided in new patches.
431    EOPNOTSUPP should be used instead.
432
433    See: https://lore.kernel.org/netdev/20200510182252.GA411829@lunn.ch/
434
435  **EXPORT_SYMBOL**
436    EXPORT_SYMBOL should immediately follow the symbol to be exported.
437
438  **IN_ATOMIC**
439    in_atomic() is not for driver use so any such use is reported as an ERROR.
440    Also in_atomic() is often used to determine if sleeping is permitted,
441    but it is not reliable in this use model.  Therefore its use is
442    strongly discouraged.
443
444    However, in_atomic() is ok for core kernel use.
445
446    See: https://lore.kernel.org/lkml/20080320201723.b87b3732.akpm@linux-foundation.org/
447
448  **LOCKDEP**
449    The lockdep_no_validate class was added as a temporary measure to
450    prevent warnings on conversion of device->sem to device->mutex.
451    It should not be used for any other purpose.
452
453    See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
454
455  **MALFORMED_INCLUDE**
456    The #include statement has a malformed path.  This has happened
457    because the author has included a double slash "//" in the pathname
458    accidentally.
459
460  **USE_LOCKDEP**
461    lockdep_assert_held() annotations should be preferred over
462    assertions based on spin_is_locked()
463
464    See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
465
466  **UAPI_INCLUDE**
467    No #include statements in include/uapi should use a uapi/ path.
468
469  **USLEEP_RANGE**
470    usleep_range() should be preferred over udelay(). The proper way of
471    using usleep_range() is mentioned in the kernel docs.
472
473    See: https://www.kernel.org/doc/html/latest/timers/timers-howto.html#delays-information-on-the-various-kernel-delay-sleep-mechanisms
474
475
476Comments
477--------
478
479  **BLOCK_COMMENT_STYLE**
480    The comment style is incorrect.  The preferred style for multi-
481    line comments is::
482
483      /*
484      * This is the preferred style
485      * for multi line comments.
486      */
487
488    The networking comment style is a bit different, with the first line
489    not empty like the former::
490
491      /* This is the preferred comment style
492      * for files in net/ and drivers/net/
493      */
494
495    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
496
497  **C99_COMMENTS**
498    C99 style single line comments (//) should not be used.
499    Prefer the block comment style instead.
500
501    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
502
503  **DATA_RACE**
504    Applications of data_race() should have a comment so as to document the
505    reasoning behind why it was deemed safe.
506
507    See: https://lore.kernel.org/lkml/20200401101714.44781-1-elver@google.com/
508
509  **FSF_MAILING_ADDRESS**
510    Kernel maintainers reject new instances of the GPL boilerplate paragraph
511    directing people to write to the FSF for a copy of the GPL, since the
512    FSF has moved in the past and may do so again.
513    So do not write paragraphs about writing to the Free Software Foundation's
514    mailing address.
515
516    See: https://lore.kernel.org/lkml/20131006222342.GT19510@leaf/
517
518
519Commit message
520--------------
521
522  **BAD_SIGN_OFF**
523    The signed-off-by line does not fall in line with the standards
524    specified by the community.
525
526    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
527
528  **BAD_STABLE_ADDRESS_STYLE**
529    The email format for stable is incorrect.
530    Some valid options for stable address are::
531
532      1. stable@vger.kernel.org
533      2. stable@kernel.org
534
535    For adding version info, the following comment style should be used::
536
537      stable@vger.kernel.org # version info
538
539  **COMMIT_COMMENT_SYMBOL**
540    Commit log lines starting with a '#' are ignored by git as
541    comments.  To solve this problem addition of a single space
542    infront of the log line is enough.
543
544  **COMMIT_MESSAGE**
545    The patch is missing a commit description.  A brief
546    description of the changes made by the patch should be added.
547
548    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
549
550  **EMAIL_SUBJECT**
551    Naming the tool that found the issue is not very useful in the
552    subject line.  A good subject line summarizes the change that
553    the patch brings.
554
555    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
556
557  **FROM_SIGN_OFF_MISMATCH**
558    The author's email does not match with that in the Signed-off-by:
559    line(s). This can be sometimes caused due to an improperly configured
560    email client.
561
562    This message is emitted due to any of the following reasons::
563
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.
568
569  **MISSING_SIGN_OFF**
570    The patch is missing a Signed-off-by line.  A signed-off-by
571    line should be added according to Developer's certificate of
572    Origin.
573
574    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
575
576  **NO_AUTHOR_SIGN_OFF**
577    The author of the patch has not signed off the patch.  It is
578    required that a simple sign off line should be present at the
579    end of explanation of the patch to denote that the author has
580    written it or otherwise has the rights to pass it on as an open
581    source patch.
582
583    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
584
585  **DIFF_IN_COMMIT_MSG**
586    Avoid having diff content in commit message.
587    This causes problems when one tries to apply a file containing both
588    the changelog and the diff because patch(1) tries to apply the diff
589    which it found in the changelog.
590
591    See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/
592
593  **GERRIT_CHANGE_ID**
594    To be picked up by gerrit, the footer of the commit message might
595    have a Change-Id like::
596
597      Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
598      Signed-off-by: A. U. Thor <author@example.com>
599
600    The Change-Id line must be removed before submitting.
601
602  **GIT_COMMIT_ID**
603    The proper way to reference a commit id is:
604    commit <12+ chars of sha1> ("<title line>")
605
606    An example may be::
607
608      Commit e21d2170f36602ae2708 ("video: remove unnecessary
609      platform_set_drvdata()") removed the unnecessary
610      platform_set_drvdata(), but left the variable "dev" unused,
611      delete it.
612
613    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
614
615  **BAD_FIXES_TAG**
616    The Fixes: tag is malformed or does not follow the community conventions.
617    This can occur if the tag have been split into multiple lines (e.g., when
618    pasted in an email program with word wrapping enabled).
619
620    See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
621
622
623Comparison style
624----------------
625
626  **ASSIGN_IN_IF**
627    Do not use assignments in if condition.
628    Example::
629
630      if ((foo = bar(...)) < BAZ) {
631
632    should be written as::
633
634      foo = bar(...);
635      if (foo < BAZ) {
636
637  **BOOL_COMPARISON**
638    Comparisons of A to true and false are better written
639    as A and !A.
640
641    See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
642
643  **COMPARISON_TO_NULL**
644    Comparisons to NULL in the form (foo == NULL) or (foo != NULL)
645    are better written as (!foo) and (foo).
646
647  **CONSTANT_COMPARISON**
648    Comparisons with a constant or upper case identifier on the left
649    side of the test should be avoided.
650
651
652Indentation and Line Breaks
653---------------------------
654
655  **CODE_INDENT**
656    Code indent should use tabs instead of spaces.
657    Outside of comments, documentation and Kconfig,
658    spaces are never used for indentation.
659
660    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
661
662  **DEEP_INDENTATION**
663    Indentation with 6 or more tabs usually indicate overly indented
664    code.
665
666    It is suggested to refactor excessive indentation of
667    if/else/for/do/while/switch statements.
668
669    See: https://lore.kernel.org/lkml/1328311239.21255.24.camel@joe2Laptop/
670
671  **SWITCH_CASE_INDENT_LEVEL**
672    switch should be at the same indent as case.
673    Example::
674
675      switch (suffix) {
676      case 'G':
677      case 'g':
678              mem <<= 30;
679              break;
680      case 'M':
681      case 'm':
682              mem <<= 20;
683              break;
684      case 'K':
685      case 'k':
686              mem <<= 10;
687              fallthrough;
688      default:
689              break;
690      }
691
692    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
693
694  **LONG_LINE**
695    The line has exceeded the specified maximum length.
696    To use a different maximum line length, the --max-line-length=n option
697    may be added while invoking checkpatch.
698
699    Earlier, the default line length was 80 columns.  Commit bdc48fa11e46
700    ("checkpatch/coding-style: deprecate 80-column warning") increased the
701    limit to 100 columns.  This is not a hard limit either and it's
702    preferable to stay within 80 columns whenever possible.
703
704    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
705
706  **LONG_LINE_STRING**
707    A string starts before but extends beyond the maximum line length.
708    To use a different maximum line length, the --max-line-length=n option
709    may be added while invoking checkpatch.
710
711    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
712
713  **LONG_LINE_COMMENT**
714    A comment starts before but extends beyond the maximum line length.
715    To use a different maximum line length, the --max-line-length=n option
716    may be added while invoking checkpatch.
717
718    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
719
720  **SPLIT_STRING**
721    Quoted strings that appear as messages in userspace and can be
722    grepped, should not be split across multiple lines.
723
724    See: https://lore.kernel.org/lkml/20120203052727.GA15035@leaf/
725
726  **MULTILINE_DEREFERENCE**
727    A single dereferencing identifier spanned on multiple lines like::
728
729      struct_identifier->member[index].
730      member = <foo>;
731
732    is generally hard to follow. It can easily lead to typos and so makes
733    the code vulnerable to bugs.
734
735    If fixing the multiple line dereferencing leads to an 80 column
736    violation, then either rewrite the code in a more simple way or if the
737    starting part of the dereferencing identifier is the same and used at
738    multiple places then store it in a temporary variable, and use that
739    temporary variable only at all the places. For example, if there are
740    two dereferencing identifiers::
741
742      member1->member2->member3.foo1;
743      member1->member2->member3.foo2;
744
745    then store the member1->member2->member3 part in a temporary variable.
746    It not only helps to avoid the 80 column violation but also reduces
747    the program size by removing the unnecessary dereferences.
748
749    But if none of the above methods work then ignore the 80 column
750    violation because it is much easier to read a dereferencing identifier
751    on a single line.
752
753  **TRAILING_STATEMENTS**
754    Trailing statements (for example after any conditional) should be
755    on the next line.
756    Statements, such as::
757
758      if (x == y) break;
759
760    should be::
761
762      if (x == y)
763              break;
764
765
766Macros, Attributes and Symbols
767------------------------------
768
769  **ARRAY_SIZE**
770    The ARRAY_SIZE(foo) macro should be preferred over
771    sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
772    array.
773
774    The macro is defined in include/linux/kernel.h::
775
776      #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
777
778  **AVOID_EXTERNS**
779    Function prototypes don't need to be declared extern in .h
780    files.  It's assumed by the compiler and is unnecessary.
781
782  **AVOID_L_PREFIX**
783    Local symbol names that are prefixed with `.L` should be avoided,
784    as this has special meaning for the assembler; a symbol entry will
785    not be emitted into the symbol table.  This can prevent `objtool`
786    from generating correct unwind info.
787
788    Symbols with STB_LOCAL binding may still be used, and `.L` prefixed
789    local symbol names are still generally usable within a function,
790    but `.L` prefixed local symbol names should not be used to denote
791    the beginning or end of code regions via
792    `SYM_CODE_START_LOCAL`/`SYM_CODE_END`
793
794  **BIT_MACRO**
795    Defines like: 1 << <digit> could be BIT(digit).
796    The BIT() macro is defined via include/linux/bits.h::
797
798      #define BIT(nr)         (1UL << (nr))
799
800  **CONST_READ_MOSTLY**
801    When a variable is tagged with the __read_mostly annotation, it is a
802    signal to the compiler that accesses to the variable will be mostly
803    reads and rarely(but NOT never) a write.
804
805    const __read_mostly does not make any sense as const data is already
806    read-only.  The __read_mostly annotation thus should be removed.
807
808  **DATE_TIME**
809    It is generally desirable that building the same source code with
810    the same set of tools is reproducible, i.e. the output is always
811    exactly the same.
812
813    The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
814    and enables warnings if they are used as they can lead to
815    non-deterministic builds.
816
817    See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
818
819  **DEFINE_ARCH_HAS**
820    The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong.
821
822    For big conceptual features use Kconfig symbols instead.  And for
823    smaller things where we have compatibility fallback functions but
824    want architectures able to override them with optimized ones, we
825    should either use weak functions (appropriate for some cases), or
826    the symbol that protects them should be the same symbol we use.
827
828    See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/
829
830  **DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON**
831    do {} while(0) macros should not have a trailing semicolon.
832
833  **INIT_ATTRIBUTE**
834    Const init definitions should use __initconst instead of
835    __initdata.
836
837    Similarly init definitions without const require a separate
838    use of const.
839
840  **INLINE_LOCATION**
841    The inline keyword should sit between storage class and type.
842
843    For example, the following segment::
844
845      inline static int example_function(void)
846      {
847              ...
848      }
849
850    should be::
851
852      static inline int example_function(void)
853      {
854              ...
855      }
856
857  **MISPLACED_INIT**
858    It is possible to use section markers on variables in a way
859    which gcc doesn't understand (or at least not the way the
860    developer intended)::
861
862      static struct __initdata samsung_pll_clock exynos4_plls[nr_plls] = {
863
864    does not put exynos4_plls in the .initdata section. The __initdata
865    marker can be virtually anywhere on the line, except right after
866    "struct". The preferred location is before the "=" sign if there is
867    one, or before the trailing ";" otherwise.
868
869    See: https://lore.kernel.org/lkml/1377655732.3619.19.camel@joe-AO722/
870
871  **MULTISTATEMENT_MACRO_USE_DO_WHILE**
872    Macros with multiple statements should be enclosed in a
873    do - while block.  Same should also be the case for macros
874    starting with `if` to avoid logic defects::
875
876      #define macrofun(a, b, c)                 \
877        do {                                    \
878                if (a == 5)                     \
879                        do_this(b, c);          \
880        } while (0)
881
882    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
883
884  **PREFER_FALLTHROUGH**
885    Use the `fallthrough;` pseudo keyword instead of
886    `/* fallthrough */` like comments.
887
888  **TRAILING_SEMICOLON**
889    Macro definition should not end with a semicolon. The macro
890    invocation style should be consistent with function calls.
891    This can prevent any unexpected code paths::
892
893      #define MAC do_something;
894
895    If this macro is used within a if else statement, like::
896
897      if (some_condition)
898              MAC;
899
900      else
901              do_something;
902
903    Then there would be a compilation error, because when the macro is
904    expanded there are two trailing semicolons, so the else branch gets
905    orphaned.
906
907    See: https://lore.kernel.org/lkml/1399671106.2912.21.camel@joe-AO725/
908
909  **SINGLE_STATEMENT_DO_WHILE_MACRO**
910    For the multi-statement macros, it is necessary to use the do-while
911    loop to avoid unpredictable code paths. The do-while loop helps to
912    group the multiple statements into a single one so that a
913    function-like macro can be used as a function only.
914
915    But for the single statement macros, it is unnecessary to use the
916    do-while loop. Although the code is syntactically correct but using
917    the do-while loop is redundant. So remove the do-while loop for single
918    statement macros.
919
920  **WEAK_DECLARATION**
921    Using weak declarations like __attribute__((weak)) or __weak
922    can have unintended link defects.  Avoid using them.
923
924
925Functions and Variables
926-----------------------
927
928  **CAMELCASE**
929    Avoid CamelCase Identifiers.
930
931    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
932
933  **CONST_CONST**
934    Using `const <type> const *` is generally meant to be
935    written `const <type> * const`.
936
937  **CONST_STRUCT**
938    Using const is generally a good idea.  Checkpatch reads
939    a list of frequently used structs that are always or
940    almost always constant.
941
942    The existing structs list can be viewed from
943    `scripts/const_structs.checkpatch`.
944
945    See: https://lore.kernel.org/lkml/alpine.DEB.2.10.1608281509480.3321@hadrien/
946
947  **EMBEDDED_FUNCTION_NAME**
948    Embedded function names are less appropriate to use as
949    refactoring can cause function renaming.  Prefer the use of
950    "%s", __func__ to embedded function names.
951
952    Note that this does not work with -f (--file) checkpatch option
953    as it depends on patch context providing the function name.
954
955  **FUNCTION_ARGUMENTS**
956    This warning is emitted due to any of the following reasons:
957
958      1. Arguments for the function declaration do not follow
959         the identifier name.  Example::
960
961           void foo
962           (int bar, int baz)
963
964         This should be corrected to::
965
966           void foo(int bar, int baz)
967
968      2. Some arguments for the function definition do not
969         have an identifier name.  Example::
970
971           void foo(int)
972
973         All arguments should have identifier names.
974
975  **FUNCTION_WITHOUT_ARGS**
976    Function declarations without arguments like::
977
978      int foo()
979
980    should be::
981
982      int foo(void)
983
984  **GLOBAL_INITIALISERS**
985    Global variables should not be initialized explicitly to
986    0 (or NULL, false, etc.).  Your compiler (or rather your
987    loader, which is responsible for zeroing out the relevant
988    sections) automatically does it for you.
989
990  **INITIALISED_STATIC**
991    Static variables should not be initialized explicitly to zero.
992    Your compiler (or rather your loader) automatically does
993    it for you.
994
995  **MULTIPLE_ASSIGNMENTS**
996    Multiple assignments on a single line makes the code unnecessarily
997    complicated. So on a single line assign value to a single variable
998    only, this makes the code more readable and helps avoid typos.
999
1000  **RETURN_PARENTHESES**
1001    return is not a function and as such doesn't need parentheses::
1002
1003      return (bar);
1004
1005    can simply be::
1006
1007      return bar;
1008
1009
1010Permissions
1011-----------
1012
1013  **DEVICE_ATTR_PERMS**
1014    The permissions used in DEVICE_ATTR are unusual.
1015    Typically only three permissions are used - 0644 (RW), 0444 (RO)
1016    and 0200 (WO).
1017
1018    See: https://www.kernel.org/doc/html/latest/filesystems/sysfs.html#attributes
1019
1020  **EXECUTE_PERMISSIONS**
1021    There is no reason for source files to be executable.  The executable
1022    bit can be removed safely.
1023
1024  **EXPORTED_WORLD_WRITABLE**
1025    Exporting world writable sysfs/debugfs files is usually a bad thing.
1026    When done arbitrarily they can introduce serious security bugs.
1027    In the past, some of the debugfs vulnerabilities would seemingly allow
1028    any local user to write arbitrary values into device registers - a
1029    situation from which little good can be expected to emerge.
1030
1031    See: https://lore.kernel.org/linux-arm-kernel/cover.1296818921.git.segoon@openwall.com/
1032
1033  **NON_OCTAL_PERMISSIONS**
1034    Permission bits should use 4 digit octal permissions (like 0700 or 0444).
1035    Avoid using any other base like decimal.
1036
1037  **SYMBOLIC_PERMS**
1038    Permission bits in the octal form are more readable and easier to
1039    understand than their symbolic counterparts because many command-line
1040    tools use this notation. Experienced kernel developers have been using
1041    these traditional Unix permission bits for decades and so they find it
1042    easier to understand the octal notation than the symbolic macros.
1043    For example, it is harder to read S_IWUSR|S_IRUGO than 0644, which
1044    obscures the developer's intent rather than clarifying it.
1045
1046    See: https://lore.kernel.org/lkml/CA+55aFw5v23T-zvDZp-MmD_EYxF8WbafwwB59934FV7g21uMGQ@mail.gmail.com/
1047
1048
1049Spacing and Brackets
1050--------------------
1051
1052  **ASSIGNMENT_CONTINUATIONS**
1053    Assignment operators should not be written at the start of a
1054    line but should follow the operand at the previous line.
1055
1056  **BRACES**
1057    The placement of braces is stylistically incorrect.
1058    The preferred way is to put the opening brace last on the line,
1059    and put the closing brace first::
1060
1061      if (x is true) {
1062              we do y
1063      }
1064
1065    This applies for all non-functional blocks.
1066    However, there is one special case, namely functions: they have the
1067    opening brace at the beginning of the next line, thus::
1068
1069      int function(int x)
1070      {
1071              body of function
1072      }
1073
1074    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1075
1076  **BRACKET_SPACE**
1077    Whitespace before opening bracket '[' is prohibited.
1078    There are some exceptions:
1079
1080    1. With a type on the left::
1081
1082        int [] a;
1083
1084    2. At the beginning of a line for slice initialisers::
1085
1086        [0...10] = 5,
1087
1088    3. Inside a curly brace::
1089
1090        = { [0...10] = 5 }
1091
1092  **CONCATENATED_STRING**
1093    Concatenated elements should have a space in between.
1094    Example::
1095
1096      printk(KERN_INFO"bar");
1097
1098    should be::
1099
1100      printk(KERN_INFO "bar");
1101
1102  **ELSE_AFTER_BRACE**
1103    `else {` should follow the closing block `}` on the same line.
1104
1105    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1106
1107  **LINE_SPACING**
1108    Vertical space is wasted given the limited number of lines an
1109    editor window can display when multiple blank lines are used.
1110
1111    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1112
1113  **OPEN_BRACE**
1114    The opening brace should be following the function definitions on the
1115    next line.  For any non-functional block it should be on the same line
1116    as the last construct.
1117
1118    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1119
1120  **POINTER_LOCATION**
1121    When using pointer data or a function that returns a pointer type,
1122    the preferred use of * is adjacent to the data name or function name
1123    and not adjacent to the type name.
1124    Examples::
1125
1126      char *linux_banner;
1127      unsigned long long memparse(char *ptr, char **retptr);
1128      char *match_strdup(substring_t *s);
1129
1130    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1131
1132  **SPACING**
1133    Whitespace style used in the kernel sources is described in kernel docs.
1134
1135    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1136
1137  **TRAILING_WHITESPACE**
1138    Trailing whitespace should always be removed.
1139    Some editors highlight the trailing whitespace and cause visual
1140    distractions when editing files.
1141
1142    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1143
1144  **UNNECESSARY_PARENTHESES**
1145    Parentheses are not required in the following cases:
1146
1147      1. Function pointer uses::
1148
1149          (foo->bar)();
1150
1151        could be::
1152
1153          foo->bar();
1154
1155      2. Comparisons in if::
1156
1157          if ((foo->bar) && (foo->baz))
1158          if ((foo == bar))
1159
1160        could be::
1161
1162          if (foo->bar && foo->baz)
1163          if (foo == bar)
1164
1165      3. addressof/dereference single Lvalues::
1166
1167          &(foo->bar)
1168          *(foo->bar)
1169
1170        could be::
1171
1172          &foo->bar
1173          *foo->bar
1174
1175  **WHILE_AFTER_BRACE**
1176    while should follow the closing bracket on the same line::
1177
1178      do {
1179              ...
1180      } while(something);
1181
1182    See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1183
1184
1185Others
1186------
1187
1188  **CONFIG_DESCRIPTION**
1189    Kconfig symbols should have a help text which fully describes
1190    it.
1191
1192  **CORRUPTED_PATCH**
1193    The patch seems to be corrupted or lines are wrapped.
1194    Please regenerate the patch file before sending it to the maintainer.
1195
1196  **CVS_KEYWORD**
1197    Since linux moved to git, the CVS markers are no longer used.
1198    So, CVS style keywords ($Id$, $Revision$, $Log$) should not be
1199    added.
1200
1201  **DEFAULT_NO_BREAK**
1202    switch default case is sometimes written as "default:;".  This can
1203    cause new cases added below default to be defective.
1204
1205    A "break;" should be added after empty default statement to avoid
1206    unwanted fallthrough.
1207
1208  **DOS_LINE_ENDINGS**
1209    For DOS-formatted patches, there are extra ^M symbols at the end of
1210    the line.  These should be removed.
1211
1212  **DT_SCHEMA_BINDING_PATCH**
1213    DT bindings moved to a json-schema based format instead of
1214    freeform text.
1215
1216    See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html
1217
1218  **DT_SPLIT_BINDING_PATCH**
1219    Devicetree bindings should be their own patch.  This is because
1220    bindings are logically independent from a driver implementation,
1221    they have a different maintainer (even though they often
1222    are applied via the same tree), and it makes for a cleaner history in the
1223    DT only tree created with git-filter-branch.
1224
1225    See: https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters
1226
1227  **EMBEDDED_FILENAME**
1228    Embedding the complete filename path inside the file isn't particularly
1229    useful as often the path is moved around and becomes incorrect.
1230
1231  **FILE_PATH_CHANGES**
1232    Whenever files are added, moved, or deleted, the MAINTAINERS file
1233    patterns can be out of sync or outdated.
1234
1235    So MAINTAINERS might need updating in these cases.
1236
1237  **MEMSET**
1238    The memset use appears to be incorrect.  This may be caused due to
1239    badly ordered parameters.  Please recheck the usage.
1240
1241  **NOT_UNIFIED_DIFF**
1242    The patch file does not appear to be in unified-diff format.  Please
1243    regenerate the patch file before sending it to the maintainer.
1244
1245  **PRINTF_0XDECIMAL**
1246    Prefixing 0x with decimal output is defective and should be corrected.
1247
1248  **SPDX_LICENSE_TAG**
1249    The source file is missing or has an improper SPDX identifier tag.
1250    The Linux kernel requires the precise SPDX identifier in all source files,
1251    and it is thoroughly documented in the kernel docs.
1252
1253    See: https://www.kernel.org/doc/html/latest/process/license-rules.html
1254
1255  **TYPO_SPELLING**
1256    Some words may have been misspelled.  Consider reviewing them.
1257