0001 .. SPDX-License-Identifier: GPL-2.0-only
0002
0003 ==========
0004 Checkpatch
0005 ==========
0006
0007 Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial
0008 style violations in patches and optionally corrects them. Checkpatch can
0009 also be run on file contexts and without the kernel tree.
0010
0011 Checkpatch is not always right. Your judgement takes precedence over checkpatch
0012 messages. If your code looks better with the violations, then its probably
0013 best left alone.
0014
0015
0016 Options
0017 =======
0018
0019 This section will describe the options checkpatch can be run with.
0020
0021 Usage::
0022
0023 ./scripts/checkpatch.pl [OPTION]... [FILE]...
0024
0025 Available options:
0026
0027 - -q, --quiet
0028
0029 Enable quiet mode.
0030
0031 - -v, --verbose
0032 Enable verbose mode. Additional verbose test descriptions are output
0033 so as to provide information on why that particular message is shown.
0034
0035 - --no-tree
0036
0037 Run checkpatch without the kernel tree.
0038
0039 - --no-signoff
0040
0041 Disable the 'Signed-off-by' line check. The sign-off is a simple line at
0042 the end of the explanation for the patch, which certifies that you wrote it
0043 or otherwise have the right to pass it on as an open-source patch.
0044
0045 Example::
0046
0047 Signed-off-by: Random J Developer <random@developer.example.org>
0048
0049 Setting this flag effectively stops a message for a missing signed-off-by
0050 line in a patch context.
0051
0052 - --patch
0053
0054 Treat FILE as a patch. This is the default option and need not be
0055 explicitly specified.
0056
0057 - --emacs
0058
0059 Set output to emacs compile window format. This allows emacs users to jump
0060 from the error in the compile window directly to the offending line in the
0061 patch.
0062
0063 - --terse
0064
0065 Output only one line per report.
0066
0067 - --showfile
0068
0069 Show the diffed file position instead of the input file position.
0070
0071 - -g, --git
0072
0073 Treat FILE as a single commit or a git revision range.
0074
0075 Single commit with:
0076
0077 - <rev>
0078 - <rev>^
0079 - <rev>~n
0080
0081 Multiple commits with:
0082
0083 - <rev1>..<rev2>
0084 - <rev1>...<rev2>
0085 - <rev>-<count>
0086
0087 - -f, --file
0088
0089 Treat FILE as a regular source file. This option must be used when running
0090 checkpatch on source files in the kernel.
0091
0092 - --subjective, --strict
0093
0094 Enable stricter tests in checkpatch. By default the tests emitted as CHECK
0095 do not activate by default. Use this flag to activate the CHECK tests.
0096
0097 - --list-types
0098
0099 Every message emitted by checkpatch has an associated TYPE. Add this flag
0100 to display all the types in checkpatch.
0101
0102 Note that when this flag is active, checkpatch does not read the input FILE,
0103 and no message is emitted. Only a list of types in checkpatch is output.
0104
0105 - --types TYPE(,TYPE2...)
0106
0107 Only display messages with the given types.
0108
0109 Example::
0110
0111 ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES
0112
0113 - --ignore TYPE(,TYPE2...)
0114
0115 Checkpatch will not emit messages for the specified types.
0116
0117 Example::
0118
0119 ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES
0120
0121 - --show-types
0122
0123 By default checkpatch doesn't display the type associated with the messages.
0124 Set this flag to show the message type in the output.
0125
0126 - --max-line-length=n
0127
0128 Set the max line length (default 100). If a line exceeds the specified
0129 length, a LONG_LINE message is emitted.
0130
0131
0132 The message level is different for patch and file contexts. For patches,
0133 a WARNING is emitted. While a milder CHECK is emitted for files. So for
0134 file contexts, the --strict flag must also be enabled.
0135
0136 - --min-conf-desc-length=n
0137
0138 Set the Kconfig entry minimum description length, if shorter, warn.
0139
0140 - --tab-size=n
0141
0142 Set the number of spaces for tab (default 8).
0143
0144 - --root=PATH
0145
0146 PATH to the kernel tree root.
0147
0148 This option must be specified when invoking checkpatch from outside
0149 the kernel root.
0150
0151 - --no-summary
0152
0153 Suppress the per file summary.
0154
0155 - --mailback
0156
0157 Only produce a report in case of Warnings or Errors. Milder Checks are
0158 excluded from this.
0159
0160 - --summary-file
0161
0162 Include the filename in summary.
0163
0164 - --debug KEY=[0|1]
0165
0166 Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
0167 'type', and 'attr' (default is all off).
0168
0169 - --fix
0170
0171 This is an EXPERIMENTAL feature. If correctable errors exists, a file
0172 <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
0173 automatically fixable errors corrected.
0174
0175 - --fix-inplace
0176
0177 EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes.
0178
0179 DO NOT USE this flag unless you are absolutely sure and you have a backup
0180 in place.
0181
0182 - --ignore-perl-version
0183
0184 Override checking of perl version. Runtime errors maybe encountered after
0185 enabling this flag if the perl version does not meet the minimum specified.
0186
0187 - --codespell
0188
0189 Use the codespell dictionary for checking spelling errors.
0190
0191 - --codespellfile
0192
0193 Use the specified codespell file.
0194 Default is '/usr/share/codespell/dictionary.txt'.
0195
0196 - --typedefsfile
0197
0198 Read additional types from this file.
0199
0200 - --color[=WHEN]
0201
0202 Use colors 'always', 'never', or only when output is a terminal ('auto').
0203 Default is 'auto'.
0204
0205 - --kconfig-prefix=WORD
0206
0207 Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
0208
0209 - -h, --help, --version
0210
0211 Display the help text.
0212
0213 Message Levels
0214 ==============
0215
0216 Messages in checkpatch are divided into three levels. The levels of messages
0217 in checkpatch denote the severity of the error. They are:
0218
0219 - ERROR
0220
0221 This is the most strict level. Messages of type ERROR must be taken
0222 seriously as they denote things that are very likely to be wrong.
0223
0224 - WARNING
0225
0226 This is the next stricter level. Messages of type WARNING requires a
0227 more careful review. But it is milder than an ERROR.
0228
0229 - CHECK
0230
0231 This is the mildest level. These are things which may require some thought.
0232
0233 Type Descriptions
0234 =================
0235
0236 This section contains a description of all the message types in checkpatch.
0237
0238 .. Types in this section are also parsed by checkpatch.
0239 .. The types are grouped into subsections based on use.
0240
0241
0242 Allocation style
0243 ----------------
0244
0245 **ALLOC_ARRAY_ARGS**
0246 The first argument for kcalloc or kmalloc_array should be the
0247 number of elements. sizeof() as the first argument is generally
0248 wrong.
0249
0250 See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
0251
0252 **ALLOC_SIZEOF_STRUCT**
0253 The allocation style is bad. In general for family of
0254 allocation functions using sizeof() to get memory size,
0255 constructs like::
0256
0257 p = alloc(sizeof(struct foo), ...)
0258
0259 should be::
0260
0261 p = alloc(sizeof(*p), ...)
0262
0263 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory
0264
0265 **ALLOC_WITH_MULTIPLY**
0266 Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
0267 sizeof multiply.
0268
0269 See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
0270
0271
0272 API usage
0273 ---------
0274
0275 **ARCH_DEFINES**
0276 Architecture specific defines should be avoided wherever
0277 possible.
0278
0279 **ARCH_INCLUDE_LINUX**
0280 Whenever asm/file.h is included and linux/file.h exists, a
0281 conversion can be made when linux/file.h includes asm/file.h.
0282 However this is not always the case (See signal.h).
0283 This message type is emitted only for includes from arch/.
0284
0285 **AVOID_BUG**
0286 BUG() or BUG_ON() should be avoided totally.
0287 Use WARN() and WARN_ON() instead, and handle the "impossible"
0288 error condition as gracefully as possible.
0289
0290 See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
0291
0292 **CONSIDER_KSTRTO**
0293 The simple_strtol(), simple_strtoll(), simple_strtoul(), and
0294 simple_strtoull() functions explicitly ignore overflows, which
0295 may lead to unexpected results in callers. The respective kstrtol(),
0296 kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the
0297 correct replacements.
0298
0299 See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
0300
0301 **CONSTANT_CONVERSION**
0302 Use of __constant_<foo> form is discouraged for the following functions::
0303
0304 __constant_cpu_to_be[x]
0305 __constant_cpu_to_le[x]
0306 __constant_be[x]_to_cpu
0307 __constant_le[x]_to_cpu
0308 __constant_htons
0309 __constant_ntohs
0310
0311 Using any of these outside of include/uapi/ is not preferred as using the
0312 function without __constant_ is identical when the argument is a
0313 constant.
0314
0315 In big endian systems, the macros like __constant_cpu_to_be32(x) and
0316 cpu_to_be32(x) expand to the same expression::
0317
0318 #define __constant_cpu_to_be32(x) ((__force __be32)(__u32)(x))
0319 #define __cpu_to_be32(x) ((__force __be32)(__u32)(x))
0320
0321 In little endian systems, the macros __constant_cpu_to_be32(x) and
0322 cpu_to_be32(x) expand to __constant_swab32 and __swab32. __swab32
0323 has a __builtin_constant_p check::
0324
0325 #define __swab32(x) \
0326 (__builtin_constant_p((__u32)(x)) ? \
0327 ___constant_swab32(x) : \
0328 __fswab32(x))
0329
0330 So ultimately they have a special case for constants.
0331 Similar is the case with all of the macros in the list. Thus
0332 using the __constant_... forms are unnecessarily verbose and
0333 not preferred outside of include/uapi.
0334
0335 See: https://lore.kernel.org/lkml/1400106425.12666.6.camel@joe-AO725/
0336
0337 **DEPRECATED_API**
0338 Usage of a deprecated RCU API is detected. It is recommended to replace
0339 old flavourful RCU APIs by their new vanilla-RCU counterparts.
0340
0341 The full list of available RCU APIs can be viewed from the kernel docs.
0342
0343 See: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis
0344
0345 **DEPRECATED_VARIABLE**
0346 EXTRA_{A,C,CPP,LD}FLAGS are deprecated and should be replaced by the new
0347 flags added via commit f77bf01425b1 ("kbuild: introduce ccflags-y,
0348 asflags-y and ldflags-y").
0349
0350 The following conversion scheme maybe used::
0351
0352 EXTRA_AFLAGS -> asflags-y
0353 EXTRA_CFLAGS -> ccflags-y
0354 EXTRA_CPPFLAGS -> cppflags-y
0355 EXTRA_LDFLAGS -> ldflags-y
0356
0357 See:
0358
0359 1. https://lore.kernel.org/lkml/20070930191054.GA15876@uranus.ravnborg.org/
0360 2. https://lore.kernel.org/lkml/1313384834-24433-12-git-send-email-lacombar@gmail.com/
0361 3. https://www.kernel.org/doc/html/latest/kbuild/makefiles.html#compilation-flags
0362
0363 **DEVICE_ATTR_FUNCTIONS**
0364 The function names used in DEVICE_ATTR is unusual.
0365 Typically, the store and show functions are used with <attr>_store and
0366 <attr>_show, where <attr> is a named attribute variable of the device.
0367
0368 Consider the following examples::
0369
0370 static DEVICE_ATTR(type, 0444, type_show, NULL);
0371 static DEVICE_ATTR(power, 0644, power_show, power_store);
0372
0373 The function names should preferably follow the above pattern.
0374
0375 See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
0376
0377 **DEVICE_ATTR_RO**
0378 The DEVICE_ATTR_RO(name) helper macro can be used instead of
0379 DEVICE_ATTR(name, 0444, name_show, NULL);
0380
0381 Note that the macro automatically appends _show to the named
0382 attribute variable of the device for the show method.
0383
0384 See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
0385
0386 **DEVICE_ATTR_RW**
0387 The DEVICE_ATTR_RW(name) helper macro can be used instead of
0388 DEVICE_ATTR(name, 0644, name_show, name_store);
0389
0390 Note that the macro automatically appends _show and _store to the
0391 named attribute variable of the device for the show and store methods.
0392
0393 See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
0394
0395 **DEVICE_ATTR_WO**
0396 The DEVICE_AATR_WO(name) helper macro can be used instead of
0397 DEVICE_ATTR(name, 0200, NULL, name_store);
0398
0399 Note that the macro automatically appends _store to the
0400 named attribute variable of the device for the store method.
0401
0402 See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
0403
0404 **DUPLICATED_SYSCTL_CONST**
0405 Commit d91bff3011cf ("proc/sysctl: add shared variables for range
0406 check") added some shared const variables to be used instead of a local
0407 copy in each source file.
0408
0409 Consider replacing the sysctl range checking value with the shared
0410 one in include/linux/sysctl.h. The following conversion scheme may
0411 be used::
0412
0413 &zero -> SYSCTL_ZERO
0414 &one -> SYSCTL_ONE
0415 &int_max -> SYSCTL_INT_MAX
0416
0417 See:
0418
0419 1. https://lore.kernel.org/lkml/20190430180111.10688-1-mcroce@redhat.com/
0420 2. https://lore.kernel.org/lkml/20190531131422.14970-1-mcroce@redhat.com/
0421
0422 **ENOSYS**
0423 ENOSYS means that a nonexistent system call was called.
0424 Earlier, it was wrongly used for things like invalid operations on
0425 otherwise valid syscalls. This should be avoided in new code.
0426
0427 See: https://lore.kernel.org/lkml/5eb299021dec23c1a48fa7d9f2c8b794e967766d.1408730669.git.luto@amacapital.net/
0428
0429 **ENOTSUPP**
0430 ENOTSUPP is not a standard error code and should be avoided in new patches.
0431 EOPNOTSUPP should be used instead.
0432
0433 See: https://lore.kernel.org/netdev/20200510182252.GA411829@lunn.ch/
0434
0435 **EXPORT_SYMBOL**
0436 EXPORT_SYMBOL should immediately follow the symbol to be exported.
0437
0438 **IN_ATOMIC**
0439 in_atomic() is not for driver use so any such use is reported as an ERROR.
0440 Also in_atomic() is often used to determine if sleeping is permitted,
0441 but it is not reliable in this use model. Therefore its use is
0442 strongly discouraged.
0443
0444 However, in_atomic() is ok for core kernel use.
0445
0446 See: https://lore.kernel.org/lkml/20080320201723.b87b3732.akpm@linux-foundation.org/
0447
0448 **LOCKDEP**
0449 The lockdep_no_validate class was added as a temporary measure to
0450 prevent warnings on conversion of device->sem to device->mutex.
0451 It should not be used for any other purpose.
0452
0453 See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
0454
0455 **MALFORMED_INCLUDE**
0456 The #include statement has a malformed path. This has happened
0457 because the author has included a double slash "//" in the pathname
0458 accidentally.
0459
0460 **USE_LOCKDEP**
0461 lockdep_assert_held() annotations should be preferred over
0462 assertions based on spin_is_locked()
0463
0464 See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
0465
0466 **UAPI_INCLUDE**
0467 No #include statements in include/uapi should use a uapi/ path.
0468
0469 **USLEEP_RANGE**
0470 usleep_range() should be preferred over udelay(). The proper way of
0471 using usleep_range() is mentioned in the kernel docs.
0472
0473 See: https://www.kernel.org/doc/html/latest/timers/timers-howto.html#delays-information-on-the-various-kernel-delay-sleep-mechanisms
0474
0475
0476 Comments
0477 --------
0478
0479 **BLOCK_COMMENT_STYLE**
0480 The comment style is incorrect. The preferred style for multi-
0481 line comments is::
0482
0483 /*
0484 * This is the preferred style
0485 * for multi line comments.
0486 */
0487
0488 The networking comment style is a bit different, with the first line
0489 not empty like the former::
0490
0491 /* This is the preferred comment style
0492 * for files in net/ and drivers/net/
0493 */
0494
0495 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
0496
0497 **C99_COMMENTS**
0498 C99 style single line comments (//) should not be used.
0499 Prefer the block comment style instead.
0500
0501 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
0502
0503 **DATA_RACE**
0504 Applications of data_race() should have a comment so as to document the
0505 reasoning behind why it was deemed safe.
0506
0507 See: https://lore.kernel.org/lkml/20200401101714.44781-1-elver@google.com/
0508
0509 **FSF_MAILING_ADDRESS**
0510 Kernel maintainers reject new instances of the GPL boilerplate paragraph
0511 directing people to write to the FSF for a copy of the GPL, since the
0512 FSF has moved in the past and may do so again.
0513 So do not write paragraphs about writing to the Free Software Foundation's
0514 mailing address.
0515
0516 See: https://lore.kernel.org/lkml/20131006222342.GT19510@leaf/
0517
0518
0519 Commit message
0520 --------------
0521
0522 **BAD_SIGN_OFF**
0523 The signed-off-by line does not fall in line with the standards
0524 specified by the community.
0525
0526 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
0527
0528 **BAD_STABLE_ADDRESS_STYLE**
0529 The email format for stable is incorrect.
0530 Some valid options for stable address are::
0531
0532 1. stable@vger.kernel.org
0533 2. stable@kernel.org
0534
0535 For adding version info, the following comment style should be used::
0536
0537 stable@vger.kernel.org # version info
0538
0539 **COMMIT_COMMENT_SYMBOL**
0540 Commit log lines starting with a '#' are ignored by git as
0541 comments. To solve this problem addition of a single space
0542 infront of the log line is enough.
0543
0544 **COMMIT_MESSAGE**
0545 The patch is missing a commit description. A brief
0546 description of the changes made by the patch should be added.
0547
0548 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
0549
0550 **EMAIL_SUBJECT**
0551 Naming the tool that found the issue is not very useful in the
0552 subject line. A good subject line summarizes the change that
0553 the patch brings.
0554
0555 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
0556
0557 **FROM_SIGN_OFF_MISMATCH**
0558 The author's email does not match with that in the Signed-off-by:
0559 line(s). This can be sometimes caused due to an improperly configured
0560 email client.
0561
0562 This message is emitted due to any of the following reasons::
0563
0564 - The email names do not match.
0565 - The email addresses do not match.
0566 - The email subaddresses do not match.
0567 - The email comments do not match.
0568
0569 **MISSING_SIGN_OFF**
0570 The patch is missing a Signed-off-by line. A signed-off-by
0571 line should be added according to Developer's certificate of
0572 Origin.
0573
0574 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
0575
0576 **NO_AUTHOR_SIGN_OFF**
0577 The author of the patch has not signed off the patch. It is
0578 required that a simple sign off line should be present at the
0579 end of explanation of the patch to denote that the author has
0580 written it or otherwise has the rights to pass it on as an open
0581 source patch.
0582
0583 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
0584
0585 **DIFF_IN_COMMIT_MSG**
0586 Avoid having diff content in commit message.
0587 This causes problems when one tries to apply a file containing both
0588 the changelog and the diff because patch(1) tries to apply the diff
0589 which it found in the changelog.
0590
0591 See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/
0592
0593 **GERRIT_CHANGE_ID**
0594 To be picked up by gerrit, the footer of the commit message might
0595 have a Change-Id like::
0596
0597 Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
0598 Signed-off-by: A. U. Thor <author@example.com>
0599
0600 The Change-Id line must be removed before submitting.
0601
0602 **GIT_COMMIT_ID**
0603 The proper way to reference a commit id is:
0604 commit <12+ chars of sha1> ("<title line>")
0605
0606 An example may be::
0607
0608 Commit e21d2170f36602ae2708 ("video: remove unnecessary
0609 platform_set_drvdata()") removed the unnecessary
0610 platform_set_drvdata(), but left the variable "dev" unused,
0611 delete it.
0612
0613 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
0614
0615
0616 Comparison style
0617 ----------------
0618
0619 **ASSIGN_IN_IF**
0620 Do not use assignments in if condition.
0621 Example::
0622
0623 if ((foo = bar(...)) < BAZ) {
0624
0625 should be written as::
0626
0627 foo = bar(...);
0628 if (foo < BAZ) {
0629
0630 **BOOL_COMPARISON**
0631 Comparisons of A to true and false are better written
0632 as A and !A.
0633
0634 See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
0635
0636 **COMPARISON_TO_NULL**
0637 Comparisons to NULL in the form (foo == NULL) or (foo != NULL)
0638 are better written as (!foo) and (foo).
0639
0640 **CONSTANT_COMPARISON**
0641 Comparisons with a constant or upper case identifier on the left
0642 side of the test should be avoided.
0643
0644
0645 Indentation and Line Breaks
0646 ---------------------------
0647
0648 **CODE_INDENT**
0649 Code indent should use tabs instead of spaces.
0650 Outside of comments, documentation and Kconfig,
0651 spaces are never used for indentation.
0652
0653 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
0654
0655 **DEEP_INDENTATION**
0656 Indentation with 6 or more tabs usually indicate overly indented
0657 code.
0658
0659 It is suggested to refactor excessive indentation of
0660 if/else/for/do/while/switch statements.
0661
0662 See: https://lore.kernel.org/lkml/1328311239.21255.24.camel@joe2Laptop/
0663
0664 **SWITCH_CASE_INDENT_LEVEL**
0665 switch should be at the same indent as case.
0666 Example::
0667
0668 switch (suffix) {
0669 case 'G':
0670 case 'g':
0671 mem <<= 30;
0672 break;
0673 case 'M':
0674 case 'm':
0675 mem <<= 20;
0676 break;
0677 case 'K':
0678 case 'k':
0679 mem <<= 10;
0680 fallthrough;
0681 default:
0682 break;
0683 }
0684
0685 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
0686
0687 **LONG_LINE**
0688 The line has exceeded the specified maximum length.
0689 To use a different maximum line length, the --max-line-length=n option
0690 may be added while invoking checkpatch.
0691
0692 Earlier, the default line length was 80 columns. Commit bdc48fa11e46
0693 ("checkpatch/coding-style: deprecate 80-column warning") increased the
0694 limit to 100 columns. This is not a hard limit either and it's
0695 preferable to stay within 80 columns whenever possible.
0696
0697 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
0698
0699 **LONG_LINE_STRING**
0700 A string starts before but extends beyond the maximum line length.
0701 To use a different maximum line length, the --max-line-length=n option
0702 may be added while invoking checkpatch.
0703
0704 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
0705
0706 **LONG_LINE_COMMENT**
0707 A comment starts before but extends beyond the maximum line length.
0708 To use a different maximum line length, the --max-line-length=n option
0709 may be added while invoking checkpatch.
0710
0711 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
0712
0713 **SPLIT_STRING**
0714 Quoted strings that appear as messages in userspace and can be
0715 grepped, should not be split across multiple lines.
0716
0717 See: https://lore.kernel.org/lkml/20120203052727.GA15035@leaf/
0718
0719 **MULTILINE_DEREFERENCE**
0720 A single dereferencing identifier spanned on multiple lines like::
0721
0722 struct_identifier->member[index].
0723 member = <foo>;
0724
0725 is generally hard to follow. It can easily lead to typos and so makes
0726 the code vulnerable to bugs.
0727
0728 If fixing the multiple line dereferencing leads to an 80 column
0729 violation, then either rewrite the code in a more simple way or if the
0730 starting part of the dereferencing identifier is the same and used at
0731 multiple places then store it in a temporary variable, and use that
0732 temporary variable only at all the places. For example, if there are
0733 two dereferencing identifiers::
0734
0735 member1->member2->member3.foo1;
0736 member1->member2->member3.foo2;
0737
0738 then store the member1->member2->member3 part in a temporary variable.
0739 It not only helps to avoid the 80 column violation but also reduces
0740 the program size by removing the unnecessary dereferences.
0741
0742 But if none of the above methods work then ignore the 80 column
0743 violation because it is much easier to read a dereferencing identifier
0744 on a single line.
0745
0746 **TRAILING_STATEMENTS**
0747 Trailing statements (for example after any conditional) should be
0748 on the next line.
0749 Statements, such as::
0750
0751 if (x == y) break;
0752
0753 should be::
0754
0755 if (x == y)
0756 break;
0757
0758
0759 Macros, Attributes and Symbols
0760 ------------------------------
0761
0762 **ARRAY_SIZE**
0763 The ARRAY_SIZE(foo) macro should be preferred over
0764 sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
0765 array.
0766
0767 The macro is defined in include/linux/kernel.h::
0768
0769 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
0770
0771 **AVOID_EXTERNS**
0772 Function prototypes don't need to be declared extern in .h
0773 files. It's assumed by the compiler and is unnecessary.
0774
0775 **AVOID_L_PREFIX**
0776 Local symbol names that are prefixed with `.L` should be avoided,
0777 as this has special meaning for the assembler; a symbol entry will
0778 not be emitted into the symbol table. This can prevent `objtool`
0779 from generating correct unwind info.
0780
0781 Symbols with STB_LOCAL binding may still be used, and `.L` prefixed
0782 local symbol names are still generally usable within a function,
0783 but `.L` prefixed local symbol names should not be used to denote
0784 the beginning or end of code regions via
0785 `SYM_CODE_START_LOCAL`/`SYM_CODE_END`
0786
0787 **BIT_MACRO**
0788 Defines like: 1 << <digit> could be BIT(digit).
0789 The BIT() macro is defined via include/linux/bits.h::
0790
0791 #define BIT(nr) (1UL << (nr))
0792
0793 **CONST_READ_MOSTLY**
0794 When a variable is tagged with the __read_mostly annotation, it is a
0795 signal to the compiler that accesses to the variable will be mostly
0796 reads and rarely(but NOT never) a write.
0797
0798 const __read_mostly does not make any sense as const data is already
0799 read-only. The __read_mostly annotation thus should be removed.
0800
0801 **DATE_TIME**
0802 It is generally desirable that building the same source code with
0803 the same set of tools is reproducible, i.e. the output is always
0804 exactly the same.
0805
0806 The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
0807 and enables warnings if they are used as they can lead to
0808 non-deterministic builds.
0809
0810 See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
0811
0812 **DEFINE_ARCH_HAS**
0813 The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong.
0814
0815 For big conceptual features use Kconfig symbols instead. And for
0816 smaller things where we have compatibility fallback functions but
0817 want architectures able to override them with optimized ones, we
0818 should either use weak functions (appropriate for some cases), or
0819 the symbol that protects them should be the same symbol we use.
0820
0821 See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/
0822
0823 **DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON**
0824 do {} while(0) macros should not have a trailing semicolon.
0825
0826 **INIT_ATTRIBUTE**
0827 Const init definitions should use __initconst instead of
0828 __initdata.
0829
0830 Similarly init definitions without const require a separate
0831 use of const.
0832
0833 **INLINE_LOCATION**
0834 The inline keyword should sit between storage class and type.
0835
0836 For example, the following segment::
0837
0838 inline static int example_function(void)
0839 {
0840 ...
0841 }
0842
0843 should be::
0844
0845 static inline int example_function(void)
0846 {
0847 ...
0848 }
0849
0850 **MISPLACED_INIT**
0851 It is possible to use section markers on variables in a way
0852 which gcc doesn't understand (or at least not the way the
0853 developer intended)::
0854
0855 static struct __initdata samsung_pll_clock exynos4_plls[nr_plls] = {
0856
0857 does not put exynos4_plls in the .initdata section. The __initdata
0858 marker can be virtually anywhere on the line, except right after
0859 "struct". The preferred location is before the "=" sign if there is
0860 one, or before the trailing ";" otherwise.
0861
0862 See: https://lore.kernel.org/lkml/1377655732.3619.19.camel@joe-AO722/
0863
0864 **MULTISTATEMENT_MACRO_USE_DO_WHILE**
0865 Macros with multiple statements should be enclosed in a
0866 do - while block. Same should also be the case for macros
0867 starting with `if` to avoid logic defects::
0868
0869 #define macrofun(a, b, c) \
0870 do { \
0871 if (a == 5) \
0872 do_this(b, c); \
0873 } while (0)
0874
0875 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
0876
0877 **PREFER_FALLTHROUGH**
0878 Use the `fallthrough;` pseudo keyword instead of
0879 `/* fallthrough */` like comments.
0880
0881 **TRAILING_SEMICOLON**
0882 Macro definition should not end with a semicolon. The macro
0883 invocation style should be consistent with function calls.
0884 This can prevent any unexpected code paths::
0885
0886 #define MAC do_something;
0887
0888 If this macro is used within a if else statement, like::
0889
0890 if (some_condition)
0891 MAC;
0892
0893 else
0894 do_something;
0895
0896 Then there would be a compilation error, because when the macro is
0897 expanded there are two trailing semicolons, so the else branch gets
0898 orphaned.
0899
0900 See: https://lore.kernel.org/lkml/1399671106.2912.21.camel@joe-AO725/
0901
0902 **SINGLE_STATEMENT_DO_WHILE_MACRO**
0903 For the multi-statement macros, it is necessary to use the do-while
0904 loop to avoid unpredictable code paths. The do-while loop helps to
0905 group the multiple statements into a single one so that a
0906 function-like macro can be used as a function only.
0907
0908 But for the single statement macros, it is unnecessary to use the
0909 do-while loop. Although the code is syntactically correct but using
0910 the do-while loop is redundant. So remove the do-while loop for single
0911 statement macros.
0912
0913 **WEAK_DECLARATION**
0914 Using weak declarations like __attribute__((weak)) or __weak
0915 can have unintended link defects. Avoid using them.
0916
0917
0918 Functions and Variables
0919 -----------------------
0920
0921 **CAMELCASE**
0922 Avoid CamelCase Identifiers.
0923
0924 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
0925
0926 **CONST_CONST**
0927 Using `const <type> const *` is generally meant to be
0928 written `const <type> * const`.
0929
0930 **CONST_STRUCT**
0931 Using const is generally a good idea. Checkpatch reads
0932 a list of frequently used structs that are always or
0933 almost always constant.
0934
0935 The existing structs list can be viewed from
0936 `scripts/const_structs.checkpatch`.
0937
0938 See: https://lore.kernel.org/lkml/alpine.DEB.2.10.1608281509480.3321@hadrien/
0939
0940 **EMBEDDED_FUNCTION_NAME**
0941 Embedded function names are less appropriate to use as
0942 refactoring can cause function renaming. Prefer the use of
0943 "%s", __func__ to embedded function names.
0944
0945 Note that this does not work with -f (--file) checkpatch option
0946 as it depends on patch context providing the function name.
0947
0948 **FUNCTION_ARGUMENTS**
0949 This warning is emitted due to any of the following reasons:
0950
0951 1. Arguments for the function declaration do not follow
0952 the identifier name. Example::
0953
0954 void foo
0955 (int bar, int baz)
0956
0957 This should be corrected to::
0958
0959 void foo(int bar, int baz)
0960
0961 2. Some arguments for the function definition do not
0962 have an identifier name. Example::
0963
0964 void foo(int)
0965
0966 All arguments should have identifier names.
0967
0968 **FUNCTION_WITHOUT_ARGS**
0969 Function declarations without arguments like::
0970
0971 int foo()
0972
0973 should be::
0974
0975 int foo(void)
0976
0977 **GLOBAL_INITIALISERS**
0978 Global variables should not be initialized explicitly to
0979 0 (or NULL, false, etc.). Your compiler (or rather your
0980 loader, which is responsible for zeroing out the relevant
0981 sections) automatically does it for you.
0982
0983 **INITIALISED_STATIC**
0984 Static variables should not be initialized explicitly to zero.
0985 Your compiler (or rather your loader) automatically does
0986 it for you.
0987
0988 **MULTIPLE_ASSIGNMENTS**
0989 Multiple assignments on a single line makes the code unnecessarily
0990 complicated. So on a single line assign value to a single variable
0991 only, this makes the code more readable and helps avoid typos.
0992
0993 **RETURN_PARENTHESES**
0994 return is not a function and as such doesn't need parentheses::
0995
0996 return (bar);
0997
0998 can simply be::
0999
1000 return bar;
1001
1002
1003 Permissions
1004 -----------
1005
1006 **DEVICE_ATTR_PERMS**
1007 The permissions used in DEVICE_ATTR are unusual.
1008 Typically only three permissions are used - 0644 (RW), 0444 (RO)
1009 and 0200 (WO).
1010
1011 See: https://www.kernel.org/doc/html/latest/filesystems/sysfs.html#attributes
1012
1013 **EXECUTE_PERMISSIONS**
1014 There is no reason for source files to be executable. The executable
1015 bit can be removed safely.
1016
1017 **EXPORTED_WORLD_WRITABLE**
1018 Exporting world writable sysfs/debugfs files is usually a bad thing.
1019 When done arbitrarily they can introduce serious security bugs.
1020 In the past, some of the debugfs vulnerabilities would seemingly allow
1021 any local user to write arbitrary values into device registers - a
1022 situation from which little good can be expected to emerge.
1023
1024 See: https://lore.kernel.org/linux-arm-kernel/cover.1296818921.git.segoon@openwall.com/
1025
1026 **NON_OCTAL_PERMISSIONS**
1027 Permission bits should use 4 digit octal permissions (like 0700 or 0444).
1028 Avoid using any other base like decimal.
1029
1030 **SYMBOLIC_PERMS**
1031 Permission bits in the octal form are more readable and easier to
1032 understand than their symbolic counterparts because many command-line
1033 tools use this notation. Experienced kernel developers have been using
1034 these traditional Unix permission bits for decades and so they find it
1035 easier to understand the octal notation than the symbolic macros.
1036 For example, it is harder to read S_IWUSR|S_IRUGO than 0644, which
1037 obscures the developer's intent rather than clarifying it.
1038
1039 See: https://lore.kernel.org/lkml/CA+55aFw5v23T-zvDZp-MmD_EYxF8WbafwwB59934FV7g21uMGQ@mail.gmail.com/
1040
1041
1042 Spacing and Brackets
1043 --------------------
1044
1045 **ASSIGNMENT_CONTINUATIONS**
1046 Assignment operators should not be written at the start of a
1047 line but should follow the operand at the previous line.
1048
1049 **BRACES**
1050 The placement of braces is stylistically incorrect.
1051 The preferred way is to put the opening brace last on the line,
1052 and put the closing brace first::
1053
1054 if (x is true) {
1055 we do y
1056 }
1057
1058 This applies for all non-functional blocks.
1059 However, there is one special case, namely functions: they have the
1060 opening brace at the beginning of the next line, thus::
1061
1062 int function(int x)
1063 {
1064 body of function
1065 }
1066
1067 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1068
1069 **BRACKET_SPACE**
1070 Whitespace before opening bracket '[' is prohibited.
1071 There are some exceptions:
1072
1073 1. With a type on the left::
1074
1075 int [] a;
1076
1077 2. At the beginning of a line for slice initialisers::
1078
1079 [0...10] = 5,
1080
1081 3. Inside a curly brace::
1082
1083 = { [0...10] = 5 }
1084
1085 **CONCATENATED_STRING**
1086 Concatenated elements should have a space in between.
1087 Example::
1088
1089 printk(KERN_INFO"bar");
1090
1091 should be::
1092
1093 printk(KERN_INFO "bar");
1094
1095 **ELSE_AFTER_BRACE**
1096 `else {` should follow the closing block `}` on the same line.
1097
1098 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1099
1100 **LINE_SPACING**
1101 Vertical space is wasted given the limited number of lines an
1102 editor window can display when multiple blank lines are used.
1103
1104 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1105
1106 **OPEN_BRACE**
1107 The opening brace should be following the function definitions on the
1108 next line. For any non-functional block it should be on the same line
1109 as the last construct.
1110
1111 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1112
1113 **POINTER_LOCATION**
1114 When using pointer data or a function that returns a pointer type,
1115 the preferred use of * is adjacent to the data name or function name
1116 and not adjacent to the type name.
1117 Examples::
1118
1119 char *linux_banner;
1120 unsigned long long memparse(char *ptr, char **retptr);
1121 char *match_strdup(substring_t *s);
1122
1123 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1124
1125 **SPACING**
1126 Whitespace style used in the kernel sources is described in kernel docs.
1127
1128 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1129
1130 **TRAILING_WHITESPACE**
1131 Trailing whitespace should always be removed.
1132 Some editors highlight the trailing whitespace and cause visual
1133 distractions when editing files.
1134
1135 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
1136
1137 **UNNECESSARY_PARENTHESES**
1138 Parentheses are not required in the following cases:
1139
1140 1. Function pointer uses::
1141
1142 (foo->bar)();
1143
1144 could be::
1145
1146 foo->bar();
1147
1148 2. Comparisons in if::
1149
1150 if ((foo->bar) && (foo->baz))
1151 if ((foo == bar))
1152
1153 could be::
1154
1155 if (foo->bar && foo->baz)
1156 if (foo == bar)
1157
1158 3. addressof/dereference single Lvalues::
1159
1160 &(foo->bar)
1161 *(foo->bar)
1162
1163 could be::
1164
1165 &foo->bar
1166 *foo->bar
1167
1168 **WHILE_AFTER_BRACE**
1169 while should follow the closing bracket on the same line::
1170
1171 do {
1172 ...
1173 } while(something);
1174
1175 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
1176
1177
1178 Others
1179 ------
1180
1181 **CONFIG_DESCRIPTION**
1182 Kconfig symbols should have a help text which fully describes
1183 it.
1184
1185 **CORRUPTED_PATCH**
1186 The patch seems to be corrupted or lines are wrapped.
1187 Please regenerate the patch file before sending it to the maintainer.
1188
1189 **CVS_KEYWORD**
1190 Since linux moved to git, the CVS markers are no longer used.
1191 So, CVS style keywords ($Id$, $Revision$, $Log$) should not be
1192 added.
1193
1194 **DEFAULT_NO_BREAK**
1195 switch default case is sometimes written as "default:;". This can
1196 cause new cases added below default to be defective.
1197
1198 A "break;" should be added after empty default statement to avoid
1199 unwanted fallthrough.
1200
1201 **DOS_LINE_ENDINGS**
1202 For DOS-formatted patches, there are extra ^M symbols at the end of
1203 the line. These should be removed.
1204
1205 **DT_SCHEMA_BINDING_PATCH**
1206 DT bindings moved to a json-schema based format instead of
1207 freeform text.
1208
1209 See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html
1210
1211 **DT_SPLIT_BINDING_PATCH**
1212 Devicetree bindings should be their own patch. This is because
1213 bindings are logically independent from a driver implementation,
1214 they have a different maintainer (even though they often
1215 are applied via the same tree), and it makes for a cleaner history in the
1216 DT only tree created with git-filter-branch.
1217
1218 See: https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters
1219
1220 **EMBEDDED_FILENAME**
1221 Embedding the complete filename path inside the file isn't particularly
1222 useful as often the path is moved around and becomes incorrect.
1223
1224 **FILE_PATH_CHANGES**
1225 Whenever files are added, moved, or deleted, the MAINTAINERS file
1226 patterns can be out of sync or outdated.
1227
1228 So MAINTAINERS might need updating in these cases.
1229
1230 **MEMSET**
1231 The memset use appears to be incorrect. This may be caused due to
1232 badly ordered parameters. Please recheck the usage.
1233
1234 **NOT_UNIFIED_DIFF**
1235 The patch file does not appear to be in unified-diff format. Please
1236 regenerate the patch file before sending it to the maintainer.
1237
1238 **PRINTF_0XDECIMAL**
1239 Prefixing 0x with decimal output is defective and should be corrected.
1240
1241 **SPDX_LICENSE_TAG**
1242 The source file is missing or has an improper SPDX identifier tag.
1243 The Linux kernel requires the precise SPDX identifier in all source files,
1244 and it is thoroughly documented in the kernel docs.
1245
1246 See: https://www.kernel.org/doc/html/latest/process/license-rules.html
1247
1248 **TYPO_SPELLING**
1249 Some words may have been misspelled. Consider reviewing them.
