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