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