Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Linux kernel coding style | |
3 | ||
4 | This is a short document describing the preferred coding style for the | |
5 | linux kernel. Coding style is very personal, and I won't _force_ my | |
6 | views on anybody, but this is what goes for anything that I have to be | |
7 | able to maintain, and I'd prefer it for most other things too. Please | |
8 | at least consider the points made here. | |
9 | ||
10 | First off, I'd suggest printing out a copy of the GNU coding standards, | |
11 | and NOT read it. Burn them, it's a great symbolic gesture. | |
12 | ||
13 | Anyway, here goes: | |
14 | ||
15 | ||
16 | Chapter 1: Indentation | |
17 | ||
18 | Tabs are 8 characters, and thus indentations are also 8 characters. | |
19 | There are heretic movements that try to make indentations 4 (or even 2!) | |
20 | characters deep, and that is akin to trying to define the value of PI to | |
21 | be 3. | |
22 | ||
23 | Rationale: The whole idea behind indentation is to clearly define where | |
24 | a block of control starts and ends. Especially when you've been looking | |
25 | at your screen for 20 straight hours, you'll find it a lot easier to see | |
26 | how the indentation works if you have large indentations. | |
27 | ||
28 | Now, some people will claim that having 8-character indentations makes | |
29 | the code move too far to the right, and makes it hard to read on a | |
30 | 80-character terminal screen. The answer to that is that if you need | |
31 | more than 3 levels of indentation, you're screwed anyway, and should fix | |
32 | your program. | |
33 | ||
34 | In short, 8-char indents make things easier to read, and have the added | |
35 | benefit of warning you when you're nesting your functions too deep. | |
36 | Heed that warning. | |
37 | ||
b3fc9941 RD |
38 | The preferred way to ease multiple indentation levels in a switch statement is |
39 | to align the "switch" and its subordinate "case" labels in the same column | |
40 | instead of "double-indenting" the "case" labels. E.g.: | |
41 | ||
42 | switch (suffix) { | |
43 | case 'G': | |
44 | case 'g': | |
45 | mem <<= 30; | |
46 | break; | |
47 | case 'M': | |
48 | case 'm': | |
49 | mem <<= 20; | |
50 | break; | |
51 | case 'K': | |
52 | case 'k': | |
53 | mem <<= 10; | |
54 | /* fall through */ | |
55 | default: | |
56 | break; | |
57 | } | |
58 | ||
59 | ||
1da177e4 LT |
60 | Don't put multiple statements on a single line unless you have |
61 | something to hide: | |
62 | ||
63 | if (condition) do_this; | |
64 | do_something_everytime; | |
65 | ||
b3fc9941 RD |
66 | Don't put multiple assignments on a single line either. Kernel coding style |
67 | is super simple. Avoid tricky expressions. | |
68 | ||
1da177e4 LT |
69 | Outside of comments, documentation and except in Kconfig, spaces are never |
70 | used for indentation, and the above example is deliberately broken. | |
71 | ||
72 | Get a decent editor and don't leave whitespace at the end of lines. | |
73 | ||
74 | ||
75 | Chapter 2: Breaking long lines and strings | |
76 | ||
77 | Coding style is all about readability and maintainability using commonly | |
78 | available tools. | |
79 | ||
80 | The limit on the length of lines is 80 columns and this is a hard limit. | |
81 | ||
82 | Statements longer than 80 columns will be broken into sensible chunks. | |
83 | Descendants are always substantially shorter than the parent and are placed | |
84 | substantially to the right. The same applies to function headers with a long | |
85 | argument list. Long strings are as well broken into shorter strings. | |
86 | ||
87 | void fun(int a, int b, int c) | |
88 | { | |
89 | if (condition) | |
90 | printk(KERN_WARNING "Warning this is a long printk with " | |
91 | "3 parameters a: %u b: %u " | |
92 | "c: %u \n", a, b, c); | |
93 | else | |
94 | next_statement; | |
95 | } | |
96 | ||
b3fc9941 | 97 | Chapter 3: Placing Braces and Spaces |
1da177e4 LT |
98 | |
99 | The other issue that always comes up in C styling is the placement of | |
100 | braces. Unlike the indent size, there are few technical reasons to | |
101 | choose one placement strategy over the other, but the preferred way, as | |
102 | shown to us by the prophets Kernighan and Ritchie, is to put the opening | |
103 | brace last on the line, and put the closing brace first, thusly: | |
104 | ||
105 | if (x is true) { | |
106 | we do y | |
107 | } | |
108 | ||
b3fc9941 RD |
109 | This applies to all non-function statement blocks (if, switch, for, |
110 | while, do). E.g.: | |
111 | ||
112 | switch (action) { | |
113 | case KOBJ_ADD: | |
114 | return "add"; | |
115 | case KOBJ_REMOVE: | |
116 | return "remove"; | |
117 | case KOBJ_CHANGE: | |
118 | return "change"; | |
119 | default: | |
120 | return NULL; | |
121 | } | |
122 | ||
1da177e4 LT |
123 | However, there is one special case, namely functions: they have the |
124 | opening brace at the beginning of the next line, thus: | |
125 | ||
126 | int function(int x) | |
127 | { | |
128 | body of function | |
129 | } | |
130 | ||
131 | Heretic people all over the world have claimed that this inconsistency | |
132 | is ... well ... inconsistent, but all right-thinking people know that | |
133 | (a) K&R are _right_ and (b) K&R are right. Besides, functions are | |
134 | special anyway (you can't nest them in C). | |
135 | ||
136 | Note that the closing brace is empty on a line of its own, _except_ in | |
137 | the cases where it is followed by a continuation of the same statement, | |
138 | ie a "while" in a do-statement or an "else" in an if-statement, like | |
139 | this: | |
140 | ||
141 | do { | |
142 | body of do-loop | |
143 | } while (condition); | |
144 | ||
145 | and | |
146 | ||
147 | if (x == y) { | |
148 | .. | |
149 | } else if (x > y) { | |
150 | ... | |
151 | } else { | |
152 | .... | |
153 | } | |
154 | ||
155 | Rationale: K&R. | |
156 | ||
157 | Also, note that this brace-placement also minimizes the number of empty | |
158 | (or almost empty) lines, without any loss of readability. Thus, as the | |
159 | supply of new-lines on your screen is not a renewable resource (think | |
160 | 25-line terminal screens here), you have more empty lines to put | |
161 | comments on. | |
162 | ||
e659ba4a ON |
163 | Do not unnecessarily use braces where a single statement will do. |
164 | ||
165 | if (condition) | |
166 | action(); | |
167 | ||
168 | This does not apply if one branch of a conditional statement is a single | |
169 | statement. Use braces in both branches. | |
170 | ||
171 | if (condition) { | |
172 | do_this(); | |
173 | do_that(); | |
174 | } else { | |
175 | otherwise(); | |
176 | } | |
177 | ||
b3fc9941 RD |
178 | 3.1: Spaces |
179 | ||
180 | Linux kernel style for use of spaces depends (mostly) on | |
181 | function-versus-keyword usage. Use a space after (most) keywords. The | |
182 | notable exceptions are sizeof, typeof, alignof, and __attribute__, which look | |
183 | somewhat like functions (and are usually used with parentheses in Linux, | |
184 | although they are not required in the language, as in: "sizeof info" after | |
185 | "struct fileinfo info;" is declared). | |
186 | ||
187 | So use a space after these keywords: | |
188 | if, switch, case, for, do, while | |
189 | but not with sizeof, typeof, alignof, or __attribute__. E.g., | |
190 | s = sizeof(struct file); | |
191 | ||
192 | Do not add spaces around (inside) parenthesized expressions. This example is | |
193 | *bad*: | |
194 | ||
195 | s = sizeof( struct file ); | |
196 | ||
197 | When declaring pointer data or a function that returns a pointer type, the | |
198 | preferred use of '*' is adjacent to the data name or function name and not | |
199 | adjacent to the type name. Examples: | |
200 | ||
201 | char *linux_banner; | |
202 | unsigned long long memparse(char *ptr, char **retptr); | |
203 | char *match_strdup(substring_t *s); | |
204 | ||
205 | Use one space around (on each side of) most binary and ternary operators, | |
206 | such as any of these: | |
207 | ||
208 | = + - < > * / % | & ^ <= >= == != ? : | |
209 | ||
210 | but no space after unary operators: | |
211 | & * + - ~ ! sizeof typeof alignof __attribute__ defined | |
212 | ||
213 | no space before the postfix increment & decrement unary operators: | |
214 | ++ -- | |
215 | ||
216 | no space after the prefix increment & decrement unary operators: | |
217 | ++ -- | |
218 | ||
219 | and no space around the '.' and "->" structure member operators. | |
220 | ||
a923fd6a JT |
221 | Do not leave trailing whitespace at the ends of lines. Some editors with |
222 | "smart" indentation will insert whitespace at the beginning of new lines as | |
223 | appropriate, so you can start typing the next line of code right away. | |
224 | However, some such editors do not remove the whitespace if you end up not | |
225 | putting a line of code there, such as if you leave a blank line. As a result, | |
226 | you end up with lines containing trailing whitespace. | |
227 | ||
228 | Git will warn you about patches that introduce trailing whitespace, and can | |
229 | optionally strip the trailing whitespace for you; however, if applying a series | |
230 | of patches, this may make later patches in the series fail by changing their | |
231 | context lines. | |
232 | ||
1da177e4 LT |
233 | |
234 | Chapter 4: Naming | |
235 | ||
236 | C is a Spartan language, and so should your naming be. Unlike Modula-2 | |
237 | and Pascal programmers, C programmers do not use cute names like | |
238 | ThisVariableIsATemporaryCounter. A C programmer would call that | |
239 | variable "tmp", which is much easier to write, and not the least more | |
240 | difficult to understand. | |
241 | ||
242 | HOWEVER, while mixed-case names are frowned upon, descriptive names for | |
243 | global variables are a must. To call a global function "foo" is a | |
244 | shooting offense. | |
245 | ||
246 | GLOBAL variables (to be used only if you _really_ need them) need to | |
247 | have descriptive names, as do global functions. If you have a function | |
248 | that counts the number of active users, you should call that | |
249 | "count_active_users()" or similar, you should _not_ call it "cntusr()". | |
250 | ||
251 | Encoding the type of a function into the name (so-called Hungarian | |
252 | notation) is brain damaged - the compiler knows the types anyway and can | |
253 | check those, and it only confuses the programmer. No wonder MicroSoft | |
254 | makes buggy programs. | |
255 | ||
256 | LOCAL variable names should be short, and to the point. If you have | |
257 | some random integer loop counter, it should probably be called "i". | |
258 | Calling it "loop_counter" is non-productive, if there is no chance of it | |
259 | being mis-understood. Similarly, "tmp" can be just about any type of | |
260 | variable that is used to hold a temporary value. | |
261 | ||
262 | If you are afraid to mix up your local variable names, you have another | |
263 | problem, which is called the function-growth-hormone-imbalance syndrome. | |
b3fc9941 | 264 | See chapter 6 (Functions). |
1da177e4 LT |
265 | |
266 | ||
226a6b84 RD |
267 | Chapter 5: Typedefs |
268 | ||
269 | Please don't use things like "vps_t". | |
270 | ||
271 | It's a _mistake_ to use typedef for structures and pointers. When you see a | |
272 | ||
273 | vps_t a; | |
274 | ||
275 | in the source, what does it mean? | |
276 | ||
277 | In contrast, if it says | |
278 | ||
279 | struct virtual_container *a; | |
280 | ||
281 | you can actually tell what "a" is. | |
282 | ||
283 | Lots of people think that typedefs "help readability". Not so. They are | |
284 | useful only for: | |
285 | ||
286 | (a) totally opaque objects (where the typedef is actively used to _hide_ | |
287 | what the object is). | |
288 | ||
289 | Example: "pte_t" etc. opaque objects that you can only access using | |
290 | the proper accessor functions. | |
291 | ||
292 | NOTE! Opaqueness and "accessor functions" are not good in themselves. | |
293 | The reason we have them for things like pte_t etc. is that there | |
294 | really is absolutely _zero_ portably accessible information there. | |
295 | ||
296 | (b) Clear integer types, where the abstraction _helps_ avoid confusion | |
297 | whether it is "int" or "long". | |
298 | ||
299 | u8/u16/u32 are perfectly fine typedefs, although they fit into | |
300 | category (d) better than here. | |
301 | ||
302 | NOTE! Again - there needs to be a _reason_ for this. If something is | |
303 | "unsigned long", then there's no reason to do | |
304 | ||
305 | typedef unsigned long myflags_t; | |
306 | ||
307 | but if there is a clear reason for why it under certain circumstances | |
308 | might be an "unsigned int" and under other configurations might be | |
309 | "unsigned long", then by all means go ahead and use a typedef. | |
310 | ||
311 | (c) when you use sparse to literally create a _new_ type for | |
312 | type-checking. | |
313 | ||
314 | (d) New types which are identical to standard C99 types, in certain | |
315 | exceptional circumstances. | |
316 | ||
317 | Although it would only take a short amount of time for the eyes and | |
318 | brain to become accustomed to the standard types like 'uint32_t', | |
319 | some people object to their use anyway. | |
320 | ||
321 | Therefore, the Linux-specific 'u8/u16/u32/u64' types and their | |
322 | signed equivalents which are identical to standard types are | |
323 | permitted -- although they are not mandatory in new code of your | |
324 | own. | |
325 | ||
326 | When editing existing code which already uses one or the other set | |
327 | of types, you should conform to the existing choices in that code. | |
328 | ||
329 | (e) Types safe for use in userspace. | |
330 | ||
331 | In certain structures which are visible to userspace, we cannot | |
332 | require C99 types and cannot use the 'u32' form above. Thus, we | |
333 | use __u32 and similar types in all structures which are shared | |
334 | with userspace. | |
335 | ||
336 | Maybe there are other cases too, but the rule should basically be to NEVER | |
337 | EVER use a typedef unless you can clearly match one of those rules. | |
338 | ||
339 | In general, a pointer, or a struct that has elements that can reasonably | |
340 | be directly accessed should _never_ be a typedef. | |
341 | ||
342 | ||
343 | Chapter 6: Functions | |
1da177e4 LT |
344 | |
345 | Functions should be short and sweet, and do just one thing. They should | |
346 | fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, | |
347 | as we all know), and do one thing and do that well. | |
348 | ||
349 | The maximum length of a function is inversely proportional to the | |
350 | complexity and indentation level of that function. So, if you have a | |
351 | conceptually simple function that is just one long (but simple) | |
352 | case-statement, where you have to do lots of small things for a lot of | |
353 | different cases, it's OK to have a longer function. | |
354 | ||
355 | However, if you have a complex function, and you suspect that a | |
356 | less-than-gifted first-year high-school student might not even | |
357 | understand what the function is all about, you should adhere to the | |
358 | maximum limits all the more closely. Use helper functions with | |
359 | descriptive names (you can ask the compiler to in-line them if you think | |
360 | it's performance-critical, and it will probably do a better job of it | |
361 | than you would have done). | |
362 | ||
363 | Another measure of the function is the number of local variables. They | |
364 | shouldn't exceed 5-10, or you're doing something wrong. Re-think the | |
365 | function, and split it into smaller pieces. A human brain can | |
366 | generally easily keep track of about 7 different things, anything more | |
367 | and it gets confused. You know you're brilliant, but maybe you'd like | |
368 | to understand what you did 2 weeks from now. | |
369 | ||
b3fc9941 RD |
370 | In source files, separate functions with one blank line. If the function is |
371 | exported, the EXPORT* macro for it should follow immediately after the closing | |
372 | function brace line. E.g.: | |
373 | ||
374 | int system_is_up(void) | |
375 | { | |
376 | return system_state == SYSTEM_RUNNING; | |
377 | } | |
378 | EXPORT_SYMBOL(system_is_up); | |
379 | ||
380 | In function prototypes, include parameter names with their data types. | |
381 | Although this is not required by the C language, it is preferred in Linux | |
382 | because it is a simple way to add valuable information for the reader. | |
383 | ||
1da177e4 | 384 | |
226a6b84 | 385 | Chapter 7: Centralized exiting of functions |
1da177e4 LT |
386 | |
387 | Albeit deprecated by some people, the equivalent of the goto statement is | |
388 | used frequently by compilers in form of the unconditional jump instruction. | |
389 | ||
390 | The goto statement comes in handy when a function exits from multiple | |
391 | locations and some common work such as cleanup has to be done. | |
392 | ||
393 | The rationale is: | |
394 | ||
395 | - unconditional statements are easier to understand and follow | |
396 | - nesting is reduced | |
397 | - errors by not updating individual exit points when making | |
398 | modifications are prevented | |
399 | - saves the compiler work to optimize redundant code away ;) | |
400 | ||
dc3d28d0 | 401 | int fun(int a) |
1da177e4 LT |
402 | { |
403 | int result = 0; | |
404 | char *buffer = kmalloc(SIZE); | |
405 | ||
406 | if (buffer == NULL) | |
407 | return -ENOMEM; | |
408 | ||
409 | if (condition1) { | |
410 | while (loop1) { | |
411 | ... | |
412 | } | |
413 | result = 1; | |
414 | goto out; | |
415 | } | |
416 | ... | |
417 | out: | |
418 | kfree(buffer); | |
419 | return result; | |
420 | } | |
421 | ||
226a6b84 | 422 | Chapter 8: Commenting |
1da177e4 LT |
423 | |
424 | Comments are good, but there is also a danger of over-commenting. NEVER | |
425 | try to explain HOW your code works in a comment: it's much better to | |
426 | write the code so that the _working_ is obvious, and it's a waste of | |
427 | time to explain badly written code. | |
428 | ||
429 | Generally, you want your comments to tell WHAT your code does, not HOW. | |
430 | Also, try to avoid putting comments inside a function body: if the | |
431 | function is so complex that you need to separately comment parts of it, | |
b3fc9941 | 432 | you should probably go back to chapter 6 for a while. You can make |
1da177e4 LT |
433 | small comments to note or warn about something particularly clever (or |
434 | ugly), but try to avoid excess. Instead, put the comments at the head | |
435 | of the function, telling people what it does, and possibly WHY it does | |
436 | it. | |
437 | ||
b3fc9941 | 438 | When commenting the kernel API functions, please use the kernel-doc format. |
e776eba0 PE |
439 | See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc |
440 | for details. | |
1da177e4 | 441 | |
b3fc9941 RD |
442 | Linux style for comments is the C89 "/* ... */" style. |
443 | Don't use C99-style "// ..." comments. | |
444 | ||
445 | The preferred style for long (multi-line) comments is: | |
446 | ||
447 | /* | |
448 | * This is the preferred style for multi-line | |
449 | * comments in the Linux kernel source code. | |
450 | * Please use it consistently. | |
451 | * | |
452 | * Description: A column of asterisks on the left side, | |
453 | * with beginning and ending almost-blank lines. | |
454 | */ | |
455 | ||
456 | It's also important to comment data, whether they are basic types or derived | |
457 | types. To this end, use just one data declaration per line (no commas for | |
458 | multiple data declarations). This leaves you room for a small comment on each | |
459 | item, explaining its use. | |
460 | ||
461 | ||
226a6b84 | 462 | Chapter 9: You've made a mess of it |
1da177e4 LT |
463 | |
464 | That's OK, we all do. You've probably been told by your long-time Unix | |
465 | user helper that "GNU emacs" automatically formats the C sources for | |
466 | you, and you've noticed that yes, it does do that, but the defaults it | |
467 | uses are less than desirable (in fact, they are worse than random | |
468 | typing - an infinite number of monkeys typing into GNU emacs would never | |
469 | make a good program). | |
470 | ||
471 | So, you can either get rid of GNU emacs, or change it to use saner | |
472 | values. To do the latter, you can stick the following in your .emacs file: | |
473 | ||
474 | (defun linux-c-mode () | |
475 | "C mode with adjusted defaults for use with the Linux kernel." | |
476 | (interactive) | |
477 | (c-mode) | |
478 | (c-set-style "K&R") | |
479 | (setq tab-width 8) | |
480 | (setq indent-tabs-mode t) | |
481 | (setq c-basic-offset 8)) | |
482 | ||
483 | This will define the M-x linux-c-mode command. When hacking on a | |
484 | module, if you put the string -*- linux-c -*- somewhere on the first | |
485 | two lines, this mode will be automatically invoked. Also, you may want | |
486 | to add | |
487 | ||
488 | (setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) | |
489 | auto-mode-alist)) | |
490 | ||
491 | to your .emacs file if you want to have linux-c-mode switched on | |
492 | automagically when you edit source files under /usr/src/linux. | |
493 | ||
494 | But even if you fail in getting emacs to do sane formatting, not | |
495 | everything is lost: use "indent". | |
496 | ||
497 | Now, again, GNU indent has the same brain-dead settings that GNU emacs | |
498 | has, which is why you need to give it a few command line options. | |
499 | However, that's not too bad, because even the makers of GNU indent | |
500 | recognize the authority of K&R (the GNU people aren't evil, they are | |
501 | just severely misguided in this matter), so you just give indent the | |
502 | options "-kr -i8" (stands for "K&R, 8 character indents"), or use | |
503 | "scripts/Lindent", which indents in the latest style. | |
504 | ||
505 | "indent" has a lot of options, and especially when it comes to comment | |
506 | re-formatting you may want to take a look at the man page. But | |
507 | remember: "indent" is not a fix for bad programming. | |
508 | ||
509 | ||
6754bb4d | 510 | Chapter 10: Kconfig configuration files |
1da177e4 | 511 | |
6754bb4d RD |
512 | For all of the Kconfig* configuration files throughout the source tree, |
513 | the indentation is somewhat different. Lines under a "config" definition | |
514 | are indented with one tab, while help text is indented an additional two | |
515 | spaces. Example: | |
1da177e4 | 516 | |
6754bb4d RD |
517 | config AUDIT |
518 | bool "Auditing support" | |
519 | depends on NET | |
1da177e4 | 520 | help |
6754bb4d RD |
521 | Enable auditing infrastructure that can be used with another |
522 | kernel subsystem, such as SELinux (which requires this for | |
523 | logging of avc messages output). Does not do system-call | |
524 | auditing without CONFIG_AUDITSYSCALL. | |
525 | ||
526 | Features that might still be considered unstable should be defined as | |
527 | dependent on "EXPERIMENTAL": | |
528 | ||
529 | config SLUB | |
530 | depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT | |
531 | bool "SLUB (Unqueued Allocator)" | |
532 | ... | |
533 | ||
534 | while seriously dangerous features (such as write support for certain | |
535 | filesystems) should advertise this prominently in their prompt string: | |
536 | ||
537 | config ADFS_FS_RW | |
538 | bool "ADFS write support (DANGEROUS)" | |
539 | depends on ADFS_FS | |
540 | ... | |
1da177e4 | 541 | |
6754bb4d RD |
542 | For full documentation on the configuration files, see the file |
543 | Documentation/kbuild/kconfig-language.txt. | |
1da177e4 LT |
544 | |
545 | ||
226a6b84 | 546 | Chapter 11: Data structures |
1da177e4 LT |
547 | |
548 | Data structures that have visibility outside the single-threaded | |
549 | environment they are created and destroyed in should always have | |
550 | reference counts. In the kernel, garbage collection doesn't exist (and | |
551 | outside the kernel garbage collection is slow and inefficient), which | |
552 | means that you absolutely _have_ to reference count all your uses. | |
553 | ||
554 | Reference counting means that you can avoid locking, and allows multiple | |
555 | users to have access to the data structure in parallel - and not having | |
556 | to worry about the structure suddenly going away from under them just | |
557 | because they slept or did something else for a while. | |
558 | ||
559 | Note that locking is _not_ a replacement for reference counting. | |
560 | Locking is used to keep data structures coherent, while reference | |
561 | counting is a memory management technique. Usually both are needed, and | |
562 | they are not to be confused with each other. | |
563 | ||
564 | Many data structures can indeed have two levels of reference counting, | |
565 | when there are users of different "classes". The subclass count counts | |
566 | the number of subclass users, and decrements the global count just once | |
567 | when the subclass count goes to zero. | |
568 | ||
569 | Examples of this kind of "multi-level-reference-counting" can be found in | |
570 | memory management ("struct mm_struct": mm_users and mm_count), and in | |
571 | filesystem code ("struct super_block": s_count and s_active). | |
572 | ||
573 | Remember: if another thread can find your data structure, and you don't | |
574 | have a reference count on it, you almost certainly have a bug. | |
575 | ||
576 | ||
226a6b84 | 577 | Chapter 12: Macros, Enums and RTL |
1da177e4 LT |
578 | |
579 | Names of macros defining constants and labels in enums are capitalized. | |
580 | ||
581 | #define CONSTANT 0x12345 | |
582 | ||
583 | Enums are preferred when defining several related constants. | |
584 | ||
585 | CAPITALIZED macro names are appreciated but macros resembling functions | |
586 | may be named in lower case. | |
587 | ||
588 | Generally, inline functions are preferable to macros resembling functions. | |
589 | ||
590 | Macros with multiple statements should be enclosed in a do - while block: | |
591 | ||
592 | #define macrofun(a, b, c) \ | |
593 | do { \ | |
594 | if (a == 5) \ | |
595 | do_this(b, c); \ | |
596 | } while (0) | |
597 | ||
598 | Things to avoid when using macros: | |
599 | ||
600 | 1) macros that affect control flow: | |
601 | ||
602 | #define FOO(x) \ | |
603 | do { \ | |
604 | if (blah(x) < 0) \ | |
605 | return -EBUGGERED; \ | |
606 | } while(0) | |
607 | ||
608 | is a _very_ bad idea. It looks like a function call but exits the "calling" | |
609 | function; don't break the internal parsers of those who will read the code. | |
610 | ||
611 | 2) macros that depend on having a local variable with a magic name: | |
612 | ||
613 | #define FOO(val) bar(index, val) | |
614 | ||
615 | might look like a good thing, but it's confusing as hell when one reads the | |
616 | code and it's prone to breakage from seemingly innocent changes. | |
617 | ||
618 | 3) macros with arguments that are used as l-values: FOO(x) = y; will | |
619 | bite you if somebody e.g. turns FOO into an inline function. | |
620 | ||
621 | 4) forgetting about precedence: macros defining constants using expressions | |
622 | must enclose the expression in parentheses. Beware of similar issues with | |
623 | macros using parameters. | |
624 | ||
625 | #define CONSTANT 0x4000 | |
626 | #define CONSTEXP (CONSTANT | 3) | |
627 | ||
628 | The cpp manual deals with macros exhaustively. The gcc internals manual also | |
629 | covers RTL which is used frequently with assembly language in the kernel. | |
630 | ||
631 | ||
226a6b84 | 632 | Chapter 13: Printing kernel messages |
1da177e4 LT |
633 | |
634 | Kernel developers like to be seen as literate. Do mind the spelling | |
635 | of kernel messages to make a good impression. Do not use crippled | |
6b09448a DB |
636 | words like "dont"; use "do not" or "don't" instead. Make the messages |
637 | concise, clear, and unambiguous. | |
1da177e4 LT |
638 | |
639 | Kernel messages do not have to be terminated with a period. | |
640 | ||
641 | Printing numbers in parentheses (%d) adds no value and should be avoided. | |
642 | ||
6b09448a DB |
643 | There are a number of driver model diagnostic macros in <linux/device.h> |
644 | which you should use to make sure messages are matched to the right device | |
645 | and driver, and are tagged with the right level: dev_err(), dev_warn(), | |
646 | dev_info(), and so forth. For messages that aren't associated with a | |
647 | particular device, <linux/kernel.h> defines pr_debug() and pr_info(). | |
648 | ||
649 | Coming up with good debugging messages can be quite a challenge; and once | |
650 | you have them, they can be a huge help for remote troubleshooting. Such | |
651 | messages should be compiled out when the DEBUG symbol is not defined (that | |
652 | is, by default they are not included). When you use dev_dbg() or pr_debug(), | |
653 | that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG. | |
654 | A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the | |
655 | ones already enabled by DEBUG. | |
656 | ||
1da177e4 | 657 | |
226a6b84 | 658 | Chapter 14: Allocating memory |
af4e5a21 PE |
659 | |
660 | The kernel provides the following general purpose memory allocators: | |
661 | kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API | |
662 | documentation for further information about them. | |
663 | ||
664 | The preferred form for passing a size of a struct is the following: | |
665 | ||
666 | p = kmalloc(sizeof(*p), ...); | |
667 | ||
668 | The alternative form where struct name is spelled out hurts readability and | |
669 | introduces an opportunity for a bug when the pointer variable type is changed | |
670 | but the corresponding sizeof that is passed to a memory allocator is not. | |
671 | ||
672 | Casting the return value which is a void pointer is redundant. The conversion | |
673 | from void pointer to any other pointer type is guaranteed by the C programming | |
674 | language. | |
675 | ||
676 | ||
226a6b84 | 677 | Chapter 15: The inline disease |
a771f2b8 AV |
678 | |
679 | There appears to be a common misperception that gcc has a magic "make me | |
680 | faster" speedup option called "inline". While the use of inlines can be | |
53ab97a1 | 681 | appropriate (for example as a means of replacing macros, see Chapter 12), it |
a771f2b8 AV |
682 | very often is not. Abundant use of the inline keyword leads to a much bigger |
683 | kernel, which in turn slows the system as a whole down, due to a bigger | |
684 | icache footprint for the CPU and simply because there is less memory | |
685 | available for the pagecache. Just think about it; a pagecache miss causes a | |
686 | disk seek, which easily takes 5 miliseconds. There are a LOT of cpu cycles | |
687 | that can go into these 5 miliseconds. | |
688 | ||
689 | A reasonable rule of thumb is to not put inline at functions that have more | |
690 | than 3 lines of code in them. An exception to this rule are the cases where | |
691 | a parameter is known to be a compiletime constant, and as a result of this | |
692 | constantness you *know* the compiler will be able to optimize most of your | |
693 | function away at compile time. For a good example of this later case, see | |
694 | the kmalloc() inline function. | |
695 | ||
696 | Often people argue that adding inline to functions that are static and used | |
697 | only once is always a win since there is no space tradeoff. While this is | |
698 | technically correct, gcc is capable of inlining these automatically without | |
699 | help, and the maintenance issue of removing the inline when a second user | |
700 | appears outweighs the potential value of the hint that tells gcc to do | |
701 | something it would have done anyway. | |
702 | ||
703 | ||
c16a02d6 AS |
704 | Chapter 16: Function return values and names |
705 | ||
706 | Functions can return values of many different kinds, and one of the | |
707 | most common is a value indicating whether the function succeeded or | |
708 | failed. Such a value can be represented as an error-code integer | |
709 | (-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure, | |
710 | non-zero = success). | |
711 | ||
712 | Mixing up these two sorts of representations is a fertile source of | |
713 | difficult-to-find bugs. If the C language included a strong distinction | |
714 | between integers and booleans then the compiler would find these mistakes | |
715 | for us... but it doesn't. To help prevent such bugs, always follow this | |
716 | convention: | |
717 | ||
718 | If the name of a function is an action or an imperative command, | |
719 | the function should return an error-code integer. If the name | |
720 | is a predicate, the function should return a "succeeded" boolean. | |
721 | ||
722 | For example, "add work" is a command, and the add_work() function returns 0 | |
723 | for success or -EBUSY for failure. In the same way, "PCI device present" is | |
724 | a predicate, and the pci_dev_present() function returns 1 if it succeeds in | |
725 | finding a matching device or 0 if it doesn't. | |
726 | ||
727 | All EXPORTed functions must respect this convention, and so should all | |
728 | public functions. Private (static) functions need not, but it is | |
729 | recommended that they do. | |
730 | ||
731 | Functions whose return value is the actual result of a computation, rather | |
732 | than an indication of whether the computation succeeded, are not subject to | |
733 | this rule. Generally they indicate failure by returning some out-of-range | |
734 | result. Typical examples would be functions that return pointers; they use | |
735 | NULL or the ERR_PTR mechanism to report failure. | |
736 | ||
737 | ||
58637ec9 RD |
738 | Chapter 17: Don't re-invent the kernel macros |
739 | ||
740 | The header file include/linux/kernel.h contains a number of macros that | |
741 | you should use, rather than explicitly coding some variant of them yourself. | |
742 | For example, if you need to calculate the length of an array, take advantage | |
743 | of the macro | |
744 | ||
745 | #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) | |
746 | ||
747 | Similarly, if you need to calculate the size of some structure member, use | |
748 | ||
749 | #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) | |
750 | ||
751 | There are also min() and max() macros that do strict type checking if you | |
752 | need them. Feel free to peruse that header file to see what else is already | |
753 | defined that you shouldn't reproduce in your code. | |
754 | ||
755 | ||
4e7bd663 JT |
756 | Chapter 18: Editor modelines and other cruft |
757 | ||
758 | Some editors can interpret configuration information embedded in source files, | |
759 | indicated with special markers. For example, emacs interprets lines marked | |
760 | like this: | |
761 | ||
762 | -*- mode: c -*- | |
763 | ||
764 | Or like this: | |
765 | ||
766 | /* | |
767 | Local Variables: | |
768 | compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" | |
769 | End: | |
770 | */ | |
771 | ||
772 | Vim interprets markers that look like this: | |
773 | ||
774 | /* vim:set sw=8 noet */ | |
775 | ||
776 | Do not include any of these in source files. People have their own personal | |
777 | editor configurations, and your source files should not override them. This | |
778 | includes markers for indentation and mode configuration. People may use their | |
779 | own custom mode, or may have some other magic method for making indentation | |
780 | work correctly. | |
781 | ||
782 | ||
a771f2b8 | 783 | |
226a6b84 | 784 | Appendix I: References |
1da177e4 LT |
785 | |
786 | The C Programming Language, Second Edition | |
787 | by Brian W. Kernighan and Dennis M. Ritchie. | |
788 | Prentice Hall, Inc., 1988. | |
789 | ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). | |
790 | URL: http://cm.bell-labs.com/cm/cs/cbook/ | |
791 | ||
792 | The Practice of Programming | |
793 | by Brian W. Kernighan and Rob Pike. | |
794 | Addison-Wesley, Inc., 1999. | |
795 | ISBN 0-201-61586-X. | |
796 | URL: http://cm.bell-labs.com/cm/cs/tpop/ | |
797 | ||
798 | GNU manuals - where in compliance with K&R and this text - for cpp, gcc, | |
5b0ed2c6 | 799 | gcc internals and indent, all available from http://www.gnu.org/manual/ |
1da177e4 LT |
800 | |
801 | WG14 is the international standardization working group for the programming | |
5b0ed2c6 XVP |
802 | language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ |
803 | ||
804 | Kernel CodingStyle, by greg@kroah.com at OLS 2002: | |
805 | http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ | |
1da177e4 LT |
806 | |
807 | -- | |
6b09448a DB |
808 | Last updated on 2007-July-13. |
809 |