Commit | Line | Data |
---|---|---|
2eecbab8 DR |
1 | .. SPDX-License-Identifier: GPL-2.0-only |
2 | ||
3 | ========== | |
4 | Checkpatch | |
5 | ========== | |
6 | ||
7 | Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial | |
8 | style violations in patches and optionally corrects them. Checkpatch can | |
9 | also be run on file contexts and without the kernel tree. | |
10 | ||
11 | Checkpatch is not always right. Your judgement takes precedence over checkpatch | |
12 | messages. If your code looks better with the violations, then its probably | |
13 | best left alone. | |
14 | ||
15 | ||
16 | Options | |
17 | ======= | |
18 | ||
19 | This section will describe the options checkpatch can be run with. | |
20 | ||
21 | Usage:: | |
22 | ||
23 | ./scripts/checkpatch.pl [OPTION]... [FILE]... | |
24 | ||
25 | Available options: | |
26 | ||
27 | - -q, --quiet | |
28 | ||
29 | Enable quiet mode. | |
30 | ||
31 | - -v, --verbose | |
32 | Enable verbose mode. Additional verbose test descriptions are output | |
33 | so as to provide information on why that particular message is shown. | |
34 | ||
35 | - --no-tree | |
36 | ||
37 | Run checkpatch without the kernel tree. | |
38 | ||
39 | - --no-signoff | |
40 | ||
41 | Disable the 'Signed-off-by' line check. The sign-off is a simple line at | |
42 | the end of the explanation for the patch, which certifies that you wrote it | |
43 | or otherwise have the right to pass it on as an open-source patch. | |
44 | ||
45 | Example:: | |
46 | ||
47 | Signed-off-by: Random J Developer <random@developer.example.org> | |
48 | ||
49 | Setting this flag effectively stops a message for a missing signed-off-by | |
50 | line in a patch context. | |
51 | ||
52 | - --patch | |
53 | ||
54 | Treat FILE as a patch. This is the default option and need not be | |
55 | explicitly specified. | |
56 | ||
57 | - --emacs | |
58 | ||
59 | Set output to emacs compile window format. This allows emacs users to jump | |
60 | from the error in the compile window directly to the offending line in the | |
61 | patch. | |
62 | ||
63 | - --terse | |
64 | ||
65 | Output only one line per report. | |
66 | ||
67 | - --showfile | |
68 | ||
69 | Show the diffed file position instead of the input file position. | |
70 | ||
71 | - -g, --git | |
72 | ||
73 | Treat FILE as a single commit or a git revision range. | |
74 | ||
75 | Single commit with: | |
76 | ||
77 | - <rev> | |
78 | - <rev>^ | |
79 | - <rev>~n | |
80 | ||
81 | Multiple commits with: | |
82 | ||
83 | - <rev1>..<rev2> | |
84 | - <rev1>...<rev2> | |
85 | - <rev>-<count> | |
86 | ||
87 | - -f, --file | |
88 | ||
89 | Treat FILE as a regular source file. This option must be used when running | |
90 | checkpatch on source files in the kernel. | |
91 | ||
92 | - --subjective, --strict | |
93 | ||
94 | Enable stricter tests in checkpatch. By default the tests emitted as CHECK | |
95 | do not activate by default. Use this flag to activate the CHECK tests. | |
96 | ||
97 | - --list-types | |
98 | ||
99 | Every message emitted by checkpatch has an associated TYPE. Add this flag | |
100 | to display all the types in checkpatch. | |
101 | ||
102 | Note that when this flag is active, checkpatch does not read the input FILE, | |
103 | and no message is emitted. Only a list of types in checkpatch is output. | |
104 | ||
105 | - --types TYPE(,TYPE2...) | |
106 | ||
107 | Only display messages with the given types. | |
108 | ||
109 | Example:: | |
110 | ||
111 | ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES | |
112 | ||
113 | - --ignore TYPE(,TYPE2...) | |
114 | ||
115 | Checkpatch will not emit messages for the specified types. | |
116 | ||
117 | Example:: | |
118 | ||
119 | ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES | |
120 | ||
121 | - --show-types | |
122 | ||
123 | By default checkpatch doesn't display the type associated with the messages. | |
124 | Set this flag to show the message type in the output. | |
125 | ||
126 | - --max-line-length=n | |
127 | ||
128 | Set the max line length (default 100). If a line exceeds the specified | |
129 | length, a LONG_LINE message is emitted. | |
130 | ||
131 | ||
132 | The message level is different for patch and file contexts. For patches, | |
133 | a WARNING is emitted. While a milder CHECK is emitted for files. So for | |
134 | file contexts, the --strict flag must also be enabled. | |
135 | ||
136 | - --min-conf-desc-length=n | |
137 | ||
138 | Set the Kconfig entry minimum description length, if shorter, warn. | |
139 | ||
140 | - --tab-size=n | |
141 | ||
142 | Set the number of spaces for tab (default 8). | |
143 | ||
144 | - --root=PATH | |
145 | ||
146 | PATH to the kernel tree root. | |
147 | ||
148 | This option must be specified when invoking checkpatch from outside | |
149 | the kernel root. | |
150 | ||
151 | - --no-summary | |
152 | ||
153 | Suppress the per file summary. | |
154 | ||
155 | - --mailback | |
156 | ||
157 | Only produce a report in case of Warnings or Errors. Milder Checks are | |
158 | excluded from this. | |
159 | ||
160 | - --summary-file | |
161 | ||
162 | Include the filename in summary. | |
163 | ||
164 | - --debug KEY=[0|1] | |
165 | ||
166 | Turn on/off debugging of KEY, where KEY is one of 'values', 'possible', | |
167 | 'type', and 'attr' (default is all off). | |
168 | ||
169 | - --fix | |
170 | ||
171 | This is an EXPERIMENTAL feature. If correctable errors exists, a file | |
172 | <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the | |
173 | automatically fixable errors corrected. | |
174 | ||
175 | - --fix-inplace | |
176 | ||
177 | EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes. | |
178 | ||
179 | DO NOT USE this flag unless you are absolutely sure and you have a backup | |
180 | in place. | |
181 | ||
182 | - --ignore-perl-version | |
183 | ||
184 | Override checking of perl version. Runtime errors maybe encountered after | |
185 | enabling this flag if the perl version does not meet the minimum specified. | |
186 | ||
187 | - --codespell | |
188 | ||
189 | Use the codespell dictionary for checking spelling errors. | |
190 | ||
191 | - --codespellfile | |
192 | ||
193 | Use the specified codespell file. | |
194 | Default is '/usr/share/codespell/dictionary.txt'. | |
195 | ||
196 | - --typedefsfile | |
197 | ||
198 | Read additional types from this file. | |
199 | ||
200 | - --color[=WHEN] | |
201 | ||
202 | Use colors 'always', 'never', or only when output is a terminal ('auto'). | |
203 | Default is 'auto'. | |
204 | ||
205 | - --kconfig-prefix=WORD | |
206 | ||
207 | Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`). | |
208 | ||
209 | - -h, --help, --version | |
210 | ||
211 | Display the help text. | |
212 | ||
213 | Message Levels | |
214 | ============== | |
215 | ||
216 | Messages in checkpatch are divided into three levels. The levels of messages | |
217 | in checkpatch denote the severity of the error. They are: | |
218 | ||
219 | - ERROR | |
220 | ||
221 | This is the most strict level. Messages of type ERROR must be taken | |
222 | seriously as they denote things that are very likely to be wrong. | |
223 | ||
224 | - WARNING | |
225 | ||
226 | This is the next stricter level. Messages of type WARNING requires a | |
227 | more careful review. But it is milder than an ERROR. | |
228 | ||
229 | - CHECK | |
230 | ||
231 | This is the mildest level. These are things which may require some thought. | |
232 | ||
233 | Type Descriptions | |
234 | ================= | |
235 | ||
236 | This section contains a description of all the message types in checkpatch. | |
237 | ||
238 | .. Types in this section are also parsed by checkpatch. | |
239 | .. The types are grouped into subsections based on use. | |
240 | ||
241 | ||
242 | Allocation style | |
243 | ---------------- | |
244 | ||
245 | **ALLOC_ARRAY_ARGS** | |
246 | The first argument for kcalloc or kmalloc_array should be the | |
247 | number of elements. sizeof() as the first argument is generally | |
248 | wrong. | |
249 | See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html | |
250 | ||
251 | **ALLOC_SIZEOF_STRUCT** | |
252 | The allocation style is bad. In general for family of | |
253 | allocation functions using sizeof() to get memory size, | |
254 | constructs like:: | |
255 | ||
256 | p = alloc(sizeof(struct foo), ...) | |
257 | ||
258 | should be:: | |
259 | ||
260 | p = alloc(sizeof(*p), ...) | |
261 | ||
262 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory | |
263 | ||
264 | **ALLOC_WITH_MULTIPLY** | |
265 | Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a | |
266 | sizeof multiply. | |
267 | See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html | |
268 | ||
269 | ||
270 | API usage | |
271 | --------- | |
272 | ||
273 | **ARCH_DEFINES** | |
274 | Architecture specific defines should be avoided wherever | |
275 | possible. | |
276 | ||
277 | **ARCH_INCLUDE_LINUX** | |
278 | Whenever asm/file.h is included and linux/file.h exists, a | |
279 | conversion can be made when linux/file.h includes asm/file.h. | |
280 | However this is not always the case (See signal.h). | |
281 | This message type is emitted only for includes from arch/. | |
282 | ||
283 | **ARRAY_SIZE** | |
284 | The ARRAY_SIZE(foo) macro should be preferred over | |
285 | sizeof(foo)/sizeof(foo[0]) for finding number of elements in an | |
286 | array. | |
287 | ||
288 | The macro is defined in include/linux/kernel.h:: | |
289 | ||
290 | #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) | |
291 | ||
292 | **AVOID_BUG** | |
293 | BUG() or BUG_ON() should be avoided totally. | |
294 | Use WARN() and WARN_ON() instead, and handle the "impossible" | |
295 | error condition as gracefully as possible. | |
296 | See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on | |
297 | ||
298 | **AVOID_EXTERNS** | |
299 | Function prototypes don't need to be declared extern in .h | |
300 | files. It's assumed by the compiler and is unnecessary. | |
301 | ||
302 | **AVOID_L_PREFIX** | |
303 | Local symbol names that are prefixed with `.L` should be avoided, | |
304 | as this has special meaning for the assembler; a symbol entry will | |
305 | not be emitted into the symbol table. This can prevent `objtool` | |
306 | from generating correct unwind info. | |
307 | ||
308 | Symbols with STB_LOCAL binding may still be used, and `.L` prefixed | |
309 | local symbol names are still generally usable within a function, | |
310 | but `.L` prefixed local symbol names should not be used to denote | |
311 | the beginning or end of code regions via | |
312 | `SYM_CODE_START_LOCAL`/`SYM_CODE_END` | |
313 | ||
314 | **BIT_MACRO** | |
315 | Defines like: 1 << <digit> could be BIT(digit). | |
316 | The BIT() macro is defined in include/linux/bitops.h:: | |
317 | ||
318 | #define BIT(nr) (1UL << (nr)) | |
319 | ||
320 | **CONSIDER_KSTRTO** | |
321 | The simple_strtol(), simple_strtoll(), simple_strtoul(), and | |
322 | simple_strtoull() functions explicitly ignore overflows, which | |
323 | may lead to unexpected results in callers. The respective kstrtol(), | |
324 | kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the | |
325 | correct replacements. | |
326 | See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull | |
327 | ||
328 | ||
329 | Comment style | |
330 | ------------- | |
331 | ||
332 | **BLOCK_COMMENT_STYLE** | |
333 | The comment style is incorrect. The preferred style for multi- | |
334 | line comments is:: | |
335 | ||
336 | /* | |
337 | * This is the preferred style | |
338 | * for multi line comments. | |
339 | */ | |
340 | ||
341 | The networking comment style is a bit different, with the first line | |
342 | not empty like the former:: | |
343 | ||
344 | /* This is the preferred comment style | |
345 | * for files in net/ and drivers/net/ | |
346 | */ | |
347 | ||
348 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting | |
349 | ||
350 | **C99_COMMENTS** | |
351 | C99 style single line comments (//) should not be used. | |
352 | Prefer the block comment style instead. | |
353 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting | |
354 | ||
355 | ||
356 | ||
357 | Commit message | |
358 | -------------- | |
359 | ||
360 | **BAD_SIGN_OFF** | |
361 | The signed-off-by line does not fall in line with the standards | |
362 | specified by the community. | |
363 | See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1 | |
364 | ||
365 | **BAD_STABLE_ADDRESS_STYLE** | |
366 | The email format for stable is incorrect. | |
367 | Some valid options for stable address are:: | |
368 | ||
369 | 1. stable@vger.kernel.org | |
370 | 2. stable@kernel.org | |
371 | ||
372 | For adding version info, the following comment style should be used:: | |
373 | ||
374 | stable@vger.kernel.org # version info | |
375 | ||
376 | **COMMIT_COMMENT_SYMBOL** | |
377 | Commit log lines starting with a '#' are ignored by git as | |
378 | comments. To solve this problem addition of a single space | |
379 | infront of the log line is enough. | |
380 | ||
381 | **COMMIT_MESSAGE** | |
382 | The patch is missing a commit description. A brief | |
383 | description of the changes made by the patch should be added. | |
384 | See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes | |
385 | ||
386 | **MISSING_SIGN_OFF** | |
387 | The patch is missing a Signed-off-by line. A signed-off-by | |
388 | line should be added according to Developer's certificate of | |
389 | Origin. | |
390 | See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin | |
391 | ||
392 | **NO_AUTHOR_SIGN_OFF** | |
393 | The author of the patch has not signed off the patch. It is | |
394 | required that a simple sign off line should be present at the | |
395 | end of explanation of the patch to denote that the author has | |
396 | written it or otherwise has the rights to pass it on as an open | |
397 | source patch. | |
398 | See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin | |
399 | ||
400 | ||
401 | Comparison style | |
402 | ---------------- | |
403 | ||
404 | **ASSIGN_IN_IF** | |
405 | Do not use assignments in if condition. | |
406 | Example:: | |
407 | ||
408 | if ((foo = bar(...)) < BAZ) { | |
409 | ||
410 | should be written as:: | |
411 | ||
412 | foo = bar(...); | |
413 | if (foo < BAZ) { | |
414 | ||
415 | **BOOL_COMPARISON** | |
416 | Comparisons of A to true and false are better written | |
417 | as A and !A. | |
418 | See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/ | |
419 | ||
420 | **COMPARISON_TO_NULL** | |
421 | Comparisons to NULL in the form (foo == NULL) or (foo != NULL) | |
422 | are better written as (!foo) and (foo). | |
423 | ||
424 | **CONSTANT_COMPARISON** | |
425 | Comparisons with a constant or upper case identifier on the left | |
426 | side of the test should be avoided. | |
427 | ||
428 | ||
429 | Spacing and Brackets | |
430 | -------------------- | |
431 | ||
432 | **ASSIGNMENT_CONTINUATIONS** | |
433 | Assignment operators should not be written at the start of a | |
434 | line but should follow the operand at the previous line. | |
435 | ||
436 | **BRACES** | |
437 | The placement of braces is stylistically incorrect. | |
438 | The preferred way is to put the opening brace last on the line, | |
439 | and put the closing brace first:: | |
440 | ||
441 | if (x is true) { | |
442 | we do y | |
443 | } | |
444 | ||
445 | This applies for all non-functional blocks. | |
446 | However, there is one special case, namely functions: they have the | |
447 | opening brace at the beginning of the next line, thus:: | |
448 | ||
449 | int function(int x) | |
450 | { | |
451 | body of function | |
452 | } | |
453 | ||
454 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces | |
455 | ||
456 | **BRACKET_SPACE** | |
457 | Whitespace before opening bracket '[' is prohibited. | |
458 | There are some exceptions: | |
459 | ||
460 | 1. With a type on the left:: | |
461 | ||
462 | ;int [] a; | |
463 | ||
464 | 2. At the beginning of a line for slice initialisers:: | |
465 | ||
466 | [0...10] = 5, | |
467 | ||
468 | 3. Inside a curly brace:: | |
469 | ||
470 | = { [0...10] = 5 } | |
471 | ||
472 | **CODE_INDENT** | |
473 | Code indent should use tabs instead of spaces. | |
474 | Outside of comments, documentation and Kconfig, | |
475 | spaces are never used for indentation. | |
476 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation | |
477 | ||
478 | **CONCATENATED_STRING** | |
479 | Concatenated elements should have a space in between. | |
480 | Example:: | |
481 | ||
482 | printk(KERN_INFO"bar"); | |
483 | ||
484 | should be:: | |
485 | ||
486 | printk(KERN_INFO "bar"); | |
487 | ||
488 | **LINE_SPACING** | |
489 | Vertical space is wasted given the limited number of lines an | |
490 | editor window can display when multiple blank lines are used. | |
491 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces | |
492 | ||
493 | **SPACING** | |
494 | Whitespace style used in the kernel sources is described in kernel docs. | |
495 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces | |
496 | ||
497 | **TRAILING_WHITESPACE** | |
498 | Trailing whitespace should always be removed. | |
499 | Some editors highlight the trailing whitespace and cause visual | |
500 | distractions when editing files. | |
501 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces | |
502 | ||
503 | ||
504 | Others | |
505 | ------ | |
506 | ||
507 | **CAMELCASE** | |
508 | Avoid CamelCase Identifiers. | |
509 | See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming | |
510 | ||
511 | **CONFIG_DESCRIPTION** | |
512 | Kconfig symbols should have a help text which fully describes | |
513 | it. |