Make the tags directly linkable by defining targets for them.
Closes: https://lore.kernel.org/r/8090211.0vHzs8tI1a@bagend/
Signed-off-by: Diederik de Haas <[email protected]>
---
Documentation/dev-tools/checkpatch.rst | 216 +++++++++++++++++++++++++
1 file changed, 216 insertions(+)
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index 127968995847..6499e29c3a19 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -242,6 +242,8 @@ This section contains a description of all the message types in checkpatch.
Allocation style
----------------
+ .. _alloc-array-args:
+
**ALLOC_ARRAY_ARGS**
The first argument for kcalloc or kmalloc_array should be the
number of elements. sizeof() as the first argument is generally
@@ -249,6 +251,8 @@ Allocation style
See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
+ .. _alloc-sizeof-struct:
+
**ALLOC_SIZEOF_STRUCT**
The allocation style is bad. In general for family of
allocation functions using sizeof() to get memory size,
@@ -262,6 +266,8 @@ Allocation style
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory
+ .. _alloc-with-multiply:
+
**ALLOC_WITH_MULTIPLY**
Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
sizeof multiply.
@@ -272,16 +278,22 @@ Allocation style
API usage
---------
+ .. _arch-defines:
+
**ARCH_DEFINES**
Architecture specific defines should be avoided wherever
possible.
+ .. _arch-include-linux:
+
**ARCH_INCLUDE_LINUX**
Whenever asm/file.h is included and linux/file.h exists, a
conversion can be made when linux/file.h includes asm/file.h.
However this is not always the case (See signal.h).
This message type is emitted only for includes from arch/.
+ .. _avoid-bug:
+
**AVOID_BUG**
BUG() or BUG_ON() should be avoided totally.
Use WARN() and WARN_ON() instead, and handle the "impossible"
@@ -289,6 +301,8 @@ API usage
See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
+ .. _consider-kstrto:
+
**CONSIDER_KSTRTO**
The simple_strtol(), simple_strtoll(), simple_strtoul(), and
simple_strtoull() functions explicitly ignore overflows, which
@@ -298,6 +312,8 @@ API usage
See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
+ .. _constant-conversion:
+
**CONSTANT_CONVERSION**
Use of __constant_<foo> form is discouraged for the following functions::
@@ -334,6 +350,8 @@ API usage
See: https://lore.kernel.org/lkml/1400106425.12666.6.camel@joe-AO725/
+ .. _deprecated-api:
+
**DEPRECATED_API**
Usage of a deprecated RCU API is detected. It is recommended to replace
old flavourful RCU APIs by their new vanilla-RCU counterparts.
@@ -342,6 +360,8 @@ API usage
See: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis
+ .. _deprecated-variable:
+
**DEPRECATED_VARIABLE**
EXTRA_{A,C,CPP,LD}FLAGS are deprecated and should be replaced by the new
flags added via commit f77bf01425b1 ("kbuild: introduce ccflags-y,
@@ -360,6 +380,8 @@ API usage
2. https://lore.kernel.org/lkml/[email protected]/
3. https://www.kernel.org/doc/html/latest/kbuild/makefiles.html#compilation-flags
+ .. _device-attr-functions:
+
**DEVICE_ATTR_FUNCTIONS**
The function names used in DEVICE_ATTR is unusual.
Typically, the store and show functions are used with <attr>_store and
@@ -374,6 +396,8 @@ API usage
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
+ .. _device-attr-ro:
+
**DEVICE_ATTR_RO**
The DEVICE_ATTR_RO(name) helper macro can be used instead of
DEVICE_ATTR(name, 0444, name_show, NULL);
@@ -383,6 +407,8 @@ API usage
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
+ .. _device-attr-rw:
+
**DEVICE_ATTR_RW**
The DEVICE_ATTR_RW(name) helper macro can be used instead of
DEVICE_ATTR(name, 0644, name_show, name_store);
@@ -392,6 +418,8 @@ API usage
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
+ .. _device-attr-wo:
+
**DEVICE_ATTR_WO**
The DEVICE_AATR_WO(name) helper macro can be used instead of
DEVICE_ATTR(name, 0200, NULL, name_store);
@@ -401,6 +429,8 @@ API usage
See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
+ .. _duplicated-sysctl-const:
+
**DUPLICATED_SYSCTL_CONST**
Commit d91bff3011cf ("proc/sysctl: add shared variables for range
check") added some shared const variables to be used instead of a local
@@ -419,6 +449,8 @@ API usage
1. https://lore.kernel.org/lkml/[email protected]/
2. https://lore.kernel.org/lkml/[email protected]/
+ .. _enosys:
+
**ENOSYS**
ENOSYS means that a nonexistent system call was called.
Earlier, it was wrongly used for things like invalid operations on
@@ -426,15 +458,21 @@ API usage
See: https://lore.kernel.org/lkml/5eb299021dec23c1a48fa7d9f2c8b794e967766d.1408730669.git.luto@amacapital.net/
+ .. _enotsupp:
+
**ENOTSUPP**
ENOTSUPP is not a standard error code and should be avoided in new patches.
EOPNOTSUPP should be used instead.
See: https://lore.kernel.org/netdev/[email protected]/
+ .. _export-symbol:
+
**EXPORT_SYMBOL**
EXPORT_SYMBOL should immediately follow the symbol to be exported.
+ .. _in-atomic:
+
**IN_ATOMIC**
in_atomic() is not for driver use so any such use is reported as an ERROR.
Also in_atomic() is often used to determine if sleeping is permitted,
@@ -445,6 +483,8 @@ API usage
See: https://lore.kernel.org/lkml/[email protected]/
+ .. _lockdep:
+
**LOCKDEP**
The lockdep_no_validate class was added as a temporary measure to
prevent warnings on conversion of device->sem to device->mutex.
@@ -452,20 +492,28 @@ API usage
See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
+ .. _malformed-include:
+
**MALFORMED_INCLUDE**
The #include statement has a malformed path. This has happened
because the author has included a double slash "//" in the pathname
accidentally.
+ .. _use-lockdep:
+
**USE_LOCKDEP**
lockdep_assert_held() annotations should be preferred over
assertions based on spin_is_locked()
See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
+ .. _uapi-include:
+
**UAPI_INCLUDE**
No #include statements in include/uapi should use a uapi/ path.
+ .. _usleep-range:
+
**USLEEP_RANGE**
usleep_range() should be preferred over udelay(). The proper way of
using usleep_range() is mentioned in the kernel docs.
@@ -476,6 +524,8 @@ API usage
Comments
--------
+ .. _block-comment-style:
+
**BLOCK_COMMENT_STYLE**
The comment style is incorrect. The preferred style for multi-
line comments is::
@@ -500,12 +550,16 @@ Comments
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
+ .. _data-race:
+
**DATA_RACE**
Applications of data_race() should have a comment so as to document the
reasoning behind why it was deemed safe.
See: https://lore.kernel.org/lkml/[email protected]/
+ .. _fsf-mailing-address:
+
**FSF_MAILING_ADDRESS**
Kernel maintainers reject new instances of the GPL boilerplate paragraph
directing people to write to the FSF for a copy of the GPL, since the
@@ -519,12 +573,16 @@ Comments
Commit message
--------------
+ .. _bad-sign-off:
+
**BAD_SIGN_OFF**
The signed-off-by line does not fall in line with the standards
specified by the community.
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
+ .. _bad-stable-address-style:
+
**BAD_STABLE_ADDRESS_STYLE**
The email format for stable is incorrect.
Some valid options for stable address are::
@@ -536,17 +594,23 @@ Commit message
[email protected] # version info
+ .. _commit-comment-symbol:
+
**COMMIT_COMMENT_SYMBOL**
Commit log lines starting with a '#' are ignored by git as
comments. To solve this problem addition of a single space
infront of the log line is enough.
+ .. _commit-message:
+
**COMMIT_MESSAGE**
The patch is missing a commit description. A brief
description of the changes made by the patch should be added.
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
+ .. _email-subject:
+
**EMAIL_SUBJECT**
Naming the tool that found the issue is not very useful in the
subject line. A good subject line summarizes the change that
@@ -554,6 +618,8 @@ Commit message
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
+ .. _from-sign-off-mismatch:
+
**FROM_SIGN_OFF_MISMATCH**
The author's email does not match with that in the Signed-off-by:
line(s). This can be sometimes caused due to an improperly configured
@@ -566,6 +632,8 @@ Commit message
- The email subaddresses do not match.
- The email comments do not match.
+ .. _missing-sign-off:
+
**MISSING_SIGN_OFF**
The patch is missing a Signed-off-by line. A signed-off-by
line should be added according to Developer's certificate of
@@ -573,6 +641,8 @@ Commit message
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
+ .. _no-author-sign-off:
+
**NO_AUTHOR_SIGN_OFF**
The author of the patch has not signed off the patch. It is
required that a simple sign off line should be present at the
@@ -582,6 +652,8 @@ Commit message
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
+ .. _diff-in-commit-msg:
+
**DIFF_IN_COMMIT_MSG**
Avoid having diff content in commit message.
This causes problems when one tries to apply a file containing both
@@ -590,6 +662,8 @@ Commit message
See: https://lore.kernel.org/lkml/[email protected]/
+ .. _gerrit-change-id:
+
**GERRIT_CHANGE_ID**
To be picked up by gerrit, the footer of the commit message might
have a Change-Id like::
@@ -599,6 +673,8 @@ Commit message
The Change-Id line must be removed before submitting.
+ .. _git-commit-id:
+
**GIT_COMMIT_ID**
The proper way to reference a commit id is:
commit <12+ chars of sha1> ("<title line>")
@@ -612,6 +688,8 @@ Commit message
See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
+ .. _bad-fixes-tag:
+
**BAD_FIXES_TAG**
The Fixes: tag is malformed or does not follow the community conventions.
This can occur if the tag have been split into multiple lines (e.g., when
@@ -623,6 +701,8 @@ Commit message
Comparison style
----------------
+ .. _assign-in-if:
+
**ASSIGN_IN_IF**
Do not use assignments in if condition.
Example::
@@ -634,16 +714,22 @@ Comparison style
foo = bar(...);
if (foo < BAZ) {
+ .. _bool-comparison:
+
**BOOL_COMPARISON**
Comparisons of A to true and false are better written
as A and !A.
See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
+ .. _comparison-to-null:
+
**COMPARISON_TO_NULL**
Comparisons to NULL in the form (foo == NULL) or (foo != NULL)
are better written as (!foo) and (foo).
+ .. _constant-comparison:
+
**CONSTANT_COMPARISON**
Comparisons with a constant or upper case identifier on the left
side of the test should be avoided.
@@ -652,6 +738,8 @@ Comparison style
Indentation and Line Breaks
---------------------------
+ .. _code-indent:
+
**CODE_INDENT**
Code indent should use tabs instead of spaces.
Outside of comments, documentation and Kconfig,
@@ -659,6 +747,8 @@ Indentation and Line Breaks
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
+ .. _deep-indentation:
+
**DEEP_INDENTATION**
Indentation with 6 or more tabs usually indicate overly indented
code.
@@ -668,6 +758,8 @@ Indentation and Line Breaks
See: https://lore.kernel.org/lkml/1328311239.21255.24.camel@joe2Laptop/
+ .. _switch-case-indent-level:
+
**SWITCH_CASE_INDENT_LEVEL**
switch should be at the same indent as case.
Example::
@@ -691,6 +783,8 @@ Indentation and Line Breaks
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
+ .. _long-line:
+
**LONG_LINE**
The line has exceeded the specified maximum length.
To use a different maximum line length, the --max-line-length=n option
@@ -703,6 +797,8 @@ Indentation and Line Breaks
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
+ .. _long-line-string:
+
**LONG_LINE_STRING**
A string starts before but extends beyond the maximum line length.
To use a different maximum line length, the --max-line-length=n option
@@ -710,6 +806,8 @@ Indentation and Line Breaks
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
+ .. _long-line-comment:
+
**LONG_LINE_COMMENT**
A comment starts before but extends beyond the maximum line length.
To use a different maximum line length, the --max-line-length=n option
@@ -717,12 +815,16 @@ Indentation and Line Breaks
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
+ .. _split-string:
+
**SPLIT_STRING**
Quoted strings that appear as messages in userspace and can be
grepped, should not be split across multiple lines.
See: https://lore.kernel.org/lkml/20120203052727.GA15035@leaf/
+ .. _multiline-dereference:
+
**MULTILINE_DEREFERENCE**
A single dereferencing identifier spanned on multiple lines like::
@@ -750,6 +852,8 @@ Indentation and Line Breaks
violation because it is much easier to read a dereferencing identifier
on a single line.
+ .. _trailing-statements:
+
**TRAILING_STATEMENTS**
Trailing statements (for example after any conditional) should be
on the next line.
@@ -766,6 +870,8 @@ Indentation and Line Breaks
Macros, Attributes and Symbols
------------------------------
+ .. _array-size:
+
**ARRAY_SIZE**
The ARRAY_SIZE(foo) macro should be preferred over
sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
@@ -775,10 +881,14 @@ Macros, Attributes and Symbols
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+ .. _avoid-externs:
+
**AVOID_EXTERNS**
Function prototypes don't need to be declared extern in .h
files. It's assumed by the compiler and is unnecessary.
+ .. _avoid-l-prefix:
+
**AVOID_L_PREFIX**
Local symbol names that are prefixed with `.L` should be avoided,
as this has special meaning for the assembler; a symbol entry will
@@ -791,12 +901,16 @@ Macros, Attributes and Symbols
the beginning or end of code regions via
`SYM_CODE_START_LOCAL`/`SYM_CODE_END`
+ .. _bit-macro:
+
**BIT_MACRO**
Defines like: 1 << <digit> could be BIT(digit).
The BIT() macro is defined via include/linux/bits.h::
#define BIT(nr) (1UL << (nr))
+ .. _const-read-mostly:
+
**CONST_READ_MOSTLY**
When a variable is tagged with the __read_mostly annotation, it is a
signal to the compiler that accesses to the variable will be mostly
@@ -805,6 +919,8 @@ Macros, Attributes and Symbols
const __read_mostly does not make any sense as const data is already
read-only. The __read_mostly annotation thus should be removed.
+ .. _date-time:
+
**DATE_TIME**
It is generally desirable that building the same source code with
the same set of tools is reproducible, i.e. the output is always
@@ -816,6 +932,8 @@ Macros, Attributes and Symbols
See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
+ .. _define-arch-has:
+
**DEFINE_ARCH_HAS**
The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong.
@@ -827,9 +945,13 @@ Macros, Attributes and Symbols
See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/
+ .. _do-while-macro-with-trailing-semicolon:
+
**DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON**
do {} while(0) macros should not have a trailing semicolon.
+ .. _init-attribute:
+
**INIT_ATTRIBUTE**
Const init definitions should use __initconst instead of
__initdata.
@@ -837,6 +959,8 @@ Macros, Attributes and Symbols
Similarly init definitions without const require a separate
use of const.
+ .. _inline-location:
+
**INLINE_LOCATION**
The inline keyword should sit between storage class and type.
@@ -854,6 +978,8 @@ Macros, Attributes and Symbols
...
}
+ .. _misplaced-init:
+
**MISPLACED_INIT**
It is possible to use section markers on variables in a way
which gcc doesn't understand (or at least not the way the
@@ -868,6 +994,8 @@ Macros, Attributes and Symbols
See: https://lore.kernel.org/lkml/1377655732.3619.19.camel@joe-AO722/
+ .. _multistatement-macro-use-do-while:
+
**MULTISTATEMENT_MACRO_USE_DO_WHILE**
Macros with multiple statements should be enclosed in a
do - while block. Same should also be the case for macros
@@ -881,10 +1009,14 @@ Macros, Attributes and Symbols
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
+ .. _prefer-fallthrough:
+
**PREFER_FALLTHROUGH**
Use the `fallthrough;` pseudo keyword instead of
`/* fallthrough */` like comments.
+ .. _trailing-semicolon:
+
**TRAILING_SEMICOLON**
Macro definition should not end with a semicolon. The macro
invocation style should be consistent with function calls.
@@ -906,6 +1038,8 @@ Macros, Attributes and Symbols
See: https://lore.kernel.org/lkml/1399671106.2912.21.camel@joe-AO725/
+ .. _single-statement-do-while-macro:
+
**SINGLE_STATEMENT_DO_WHILE_MACRO**
For the multi-statement macros, it is necessary to use the do-while
loop to avoid unpredictable code paths. The do-while loop helps to
@@ -917,6 +1051,8 @@ Macros, Attributes and Symbols
the do-while loop is redundant. So remove the do-while loop for single
statement macros.
+ .. _weak-declaration:
+
**WEAK_DECLARATION**
Using weak declarations like __attribute__((weak)) or __weak
can have unintended link defects. Avoid using them.
@@ -925,15 +1061,21 @@ Macros, Attributes and Symbols
Functions and Variables
-----------------------
+ .. _camelcase:
+
**CAMELCASE**
Avoid CamelCase Identifiers.
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
+ .. _const-const:
+
**CONST_CONST**
Using `const <type> const *` is generally meant to be
written `const <type> * const`.
+ .. _const-struct:
+
**CONST_STRUCT**
Using const is generally a good idea. Checkpatch reads
a list of frequently used structs that are always or
@@ -944,6 +1086,8 @@ Functions and Variables
See: https://lore.kernel.org/lkml/alpine.DEB.2.10.1608281509480.3321@hadrien/
+ .. _embedded-function-name:
+
**EMBEDDED_FUNCTION_NAME**
Embedded function names are less appropriate to use as
refactoring can cause function renaming. Prefer the use of
@@ -952,6 +1096,8 @@ Functions and Variables
Note that this does not work with -f (--file) checkpatch option
as it depends on patch context providing the function name.
+ .. _function-arguments:
+
**FUNCTION_ARGUMENTS**
This warning is emitted due to any of the following reasons:
@@ -972,6 +1118,8 @@ Functions and Variables
All arguments should have identifier names.
+ .. _function-without-args:
+
**FUNCTION_WITHOUT_ARGS**
Function declarations without arguments like::
@@ -981,22 +1129,30 @@ Functions and Variables
int foo(void)
+ .. _global-initialisers:
+
**GLOBAL_INITIALISERS**
Global variables should not be initialized explicitly to
0 (or NULL, false, etc.). Your compiler (or rather your
loader, which is responsible for zeroing out the relevant
sections) automatically does it for you.
+ .. _initialised-static:
+
**INITIALISED_STATIC**
Static variables should not be initialized explicitly to zero.
Your compiler (or rather your loader) automatically does
it for you.
+ .. _multiple-assignments:
+
**MULTIPLE_ASSIGNMENTS**
Multiple assignments on a single line makes the code unnecessarily
complicated. So on a single line assign value to a single variable
only, this makes the code more readable and helps avoid typos.
+ .. _return-parentheses:
+
**RETURN_PARENTHESES**
return is not a function and as such doesn't need parentheses::
@@ -1010,6 +1166,8 @@ Functions and Variables
Permissions
-----------
+ .. _device-attr-perms:
+
**DEVICE_ATTR_PERMS**
The permissions used in DEVICE_ATTR are unusual.
Typically only three permissions are used - 0644 (RW), 0444 (RO)
@@ -1017,10 +1175,14 @@ Permissions
See: https://www.kernel.org/doc/html/latest/filesystems/sysfs.html#attributes
+ .. _execute-permissions:
+
**EXECUTE_PERMISSIONS**
There is no reason for source files to be executable. The executable
bit can be removed safely.
+ .. _exported-world-writable:
+
**EXPORTED_WORLD_WRITABLE**
Exporting world writable sysfs/debugfs files is usually a bad thing.
When done arbitrarily they can introduce serious security bugs.
@@ -1030,10 +1192,14 @@ Permissions
See: https://lore.kernel.org/linux-arm-kernel/[email protected]/
+ .. _non-octal-permissions:
+
**NON_OCTAL_PERMISSIONS**
Permission bits should use 4 digit octal permissions (like 0700 or 0444).
Avoid using any other base like decimal.
+ .. _symbolic-perms:
+
**SYMBOLIC_PERMS**
Permission bits in the octal form are more readable and easier to
understand than their symbolic counterparts because many command-line
@@ -1049,10 +1215,14 @@ Permissions
Spacing and Brackets
--------------------
+ .. _assignment-continuations:
+
**ASSIGNMENT_CONTINUATIONS**
Assignment operators should not be written at the start of a
line but should follow the operand at the previous line.
+ .. _braces:
+
**BRACES**
The placement of braces is stylistically incorrect.
The preferred way is to put the opening brace last on the line,
@@ -1073,6 +1243,8 @@ Spacing and Brackets
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
+ .. _bracket-space:
+
**BRACKET_SPACE**
Whitespace before opening bracket '[' is prohibited.
There are some exceptions:
@@ -1089,6 +1261,8 @@ Spacing and Brackets
= { [0...10] = 5 }
+ .. _concatenated-string:
+
**CONCATENATED_STRING**
Concatenated elements should have a space in between.
Example::
@@ -1099,17 +1273,23 @@ Spacing and Brackets
printk(KERN_INFO "bar");
+ .. _else-after-brace:
+
**ELSE_AFTER_BRACE**
`else {` should follow the closing block `}` on the same line.
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
+ .. _line-spacing:
+
**LINE_SPACING**
Vertical space is wasted given the limited number of lines an
editor window can display when multiple blank lines are used.
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
+ .. _open-brace:
+
**OPEN_BRACE**
The opening brace should be following the function definitions on the
next line. For any non-functional block it should be on the same line
@@ -1117,6 +1297,8 @@ Spacing and Brackets
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
+ .. _pointer-location:
+
**POINTER_LOCATION**
When using pointer data or a function that returns a pointer type,
the preferred use of * is adjacent to the data name or function name
@@ -1129,11 +1311,15 @@ Spacing and Brackets
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
+ .. _spacing:
+
**SPACING**
Whitespace style used in the kernel sources is described in kernel docs.
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
+ .. _trailing-whitespace:
+
**TRAILING_WHITESPACE**
Trailing whitespace should always be removed.
Some editors highlight the trailing whitespace and cause visual
@@ -1141,6 +1327,8 @@ Spacing and Brackets
See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
+ .. _unnecessary-parentheses:
+
**UNNECESSARY_PARENTHESES**
Parentheses are not required in the following cases:
@@ -1172,6 +1360,8 @@ Spacing and Brackets
&foo->bar
*foo->bar
+ .. _while-after-brace:
+
**WHILE_AFTER_BRACE**
while should follow the closing bracket on the same line::
@@ -1185,19 +1375,27 @@ Spacing and Brackets
Others
------
+ .. _config-description:
+
**CONFIG_DESCRIPTION**
Kconfig symbols should have a help text which fully describes
it.
+ .. _corrupted-patch:
+
**CORRUPTED_PATCH**
The patch seems to be corrupted or lines are wrapped.
Please regenerate the patch file before sending it to the maintainer.
+ .. _cvs-keyword:
+
**CVS_KEYWORD**
Since linux moved to git, the CVS markers are no longer used.
So, CVS style keywords ($Id$, $Revision$, $Log$) should not be
added.
+ .. _default-no-break:
+
**DEFAULT_NO_BREAK**
switch default case is sometimes written as "default:;". This can
cause new cases added below default to be defective.
@@ -1205,16 +1403,22 @@ Others
A "break;" should be added after empty default statement to avoid
unwanted fallthrough.
+ .. _dos-line-endings:
+
**DOS_LINE_ENDINGS**
For DOS-formatted patches, there are extra ^M symbols at the end of
the line. These should be removed.
+ .. _dt-schema-binding-patch:
+
**DT_SCHEMA_BINDING_PATCH**
DT bindings moved to a json-schema based format instead of
freeform text.
See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html
+ .. _dt-split-binding-patch:
+
**DT_SPLIT_BINDING_PATCH**
Devicetree bindings should be their own patch. This is because
bindings are logically independent from a driver implementation,
@@ -1224,20 +1428,28 @@ Others
See: https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters
+ .. _embedded-filename:
+
**EMBEDDED_FILENAME**
Embedding the complete filename path inside the file isn't particularly
useful as often the path is moved around and becomes incorrect.
+ .. _file-path-changes:
+
**FILE_PATH_CHANGES**
Whenever files are added, moved, or deleted, the MAINTAINERS file
patterns can be out of sync or outdated.
So MAINTAINERS might need updating in these cases.
+ .. _memset:
+
**MEMSET**
The memset use appears to be incorrect. This may be caused due to
badly ordered parameters. Please recheck the usage.
+ .. _not-unified-diff:
+
**NOT_UNIFIED_DIFF**
The patch file does not appear to be in unified-diff format. Please
regenerate the patch file before sending it to the maintainer.
@@ -1245,6 +1457,8 @@ Others
**PRINTF_0XDECIMAL**
Prefixing 0x with decimal output is defective and should be corrected.
+ .. _spdx-license-tag:
+
**SPDX_LICENSE_TAG**
The source file is missing or has an improper SPDX identifier tag.
The Linux kernel requires the precise SPDX identifier in all source files,
@@ -1252,5 +1466,7 @@ Others
See: https://www.kernel.org/doc/html/latest/process/license-rules.html
+ .. _typo-spelling:
+
**TYPO_SPELLING**
Some words may have been misspelled. Consider reviewing them.
--
2.43.0
On Mon, 13 May 2024, Diederik de Haas <[email protected]> wrote:
> Make the tags directly linkable by defining targets for them.
>
> Closes: https://lore.kernel.org/r/8090211.0vHzs8tI1a@bagend/
> Signed-off-by: Diederik de Haas <[email protected]>
> ---
> Documentation/dev-tools/checkpatch.rst | 216 +++++++++++++++++++++++++
> 1 file changed, 216 insertions(+)
>
> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> index 127968995847..6499e29c3a19 100644
> --- a/Documentation/dev-tools/checkpatch.rst
> +++ b/Documentation/dev-tools/checkpatch.rst
> @@ -242,6 +242,8 @@ This section contains a description of all the message types in checkpatch.
> Allocation style
> ----------------
>
> + .. _alloc-array-args:
> +
> **ALLOC_ARRAY_ARGS**
Alternatively, you could just convert the definition lists into section
titles to make them implicit hyperlink targets. The rst stays cleaner
and there's no manual updating.
BR,
Jani.
> The first argument for kcalloc or kmalloc_array should be the
> number of elements. sizeof() as the first argument is generally
> @@ -249,6 +251,8 @@ Allocation style
>
> See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html
>
> + .. _alloc-sizeof-struct:
> +
> **ALLOC_SIZEOF_STRUCT**
> The allocation style is bad. In general for family of
> allocation functions using sizeof() to get memory size,
> @@ -262,6 +266,8 @@ Allocation style
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory
>
> + .. _alloc-with-multiply:
> +
> **ALLOC_WITH_MULTIPLY**
> Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a
> sizeof multiply.
> @@ -272,16 +278,22 @@ Allocation style
> API usage
> ---------
>
> + .. _arch-defines:
> +
> **ARCH_DEFINES**
> Architecture specific defines should be avoided wherever
> possible.
>
> + .. _arch-include-linux:
> +
> **ARCH_INCLUDE_LINUX**
> Whenever asm/file.h is included and linux/file.h exists, a
> conversion can be made when linux/file.h includes asm/file.h.
> However this is not always the case (See signal.h).
> This message type is emitted only for includes from arch/.
>
> + .. _avoid-bug:
> +
> **AVOID_BUG**
> BUG() or BUG_ON() should be avoided totally.
> Use WARN() and WARN_ON() instead, and handle the "impossible"
> @@ -289,6 +301,8 @@ API usage
>
> See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on
>
> + .. _consider-kstrto:
> +
> **CONSIDER_KSTRTO**
> The simple_strtol(), simple_strtoll(), simple_strtoul(), and
> simple_strtoull() functions explicitly ignore overflows, which
> @@ -298,6 +312,8 @@ API usage
>
> See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull
>
> + .. _constant-conversion:
> +
> **CONSTANT_CONVERSION**
> Use of __constant_<foo> form is discouraged for the following functions::
>
> @@ -334,6 +350,8 @@ API usage
>
> See: https://lore.kernel.org/lkml/1400106425.12666.6.camel@joe-AO725/
>
> + .. _deprecated-api:
> +
> **DEPRECATED_API**
> Usage of a deprecated RCU API is detected. It is recommended to replace
> old flavourful RCU APIs by their new vanilla-RCU counterparts.
> @@ -342,6 +360,8 @@ API usage
>
> See: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis
>
> + .. _deprecated-variable:
> +
> **DEPRECATED_VARIABLE**
> EXTRA_{A,C,CPP,LD}FLAGS are deprecated and should be replaced by the new
> flags added via commit f77bf01425b1 ("kbuild: introduce ccflags-y,
> @@ -360,6 +380,8 @@ API usage
> 2. https://lore.kernel.org/lkml/[email protected]/
> 3. https://www.kernel.org/doc/html/latest/kbuild/makefiles.html#compilation-flags
>
> + .. _device-attr-functions:
> +
> **DEVICE_ATTR_FUNCTIONS**
> The function names used in DEVICE_ATTR is unusual.
> Typically, the store and show functions are used with <attr>_store and
> @@ -374,6 +396,8 @@ API usage
>
> See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
>
> + .. _device-attr-ro:
> +
> **DEVICE_ATTR_RO**
> The DEVICE_ATTR_RO(name) helper macro can be used instead of
> DEVICE_ATTR(name, 0444, name_show, NULL);
> @@ -383,6 +407,8 @@ API usage
>
> See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
>
> + .. _device-attr-rw:
> +
> **DEVICE_ATTR_RW**
> The DEVICE_ATTR_RW(name) helper macro can be used instead of
> DEVICE_ATTR(name, 0644, name_show, name_store);
> @@ -392,6 +418,8 @@ API usage
>
> See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
>
> + .. _device-attr-wo:
> +
> **DEVICE_ATTR_WO**
> The DEVICE_AATR_WO(name) helper macro can be used instead of
> DEVICE_ATTR(name, 0200, NULL, name_store);
> @@ -401,6 +429,8 @@ API usage
>
> See: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes
>
> + .. _duplicated-sysctl-const:
> +
> **DUPLICATED_SYSCTL_CONST**
> Commit d91bff3011cf ("proc/sysctl: add shared variables for range
> check") added some shared const variables to be used instead of a local
> @@ -419,6 +449,8 @@ API usage
> 1. https://lore.kernel.org/lkml/[email protected]/
> 2. https://lore.kernel.org/lkml/[email protected]/
>
> + .. _enosys:
> +
> **ENOSYS**
> ENOSYS means that a nonexistent system call was called.
> Earlier, it was wrongly used for things like invalid operations on
> @@ -426,15 +458,21 @@ API usage
>
> See: https://lore.kernel.org/lkml/5eb299021dec23c1a48fa7d9f2c8b794e967766d.1408730669.git.luto@amacapital.net/
>
> + .. _enotsupp:
> +
> **ENOTSUPP**
> ENOTSUPP is not a standard error code and should be avoided in new patches.
> EOPNOTSUPP should be used instead.
>
> See: https://lore.kernel.org/netdev/[email protected]/
>
> + .. _export-symbol:
> +
> **EXPORT_SYMBOL**
> EXPORT_SYMBOL should immediately follow the symbol to be exported.
>
> + .. _in-atomic:
> +
> **IN_ATOMIC**
> in_atomic() is not for driver use so any such use is reported as an ERROR.
> Also in_atomic() is often used to determine if sleeping is permitted,
> @@ -445,6 +483,8 @@ API usage
>
> See: https://lore.kernel.org/lkml/[email protected]/
>
> + .. _lockdep:
> +
> **LOCKDEP**
> The lockdep_no_validate class was added as a temporary measure to
> prevent warnings on conversion of device->sem to device->mutex.
> @@ -452,20 +492,28 @@ API usage
>
> See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/
>
> + .. _malformed-include:
> +
> **MALFORMED_INCLUDE**
> The #include statement has a malformed path. This has happened
> because the author has included a double slash "//" in the pathname
> accidentally.
>
> + .. _use-lockdep:
> +
> **USE_LOCKDEP**
> lockdep_assert_held() annotations should be preferred over
> assertions based on spin_is_locked()
>
> See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations
>
> + .. _uapi-include:
> +
> **UAPI_INCLUDE**
> No #include statements in include/uapi should use a uapi/ path.
>
> + .. _usleep-range:
> +
> **USLEEP_RANGE**
> usleep_range() should be preferred over udelay(). The proper way of
> using usleep_range() is mentioned in the kernel docs.
> @@ -476,6 +524,8 @@ API usage
> Comments
> --------
>
> + .. _block-comment-style:
> +
> **BLOCK_COMMENT_STYLE**
> The comment style is incorrect. The preferred style for multi-
> line comments is::
> @@ -500,12 +550,16 @@ Comments
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting
>
> + .. _data-race:
> +
> **DATA_RACE**
> Applications of data_race() should have a comment so as to document the
> reasoning behind why it was deemed safe.
>
> See: https://lore.kernel.org/lkml/[email protected]/
>
> + .. _fsf-mailing-address:
> +
> **FSF_MAILING_ADDRESS**
> Kernel maintainers reject new instances of the GPL boilerplate paragraph
> directing people to write to the FSF for a copy of the GPL, since the
> @@ -519,12 +573,16 @@ Comments
> Commit message
> --------------
>
> + .. _bad-sign-off:
> +
> **BAD_SIGN_OFF**
> The signed-off-by line does not fall in line with the standards
> specified by the community.
>
> See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1
>
> + .. _bad-stable-address-style:
> +
> **BAD_STABLE_ADDRESS_STYLE**
> The email format for stable is incorrect.
> Some valid options for stable address are::
> @@ -536,17 +594,23 @@ Commit message
>
> [email protected] # version info
>
> + .. _commit-comment-symbol:
> +
> **COMMIT_COMMENT_SYMBOL**
> Commit log lines starting with a '#' are ignored by git as
> comments. To solve this problem addition of a single space
> infront of the log line is enough.
>
> + .. _commit-message:
> +
> **COMMIT_MESSAGE**
> The patch is missing a commit description. A brief
> description of the changes made by the patch should be added.
>
> See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
>
> + .. _email-subject:
> +
> **EMAIL_SUBJECT**
> Naming the tool that found the issue is not very useful in the
> subject line. A good subject line summarizes the change that
> @@ -554,6 +618,8 @@ Commit message
>
> See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
>
> + .. _from-sign-off-mismatch:
> +
> **FROM_SIGN_OFF_MISMATCH**
> The author's email does not match with that in the Signed-off-by:
> line(s). This can be sometimes caused due to an improperly configured
> @@ -566,6 +632,8 @@ Commit message
> - The email subaddresses do not match.
> - The email comments do not match.
>
> + .. _missing-sign-off:
> +
> **MISSING_SIGN_OFF**
> The patch is missing a Signed-off-by line. A signed-off-by
> line should be added according to Developer's certificate of
> @@ -573,6 +641,8 @@ Commit message
>
> See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
>
> + .. _no-author-sign-off:
> +
> **NO_AUTHOR_SIGN_OFF**
> The author of the patch has not signed off the patch. It is
> required that a simple sign off line should be present at the
> @@ -582,6 +652,8 @@ Commit message
>
> See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin
>
> + .. _diff-in-commit-msg:
> +
> **DIFF_IN_COMMIT_MSG**
> Avoid having diff content in commit message.
> This causes problems when one tries to apply a file containing both
> @@ -590,6 +662,8 @@ Commit message
>
> See: https://lore.kernel.org/lkml/[email protected]/
>
> + .. _gerrit-change-id:
> +
> **GERRIT_CHANGE_ID**
> To be picked up by gerrit, the footer of the commit message might
> have a Change-Id like::
> @@ -599,6 +673,8 @@ Commit message
>
> The Change-Id line must be removed before submitting.
>
> + .. _git-commit-id:
> +
> **GIT_COMMIT_ID**
> The proper way to reference a commit id is:
> commit <12+ chars of sha1> ("<title line>")
> @@ -612,6 +688,8 @@ Commit message
>
> See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes
>
> + .. _bad-fixes-tag:
> +
> **BAD_FIXES_TAG**
> The Fixes: tag is malformed or does not follow the community conventions.
> This can occur if the tag have been split into multiple lines (e.g., when
> @@ -623,6 +701,8 @@ Commit message
> Comparison style
> ----------------
>
> + .. _assign-in-if:
> +
> **ASSIGN_IN_IF**
> Do not use assignments in if condition.
> Example::
> @@ -634,16 +714,22 @@ Comparison style
> foo = bar(...);
> if (foo < BAZ) {
>
> + .. _bool-comparison:
> +
> **BOOL_COMPARISON**
> Comparisons of A to true and false are better written
> as A and !A.
>
> See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/
>
> + .. _comparison-to-null:
> +
> **COMPARISON_TO_NULL**
> Comparisons to NULL in the form (foo == NULL) or (foo != NULL)
> are better written as (!foo) and (foo).
>
> + .. _constant-comparison:
> +
> **CONSTANT_COMPARISON**
> Comparisons with a constant or upper case identifier on the left
> side of the test should be avoided.
> @@ -652,6 +738,8 @@ Comparison style
> Indentation and Line Breaks
> ---------------------------
>
> + .. _code-indent:
> +
> **CODE_INDENT**
> Code indent should use tabs instead of spaces.
> Outside of comments, documentation and Kconfig,
> @@ -659,6 +747,8 @@ Indentation and Line Breaks
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
>
> + .. _deep-indentation:
> +
> **DEEP_INDENTATION**
> Indentation with 6 or more tabs usually indicate overly indented
> code.
> @@ -668,6 +758,8 @@ Indentation and Line Breaks
>
> See: https://lore.kernel.org/lkml/1328311239.21255.24.camel@joe2Laptop/
>
> + .. _switch-case-indent-level:
> +
> **SWITCH_CASE_INDENT_LEVEL**
> switch should be at the same indent as case.
> Example::
> @@ -691,6 +783,8 @@ Indentation and Line Breaks
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation
>
> + .. _long-line:
> +
> **LONG_LINE**
> The line has exceeded the specified maximum length.
> To use a different maximum line length, the --max-line-length=n option
> @@ -703,6 +797,8 @@ Indentation and Line Breaks
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
>
> + .. _long-line-string:
> +
> **LONG_LINE_STRING**
> A string starts before but extends beyond the maximum line length.
> To use a different maximum line length, the --max-line-length=n option
> @@ -710,6 +806,8 @@ Indentation and Line Breaks
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
>
> + .. _long-line-comment:
> +
> **LONG_LINE_COMMENT**
> A comment starts before but extends beyond the maximum line length.
> To use a different maximum line length, the --max-line-length=n option
> @@ -717,12 +815,16 @@ Indentation and Line Breaks
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings
>
> + .. _split-string:
> +
> **SPLIT_STRING**
> Quoted strings that appear as messages in userspace and can be
> grepped, should not be split across multiple lines.
>
> See: https://lore.kernel.org/lkml/20120203052727.GA15035@leaf/
>
> + .. _multiline-dereference:
> +
> **MULTILINE_DEREFERENCE**
> A single dereferencing identifier spanned on multiple lines like::
>
> @@ -750,6 +852,8 @@ Indentation and Line Breaks
> violation because it is much easier to read a dereferencing identifier
> on a single line.
>
> + .. _trailing-statements:
> +
> **TRAILING_STATEMENTS**
> Trailing statements (for example after any conditional) should be
> on the next line.
> @@ -766,6 +870,8 @@ Indentation and Line Breaks
> Macros, Attributes and Symbols
> ------------------------------
>
> + .. _array-size:
> +
> **ARRAY_SIZE**
> The ARRAY_SIZE(foo) macro should be preferred over
> sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
> @@ -775,10 +881,14 @@ Macros, Attributes and Symbols
>
> #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
>
> + .. _avoid-externs:
> +
> **AVOID_EXTERNS**
> Function prototypes don't need to be declared extern in .h
> files. It's assumed by the compiler and is unnecessary.
>
> + .. _avoid-l-prefix:
> +
> **AVOID_L_PREFIX**
> Local symbol names that are prefixed with `.L` should be avoided,
> as this has special meaning for the assembler; a symbol entry will
> @@ -791,12 +901,16 @@ Macros, Attributes and Symbols
> the beginning or end of code regions via
> `SYM_CODE_START_LOCAL`/`SYM_CODE_END`
>
> + .. _bit-macro:
> +
> **BIT_MACRO**
> Defines like: 1 << <digit> could be BIT(digit).
> The BIT() macro is defined via include/linux/bits.h::
>
> #define BIT(nr) (1UL << (nr))
>
> + .. _const-read-mostly:
> +
> **CONST_READ_MOSTLY**
> When a variable is tagged with the __read_mostly annotation, it is a
> signal to the compiler that accesses to the variable will be mostly
> @@ -805,6 +919,8 @@ Macros, Attributes and Symbols
> const __read_mostly does not make any sense as const data is already
> read-only. The __read_mostly annotation thus should be removed.
>
> + .. _date-time:
> +
> **DATE_TIME**
> It is generally desirable that building the same source code with
> the same set of tools is reproducible, i.e. the output is always
> @@ -816,6 +932,8 @@ Macros, Attributes and Symbols
>
> See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps
>
> + .. _define-arch-has:
> +
> **DEFINE_ARCH_HAS**
> The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong.
>
> @@ -827,9 +945,13 @@ Macros, Attributes and Symbols
>
> See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/
>
> + .. _do-while-macro-with-trailing-semicolon:
> +
> **DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON**
> do {} while(0) macros should not have a trailing semicolon.
>
> + .. _init-attribute:
> +
> **INIT_ATTRIBUTE**
> Const init definitions should use __initconst instead of
> __initdata.
> @@ -837,6 +959,8 @@ Macros, Attributes and Symbols
> Similarly init definitions without const require a separate
> use of const.
>
> + .. _inline-location:
> +
> **INLINE_LOCATION**
> The inline keyword should sit between storage class and type.
>
> @@ -854,6 +978,8 @@ Macros, Attributes and Symbols
> ...
> }
>
> + .. _misplaced-init:
> +
> **MISPLACED_INIT**
> It is possible to use section markers on variables in a way
> which gcc doesn't understand (or at least not the way the
> @@ -868,6 +994,8 @@ Macros, Attributes and Symbols
>
> See: https://lore.kernel.org/lkml/1377655732.3619.19.camel@joe-AO722/
>
> + .. _multistatement-macro-use-do-while:
> +
> **MULTISTATEMENT_MACRO_USE_DO_WHILE**
> Macros with multiple statements should be enclosed in a
> do - while block. Same should also be the case for macros
> @@ -881,10 +1009,14 @@ Macros, Attributes and Symbols
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl
>
> + .. _prefer-fallthrough:
> +
> **PREFER_FALLTHROUGH**
> Use the `fallthrough;` pseudo keyword instead of
> `/* fallthrough */` like comments.
>
> + .. _trailing-semicolon:
> +
> **TRAILING_SEMICOLON**
> Macro definition should not end with a semicolon. The macro
> invocation style should be consistent with function calls.
> @@ -906,6 +1038,8 @@ Macros, Attributes and Symbols
>
> See: https://lore.kernel.org/lkml/1399671106.2912.21.camel@joe-AO725/
>
> + .. _single-statement-do-while-macro:
> +
> **SINGLE_STATEMENT_DO_WHILE_MACRO**
> For the multi-statement macros, it is necessary to use the do-while
> loop to avoid unpredictable code paths. The do-while loop helps to
> @@ -917,6 +1051,8 @@ Macros, Attributes and Symbols
> the do-while loop is redundant. So remove the do-while loop for single
> statement macros.
>
> + .. _weak-declaration:
> +
> **WEAK_DECLARATION**
> Using weak declarations like __attribute__((weak)) or __weak
> can have unintended link defects. Avoid using them.
> @@ -925,15 +1061,21 @@ Macros, Attributes and Symbols
> Functions and Variables
> -----------------------
>
> + .. _camelcase:
> +
> **CAMELCASE**
> Avoid CamelCase Identifiers.
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming
>
> + .. _const-const:
> +
> **CONST_CONST**
> Using `const <type> const *` is generally meant to be
> written `const <type> * const`.
>
> + .. _const-struct:
> +
> **CONST_STRUCT**
> Using const is generally a good idea. Checkpatch reads
> a list of frequently used structs that are always or
> @@ -944,6 +1086,8 @@ Functions and Variables
>
> See: https://lore.kernel.org/lkml/alpine.DEB.2.10.1608281509480.3321@hadrien/
>
> + .. _embedded-function-name:
> +
> **EMBEDDED_FUNCTION_NAME**
> Embedded function names are less appropriate to use as
> refactoring can cause function renaming. Prefer the use of
> @@ -952,6 +1096,8 @@ Functions and Variables
> Note that this does not work with -f (--file) checkpatch option
> as it depends on patch context providing the function name.
>
> + .. _function-arguments:
> +
> **FUNCTION_ARGUMENTS**
> This warning is emitted due to any of the following reasons:
>
> @@ -972,6 +1118,8 @@ Functions and Variables
>
> All arguments should have identifier names.
>
> + .. _function-without-args:
> +
> **FUNCTION_WITHOUT_ARGS**
> Function declarations without arguments like::
>
> @@ -981,22 +1129,30 @@ Functions and Variables
>
> int foo(void)
>
> + .. _global-initialisers:
> +
> **GLOBAL_INITIALISERS**
> Global variables should not be initialized explicitly to
> 0 (or NULL, false, etc.). Your compiler (or rather your
> loader, which is responsible for zeroing out the relevant
> sections) automatically does it for you.
>
> + .. _initialised-static:
> +
> **INITIALISED_STATIC**
> Static variables should not be initialized explicitly to zero.
> Your compiler (or rather your loader) automatically does
> it for you.
>
> + .. _multiple-assignments:
> +
> **MULTIPLE_ASSIGNMENTS**
> Multiple assignments on a single line makes the code unnecessarily
> complicated. So on a single line assign value to a single variable
> only, this makes the code more readable and helps avoid typos.
>
> + .. _return-parentheses:
> +
> **RETURN_PARENTHESES**
> return is not a function and as such doesn't need parentheses::
>
> @@ -1010,6 +1166,8 @@ Functions and Variables
> Permissions
> -----------
>
> + .. _device-attr-perms:
> +
> **DEVICE_ATTR_PERMS**
> The permissions used in DEVICE_ATTR are unusual.
> Typically only three permissions are used - 0644 (RW), 0444 (RO)
> @@ -1017,10 +1175,14 @@ Permissions
>
> See: https://www.kernel.org/doc/html/latest/filesystems/sysfs.html#attributes
>
> + .. _execute-permissions:
> +
> **EXECUTE_PERMISSIONS**
> There is no reason for source files to be executable. The executable
> bit can be removed safely.
>
> + .. _exported-world-writable:
> +
> **EXPORTED_WORLD_WRITABLE**
> Exporting world writable sysfs/debugfs files is usually a bad thing.
> When done arbitrarily they can introduce serious security bugs.
> @@ -1030,10 +1192,14 @@ Permissions
>
> See: https://lore.kernel.org/linux-arm-kernel/[email protected]/
>
> + .. _non-octal-permissions:
> +
> **NON_OCTAL_PERMISSIONS**
> Permission bits should use 4 digit octal permissions (like 0700 or 0444).
> Avoid using any other base like decimal.
>
> + .. _symbolic-perms:
> +
> **SYMBOLIC_PERMS**
> Permission bits in the octal form are more readable and easier to
> understand than their symbolic counterparts because many command-line
> @@ -1049,10 +1215,14 @@ Permissions
> Spacing and Brackets
> --------------------
>
> + .. _assignment-continuations:
> +
> **ASSIGNMENT_CONTINUATIONS**
> Assignment operators should not be written at the start of a
> line but should follow the operand at the previous line.
>
> + .. _braces:
> +
> **BRACES**
> The placement of braces is stylistically incorrect.
> The preferred way is to put the opening brace last on the line,
> @@ -1073,6 +1243,8 @@ Spacing and Brackets
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
>
> + .. _bracket-space:
> +
> **BRACKET_SPACE**
> Whitespace before opening bracket '[' is prohibited.
> There are some exceptions:
> @@ -1089,6 +1261,8 @@ Spacing and Brackets
>
> = { [0...10] = 5 }
>
> + .. _concatenated-string:
> +
> **CONCATENATED_STRING**
> Concatenated elements should have a space in between.
> Example::
> @@ -1099,17 +1273,23 @@ Spacing and Brackets
>
> printk(KERN_INFO "bar");
>
> + .. _else-after-brace:
> +
> **ELSE_AFTER_BRACE**
> `else {` should follow the closing block `}` on the same line.
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
>
> + .. _line-spacing:
> +
> **LINE_SPACING**
> Vertical space is wasted given the limited number of lines an
> editor window can display when multiple blank lines are used.
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
>
> + .. _open-brace:
> +
> **OPEN_BRACE**
> The opening brace should be following the function definitions on the
> next line. For any non-functional block it should be on the same line
> @@ -1117,6 +1297,8 @@ Spacing and Brackets
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces
>
> + .. _pointer-location:
> +
> **POINTER_LOCATION**
> When using pointer data or a function that returns a pointer type,
> the preferred use of * is adjacent to the data name or function name
> @@ -1129,11 +1311,15 @@ Spacing and Brackets
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
>
> + .. _spacing:
> +
> **SPACING**
> Whitespace style used in the kernel sources is described in kernel docs.
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
>
> + .. _trailing-whitespace:
> +
> **TRAILING_WHITESPACE**
> Trailing whitespace should always be removed.
> Some editors highlight the trailing whitespace and cause visual
> @@ -1141,6 +1327,8 @@ Spacing and Brackets
>
> See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces
>
> + .. _unnecessary-parentheses:
> +
> **UNNECESSARY_PARENTHESES**
> Parentheses are not required in the following cases:
>
> @@ -1172,6 +1360,8 @@ Spacing and Brackets
> &foo->bar
> *foo->bar
>
> + .. _while-after-brace:
> +
> **WHILE_AFTER_BRACE**
> while should follow the closing bracket on the same line::
>
> @@ -1185,19 +1375,27 @@ Spacing and Brackets
> Others
> ------
>
> + .. _config-description:
> +
> **CONFIG_DESCRIPTION**
> Kconfig symbols should have a help text which fully describes
> it.
>
> + .. _corrupted-patch:
> +
> **CORRUPTED_PATCH**
> The patch seems to be corrupted or lines are wrapped.
> Please regenerate the patch file before sending it to the maintainer.
>
> + .. _cvs-keyword:
> +
> **CVS_KEYWORD**
> Since linux moved to git, the CVS markers are no longer used.
> So, CVS style keywords ($Id$, $Revision$, $Log$) should not be
> added.
>
> + .. _default-no-break:
> +
> **DEFAULT_NO_BREAK**
> switch default case is sometimes written as "default:;". This can
> cause new cases added below default to be defective.
> @@ -1205,16 +1403,22 @@ Others
> A "break;" should be added after empty default statement to avoid
> unwanted fallthrough.
>
> + .. _dos-line-endings:
> +
> **DOS_LINE_ENDINGS**
> For DOS-formatted patches, there are extra ^M symbols at the end of
> the line. These should be removed.
>
> + .. _dt-schema-binding-patch:
> +
> **DT_SCHEMA_BINDING_PATCH**
> DT bindings moved to a json-schema based format instead of
> freeform text.
>
> See: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html
>
> + .. _dt-split-binding-patch:
> +
> **DT_SPLIT_BINDING_PATCH**
> Devicetree bindings should be their own patch. This is because
> bindings are logically independent from a driver implementation,
> @@ -1224,20 +1428,28 @@ Others
>
> See: https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters
>
> + .. _embedded-filename:
> +
> **EMBEDDED_FILENAME**
> Embedding the complete filename path inside the file isn't particularly
> useful as often the path is moved around and becomes incorrect.
>
> + .. _file-path-changes:
> +
> **FILE_PATH_CHANGES**
> Whenever files are added, moved, or deleted, the MAINTAINERS file
> patterns can be out of sync or outdated.
>
> So MAINTAINERS might need updating in these cases.
>
> + .. _memset:
> +
> **MEMSET**
> The memset use appears to be incorrect. This may be caused due to
> badly ordered parameters. Please recheck the usage.
>
> + .. _not-unified-diff:
> +
> **NOT_UNIFIED_DIFF**
> The patch file does not appear to be in unified-diff format. Please
> regenerate the patch file before sending it to the maintainer.
> @@ -1245,6 +1457,8 @@ Others
> **PRINTF_0XDECIMAL**
> Prefixing 0x with decimal output is defective and should be corrected.
>
> + .. _spdx-license-tag:
> +
> **SPDX_LICENSE_TAG**
> The source file is missing or has an improper SPDX identifier tag.
> The Linux kernel requires the precise SPDX identifier in all source files,
> @@ -1252,5 +1466,7 @@ Others
>
> See: https://www.kernel.org/doc/html/latest/process/license-rules.html
>
> + .. _typo-spelling:
> +
> **TYPO_SPELLING**
> Some words may have been misspelled. Consider reviewing them.
--
Jani Nikula, Intel
On Mon, May 13, 2024 at 1:18 PM Jani Nikula <[email protected]> wrote:
>
> On Mon, 13 May 2024, Diederik de Haas <[email protected]> wrote:
> > Make the tags directly linkable by defining targets for them.
> >
> > Closes: https://lore.kernel.org/r/8090211.0vHzs8tI1a@bagend/
> > Signed-off-by: Diederik de Haas <[email protected]>
> > ---
> > Documentation/dev-tools/checkpatch.rst | 216 +++++++++++++++++++++++++
> > 1 file changed, 216 insertions(+)
> >
> > diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> > index 127968995847..6499e29c3a19 100644
> > --- a/Documentation/dev-tools/checkpatch.rst
> > +++ b/Documentation/dev-tools/checkpatch.rst
> > @@ -242,6 +242,8 @@ This section contains a description of all the message types in checkpatch.
> > Allocation style
> > ----------------
> >
> > + .. _alloc-array-args:
> > +
> > **ALLOC_ARRAY_ARGS**
>
> Alternatively, you could just convert the definition lists into section
> titles to make them implicit hyperlink targets. The rst stays cleaner
> and there's no manual updating.
>
Agree with Jani. It is important to check that the verbose option of
the checkpatch still works. The script actually parses the
documentation and then shows the relevant parts as verbose output to
the user. It currently relies on the specific format, but it is not
difficult to change that to use a different pattern, see sub load_docs
in checkpatch.pl.
So, please make sure the current --verbose option in checkpatch.pl
does not break.
Thanks,
Lukas
On Mon, 13 May 2024 14:18:28 +0300, Jani Nikula wrote:
> On Mon, 13 May 2024, Diederik de Haas <[email protected]> wrote:
>> Make the tags directly linkable by defining targets for them.
>>
>> Closes: https://lore.kernel.org/r/8090211.0vHzs8tI1a@bagend/
>> Signed-off-by: Diederik de Haas <[email protected]>
>> ---
>> Documentation/dev-tools/checkpatch.rst | 216 +++++++++++++++++++++++++
>> 1 file changed, 216 insertions(+)
>>
>> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
>> index 127968995847..6499e29c3a19 100644
>> --- a/Documentation/dev-tools/checkpatch.rst
>> +++ b/Documentation/dev-tools/checkpatch.rst
>> @@ -242,6 +242,8 @@ This section contains a description of all the message types in checkpatch.
>> Allocation style
>> ----------------
>>
>> + .. _alloc-array-args:
>> +
>> **ALLOC_ARRAY_ARGS**
>
> Alternatively, you could just convert the definition lists into section
> titles to make them implicit hyperlink targets. The rst stays cleaner
> and there's no manual updating.
>
+1
I misread Diederik's intention and thought he wanted that single target
he mentioned in the other thread.
I believe Jani's suggestion is the right way going forward.
Thanks, Akira
> BR,
> Jani.
[snip]
Diederik de Haas <[email protected]> writes:
> Make the tags directly linkable by defining targets for them.
>
> Closes: https://lore.kernel.org/r/8090211.0vHzs8tI1a@bagend/
> Signed-off-by: Diederik de Haas <[email protected]>
> ---
> Documentation/dev-tools/checkpatch.rst | 216 +++++++++++++++++++++++++
> 1 file changed, 216 insertions(+)
In addition to the other comments, I have to add: you have said what you
are doing but not *why*. All of these labels clutter up the text; what
use will be made of them to justify that?
Thanks,
jon
On Monday, 13 May 2024 13:46:39 CEST Lukas Bulwahn wrote:
> On Mon, May 13, 2024 at 1:18 PM Jani Nikula <[email protected]>
wrote:
> > On Mon, 13 May 2024, Diederik de Haas <[email protected]> wrote:
> > > Make the tags directly linkable by defining targets for them.
> > >
> > > Closes: https://lore.kernel.org/r/8090211.0vHzs8tI1a@bagend/
> > > Signed-off-by: Diederik de Haas <[email protected]>
> > > ---
> > >
> > > Documentation/dev-tools/checkpatch.rst | 216 +++++++++++++++++++++++++
> > > 1 file changed, 216 insertions(+)
> > >
> > > diff --git a/Documentation/dev-tools/checkpatch.rst
> > > b/Documentation/dev-tools/checkpatch.rst index
> > > 127968995847..6499e29c3a19 100644
> > > --- a/Documentation/dev-tools/checkpatch.rst
> > > +++ b/Documentation/dev-tools/checkpatch.rst
> > > @@ -242,6 +242,8 @@ This section contains a description of all the
> > > message types in checkpatch.> >
> > > Allocation style
> > > ----------------
> > >
> > > + .. _alloc-array-args:
> > > +
> > >
> > > **ALLOC_ARRAY_ARGS**
> >
> > Alternatively, you could just convert the definition lists into section
> > titles to make them implicit hyperlink targets. The rst stays cleaner
> > and there's no manual updating.
Yeah, makes sense.
Indented boldface letters (as it is now), stands out visually much more then
an ``<h4>`` header (tried it with "^ for subsubsections").
Is being able to use URLs/Links like this:
https://docs.kernel.org/dev-tools/checkpatch.html#BAD_FIXES_TAG
considered worth the (visual) trade-off?
> Agree with Jani. It is important to check that the verbose option of
> the checkpatch still works. The script actually parses the
> documentation and then shows the relevant parts as verbose output to
> the user. It currently relies on the specific format, but it is not
> difficult to change that to use a different pattern, see sub load_docs
> in checkpatch.pl.
>
> So, please make sure the current --verbose option in checkpatch.pl
> does not break.
It's a bit more challenging for me being (mostly) clueless about Perl.
Cheers,
Diederik
On Monday, 13 May 2024 13:46:39 CEST Lukas Bulwahn wrote:
> It is important to check that the verbose option of
> the checkpatch still works. The script actually parses the
> documentation and then shows the relevant parts as verbose output to
> the user.
I wasn't aware of that functionality as I've mostly used ``--terse``.
What I want(ed) is having the documentation for a tag easily accessible.
But it doesn't get much better then it already being part of the tool.
IOW: Please disregard this patch.
Cheers,
Diederik