docs: checkpatch: Document and segregate more checkpatch message types

+328 -71

1 changed file

expand all

Documentation

dev-tools

+328 -71

Documentation/dev-tools/checkpatch.rst

··· 298 298 299 299 See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull 300 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 + 301 438 **IN_ATOMIC** 302 439 in_atomic() is not for driver use so any such use is reported as an ERROR. 303 - Also in_atomic() is often used to determine if we may sleep, but it is not 304 - reliable in this use model therefore its use is strongly discouraged. 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. 305 443 306 444 However, in_atomic() is ok for core kernel use. 307 445 ··· 473 335 See: https://www.kernel.org/doc/html/latest/timers/timers-howto.html#delays-information-on-the-various-kernel-delay-sleep-mechanisms 474 336 475 337 476 - Comment style 477 - ------------- 338 + Comments 339 + -------- 478 340 479 341 **BLOCK_COMMENT_STYLE** 480 342 The comment style is incorrect. The preferred style for multi- ··· 499 361 Prefer the block comment style instead. 500 362 501 363 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting 364 + 365 + **DATA_RACE** 366 + Applications of data_race() should have a comment so as to document the 367 + reasoning behind why it was deemed safe. 368 + 369 + See: https://lore.kernel.org/lkml/20200401101714.44781-1-elver@google.com/ 370 + 371 + **FSF_MAILING_ADDRESS** 372 + Kernel maintainers reject new instances of the GPL boilerplate paragraph 373 + directing people to write to the FSF for a copy of the GPL, since the 374 + FSF has moved in the past and may do so again. 375 + So do not write paragraphs about writing to the Free Software Foundation's 376 + mailing address. 377 + 378 + See: https://lore.kernel.org/lkml/20131006222342.GT19510@leaf/ 502 379 503 380 504 381 Commit message ··· 544 391 **COMMIT_MESSAGE** 545 392 The patch is missing a commit description. A brief 546 393 description of the changes made by the patch should be added. 394 + 395 + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes 396 + 397 + **EMAIL_SUBJECT** 398 + Naming the tool that found the issue is not very useful in the 399 + subject line. A good subject line summarizes the change that 400 + the patch brings. 547 401 548 402 See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes 549 403 ··· 642 482 side of the test should be avoided. 643 483 644 484 485 + Indentation and Line Breaks 486 + --------------------------- 487 + 488 + **CODE_INDENT** 489 + Code indent should use tabs instead of spaces. 490 + Outside of comments, documentation and Kconfig, 491 + spaces are never used for indentation. 492 + 493 + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation 494 + 495 + **DEEP_INDENTATION** 496 + Indentation with 6 or more tabs usually indicate overly indented 497 + code. 498 + 499 + It is suggested to refactor excessive indentation of 500 + if/else/for/do/while/switch statements. 501 + 502 + See: https://lore.kernel.org/lkml/1328311239.21255.24.camel@joe2Laptop/ 503 + 504 + **SWITCH_CASE_INDENT_LEVEL** 505 + switch should be at the same indent as case. 506 + Example:: 507 + 508 + switch (suffix) { 509 + case 'G': 510 + case 'g': 511 + mem <<= 30; 512 + break; 513 + case 'M': 514 + case 'm': 515 + mem <<= 20; 516 + break; 517 + case 'K': 518 + case 'k': 519 + mem <<= 10; 520 + fallthrough; 521 + default: 522 + break; 523 + } 524 + 525 + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation 526 + 527 + **LONG_LINE** 528 + The line has exceeded the specified maximum length. 529 + To use a different maximum line length, the --max-line-length=n option 530 + may be added while invoking checkpatch. 531 + 532 + Earlier, the default line length was 80 columns. Commit bdc48fa11e46 533 + ("checkpatch/coding-style: deprecate 80-column warning") increased the 534 + limit to 100 columns. This is not a hard limit either and it's 535 + preferable to stay within 80 columns whenever possible. 536 + 537 + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings 538 + 539 + **LONG_LINE_STRING** 540 + A string starts before but extends beyond the maximum line length. 541 + To use a different maximum line length, the --max-line-length=n option 542 + may be added while invoking checkpatch. 543 + 544 + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings 545 + 546 + **LONG_LINE_COMMENT** 547 + A comment starts before but extends beyond the maximum line length. 548 + To use a different maximum line length, the --max-line-length=n option 549 + may be added while invoking checkpatch. 550 + 551 + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings 552 + 553 + **TRAILING_STATEMENTS** 554 + Trailing statements (for example after any conditional) should be 555 + on the next line. 556 + Statements, such as:: 557 + 558 + if (x == y) break; 559 + 560 + should be:: 561 + 562 + if (x == y) 563 + break; 564 + 565 + 645 566 Macros, Attributes and Symbols 646 567 ------------------------------ 647 568 ··· 786 545 the symbol that protects them should be the same symbol we use. 787 546 788 547 See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/ 548 + 549 + **DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON** 550 + do {} while(0) macros should not have a trailing semicolon. 789 551 790 552 **INIT_ATTRIBUTE** 791 553 Const init definitions should use __initconst instead of ··· 858 614 859 615 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming 860 616 617 + **CONST_CONST** 618 + Using `const <type> const *` is generally meant to be 619 + written `const <type> * const`. 620 + 621 + **CONST_STRUCT** 622 + Using const is generally a good idea. Checkpatch reads 623 + a list of frequently used structs that are always or 624 + almost always constant. 625 + 626 + The existing structs list can be viewed from 627 + `scripts/const_structs.checkpatch`. 628 + 629 + See: https://lore.kernel.org/lkml/alpine.DEB.2.10.1608281509480.3321@hadrien/ 630 + 631 + **EMBEDDED_FUNCTION_NAME** 632 + Embedded function names are less appropriate to use as 633 + refactoring can cause function renaming. Prefer the use of 634 + "%s", __func__ to embedded function names. 635 + 636 + Note that this does not work with -f (--file) checkpatch option 637 + as it depends on patch context providing the function name. 638 + 639 + **FUNCTION_ARGUMENTS** 640 + This warning is emitted due to any of the following reasons: 641 + 642 + 1. Arguments for the function declaration do not follow 643 + the identifier name. Example:: 644 + 645 + void foo 646 + (int bar, int baz) 647 + 648 + This should be corrected to:: 649 + 650 + void foo(int bar, int baz) 651 + 652 + 2. Some arguments for the function definition do not 653 + have an identifier name. Example:: 654 + 655 + void foo(int) 656 + 657 + All arguments should have identifier names. 658 + 861 659 **FUNCTION_WITHOUT_ARGS** 862 660 Function declarations without arguments like:: 863 661 ··· 932 646 933 647 Permissions 934 648 ----------- 649 + 650 + **DEVICE_ATTR_PERMS** 651 + The permissions used in DEVICE_ATTR are unusual. 652 + Typically only three permissions are used - 0644 (RW), 0444 (RO) 653 + and 0200 (WO). 654 + 655 + See: https://www.kernel.org/doc/html/latest/filesystems/sysfs.html#attributes 935 656 936 657 **EXECUTE_PERMISSIONS** 937 658 There is no reason for source files to be executable. The executable ··· 1001 708 1002 709 = { [0...10] = 5 } 1003 710 1004 - **CODE_INDENT** 1005 - Code indent should use tabs instead of spaces. 1006 - Outside of comments, documentation and Kconfig, 1007 - spaces are never used for indentation. 1008 - 1009 - See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation 1010 - 1011 711 **CONCATENATED_STRING** 1012 712 Concatenated elements should have a space in between. 1013 713 Example:: ··· 1046 760 1047 761 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces 1048 762 1049 - **SWITCH_CASE_INDENT_LEVEL** 1050 - switch should be at the same indent as case. 1051 - Example:: 1052 - 1053 - switch (suffix) { 1054 - case 'G': 1055 - case 'g': 1056 - mem <<= 30; 1057 - break; 1058 - case 'M': 1059 - case 'm': 1060 - mem <<= 20; 1061 - break; 1062 - case 'K': 1063 - case 'k': 1064 - mem <<= 10; 1065 - /* fall through */ 1066 - default: 1067 - break; 1068 - } 1069 - 1070 - See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation 1071 - 1072 763 **TRAILING_WHITESPACE** 1073 764 Trailing whitespace should always be removed. 1074 765 Some editors highlight the trailing whitespace and cause visual ··· 1054 791 See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces 1055 792 1056 793 **UNNECESSARY_PARENTHESES** 1057 - Parentheses are not required in the following cases:: 794 + Parentheses are not required in the following cases: 1058 795 1059 796 1. Function pointer uses:: 1060 797 ··· 1105 842 The patch seems to be corrupted or lines are wrapped. 1106 843 Please regenerate the patch file before sending it to the maintainer. 1107 844 845 + **CVS_KEYWORD** 846 + Since linux moved to git, the CVS markers are no longer used. 847 + So, CVS style keywords ($Id$, $Revision$, $Log$) should not be 848 + added. 849 + 850 + **DEFAULT_NO_BREAK** 851 + switch default case is sometimes written as "default:;". This can 852 + cause new cases added below default to be defective. 853 + 854 + A "break;" should be added after empty default statement to avoid 855 + unwanted fallthrough. 856 + 1108 857 **DOS_LINE_ENDINGS** 1109 858 For DOS-formatted patches, there are extra ^M symbols at the end of 1110 859 the line. These should be removed. 1111 860 1112 - **FSF_MAILING_ADDRESS** 1113 - Kernel maintainers reject new instances of the GPL boilerplate paragraph 1114 - directing people to write to the FSF for a copy of the GPL, since the 1115 - FSF has moved in the past and may do so again. 1116 - So do not write paragraphs about writing to the Free Software Foundation's 1117 - mailing address. 861 + **DT_SCHEMA_BINDING_PATCH** 862 + DT bindings moved to a json-schema based format instead of 863 + freeform text. 1118 864 1119 - See: https://lore.kernel.org/lkml/20131006222342.GT19510@leaf/ 865 + See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html 1120 866 1121 - **LONG_LINE** 1122 - The line has exceeded the specified maximum length. Consider refactoring 1123 - it. 1124 - To use a different maximum line length, the --max-line-length=n option 1125 - may be added while invoking checkpatch. 867 + **DT_SPLIT_BINDING_PATCH** 868 + Devicetree bindings should be their own patch. This is because 869 + bindings are logically independent from a driver implementation, 870 + they have a different maintainer (even though they often 871 + are applied via the same tree), and it makes for a cleaner history in the 872 + DT only tree created with git-filter-branch. 1126 873 1127 - See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings 874 + See: https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters 1128 875 1129 - **LONG_LINE_STRING** 1130 - A string starts before but extends beyond the maximum line length. 1131 - To use a different maximum line length, the --max-line-length=n option 1132 - may be added while invoking checkpatch. 876 + **EMBEDDED_FILENAME** 877 + Embedding the complete filename path inside the file isn't particularly 878 + useful as often the path is moved around and becomes incorrect. 1133 879 1134 - See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings 880 + **FILE_PATH_CHANGES** 881 + Whenever files are added, moved, or deleted, the MAINTAINERS file 882 + patterns can be out of sync or outdated. 1135 883 1136 - **LONG_LINE_COMMENT** 1137 - A comment starts before but extends beyond the maximum line length. 1138 - To use a different maximum line length, the --max-line-length=n option 1139 - may be added while invoking checkpatch. 1140 - 1141 - See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings 884 + So MAINTAINERS might need updating in these cases. 1142 885 1143 886 **MEMSET** 1144 887 The memset use appears to be incorrect. This may be caused due to ··· 1163 894 and it is thoroughly documented in the kernel docs. 1164 895 1165 896 See: https://www.kernel.org/doc/html/latest/process/license-rules.html 1166 - 1167 - **TRAILING_STATEMENTS** 1168 - Trailing statements (for example after any conditional) should be 1169 - on the next line. 1170 - Like:: 1171 - 1172 - if (x == y) break; 1173 - 1174 - should be:: 1175 - 1176 - if (x == y) 1177 - break; 1178 897 1179 898 **TYPO_SPELLING** 1180 899 Some words may have been misspelled. Consider reviewing them.

Configure Feed

Configure Feed