Commit | Line | Data |
---|---|---|
609d99a3 MCC |
1 | .. _codingstyle: |
2 | ||
d8dbbbc5 MCC |
3 | Linux kernel coding style |
4 | ========================= | |
1da177e4 LT |
5 | |
6 | This is a short document describing the preferred coding style for the | |
5d628b45 | 7 | linux kernel. Coding style is very personal, and I won't **force** my |
1da177e4 LT |
8 | views on anybody, but this is what goes for anything that I have to be |
9 | able to maintain, and I'd prefer it for most other things too. Please | |
10 | at least consider the points made here. | |
11 | ||
12 | First off, I'd suggest printing out a copy of the GNU coding standards, | |
13 | and NOT read it. Burn them, it's a great symbolic gesture. | |
14 | ||
15 | Anyway, here goes: | |
16 | ||
17 | ||
d8dbbbc5 MCC |
18 | 1) Indentation |
19 | -------------- | |
1da177e4 LT |
20 | |
21 | Tabs are 8 characters, and thus indentations are also 8 characters. | |
22 | There are heretic movements that try to make indentations 4 (or even 2!) | |
23 | characters deep, and that is akin to trying to define the value of PI to | |
24 | be 3. | |
25 | ||
26 | Rationale: The whole idea behind indentation is to clearly define where | |
27 | a block of control starts and ends. Especially when you've been looking | |
28 | at your screen for 20 straight hours, you'll find it a lot easier to see | |
29 | how the indentation works if you have large indentations. | |
30 | ||
31 | Now, some people will claim that having 8-character indentations makes | |
32 | the code move too far to the right, and makes it hard to read on a | |
33 | 80-character terminal screen. The answer to that is that if you need | |
34 | more than 3 levels of indentation, you're screwed anyway, and should fix | |
35 | your program. | |
36 | ||
37 | In short, 8-char indents make things easier to read, and have the added | |
38 | benefit of warning you when you're nesting your functions too deep. | |
39 | Heed that warning. | |
40 | ||
b3fc9941 | 41 | The preferred way to ease multiple indentation levels in a switch statement is |
b1a3459b MCC |
42 | to align the ``switch`` and its subordinate ``case`` labels in the same column |
43 | instead of ``double-indenting`` the ``case`` labels. E.g.: | |
b3fc9941 | 44 | |
d8dbbbc5 MCC |
45 | .. code-block:: c |
46 | ||
b3fc9941 RD |
47 | switch (suffix) { |
48 | case 'G': | |
49 | case 'g': | |
50 | mem <<= 30; | |
51 | break; | |
52 | case 'M': | |
53 | case 'm': | |
54 | mem <<= 20; | |
55 | break; | |
56 | case 'K': | |
57 | case 'k': | |
58 | mem <<= 10; | |
b9918bdc | 59 | fallthrough; |
b3fc9941 RD |
60 | default: |
61 | break; | |
62 | } | |
63 | ||
1da177e4 LT |
64 | Don't put multiple statements on a single line unless you have |
65 | something to hide: | |
66 | ||
d8dbbbc5 MCC |
67 | .. code-block:: c |
68 | ||
1da177e4 LT |
69 | if (condition) do_this; |
70 | do_something_everytime; | |
71 | ||
26606ce0 JP |
72 | Don't use commas to avoid using braces: |
73 | ||
74 | .. code-block:: c | |
75 | ||
76 | if (condition) | |
77 | do_this(), do_that(); | |
78 | ||
79 | Always uses braces for multiple statements: | |
80 | ||
81 | .. code-block:: c | |
82 | ||
83 | if (condition) { | |
84 | do_this(); | |
85 | do_that(); | |
86 | } | |
87 | ||
b3fc9941 RD |
88 | Don't put multiple assignments on a single line either. Kernel coding style |
89 | is super simple. Avoid tricky expressions. | |
90 | ||
26606ce0 | 91 | |
1da177e4 LT |
92 | Outside of comments, documentation and except in Kconfig, spaces are never |
93 | used for indentation, and the above example is deliberately broken. | |
94 | ||
95 | Get a decent editor and don't leave whitespace at the end of lines. | |
96 | ||
97 | ||
d8dbbbc5 MCC |
98 | 2) Breaking long lines and strings |
99 | ---------------------------------- | |
1da177e4 LT |
100 | |
101 | Coding style is all about readability and maintainability using commonly | |
102 | available tools. | |
103 | ||
bdc48fa1 JP |
104 | The preferred limit on the length of a single line is 80 columns. |
105 | ||
106 | Statements longer than 80 columns should be broken into sensible chunks, | |
107 | unless exceeding 80 columns significantly increases readability and does | |
108 | not hide information. | |
109 | ||
77d22a43 | 110 | Descendants are always substantially shorter than the parent and |
bdc48fa1 JP |
111 | are placed substantially to the right. A very commonly used style |
112 | is to align descendants to a function open parenthesis. | |
113 | ||
114 | These same rules are applied to function headers with a long argument list. | |
115 | ||
116 | However, never break user-visible strings such as printk messages because | |
117 | that breaks the ability to grep for them. | |
6f76b6fc | 118 | |
1da177e4 | 119 | |
d8dbbbc5 MCC |
120 | 3) Placing Braces and Spaces |
121 | ---------------------------- | |
1da177e4 LT |
122 | |
123 | The other issue that always comes up in C styling is the placement of | |
124 | braces. Unlike the indent size, there are few technical reasons to | |
125 | choose one placement strategy over the other, but the preferred way, as | |
126 | shown to us by the prophets Kernighan and Ritchie, is to put the opening | |
127 | brace last on the line, and put the closing brace first, thusly: | |
128 | ||
d8dbbbc5 MCC |
129 | .. code-block:: c |
130 | ||
1da177e4 LT |
131 | if (x is true) { |
132 | we do y | |
133 | } | |
134 | ||
b3fc9941 RD |
135 | This applies to all non-function statement blocks (if, switch, for, |
136 | while, do). E.g.: | |
137 | ||
d8dbbbc5 MCC |
138 | .. code-block:: c |
139 | ||
b3fc9941 RD |
140 | switch (action) { |
141 | case KOBJ_ADD: | |
142 | return "add"; | |
143 | case KOBJ_REMOVE: | |
144 | return "remove"; | |
145 | case KOBJ_CHANGE: | |
146 | return "change"; | |
147 | default: | |
148 | return NULL; | |
149 | } | |
150 | ||
1da177e4 LT |
151 | However, there is one special case, namely functions: they have the |
152 | opening brace at the beginning of the next line, thus: | |
153 | ||
d8dbbbc5 MCC |
154 | .. code-block:: c |
155 | ||
1da177e4 LT |
156 | int function(int x) |
157 | { | |
158 | body of function | |
159 | } | |
160 | ||
161 | Heretic people all over the world have claimed that this inconsistency | |
162 | is ... well ... inconsistent, but all right-thinking people know that | |
5d628b45 | 163 | (a) K&R are **right** and (b) K&R are right. Besides, functions are |
1da177e4 LT |
164 | special anyway (you can't nest them in C). |
165 | ||
5d628b45 | 166 | Note that the closing brace is empty on a line of its own, **except** in |
1da177e4 | 167 | the cases where it is followed by a continuation of the same statement, |
b1a3459b | 168 | ie a ``while`` in a do-statement or an ``else`` in an if-statement, like |
1da177e4 LT |
169 | this: |
170 | ||
d8dbbbc5 MCC |
171 | .. code-block:: c |
172 | ||
1da177e4 LT |
173 | do { |
174 | body of do-loop | |
175 | } while (condition); | |
176 | ||
177 | and | |
178 | ||
d8dbbbc5 MCC |
179 | .. code-block:: c |
180 | ||
1da177e4 LT |
181 | if (x == y) { |
182 | .. | |
183 | } else if (x > y) { | |
184 | ... | |
185 | } else { | |
186 | .... | |
187 | } | |
188 | ||
189 | Rationale: K&R. | |
190 | ||
191 | Also, note that this brace-placement also minimizes the number of empty | |
192 | (or almost empty) lines, without any loss of readability. Thus, as the | |
193 | supply of new-lines on your screen is not a renewable resource (think | |
194 | 25-line terminal screens here), you have more empty lines to put | |
195 | comments on. | |
196 | ||
e659ba4a ON |
197 | Do not unnecessarily use braces where a single statement will do. |
198 | ||
d8dbbbc5 MCC |
199 | .. code-block:: c |
200 | ||
09677e0f PK |
201 | if (condition) |
202 | action(); | |
e659ba4a | 203 | |
38829dc9 HW |
204 | and |
205 | ||
d8dbbbc5 MCC |
206 | .. code-block:: none |
207 | ||
09677e0f PK |
208 | if (condition) |
209 | do_this(); | |
210 | else | |
211 | do_that(); | |
38829dc9 | 212 | |
b218ab0a AO |
213 | This does not apply if only one branch of a conditional statement is a single |
214 | statement; in the latter case use braces in both branches: | |
e659ba4a | 215 | |
d8dbbbc5 MCC |
216 | .. code-block:: c |
217 | ||
09677e0f PK |
218 | if (condition) { |
219 | do_this(); | |
220 | do_that(); | |
221 | } else { | |
222 | otherwise(); | |
223 | } | |
e659ba4a | 224 | |
1dbba2cf GH |
225 | Also, use braces when a loop contains more than a single simple statement: |
226 | ||
227 | .. code-block:: c | |
228 | ||
229 | while (condition) { | |
230 | if (test) | |
231 | do_something(); | |
232 | } | |
233 | ||
d8dbbbc5 MCC |
234 | 3.1) Spaces |
235 | *********** | |
b3fc9941 RD |
236 | |
237 | Linux kernel style for use of spaces depends (mostly) on | |
238 | function-versus-keyword usage. Use a space after (most) keywords. The | |
239 | notable exceptions are sizeof, typeof, alignof, and __attribute__, which look | |
240 | somewhat like functions (and are usually used with parentheses in Linux, | |
d8dbbbc5 MCC |
241 | although they are not required in the language, as in: ``sizeof info`` after |
242 | ``struct fileinfo info;`` is declared). | |
b3fc9941 | 243 | |
d8dbbbc5 | 244 | So use a space after these keywords:: |
09677e0f | 245 | |
b3fc9941 | 246 | if, switch, case, for, do, while |
09677e0f | 247 | |
b3fc9941 | 248 | but not with sizeof, typeof, alignof, or __attribute__. E.g., |
09677e0f | 249 | |
d8dbbbc5 MCC |
250 | .. code-block:: c |
251 | ||
252 | ||
b3fc9941 RD |
253 | s = sizeof(struct file); |
254 | ||
255 | Do not add spaces around (inside) parenthesized expressions. This example is | |
d8dbbbc5 MCC |
256 | **bad**: |
257 | ||
258 | .. code-block:: c | |
259 | ||
b3fc9941 RD |
260 | |
261 | s = sizeof( struct file ); | |
262 | ||
263 | When declaring pointer data or a function that returns a pointer type, the | |
b1a3459b | 264 | preferred use of ``*`` is adjacent to the data name or function name and not |
b3fc9941 RD |
265 | adjacent to the type name. Examples: |
266 | ||
d8dbbbc5 MCC |
267 | .. code-block:: c |
268 | ||
269 | ||
b3fc9941 RD |
270 | char *linux_banner; |
271 | unsigned long long memparse(char *ptr, char **retptr); | |
272 | char *match_strdup(substring_t *s); | |
273 | ||
274 | Use one space around (on each side of) most binary and ternary operators, | |
d8dbbbc5 | 275 | such as any of these:: |
b3fc9941 RD |
276 | |
277 | = + - < > * / % | & ^ <= >= == != ? : | |
278 | ||
d8dbbbc5 | 279 | but no space after unary operators:: |
09677e0f | 280 | |
b3fc9941 RD |
281 | & * + - ~ ! sizeof typeof alignof __attribute__ defined |
282 | ||
d8dbbbc5 | 283 | no space before the postfix increment & decrement unary operators:: |
09677e0f | 284 | |
b3fc9941 RD |
285 | ++ -- |
286 | ||
d8dbbbc5 | 287 | no space after the prefix increment & decrement unary operators:: |
09677e0f | 288 | |
b3fc9941 RD |
289 | ++ -- |
290 | ||
b1a3459b | 291 | and no space around the ``.`` and ``->`` structure member operators. |
b3fc9941 | 292 | |
a923fd6a | 293 | Do not leave trailing whitespace at the ends of lines. Some editors with |
b1a3459b | 294 | ``smart`` indentation will insert whitespace at the beginning of new lines as |
a923fd6a JT |
295 | appropriate, so you can start typing the next line of code right away. |
296 | However, some such editors do not remove the whitespace if you end up not | |
297 | putting a line of code there, such as if you leave a blank line. As a result, | |
298 | you end up with lines containing trailing whitespace. | |
299 | ||
300 | Git will warn you about patches that introduce trailing whitespace, and can | |
301 | optionally strip the trailing whitespace for you; however, if applying a series | |
302 | of patches, this may make later patches in the series fail by changing their | |
303 | context lines. | |
304 | ||
1da177e4 | 305 | |
d8dbbbc5 MCC |
306 | 4) Naming |
307 | --------- | |
1da177e4 | 308 | |
fb0e0ffe TF |
309 | C is a Spartan language, and your naming conventions should follow suit. |
310 | Unlike Modula-2 and Pascal programmers, C programmers do not use cute | |
311 | names like ThisVariableIsATemporaryCounter. A C programmer would call that | |
b1a3459b | 312 | variable ``tmp``, which is much easier to write, and not the least more |
1da177e4 LT |
313 | difficult to understand. |
314 | ||
315 | HOWEVER, while mixed-case names are frowned upon, descriptive names for | |
b1a3459b | 316 | global variables are a must. To call a global function ``foo`` is a |
1da177e4 LT |
317 | shooting offense. |
318 | ||
5d628b45 | 319 | GLOBAL variables (to be used only if you **really** need them) need to |
1da177e4 LT |
320 | have descriptive names, as do global functions. If you have a function |
321 | that counts the number of active users, you should call that | |
5d628b45 | 322 | ``count_active_users()`` or similar, you should **not** call it ``cntusr()``. |
1da177e4 LT |
323 | |
324 | Encoding the type of a function into the name (so-called Hungarian | |
fb0e0ffe | 325 | notation) is asinine - the compiler knows the types anyway and can check |
b7592e5b | 326 | those, and it only confuses the programmer. |
1da177e4 LT |
327 | |
328 | LOCAL variable names should be short, and to the point. If you have | |
b1a3459b MCC |
329 | some random integer loop counter, it should probably be called ``i``. |
330 | Calling it ``loop_counter`` is non-productive, if there is no chance of it | |
331 | being mis-understood. Similarly, ``tmp`` can be just about any type of | |
1da177e4 LT |
332 | variable that is used to hold a temporary value. |
333 | ||
334 | If you are afraid to mix up your local variable names, you have another | |
335 | problem, which is called the function-growth-hormone-imbalance syndrome. | |
b3fc9941 | 336 | See chapter 6 (Functions). |
1da177e4 | 337 | |
a5f526ec DW |
338 | For symbol names and documentation, avoid introducing new usage of |
339 | 'master / slave' (or 'slave' independent of 'master') and 'blacklist / | |
340 | whitelist'. | |
341 | ||
342 | Recommended replacements for 'master / slave' are: | |
343 | '{primary,main} / {secondary,replica,subordinate}' | |
344 | '{initiator,requester} / {target,responder}' | |
345 | '{controller,host} / {device,worker,proxy}' | |
346 | 'leader / follower' | |
347 | 'director / performer' | |
348 | ||
349 | Recommended replacements for 'blacklist/whitelist' are: | |
350 | 'denylist / allowlist' | |
351 | 'blocklist / passlist' | |
352 | ||
353 | Exceptions for introducing new usage is to maintain a userspace ABI/API, | |
354 | or when updating code for an existing (as of 2020) hardware or protocol | |
355 | specification that mandates those terms. For new specifications | |
356 | translate specification usage of the terminology to the kernel coding | |
357 | standard where possible. | |
1da177e4 | 358 | |
d8dbbbc5 MCC |
359 | 5) Typedefs |
360 | ----------- | |
226a6b84 | 361 | |
b1a3459b | 362 | Please don't use things like ``vps_t``. |
5d628b45 | 363 | It's a **mistake** to use typedef for structures and pointers. When you see a |
226a6b84 | 364 | |
d8dbbbc5 MCC |
365 | .. code-block:: c |
366 | ||
367 | ||
226a6b84 RD |
368 | vps_t a; |
369 | ||
370 | in the source, what does it mean? | |
226a6b84 RD |
371 | In contrast, if it says |
372 | ||
d8dbbbc5 MCC |
373 | .. code-block:: c |
374 | ||
226a6b84 RD |
375 | struct virtual_container *a; |
376 | ||
b1a3459b | 377 | you can actually tell what ``a`` is. |
226a6b84 | 378 | |
b1a3459b | 379 | Lots of people think that typedefs ``help readability``. Not so. They are |
226a6b84 RD |
380 | useful only for: |
381 | ||
5d628b45 | 382 | (a) totally opaque objects (where the typedef is actively used to **hide** |
226a6b84 RD |
383 | what the object is). |
384 | ||
b1a3459b | 385 | Example: ``pte_t`` etc. opaque objects that you can only access using |
226a6b84 RD |
386 | the proper accessor functions. |
387 | ||
3772ec4a MCC |
388 | .. note:: |
389 | ||
390 | Opaqueness and ``accessor functions`` are not good in themselves. | |
391 | The reason we have them for things like pte_t etc. is that there | |
392 | really is absolutely **zero** portably accessible information there. | |
226a6b84 | 393 | |
5d628b45 | 394 | (b) Clear integer types, where the abstraction **helps** avoid confusion |
b1a3459b | 395 | whether it is ``int`` or ``long``. |
226a6b84 RD |
396 | |
397 | u8/u16/u32 are perfectly fine typedefs, although they fit into | |
398 | category (d) better than here. | |
399 | ||
3772ec4a MCC |
400 | .. note:: |
401 | ||
402 | Again - there needs to be a **reason** for this. If something is | |
403 | ``unsigned long``, then there's no reason to do | |
226a6b84 RD |
404 | |
405 | typedef unsigned long myflags_t; | |
406 | ||
407 | but if there is a clear reason for why it under certain circumstances | |
b1a3459b MCC |
408 | might be an ``unsigned int`` and under other configurations might be |
409 | ``unsigned long``, then by all means go ahead and use a typedef. | |
226a6b84 | 410 | |
5d628b45 | 411 | (c) when you use sparse to literally create a **new** type for |
226a6b84 RD |
412 | type-checking. |
413 | ||
414 | (d) New types which are identical to standard C99 types, in certain | |
415 | exceptional circumstances. | |
416 | ||
417 | Although it would only take a short amount of time for the eyes and | |
b1a3459b | 418 | brain to become accustomed to the standard types like ``uint32_t``, |
226a6b84 RD |
419 | some people object to their use anyway. |
420 | ||
b1a3459b | 421 | Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their |
226a6b84 RD |
422 | signed equivalents which are identical to standard types are |
423 | permitted -- although they are not mandatory in new code of your | |
424 | own. | |
425 | ||
426 | When editing existing code which already uses one or the other set | |
427 | of types, you should conform to the existing choices in that code. | |
428 | ||
429 | (e) Types safe for use in userspace. | |
430 | ||
431 | In certain structures which are visible to userspace, we cannot | |
b1a3459b | 432 | require C99 types and cannot use the ``u32`` form above. Thus, we |
226a6b84 RD |
433 | use __u32 and similar types in all structures which are shared |
434 | with userspace. | |
435 | ||
436 | Maybe there are other cases too, but the rule should basically be to NEVER | |
437 | EVER use a typedef unless you can clearly match one of those rules. | |
438 | ||
439 | In general, a pointer, or a struct that has elements that can reasonably | |
5d628b45 | 440 | be directly accessed should **never** be a typedef. |
226a6b84 RD |
441 | |
442 | ||
d8dbbbc5 MCC |
443 | 6) Functions |
444 | ------------ | |
1da177e4 LT |
445 | |
446 | Functions should be short and sweet, and do just one thing. They should | |
447 | fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, | |
448 | as we all know), and do one thing and do that well. | |
449 | ||
450 | The maximum length of a function is inversely proportional to the | |
451 | complexity and indentation level of that function. So, if you have a | |
452 | conceptually simple function that is just one long (but simple) | |
453 | case-statement, where you have to do lots of small things for a lot of | |
454 | different cases, it's OK to have a longer function. | |
455 | ||
456 | However, if you have a complex function, and you suspect that a | |
457 | less-than-gifted first-year high-school student might not even | |
458 | understand what the function is all about, you should adhere to the | |
459 | maximum limits all the more closely. Use helper functions with | |
460 | descriptive names (you can ask the compiler to in-line them if you think | |
461 | it's performance-critical, and it will probably do a better job of it | |
462 | than you would have done). | |
463 | ||
464 | Another measure of the function is the number of local variables. They | |
465 | shouldn't exceed 5-10, or you're doing something wrong. Re-think the | |
466 | function, and split it into smaller pieces. A human brain can | |
467 | generally easily keep track of about 7 different things, anything more | |
468 | and it gets confused. You know you're brilliant, but maybe you'd like | |
469 | to understand what you did 2 weeks from now. | |
470 | ||
b3fc9941 | 471 | In source files, separate functions with one blank line. If the function is |
d8dbbbc5 MCC |
472 | exported, the **EXPORT** macro for it should follow immediately after the |
473 | closing function brace line. E.g.: | |
474 | ||
475 | .. code-block:: c | |
b3fc9941 | 476 | |
09677e0f PK |
477 | int system_is_up(void) |
478 | { | |
479 | return system_state == SYSTEM_RUNNING; | |
480 | } | |
481 | EXPORT_SYMBOL(system_is_up); | |
b3fc9941 | 482 | |
d5b421fe KC |
483 | 6.1) Function prototypes |
484 | ************************ | |
485 | ||
b3fc9941 RD |
486 | In function prototypes, include parameter names with their data types. |
487 | Although this is not required by the C language, it is preferred in Linux | |
488 | because it is a simple way to add valuable information for the reader. | |
489 | ||
d5b421fe | 490 | Do not use the ``extern`` keyword with function declarations as this makes |
3fe5dbfe AD |
491 | lines longer and isn't strictly necessary. |
492 | ||
d5b421fe KC |
493 | When writing function prototypes, please keep the `order of elements regular |
494 | <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_. | |
495 | For example, using this function declaration example:: | |
496 | ||
497 | __init void * __must_check action(enum magic value, size_t size, u8 count, | |
498 | char *fmt, ...) __printf(4, 5) __malloc; | |
499 | ||
500 | The preferred order of elements for a function prototype is: | |
501 | ||
502 | - storage class (below, ``static __always_inline``, noting that ``__always_inline`` | |
503 | is technically an attribute but is treated like ``inline``) | |
504 | - storage class attributes (here, ``__init`` -- i.e. section declarations, but also | |
505 | things like ``__cold``) | |
506 | - return type (here, ``void *``) | |
507 | - return type attributes (here, ``__must_check``) | |
508 | - function name (here, ``action``) | |
509 | - function parameters (here, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, | |
510 | noting that parameter names should always be included) | |
511 | - function parameter attributes (here, ``__printf(4, 5)``) | |
512 | - function behavior attributes (here, ``__malloc``) | |
513 | ||
514 | Note that for a function **definition** (i.e. the actual function body), | |
515 | the compiler does not allow function parameter attributes after the | |
516 | function parameters. In these cases, they should go after the storage | |
517 | class attributes (e.g. note the changed position of ``__printf(4, 5)`` | |
518 | below, compared to the **declaration** example above):: | |
519 | ||
520 | static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, | |
521 | size_t size, u8 count, char *fmt, ...) __malloc | |
522 | { | |
523 | ... | |
524 | } | |
1da177e4 | 525 | |
d8dbbbc5 MCC |
526 | 7) Centralized exiting of functions |
527 | ----------------------------------- | |
1da177e4 LT |
528 | |
529 | Albeit deprecated by some people, the equivalent of the goto statement is | |
530 | used frequently by compilers in form of the unconditional jump instruction. | |
531 | ||
532 | The goto statement comes in handy when a function exits from multiple | |
b57a0505 DC |
533 | locations and some common work such as cleanup has to be done. If there is no |
534 | cleanup needed then just return directly. | |
1da177e4 | 535 | |
ea040360 | 536 | Choose label names which say what the goto does or why the goto exists. An |
b1a3459b MCC |
537 | example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. |
538 | Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to | |
865a1caa JD |
539 | renumber them if you ever add or remove exit paths, and they make correctness |
540 | difficult to verify anyway. | |
541 | ||
ea040360 | 542 | The rationale for using gotos is: |
1da177e4 LT |
543 | |
544 | - unconditional statements are easier to understand and follow | |
545 | - nesting is reduced | |
546 | - errors by not updating individual exit points when making | |
d8dbbbc5 | 547 | modifications are prevented |
1da177e4 LT |
548 | - saves the compiler work to optimize redundant code away ;) |
549 | ||
d8dbbbc5 MCC |
550 | .. code-block:: c |
551 | ||
09677e0f PK |
552 | int fun(int a) |
553 | { | |
554 | int result = 0; | |
555 | char *buffer; | |
556 | ||
557 | buffer = kmalloc(SIZE, GFP_KERNEL); | |
558 | if (!buffer) | |
559 | return -ENOMEM; | |
560 | ||
561 | if (condition1) { | |
562 | while (loop1) { | |
563 | ... | |
564 | } | |
565 | result = 1; | |
beab6cb2 | 566 | goto out_free_buffer; |
1da177e4 | 567 | } |
09677e0f | 568 | ... |
79c70c30 | 569 | out_free_buffer: |
09677e0f PK |
570 | kfree(buffer); |
571 | return result; | |
1da177e4 | 572 | } |
1da177e4 | 573 | |
b1a3459b | 574 | A common type of bug to be aware of is ``one err bugs`` which look like this: |
ea040360 | 575 | |
d8dbbbc5 MCC |
576 | .. code-block:: c |
577 | ||
79c70c30 | 578 | err: |
09677e0f PK |
579 | kfree(foo->bar); |
580 | kfree(foo); | |
581 | return ret; | |
ea040360 | 582 | |
b1a3459b MCC |
583 | The bug in this code is that on some exit paths ``foo`` is NULL. Normally the |
584 | fix for this is to split it up into two error labels ``err_free_bar:`` and | |
585 | ``err_free_foo:``: | |
865a1caa | 586 | |
d8dbbbc5 MCC |
587 | .. code-block:: c |
588 | ||
865a1caa JD |
589 | err_free_bar: |
590 | kfree(foo->bar); | |
591 | err_free_foo: | |
592 | kfree(foo); | |
593 | return ret; | |
594 | ||
595 | Ideally you should simulate errors to test all exit paths. | |
ea040360 DC |
596 | |
597 | ||
d8dbbbc5 MCC |
598 | 8) Commenting |
599 | ------------- | |
1da177e4 LT |
600 | |
601 | Comments are good, but there is also a danger of over-commenting. NEVER | |
602 | try to explain HOW your code works in a comment: it's much better to | |
5d628b45 | 603 | write the code so that the **working** is obvious, and it's a waste of |
1da177e4 LT |
604 | time to explain badly written code. |
605 | ||
606 | Generally, you want your comments to tell WHAT your code does, not HOW. | |
607 | Also, try to avoid putting comments inside a function body: if the | |
608 | function is so complex that you need to separately comment parts of it, | |
b3fc9941 | 609 | you should probably go back to chapter 6 for a while. You can make |
1da177e4 LT |
610 | small comments to note or warn about something particularly clever (or |
611 | ugly), but try to avoid excess. Instead, put the comments at the head | |
612 | of the function, telling people what it does, and possibly WHY it does | |
613 | it. | |
614 | ||
b3fc9941 | 615 | When commenting the kernel API functions, please use the kernel-doc format. |
1dc4bbf0 MCC |
616 | See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and |
617 | ``scripts/kernel-doc`` for details. | |
1da177e4 | 618 | |
b3fc9941 RD |
619 | The preferred style for long (multi-line) comments is: |
620 | ||
d8dbbbc5 MCC |
621 | .. code-block:: c |
622 | ||
b3fc9941 RD |
623 | /* |
624 | * This is the preferred style for multi-line | |
625 | * comments in the Linux kernel source code. | |
626 | * Please use it consistently. | |
627 | * | |
628 | * Description: A column of asterisks on the left side, | |
629 | * with beginning and ending almost-blank lines. | |
630 | */ | |
631 | ||
c4ff1b5f JP |
632 | For files in net/ and drivers/net/ the preferred style for long (multi-line) |
633 | comments is a little different. | |
634 | ||
d8dbbbc5 MCC |
635 | .. code-block:: c |
636 | ||
c4ff1b5f JP |
637 | /* The preferred comment style for files in net/ and drivers/net |
638 | * looks like this. | |
639 | * | |
640 | * It is nearly the same as the generally preferred comment style, | |
641 | * but there is no initial almost-blank line. | |
642 | */ | |
643 | ||
b3fc9941 RD |
644 | It's also important to comment data, whether they are basic types or derived |
645 | types. To this end, use just one data declaration per line (no commas for | |
646 | multiple data declarations). This leaves you room for a small comment on each | |
647 | item, explaining its use. | |
648 | ||
649 | ||
d8dbbbc5 MCC |
650 | 9) You've made a mess of it |
651 | --------------------------- | |
1da177e4 LT |
652 | |
653 | That's OK, we all do. You've probably been told by your long-time Unix | |
b1a3459b | 654 | user helper that ``GNU emacs`` automatically formats the C sources for |
1da177e4 LT |
655 | you, and you've noticed that yes, it does do that, but the defaults it |
656 | uses are less than desirable (in fact, they are worse than random | |
657 | typing - an infinite number of monkeys typing into GNU emacs would never | |
658 | make a good program). | |
659 | ||
660 | So, you can either get rid of GNU emacs, or change it to use saner | |
661 | values. To do the latter, you can stick the following in your .emacs file: | |
662 | ||
d8dbbbc5 MCC |
663 | .. code-block:: none |
664 | ||
665 | (defun c-lineup-arglist-tabs-only (ignored) | |
666 | "Line up argument lists by tabs, not spaces" | |
667 | (let* ((anchor (c-langelem-pos c-syntactic-element)) | |
668 | (column (c-langelem-2nd-pos c-syntactic-element)) | |
669 | (offset (- (1+ column) anchor)) | |
670 | (steps (floor offset c-basic-offset))) | |
671 | (* (max steps 1) | |
672 | c-basic-offset))) | |
673 | ||
2fec7b33 BVA |
674 | (dir-locals-set-class-variables |
675 | 'linux-kernel | |
676 | '((c-mode . ( | |
677 | (c-basic-offset . 8) | |
678 | (c-label-minimum-indentation . 0) | |
679 | (c-offsets-alist . ( | |
680 | (arglist-close . c-lineup-arglist-tabs-only) | |
681 | (arglist-cont-nonempty . | |
682 | (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) | |
683 | (arglist-intro . +) | |
684 | (brace-list-intro . +) | |
685 | (c . c-lineup-C-comments) | |
686 | (case-label . 0) | |
687 | (comment-intro . c-lineup-comment) | |
688 | (cpp-define-intro . +) | |
689 | (cpp-macro . -1000) | |
690 | (cpp-macro-cont . +) | |
691 | (defun-block-intro . +) | |
692 | (else-clause . 0) | |
693 | (func-decl-cont . +) | |
694 | (inclass . +) | |
695 | (inher-cont . c-lineup-multi-inher) | |
696 | (knr-argdecl-intro . 0) | |
697 | (label . -1000) | |
698 | (statement . 0) | |
699 | (statement-block-intro . +) | |
700 | (statement-case-intro . +) | |
701 | (statement-cont . +) | |
702 | (substatement . +) | |
703 | )) | |
704 | (indent-tabs-mode . t) | |
705 | (show-trailing-whitespace . t) | |
706 | )))) | |
707 | ||
708 | (dir-locals-set-directory-class | |
709 | (expand-file-name "~/src/linux-trees") | |
710 | 'linux-kernel) | |
a7f371e5 JW |
711 | |
712 | This will make emacs go better with the kernel coding style for C | |
d8dbbbc5 | 713 | files below ``~/src/linux-trees``. |
1da177e4 LT |
714 | |
715 | But even if you fail in getting emacs to do sane formatting, not | |
b1a3459b | 716 | everything is lost: use ``indent``. |
1da177e4 LT |
717 | |
718 | Now, again, GNU indent has the same brain-dead settings that GNU emacs | |
719 | has, which is why you need to give it a few command line options. | |
720 | However, that's not too bad, because even the makers of GNU indent | |
721 | recognize the authority of K&R (the GNU people aren't evil, they are | |
722 | just severely misguided in this matter), so you just give indent the | |
b1a3459b MCC |
723 | options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use |
724 | ``scripts/Lindent``, which indents in the latest style. | |
1da177e4 | 725 | |
b1a3459b | 726 | ``indent`` has a lot of options, and especially when it comes to comment |
1da177e4 | 727 | re-formatting you may want to take a look at the man page. But |
b1a3459b | 728 | remember: ``indent`` is not a fix for bad programming. |
1da177e4 | 729 | |
d4ef8d3f MO |
730 | Note that you can also use the ``clang-format`` tool to help you with |
731 | these rules, to quickly re-format parts of your code automatically, | |
732 | and to review full files in order to spot coding style mistakes, | |
733 | typos and possible improvements. It is also handy for sorting ``#includes``, | |
734 | for aligning variables/macros, for reflowing text and other similar tasks. | |
735 | See the file :ref:`Documentation/process/clang-format.rst <clangformat>` | |
736 | for more details. | |
737 | ||
1da177e4 | 738 | |
d8dbbbc5 MCC |
739 | 10) Kconfig configuration files |
740 | ------------------------------- | |
1da177e4 | 741 | |
6754bb4d | 742 | For all of the Kconfig* configuration files throughout the source tree, |
b1a3459b | 743 | the indentation is somewhat different. Lines under a ``config`` definition |
6754bb4d | 744 | are indented with one tab, while help text is indented an additional two |
d8dbbbc5 | 745 | spaces. Example:: |
1da177e4 | 746 | |
d8dbbbc5 | 747 | config AUDIT |
6754bb4d RD |
748 | bool "Auditing support" |
749 | depends on NET | |
1da177e4 | 750 | help |
6754bb4d RD |
751 | Enable auditing infrastructure that can be used with another |
752 | kernel subsystem, such as SELinux (which requires this for | |
753 | logging of avc messages output). Does not do system-call | |
754 | auditing without CONFIG_AUDITSYSCALL. | |
755 | ||
0335cb46 | 756 | Seriously dangerous features (such as write support for certain |
d8dbbbc5 | 757 | filesystems) should advertise this prominently in their prompt string:: |
6754bb4d | 758 | |
d8dbbbc5 | 759 | config ADFS_FS_RW |
6754bb4d RD |
760 | bool "ADFS write support (DANGEROUS)" |
761 | depends on ADFS_FS | |
762 | ... | |
1da177e4 | 763 | |
6754bb4d | 764 | For full documentation on the configuration files, see the file |
cd238eff | 765 | Documentation/kbuild/kconfig-language.rst. |
1da177e4 LT |
766 | |
767 | ||
d8dbbbc5 MCC |
768 | 11) Data structures |
769 | ------------------- | |
1da177e4 LT |
770 | |
771 | Data structures that have visibility outside the single-threaded | |
772 | environment they are created and destroyed in should always have | |
773 | reference counts. In the kernel, garbage collection doesn't exist (and | |
774 | outside the kernel garbage collection is slow and inefficient), which | |
5d628b45 | 775 | means that you absolutely **have** to reference count all your uses. |
1da177e4 LT |
776 | |
777 | Reference counting means that you can avoid locking, and allows multiple | |
778 | users to have access to the data structure in parallel - and not having | |
779 | to worry about the structure suddenly going away from under them just | |
780 | because they slept or did something else for a while. | |
781 | ||
5d628b45 | 782 | Note that locking is **not** a replacement for reference counting. |
1da177e4 LT |
783 | Locking is used to keep data structures coherent, while reference |
784 | counting is a memory management technique. Usually both are needed, and | |
785 | they are not to be confused with each other. | |
786 | ||
787 | Many data structures can indeed have two levels of reference counting, | |
b1a3459b | 788 | when there are users of different ``classes``. The subclass count counts |
1da177e4 LT |
789 | the number of subclass users, and decrements the global count just once |
790 | when the subclass count goes to zero. | |
791 | ||
b1a3459b MCC |
792 | Examples of this kind of ``multi-level-reference-counting`` can be found in |
793 | memory management (``struct mm_struct``: mm_users and mm_count), and in | |
794 | filesystem code (``struct super_block``: s_count and s_active). | |
1da177e4 LT |
795 | |
796 | Remember: if another thread can find your data structure, and you don't | |
797 | have a reference count on it, you almost certainly have a bug. | |
798 | ||
799 | ||
d8dbbbc5 MCC |
800 | 12) Macros, Enums and RTL |
801 | ------------------------- | |
1da177e4 LT |
802 | |
803 | Names of macros defining constants and labels in enums are capitalized. | |
804 | ||
d8dbbbc5 MCC |
805 | .. code-block:: c |
806 | ||
09677e0f | 807 | #define CONSTANT 0x12345 |
1da177e4 LT |
808 | |
809 | Enums are preferred when defining several related constants. | |
810 | ||
811 | CAPITALIZED macro names are appreciated but macros resembling functions | |
812 | may be named in lower case. | |
813 | ||
814 | Generally, inline functions are preferable to macros resembling functions. | |
815 | ||
816 | Macros with multiple statements should be enclosed in a do - while block: | |
817 | ||
d8dbbbc5 MCC |
818 | .. code-block:: c |
819 | ||
820 | #define macrofun(a, b, c) \ | |
09677e0f PK |
821 | do { \ |
822 | if (a == 5) \ | |
823 | do_this(b, c); \ | |
824 | } while (0) | |
1da177e4 LT |
825 | |
826 | Things to avoid when using macros: | |
827 | ||
828 | 1) macros that affect control flow: | |
829 | ||
d8dbbbc5 MCC |
830 | .. code-block:: c |
831 | ||
09677e0f PK |
832 | #define FOO(x) \ |
833 | do { \ | |
834 | if (blah(x) < 0) \ | |
835 | return -EBUGGERED; \ | |
32fd52d5 | 836 | } while (0) |
1da177e4 | 837 | |
5d628b45 | 838 | is a **very** bad idea. It looks like a function call but exits the ``calling`` |
1da177e4 LT |
839 | function; don't break the internal parsers of those who will read the code. |
840 | ||
841 | 2) macros that depend on having a local variable with a magic name: | |
842 | ||
d8dbbbc5 MCC |
843 | .. code-block:: c |
844 | ||
09677e0f | 845 | #define FOO(val) bar(index, val) |
1da177e4 LT |
846 | |
847 | might look like a good thing, but it's confusing as hell when one reads the | |
848 | code and it's prone to breakage from seemingly innocent changes. | |
849 | ||
850 | 3) macros with arguments that are used as l-values: FOO(x) = y; will | |
851 | bite you if somebody e.g. turns FOO into an inline function. | |
852 | ||
853 | 4) forgetting about precedence: macros defining constants using expressions | |
854 | must enclose the expression in parentheses. Beware of similar issues with | |
855 | macros using parameters. | |
856 | ||
d8dbbbc5 MCC |
857 | .. code-block:: c |
858 | ||
09677e0f PK |
859 | #define CONSTANT 0x4000 |
860 | #define CONSTEXP (CONSTANT | 3) | |
1da177e4 | 861 | |
f2027543 BG |
862 | 5) namespace collisions when defining local variables in macros resembling |
863 | functions: | |
864 | ||
d8dbbbc5 MCC |
865 | .. code-block:: c |
866 | ||
867 | #define FOO(x) \ | |
868 | ({ \ | |
869 | typeof(x) ret; \ | |
870 | ret = calc_ret(x); \ | |
871 | (ret); \ | |
872 | }) | |
f2027543 BG |
873 | |
874 | ret is a common name for a local variable - __foo_ret is less likely | |
875 | to collide with an existing variable. | |
876 | ||
1da177e4 LT |
877 | The cpp manual deals with macros exhaustively. The gcc internals manual also |
878 | covers RTL which is used frequently with assembly language in the kernel. | |
879 | ||
880 | ||
d8dbbbc5 MCC |
881 | 13) Printing kernel messages |
882 | ---------------------------- | |
1da177e4 LT |
883 | |
884 | Kernel developers like to be seen as literate. Do mind the spelling | |
fb0e0ffe TF |
885 | of kernel messages to make a good impression. Do not use incorrect |
886 | contractions like ``dont``; use ``do not`` or ``don't`` instead. Make the | |
887 | messages concise, clear, and unambiguous. | |
1da177e4 LT |
888 | |
889 | Kernel messages do not have to be terminated with a period. | |
890 | ||
891 | Printing numbers in parentheses (%d) adds no value and should be avoided. | |
892 | ||
c04639a7 | 893 | There are a number of driver model diagnostic macros in <linux/dev_printk.h> |
6b09448a DB |
894 | which you should use to make sure messages are matched to the right device |
895 | and driver, and are tagged with the right level: dev_err(), dev_warn(), | |
896 | dev_info(), and so forth. For messages that aren't associated with a | |
6e099f55 DS |
897 | particular device, <linux/printk.h> defines pr_notice(), pr_info(), |
898 | pr_warn(), pr_err(), etc. | |
6b09448a DB |
899 | |
900 | Coming up with good debugging messages can be quite a challenge; and once | |
6e099f55 DS |
901 | you have them, they can be a huge help for remote troubleshooting. However |
902 | debug message printing is handled differently than printing other non-debug | |
903 | messages. While the other pr_XXX() functions print unconditionally, | |
904 | pr_debug() does not; it is compiled out by default, unless either DEBUG is | |
905 | defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, | |
906 | and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to | |
907 | the ones already enabled by DEBUG. | |
908 | ||
909 | Many subsystems have Kconfig debug options to turn on -DDEBUG in the | |
910 | corresponding Makefile; in other cases specific files #define DEBUG. And | |
911 | when a debug message should be unconditionally printed, such as if it is | |
7c18fd78 | 912 | already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be |
6e099f55 | 913 | used. |
6b09448a | 914 | |
1da177e4 | 915 | |
d8dbbbc5 MCC |
916 | 14) Allocating memory |
917 | --------------------- | |
af4e5a21 PE |
918 | |
919 | The kernel provides the following general purpose memory allocators: | |
15837294 XW |
920 | kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and |
921 | vzalloc(). Please refer to the API documentation for further information | |
bba757d8 JP |
922 | about them. :ref:`Documentation/core-api/memory-allocation.rst |
923 | <memory_allocation>` | |
af4e5a21 PE |
924 | |
925 | The preferred form for passing a size of a struct is the following: | |
926 | ||
d8dbbbc5 MCC |
927 | .. code-block:: c |
928 | ||
af4e5a21 PE |
929 | p = kmalloc(sizeof(*p), ...); |
930 | ||
931 | The alternative form where struct name is spelled out hurts readability and | |
932 | introduces an opportunity for a bug when the pointer variable type is changed | |
933 | but the corresponding sizeof that is passed to a memory allocator is not. | |
934 | ||
935 | Casting the return value which is a void pointer is redundant. The conversion | |
936 | from void pointer to any other pointer type is guaranteed by the C programming | |
937 | language. | |
938 | ||
15837294 XW |
939 | The preferred form for allocating an array is the following: |
940 | ||
d8dbbbc5 MCC |
941 | .. code-block:: c |
942 | ||
15837294 XW |
943 | p = kmalloc_array(n, sizeof(...), ...); |
944 | ||
945 | The preferred form for allocating a zeroed array is the following: | |
946 | ||
d8dbbbc5 MCC |
947 | .. code-block:: c |
948 | ||
15837294 XW |
949 | p = kcalloc(n, sizeof(...), ...); |
950 | ||
951 | Both forms check for overflow on the allocation size n * sizeof(...), | |
952 | and return NULL if that occurred. | |
953 | ||
bba757d8 JP |
954 | These generic allocation functions all emit a stack dump on failure when used |
955 | without __GFP_NOWARN so there is no use in emitting an additional failure | |
956 | message when NULL is returned. | |
af4e5a21 | 957 | |
d8dbbbc5 MCC |
958 | 15) The inline disease |
959 | ---------------------- | |
a771f2b8 AV |
960 | |
961 | There appears to be a common misperception that gcc has a magic "make me | |
b1a3459b | 962 | faster" speedup option called ``inline``. While the use of inlines can be |
53ab97a1 | 963 | appropriate (for example as a means of replacing macros, see Chapter 12), it |
a771f2b8 AV |
964 | very often is not. Abundant use of the inline keyword leads to a much bigger |
965 | kernel, which in turn slows the system as a whole down, due to a bigger | |
966 | icache footprint for the CPU and simply because there is less memory | |
967 | available for the pagecache. Just think about it; a pagecache miss causes a | |
19af5cdb MO |
968 | disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles |
969 | that can go into these 5 milliseconds. | |
a771f2b8 AV |
970 | |
971 | A reasonable rule of thumb is to not put inline at functions that have more | |
972 | than 3 lines of code in them. An exception to this rule are the cases where | |
973 | a parameter is known to be a compiletime constant, and as a result of this | |
974 | constantness you *know* the compiler will be able to optimize most of your | |
975 | function away at compile time. For a good example of this later case, see | |
976 | the kmalloc() inline function. | |
977 | ||
978 | Often people argue that adding inline to functions that are static and used | |
979 | only once is always a win since there is no space tradeoff. While this is | |
980 | technically correct, gcc is capable of inlining these automatically without | |
981 | help, and the maintenance issue of removing the inline when a second user | |
982 | appears outweighs the potential value of the hint that tells gcc to do | |
983 | something it would have done anyway. | |
984 | ||
985 | ||
d8dbbbc5 MCC |
986 | 16) Function return values and names |
987 | ------------------------------------ | |
c16a02d6 AS |
988 | |
989 | Functions can return values of many different kinds, and one of the | |
990 | most common is a value indicating whether the function succeeded or | |
991 | failed. Such a value can be represented as an error-code integer | |
b1a3459b | 992 | (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure, |
c16a02d6 AS |
993 | non-zero = success). |
994 | ||
995 | Mixing up these two sorts of representations is a fertile source of | |
996 | difficult-to-find bugs. If the C language included a strong distinction | |
997 | between integers and booleans then the compiler would find these mistakes | |
998 | for us... but it doesn't. To help prevent such bugs, always follow this | |
d8dbbbc5 | 999 | convention:: |
c16a02d6 AS |
1000 | |
1001 | If the name of a function is an action or an imperative command, | |
1002 | the function should return an error-code integer. If the name | |
1003 | is a predicate, the function should return a "succeeded" boolean. | |
1004 | ||
b1a3459b MCC |
1005 | For example, ``add work`` is a command, and the add_work() function returns 0 |
1006 | for success or -EBUSY for failure. In the same way, ``PCI device present`` is | |
c16a02d6 AS |
1007 | a predicate, and the pci_dev_present() function returns 1 if it succeeds in |
1008 | finding a matching device or 0 if it doesn't. | |
1009 | ||
1010 | All EXPORTed functions must respect this convention, and so should all | |
1011 | public functions. Private (static) functions need not, but it is | |
1012 | recommended that they do. | |
1013 | ||
1014 | Functions whose return value is the actual result of a computation, rather | |
1015 | than an indication of whether the computation succeeded, are not subject to | |
1016 | this rule. Generally they indicate failure by returning some out-of-range | |
1017 | result. Typical examples would be functions that return pointers; they use | |
1018 | NULL or the ERR_PTR mechanism to report failure. | |
1019 | ||
1020 | ||
7967656f JG |
1021 | 17) Using bool |
1022 | -------------- | |
1023 | ||
1024 | The Linux kernel bool type is an alias for the C99 _Bool type. bool values can | |
1025 | only evaluate to 0 or 1, and implicit or explicit conversion to bool | |
1026 | automatically converts the value to true or false. When using bool types the | |
1027 | !! construction is not needed, which eliminates a class of bugs. | |
1028 | ||
1029 | When working with bool values the true and false definitions should be used | |
1030 | instead of 1 and 0. | |
1031 | ||
1032 | bool function return types and stack variables are always fine to use whenever | |
1033 | appropriate. Use of bool is encouraged to improve readability and is often a | |
1034 | better option than 'int' for storing boolean values. | |
1035 | ||
1036 | Do not use bool if cache line layout or size of the value matters, as its size | |
1037 | and alignment varies based on the compiled architecture. Structures that are | |
1038 | optimized for alignment and size should not use bool. | |
1039 | ||
1040 | If a structure has many true/false values, consider consolidating them into a | |
1041 | bitfield with 1 bit members, or using an appropriate fixed width type, such as | |
1042 | u8. | |
1043 | ||
1044 | Similarly for function arguments, many true/false values can be consolidated | |
1045 | into a single bitwise 'flags' argument and 'flags' can often be a more | |
1046 | readable alternative if the call-sites have naked true/false constants. | |
1047 | ||
1048 | Otherwise limited use of bool in structures and arguments can improve | |
1049 | readability. | |
1050 | ||
1051 | 18) Don't re-invent the kernel macros | |
d8dbbbc5 | 1052 | ------------------------------------- |
58637ec9 RD |
1053 | |
1054 | The header file include/linux/kernel.h contains a number of macros that | |
1055 | you should use, rather than explicitly coding some variant of them yourself. | |
1056 | For example, if you need to calculate the length of an array, take advantage | |
1057 | of the macro | |
1058 | ||
d8dbbbc5 MCC |
1059 | .. code-block:: c |
1060 | ||
09677e0f | 1061 | #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) |
58637ec9 RD |
1062 | |
1063 | Similarly, if you need to calculate the size of some structure member, use | |
1064 | ||
d8dbbbc5 MCC |
1065 | .. code-block:: c |
1066 | ||
c593642c | 1067 | #define sizeof_field(t, f) (sizeof(((t*)0)->f)) |
58637ec9 RD |
1068 | |
1069 | There are also min() and max() macros that do strict type checking if you | |
1070 | need them. Feel free to peruse that header file to see what else is already | |
1071 | defined that you shouldn't reproduce in your code. | |
1072 | ||
1073 | ||
7967656f | 1074 | 19) Editor modelines and other cruft |
d8dbbbc5 | 1075 | ------------------------------------ |
4e7bd663 JT |
1076 | |
1077 | Some editors can interpret configuration information embedded in source files, | |
1078 | indicated with special markers. For example, emacs interprets lines marked | |
1079 | like this: | |
1080 | ||
d8dbbbc5 MCC |
1081 | .. code-block:: c |
1082 | ||
09677e0f | 1083 | -*- mode: c -*- |
4e7bd663 JT |
1084 | |
1085 | Or like this: | |
1086 | ||
d8dbbbc5 MCC |
1087 | .. code-block:: c |
1088 | ||
09677e0f PK |
1089 | /* |
1090 | Local Variables: | |
1091 | compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" | |
1092 | End: | |
1093 | */ | |
4e7bd663 JT |
1094 | |
1095 | Vim interprets markers that look like this: | |
1096 | ||
d8dbbbc5 MCC |
1097 | .. code-block:: c |
1098 | ||
09677e0f | 1099 | /* vim:set sw=8 noet */ |
4e7bd663 JT |
1100 | |
1101 | Do not include any of these in source files. People have their own personal | |
1102 | editor configurations, and your source files should not override them. This | |
1103 | includes markers for indentation and mode configuration. People may use their | |
1104 | own custom mode, or may have some other magic method for making indentation | |
1105 | work correctly. | |
1106 | ||
1107 | ||
7967656f | 1108 | 20) Inline assembly |
d8dbbbc5 | 1109 | ------------------- |
9a7c48b7 JT |
1110 | |
1111 | In architecture-specific code, you may need to use inline assembly to interface | |
1112 | with CPU or platform functionality. Don't hesitate to do so when necessary. | |
1113 | However, don't use inline assembly gratuitously when C can do the job. You can | |
1114 | and should poke hardware from C when possible. | |
1115 | ||
1116 | Consider writing simple helper functions that wrap common bits of inline | |
1117 | assembly, rather than repeatedly writing them with slight variations. Remember | |
1118 | that inline assembly can use C parameters. | |
1119 | ||
1120 | Large, non-trivial assembly functions should go in .S files, with corresponding | |
1121 | C prototypes defined in C header files. The C prototypes for assembly | |
b1a3459b | 1122 | functions should use ``asmlinkage``. |
9a7c48b7 JT |
1123 | |
1124 | You may need to mark your asm statement as volatile, to prevent GCC from | |
1125 | removing it if GCC doesn't notice any side effects. You don't always need to | |
1126 | do so, though, and doing so unnecessarily can limit optimization. | |
1127 | ||
1128 | When writing a single inline assembly statement containing multiple | |
1129 | instructions, put each instruction on a separate line in a separate quoted | |
68f04b57 AS |
1130 | string, and end each string except the last with ``\n\t`` to properly indent |
1131 | the next instruction in the assembly output: | |
9a7c48b7 | 1132 | |
d8dbbbc5 MCC |
1133 | .. code-block:: c |
1134 | ||
9a7c48b7 JT |
1135 | asm ("magic %reg1, #42\n\t" |
1136 | "more_magic %reg2, %reg3" | |
1137 | : /* outputs */ : /* inputs */ : /* clobbers */); | |
1138 | ||
1139 | ||
7967656f | 1140 | 21) Conditional Compilation |
d8dbbbc5 | 1141 | --------------------------- |
21228a18 JT |
1142 | |
1143 | Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c | |
1144 | files; doing so makes code harder to read and logic harder to follow. Instead, | |
1145 | use such conditionals in a header file defining functions for use in those .c | |
1146 | files, providing no-op stub versions in the #else case, and then call those | |
1147 | functions unconditionally from .c files. The compiler will avoid generating | |
1148 | any code for the stub calls, producing identical results, but the logic will | |
1149 | remain easy to follow. | |
1150 | ||
1151 | Prefer to compile out entire functions, rather than portions of functions or | |
1152 | portions of expressions. Rather than putting an ifdef in an expression, factor | |
1153 | out part or all of the expression into a separate helper function and apply the | |
1154 | conditional to that function. | |
1155 | ||
1156 | If you have a function or variable which may potentially go unused in a | |
1157 | particular configuration, and the compiler would warn about its definition | |
1158 | going unused, mark the definition as __maybe_unused rather than wrapping it in | |
1159 | a preprocessor conditional. (However, if a function or variable *always* goes | |
1160 | unused, delete it.) | |
1161 | ||
1162 | Within code, where possible, use the IS_ENABLED macro to convert a Kconfig | |
1163 | symbol into a C boolean expression, and use it in a normal C conditional: | |
1164 | ||
d8dbbbc5 MCC |
1165 | .. code-block:: c |
1166 | ||
21228a18 JT |
1167 | if (IS_ENABLED(CONFIG_SOMETHING)) { |
1168 | ... | |
1169 | } | |
1170 | ||
1171 | The compiler will constant-fold the conditional away, and include or exclude | |
1172 | the block of code just as with an #ifdef, so this will not add any runtime | |
1173 | overhead. However, this approach still allows the C compiler to see the code | |
1174 | inside the block, and check it for correctness (syntax, types, symbol | |
1175 | references, etc). Thus, you still have to use an #ifdef if the code inside the | |
1176 | block references symbols that will not exist if the condition is not met. | |
1177 | ||
1178 | At the end of any non-trivial #if or #ifdef block (more than a few lines), | |
1179 | place a comment after the #endif on the same line, noting the conditional | |
1180 | expression used. For instance: | |
1181 | ||
d8dbbbc5 MCC |
1182 | .. code-block:: c |
1183 | ||
09677e0f PK |
1184 | #ifdef CONFIG_SOMETHING |
1185 | ... | |
1186 | #endif /* CONFIG_SOMETHING */ | |
21228a18 | 1187 | |
a771f2b8 | 1188 | |
1cfd9d7e DH |
1189 | 22) Do not crash the kernel |
1190 | --------------------------- | |
1191 | ||
1192 | In general, the decision to crash the kernel belongs to the user, rather | |
1193 | than to the kernel developer. | |
1194 | ||
1195 | Avoid panic() | |
1196 | ************* | |
1197 | ||
1198 | panic() should be used with care and primarily only during system boot. | |
1199 | panic() is, for example, acceptable when running out of memory during boot and | |
1200 | not being able to continue. | |
1201 | ||
1202 | Use WARN() rather than BUG() | |
1203 | **************************** | |
1204 | ||
1205 | Do not add new code that uses any of the BUG() variants, such as BUG(), | |
1206 | BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably | |
1207 | WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not | |
1208 | required if there is no reasonable way to at least partially recover. | |
1209 | ||
1210 | "I'm too lazy to do error handling" is not an excuse for using BUG(). Major | |
1211 | internal corruptions with no way of continuing may still use BUG(), but need | |
1212 | good justification. | |
1213 | ||
1214 | Use WARN_ON_ONCE() rather than WARN() or WARN_ON() | |
1215 | ************************************************** | |
1216 | ||
1217 | WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it | |
1218 | is common for a given warning condition, if it occurs at all, to occur | |
1219 | multiple times. This can fill up and wrap the kernel log, and can even slow | |
1220 | the system enough that the excessive logging turns into its own, additional | |
1221 | problem. | |
1222 | ||
1223 | Do not WARN lightly | |
1224 | ******************* | |
1225 | ||
1226 | WARN*() is intended for unexpected, this-should-never-happen situations. | |
1227 | WARN*() macros are not to be used for anything that is expected to happen | |
1228 | during normal operation. These are not pre- or post-condition asserts, for | |
1229 | example. Again: WARN*() must not be used for a condition that is expected | |
1230 | to trigger easily, for example, by user space actions. pr_warn_once() is a | |
1231 | possible alternative, if you need to notify the user of a problem. | |
1232 | ||
1233 | Do not worry about panic_on_warn users | |
1234 | ************************************** | |
1235 | ||
1236 | A few more words about panic_on_warn: Remember that ``panic_on_warn`` is an | |
1237 | available kernel option, and that many users set this option. This is why | |
1238 | there is a "Do not WARN lightly" writeup, above. However, the existence of | |
1239 | panic_on_warn users is not a valid reason to avoid the judicious use | |
1240 | WARN*(). That is because, whoever enables panic_on_warn has explicitly | |
1241 | asked the kernel to crash if a WARN*() fires, and such users must be | |
1242 | prepared to deal with the consequences of a system that is somewhat more | |
1243 | likely to crash. | |
1244 | ||
1245 | Use BUILD_BUG_ON() for compile-time assertions | |
1246 | ********************************************** | |
1247 | ||
1248 | The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a | |
1249 | compile-time assertion that has no effect at runtime. | |
1250 | ||
d8dbbbc5 MCC |
1251 | Appendix I) References |
1252 | ---------------------- | |
1da177e4 LT |
1253 | |
1254 | The C Programming Language, Second Edition | |
1255 | by Brian W. Kernighan and Dennis M. Ritchie. | |
1256 | Prentice Hall, Inc., 1988. | |
1257 | ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). | |
1da177e4 LT |
1258 | |
1259 | The Practice of Programming | |
1260 | by Brian W. Kernighan and Rob Pike. | |
1261 | Addison-Wesley, Inc., 1999. | |
1262 | ISBN 0-201-61586-X. | |
1da177e4 LT |
1263 | |
1264 | GNU manuals - where in compliance with K&R and this text - for cpp, gcc, | |
e7b4311e | 1265 | gcc internals and indent, all available from https://www.gnu.org/manual/ |
1da177e4 LT |
1266 | |
1267 | WG14 is the international standardization working group for the programming | |
5b0ed2c6 XVP |
1268 | language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ |
1269 | ||
775a445d | 1270 | Kernel CodingStyle, by greg@kroah.com at OLS 2002: |
5b0ed2c6 | 1271 | http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ |