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