1 This file has moved to process/coding-style.rs !! 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 c-lineup-arglist-tabs-only (ignored)
>> 478 "Line up argument lists by tabs, not spaces"
>> 479 (let* ((anchor (c-langelem-pos c-syntactic-element))
>> 480 (column (c-langelem-2nd-pos c-syntactic-element))
>> 481 (offset (- (1+ column) anchor))
>> 482 (steps (floor offset c-basic-offset)))
>> 483 (* (max steps 1)
>> 484 c-basic-offset)))
>> 485
>> 486 (add-hook 'c-mode-common-hook
>> 487 (lambda ()
>> 488 ;; Add kernel style
>> 489 (c-add-style
>> 490 "linux-tabs-only"
>> 491 '("linux" (c-offsets-alist
>> 492 (arglist-cont-nonempty
>> 493 c-lineup-gcc-asm-reg
>> 494 c-lineup-arglist-tabs-only))))))
>> 495
>> 496 (add-hook 'c-mode-hook
>> 497 (lambda ()
>> 498 (let ((filename (buffer-file-name)))
>> 499 ;; Enable kernel mode for the appropriate files
>> 500 (when (and filename
>> 501 (string-match (expand-file-name "~/src/linux-trees")
>> 502 filename))
>> 503 (setq indent-tabs-mode t)
>> 504 (c-set-style "linux-tabs-only")))))
>> 505
>> 506 This will make emacs go better with the kernel coding style for C
>> 507 files below ~/src/linux-trees.
>> 508
>> 509 But even if you fail in getting emacs to do sane formatting, not
>> 510 everything is lost: use "indent".
>> 511
>> 512 Now, again, GNU indent has the same brain-dead settings that GNU emacs
>> 513 has, which is why you need to give it a few command line options.
>> 514 However, that's not too bad, because even the makers of GNU indent
>> 515 recognize the authority of K&R (the GNU people aren't evil, they are
>> 516 just severely misguided in this matter), so you just give indent the
>> 517 options "-kr -i8" (stands for "K&R, 8 character indents"), or use
>> 518 "scripts/Lindent", which indents in the latest style.
>> 519
>> 520 "indent" has a lot of options, and especially when it comes to comment
>> 521 re-formatting you may want to take a look at the man page. But
>> 522 remember: "indent" is not a fix for bad programming.
>> 523
>> 524
>> 525 Chapter 10: Kconfig configuration files
>> 526
>> 527 For all of the Kconfig* configuration files throughout the source tree,
>> 528 the indentation is somewhat different. Lines under a "config" definition
>> 529 are indented with one tab, while help text is indented an additional two
>> 530 spaces. Example:
>> 531
>> 532 config AUDIT
>> 533 bool "Auditing support"
>> 534 depends on NET
>> 535 help
>> 536 Enable auditing infrastructure that can be used with another
>> 537 kernel subsystem, such as SELinux (which requires this for
>> 538 logging of avc messages output). Does not do system-call
>> 539 auditing without CONFIG_AUDITSYSCALL.
>> 540
>> 541 Features that might still be considered unstable should be defined as
>> 542 dependent on "EXPERIMENTAL":
>> 543
>> 544 config SLUB
>> 545 depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT
>> 546 bool "SLUB (Unqueued Allocator)"
>> 547 ...
>> 548
>> 549 while seriously dangerous features (such as write support for certain
>> 550 filesystems) should advertise this prominently in their prompt string:
>> 551
>> 552 config ADFS_FS_RW
>> 553 bool "ADFS write support (DANGEROUS)"
>> 554 depends on ADFS_FS
>> 555 ...
>> 556
>> 557 For full documentation on the configuration files, see the file
>> 558 Documentation/kbuild/kconfig-language.txt.
>> 559
>> 560
>> 561 Chapter 11: Data structures
>> 562
>> 563 Data structures that have visibility outside the single-threaded
>> 564 environment they are created and destroyed in should always have
>> 565 reference counts. In the kernel, garbage collection doesn't exist (and
>> 566 outside the kernel garbage collection is slow and inefficient), which
>> 567 means that you absolutely _have_ to reference count all your uses.
>> 568
>> 569 Reference counting means that you can avoid locking, and allows multiple
>> 570 users to have access to the data structure in parallel - and not having
>> 571 to worry about the structure suddenly going away from under them just
>> 572 because they slept or did something else for a while.
>> 573
>> 574 Note that locking is _not_ a replacement for reference counting.
>> 575 Locking is used to keep data structures coherent, while reference
>> 576 counting is a memory management technique. Usually both are needed, and
>> 577 they are not to be confused with each other.
>> 578
>> 579 Many data structures can indeed have two levels of reference counting,
>> 580 when there are users of different "classes". The subclass count counts
>> 581 the number of subclass users, and decrements the global count just once
>> 582 when the subclass count goes to zero.
>> 583
>> 584 Examples of this kind of "multi-level-reference-counting" can be found in
>> 585 memory management ("struct mm_struct": mm_users and mm_count), and in
>> 586 filesystem code ("struct super_block": s_count and s_active).
>> 587
>> 588 Remember: if another thread can find your data structure, and you don't
>> 589 have a reference count on it, you almost certainly have a bug.
>> 590
>> 591
>> 592 Chapter 12: Macros, Enums and RTL
>> 593
>> 594 Names of macros defining constants and labels in enums are capitalized.
>> 595
>> 596 #define CONSTANT 0x12345
>> 597
>> 598 Enums are preferred when defining several related constants.
>> 599
>> 600 CAPITALIZED macro names are appreciated but macros resembling functions
>> 601 may be named in lower case.
>> 602
>> 603 Generally, inline functions are preferable to macros resembling functions.
>> 604
>> 605 Macros with multiple statements should be enclosed in a do - while block:
>> 606
>> 607 #define macrofun(a, b, c) \
>> 608 do { \
>> 609 if (a == 5) \
>> 610 do_this(b, c); \
>> 611 } while (0)
>> 612
>> 613 Things to avoid when using macros:
>> 614
>> 615 1) macros that affect control flow:
>> 616
>> 617 #define FOO(x) \
>> 618 do { \
>> 619 if (blah(x) < 0) \
>> 620 return -EBUGGERED; \
>> 621 } while(0)
>> 622
>> 623 is a _very_ bad idea. It looks like a function call but exits the "calling"
>> 624 function; don't break the internal parsers of those who will read the code.
>> 625
>> 626 2) macros that depend on having a local variable with a magic name:
>> 627
>> 628 #define FOO(val) bar(index, val)
>> 629
>> 630 might look like a good thing, but it's confusing as hell when one reads the
>> 631 code and it's prone to breakage from seemingly innocent changes.
>> 632
>> 633 3) macros with arguments that are used as l-values: FOO(x) = y; will
>> 634 bite you if somebody e.g. turns FOO into an inline function.
>> 635
>> 636 4) forgetting about precedence: macros defining constants using expressions
>> 637 must enclose the expression in parentheses. Beware of similar issues with
>> 638 macros using parameters.
>> 639
>> 640 #define CONSTANT 0x4000
>> 641 #define CONSTEXP (CONSTANT | 3)
>> 642
>> 643 The cpp manual deals with macros exhaustively. The gcc internals manual also
>> 644 covers RTL which is used frequently with assembly language in the kernel.
>> 645
>> 646
>> 647 Chapter 13: Printing kernel messages
>> 648
>> 649 Kernel developers like to be seen as literate. Do mind the spelling
>> 650 of kernel messages to make a good impression. Do not use crippled
>> 651 words like "dont"; use "do not" or "don't" instead. Make the messages
>> 652 concise, clear, and unambiguous.
>> 653
>> 654 Kernel messages do not have to be terminated with a period.
>> 655
>> 656 Printing numbers in parentheses (%d) adds no value and should be avoided.
>> 657
>> 658 There are a number of driver model diagnostic macros in <linux/device.h>
>> 659 which you should use to make sure messages are matched to the right device
>> 660 and driver, and are tagged with the right level: dev_err(), dev_warn(),
>> 661 dev_info(), and so forth. For messages that aren't associated with a
>> 662 particular device, <linux/kernel.h> defines pr_debug() and pr_info().
>> 663
>> 664 Coming up with good debugging messages can be quite a challenge; and once
>> 665 you have them, they can be a huge help for remote troubleshooting. Such
>> 666 messages should be compiled out when the DEBUG symbol is not defined (that
>> 667 is, by default they are not included). When you use dev_dbg() or pr_debug(),
>> 668 that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG.
>> 669 A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
>> 670 ones already enabled by DEBUG.
>> 671
>> 672
>> 673 Chapter 14: Allocating memory
>> 674
>> 675 The kernel provides the following general purpose memory allocators:
>> 676 kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
>> 677 documentation for further information about them.
>> 678
>> 679 The preferred form for passing a size of a struct is the following:
>> 680
>> 681 p = kmalloc(sizeof(*p), ...);
>> 682
>> 683 The alternative form where struct name is spelled out hurts readability and
>> 684 introduces an opportunity for a bug when the pointer variable type is changed
>> 685 but the corresponding sizeof that is passed to a memory allocator is not.
>> 686
>> 687 Casting the return value which is a void pointer is redundant. The conversion
>> 688 from void pointer to any other pointer type is guaranteed by the C programming
>> 689 language.
>> 690
>> 691
>> 692 Chapter 15: The inline disease
>> 693
>> 694 There appears to be a common misperception that gcc has a magic "make me
>> 695 faster" speedup option called "inline". While the use of inlines can be
>> 696 appropriate (for example as a means of replacing macros, see Chapter 12), it
>> 697 very often is not. Abundant use of the inline keyword leads to a much bigger
>> 698 kernel, which in turn slows the system as a whole down, due to a bigger
>> 699 icache footprint for the CPU and simply because there is less memory
>> 700 available for the pagecache. Just think about it; a pagecache miss causes a
>> 701 disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
>> 702 that can go into these 5 milliseconds.
>> 703
>> 704 A reasonable rule of thumb is to not put inline at functions that have more
>> 705 than 3 lines of code in them. An exception to this rule are the cases where
>> 706 a parameter is known to be a compiletime constant, and as a result of this
>> 707 constantness you *know* the compiler will be able to optimize most of your
>> 708 function away at compile time. For a good example of this later case, see
>> 709 the kmalloc() inline function.
>> 710
>> 711 Often people argue that adding inline to functions that are static and used
>> 712 only once is always a win since there is no space tradeoff. While this is
>> 713 technically correct, gcc is capable of inlining these automatically without
>> 714 help, and the maintenance issue of removing the inline when a second user
>> 715 appears outweighs the potential value of the hint that tells gcc to do
>> 716 something it would have done anyway.
>> 717
>> 718
>> 719 Chapter 16: Function return values and names
>> 720
>> 721 Functions can return values of many different kinds, and one of the
>> 722 most common is a value indicating whether the function succeeded or
>> 723 failed. Such a value can be represented as an error-code integer
>> 724 (-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
>> 725 non-zero = success).
>> 726
>> 727 Mixing up these two sorts of representations is a fertile source of
>> 728 difficult-to-find bugs. If the C language included a strong distinction
>> 729 between integers and booleans then the compiler would find these mistakes
>> 730 for us... but it doesn't. To help prevent such bugs, always follow this
>> 731 convention:
>> 732
>> 733 If the name of a function is an action or an imperative command,
>> 734 the function should return an error-code integer. If the name
>> 735 is a predicate, the function should return a "succeeded" boolean.
>> 736
>> 737 For example, "add work" is a command, and the add_work() function returns 0
>> 738 for success or -EBUSY for failure. In the same way, "PCI device present" is
>> 739 a predicate, and the pci_dev_present() function returns 1 if it succeeds in
>> 740 finding a matching device or 0 if it doesn't.
>> 741
>> 742 All EXPORTed functions must respect this convention, and so should all
>> 743 public functions. Private (static) functions need not, but it is
>> 744 recommended that they do.
>> 745
>> 746 Functions whose return value is the actual result of a computation, rather
>> 747 than an indication of whether the computation succeeded, are not subject to
>> 748 this rule. Generally they indicate failure by returning some out-of-range
>> 749 result. Typical examples would be functions that return pointers; they use
>> 750 NULL or the ERR_PTR mechanism to report failure.
>> 751
>> 752
>> 753 Chapter 17: Don't re-invent the kernel macros
>> 754
>> 755 The header file include/linux/kernel.h contains a number of macros that
>> 756 you should use, rather than explicitly coding some variant of them yourself.
>> 757 For example, if you need to calculate the length of an array, take advantage
>> 758 of the macro
>> 759
>> 760 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
>> 761
>> 762 Similarly, if you need to calculate the size of some structure member, use
>> 763
>> 764 #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
>> 765
>> 766 There are also min() and max() macros that do strict type checking if you
>> 767 need them. Feel free to peruse that header file to see what else is already
>> 768 defined that you shouldn't reproduce in your code.
>> 769
>> 770
>> 771 Chapter 18: Editor modelines and other cruft
>> 772
>> 773 Some editors can interpret configuration information embedded in source files,
>> 774 indicated with special markers. For example, emacs interprets lines marked
>> 775 like this:
>> 776
>> 777 -*- mode: c -*-
>> 778
>> 779 Or like this:
>> 780
>> 781 /*
>> 782 Local Variables:
>> 783 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
>> 784 End:
>> 785 */
>> 786
>> 787 Vim interprets markers that look like this:
>> 788
>> 789 /* vim:set sw=8 noet */
>> 790
>> 791 Do not include any of these in source files. People have their own personal
>> 792 editor configurations, and your source files should not override them. This
>> 793 includes markers for indentation and mode configuration. People may use their
>> 794 own custom mode, or may have some other magic method for making indentation
>> 795 work correctly.
>> 796
>> 797
>> 798
>> 799 Appendix I: References
>> 800
>> 801 The C Programming Language, Second Edition
>> 802 by Brian W. Kernighan and Dennis M. Ritchie.
>> 803 Prentice Hall, Inc., 1988.
>> 804 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
>> 805 URL: http://cm.bell-labs.com/cm/cs/cbook/
>> 806
>> 807 The Practice of Programming
>> 808 by Brian W. Kernighan and Rob Pike.
>> 809 Addison-Wesley, Inc., 1999.
>> 810 ISBN 0-201-61586-X.
>> 811 URL: http://cm.bell-labs.com/cm/cs/tpop/
>> 812
>> 813 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
>> 814 gcc internals and indent, all available from http://www.gnu.org/manual/
>> 815
>> 816 WG14 is the international standardization working group for the programming
>> 817 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
>> 818
>> 819 Kernel CodingStyle, by greg@kroah.com at OLS 2002:
>> 820 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
>> 821
>> 822 --
>> 823 Last updated on 2007-July-13.
>> 824
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.