"Fossies" - the Fresh Open Source Software Archive

Member "syslinux-6.03/doc/CodingStyle.txt" (6 Oct 2014, 30063 Bytes) of package /linux/misc/syslinux-6.03.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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