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