Documentation/CodingStyle: Convert to ReST markup

Linux kernel coding style

=========================

This is a short document describing the preferred coding style for the

linux kernel.  Coding style is very personal, and I won't _force_ my

Anyway, here goes:

		Chapter 1: Indentation

1) Indentation

--------------

Tabs are 8 characters, and thus indentations are also 8 characters.

There are heretic movements that try to make indentations 4 (or even 2!)

to align the "switch" and its subordinate "case" labels in the same column

instead of "double-indenting" the "case" labels.  E.g.:

.. code-block:: c

	switch (suffix) {

	case 'G':

	case 'g':

Don't put multiple statements on a single line unless you have

something to hide:

.. code-block:: c

	if (condition) do_this;

	  do_something_everytime;

Get a decent editor and don't leave whitespace at the end of lines.

		Chapter 2: Breaking long lines and strings

2) Breaking long lines and strings

----------------------------------

Coding style is all about readability and maintainability using commonly

available tools.

printk messages, because that breaks the ability to grep for them.

		Chapter 3: Placing Braces and Spaces

3) Placing Braces and Spaces

----------------------------

The other issue that always comes up in C styling is the placement of

braces.  Unlike the indent size, there are few technical reasons to

shown to us by the prophets Kernighan and Ritchie, is to put the opening

brace last on the line, and put the closing brace first, thusly:

.. code-block:: c

	if (x is true) {

		we do y

	}

This applies to all non-function statement blocks (if, switch, for,

while, do).  E.g.:

.. code-block:: c

	switch (action) {

	case KOBJ_ADD:

		return "add";

However, there is one special case, namely functions: they have the

opening brace at the beginning of the next line, thus:

.. code-block:: c

	int function(int x)

	{

		body of function

ie a "while" in a do-statement or an "else" in an if-statement, like

this:

.. code-block:: c

	do {

		body of do-loop

	} while (condition);

and

.. code-block:: c

	if (x == y) {

		..

	} else if (x > y) {

Do not unnecessarily use braces where a single statement will do.

.. code-block:: c

	if (condition)

		action();

and

.. code-block:: none

	if (condition)

		do_this();

	else

This does not apply if only one branch of a conditional statement is a single

statement; in the latter case use braces in both branches:

.. code-block:: c

	if (condition) {

		do_this();

		do_that();

		otherwise();

	}

		3.1:  Spaces

3.1) Spaces

***********

Linux kernel style for use of spaces depends (mostly) on

function-versus-keyword usage.  Use a space after (most) keywords.  The

notable exceptions are sizeof, typeof, alignof, and __attribute__, which look

somewhat like functions (and are usually used with parentheses in Linux,

although they are not required in the language, as in: "sizeof info" after

"struct fileinfo info;" is declared).

although they are not required in the language, as in: ``sizeof info`` after

``struct fileinfo info;`` is declared).

So use a space after these keywords:

So use a space after these keywords::

	if, switch, case, for, do, while

but not with sizeof, typeof, alignof, or __attribute__.  E.g.,

.. code-block:: c

	s = sizeof(struct file);

Do not add spaces around (inside) parenthesized expressions.  This example is

*bad*:

**bad**:

.. code-block:: c

	s = sizeof( struct file );

When declaring pointer data or a function that returns a pointer type, the

preferred use of '*' is adjacent to the data name or function name and not

preferred use of '\*' is adjacent to the data name or function name and not

adjacent to the type name.  Examples:

.. code-block:: c

	char *linux_banner;

	unsigned long long memparse(char *ptr, char **retptr);

	char *match_strdup(substring_t *s);

Use one space around (on each side of) most binary and ternary operators,

such as any of these:

such as any of these::

	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :

but no space after unary operators:

but no space after unary operators::

	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined

no space before the postfix increment & decrement unary operators:

no space before the postfix increment & decrement unary operators::

	++  --

no space after the prefix increment & decrement unary operators:

no space after the prefix increment & decrement unary operators::

	++  --

context lines.

		Chapter 4: Naming

4) Naming

---------

C is a Spartan language, and so should your naming be.  Unlike Modula-2

and Pascal programmers, C programmers do not use cute names like

See chapter 6 (Functions).

		Chapter 5: Typedefs

5) Typedefs

-----------

Please don't use things like "vps_t".

It's a _mistake_ to use typedef for structures and pointers. When you see a

.. code-block:: c

	vps_t a;

in the source, what does it mean?

In contrast, if it says

.. code-block:: c

	struct virtual_container *a;

you can actually tell what "a" is.

be directly accessed should _never_ be a typedef.

		Chapter 6: Functions

6) Functions

------------

Functions should be short and sweet, and do just one thing.  They should

fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,

to understand what you did 2 weeks from now.

In source files, separate functions with one blank line.  If the function is

exported, the EXPORT* macro for it should follow immediately after the closing

function brace line.  E.g.:

exported, the **EXPORT** macro for it should follow immediately after the

closing function brace line.  E.g.:

.. code-block:: c

	int system_is_up(void)

	{

because it is a simple way to add valuable information for the reader.

		Chapter 7: Centralized exiting of functions

7) Centralized exiting of functions

-----------------------------------

Albeit deprecated by some people, the equivalent of the goto statement is

used frequently by compilers in form of the unconditional jump instruction.

  modifications are prevented

- saves the compiler work to optimize redundant code away ;)

.. code-block:: c

	int fun(int a)

	{

		int result = 0;

A common type of bug to be aware of is "one err bugs" which look like this:

.. code-block:: c

	 err:

		kfree(foo->bar);

		kfree(foo);

fix for this is to split it up into two error labels "err_free_bar:" and

"err_free_foo:":

.. code-block:: c

	 err_free_bar:

		kfree(foo->bar);

	 err_free_foo:

Ideally you should simulate errors to test all exit paths.

		Chapter 8: Commenting

8) Commenting

-------------

Comments are good, but there is also a danger of over-commenting.  NEVER

try to explain HOW your code works in a comment: it's much better to

The preferred style for long (multi-line) comments is:

.. code-block:: c

	/*

	 * This is the preferred style for multi-line

	 * comments in the Linux kernel source code.

For files in net/ and drivers/net/ the preferred style for long (multi-line)

comments is a little different.

.. code-block:: c

	/* The preferred comment style for files in net/ and drivers/net

	 * looks like this.

	 *

item, explaining its use.

		Chapter 9: You've made a mess of it

9) You've made a mess of it

---------------------------

That's OK, we all do.  You've probably been told by your long-time Unix

user helper that "GNU emacs" automatically formats the C sources for

So, you can either get rid of GNU emacs, or change it to use saner

values.  To do the latter, you can stick the following in your .emacs file:

.. code-block:: none

  (defun c-lineup-arglist-tabs-only (ignored)

    "Line up argument lists by tabs, not spaces"

    (let* ((anchor (c-langelem-pos c-syntactic-element))

                  (c-set-style "linux-tabs-only")))))

This will make emacs go better with the kernel coding style for C

files below ~/src/linux-trees.

files below ``~/src/linux-trees``.

But even if you fail in getting emacs to do sane formatting, not

everything is lost: use "indent".

remember: "indent" is not a fix for bad programming.

		Chapter 10: Kconfig configuration files

10) Kconfig configuration files

-------------------------------

For all of the Kconfig* configuration files throughout the source tree,

the indentation is somewhat different.  Lines under a "config" definition

are indented with one tab, while help text is indented an additional two

spaces.  Example:

spaces.  Example::

  config AUDIT

	bool "Auditing support"

	  auditing without CONFIG_AUDITSYSCALL.

Seriously dangerous features (such as write support for certain

filesystems) should advertise this prominently in their prompt string:

filesystems) should advertise this prominently in their prompt string::

  config ADFS_FS_RW

	bool "ADFS write support (DANGEROUS)"

Documentation/kbuild/kconfig-language.txt.

		Chapter 11: Data structures

11) Data structures

-------------------

Data structures that have visibility outside the single-threaded

environment they are created and destroyed in should always have

have a reference count on it, you almost certainly have a bug.

		Chapter 12: Macros, Enums and RTL

12) Macros, Enums and RTL

-------------------------

Names of macros defining constants and labels in enums are capitalized.

.. code-block:: c

	#define CONSTANT 0x12345

Enums are preferred when defining several related constants.

Macros with multiple statements should be enclosed in a do - while block:

.. code-block:: c

	#define macrofun(a, b, c)			\

		do {					\

			if (a == 5)			\

1) macros that affect control flow:

.. code-block:: c

	#define FOO(x)					\

		do {					\

			if (blah(x) < 0)		\

2) macros that depend on having a local variable with a magic name:

.. code-block:: c

	#define FOO(val) bar(index, val)

might look like a good thing, but it's confusing as hell when one reads the

must enclose the expression in parentheses. Beware of similar issues with

macros using parameters.

.. code-block:: c

	#define CONSTANT 0x4000

	#define CONSTEXP (CONSTANT | 3)

5) namespace collisions when defining local variables in macros resembling

functions:

.. code-block:: c

	#define FOO(x)				\

	({					\

		typeof(x) ret;			\

covers RTL which is used frequently with assembly language in the kernel.

		Chapter 13: Printing kernel messages

13) Printing kernel messages

----------------------------

Kernel developers like to be seen as literate. Do mind the spelling

of kernel messages to make a good impression. Do not use crippled

used.

		Chapter 14: Allocating memory

14) Allocating memory

---------------------

The kernel provides the following general purpose memory allocators:

kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and

The preferred form for passing a size of a struct is the following:

.. code-block:: c

	p = kmalloc(sizeof(*p), ...);

The alternative form where struct name is spelled out hurts readability and

The preferred form for allocating an array is the following:

.. code-block:: c

	p = kmalloc_array(n, sizeof(...), ...);

The preferred form for allocating a zeroed array is the following:

.. code-block:: c

	p = kcalloc(n, sizeof(...), ...);

Both forms check for overflow on the allocation size n * sizeof(...),

and return NULL if that occurred.

		Chapter 15: The inline disease

15) The inline disease

----------------------

There appears to be a common misperception that gcc has a magic "make me

faster" speedup option called "inline". While the use of inlines can be

something it would have done anyway.

		Chapter 16: Function return values and names

16) Function return values and names

------------------------------------

Functions can return values of many different kinds, and one of the

most common is a value indicating whether the function succeeded or

difficult-to-find bugs.  If the C language included a strong distinction

between integers and booleans then the compiler would find these mistakes

for us... but it doesn't.  To help prevent such bugs, always follow this

convention:

convention::

	If the name of a function is an action or an imperative command,

	the function should return an error-code integer.  If the name

NULL or the ERR_PTR mechanism to report failure.

		Chapter 17:  Don't re-invent the kernel macros

17) Don't re-invent the kernel macros

-------------------------------------

The header file include/linux/kernel.h contains a number of macros that

you should use, rather than explicitly coding some variant of them yourself.

For example, if you need to calculate the length of an array, take advantage

of the macro

.. code-block:: c

	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))

Similarly, if you need to calculate the size of some structure member, use

.. code-block:: c

	#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))

There are also min() and max() macros that do strict type checking if you

defined that you shouldn't reproduce in your code.

		Chapter 18:  Editor modelines and other cruft

18) Editor modelines and other cruft

------------------------------------

Some editors can interpret configuration information embedded in source files,

indicated with special markers.  For example, emacs interprets lines marked

like this:

.. code-block:: c

	-*- mode: c -*-

Or like this:

.. code-block:: c

	/*

	Local Variables:

	compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"

Vim interprets markers that look like this:

.. code-block:: c

	/* vim:set sw=8 noet */

Do not include any of these in source files.  People have their own personal

work correctly.

		Chapter 19:  Inline assembly

19) Inline assembly

-------------------

In architecture-specific code, you may need to use inline assembly to interface

with CPU or platform functionality.  Don't hesitate to do so when necessary.

string, and end each string except the last with \n\t to properly indent the

next instruction in the assembly output:

.. code-block:: c

	asm ("magic %reg1, #42\n\t"

	     "more_magic %reg2, %reg3"

	     : /* outputs */ : /* inputs */ : /* clobbers */);

		Chapter 20: Conditional Compilation

20) Conditional Compilation

---------------------------

Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c

files; doing so makes code harder to read and logic harder to follow.  Instead,

Within code, where possible, use the IS_ENABLED macro to convert a Kconfig

symbol into a C boolean expression, and use it in a normal C conditional:

.. code-block:: c

	if (IS_ENABLED(CONFIG_SOMETHING)) {

		...

	}

place a comment after the #endif on the same line, noting the conditional

expression used.  For instance:

.. code-block:: c

	#ifdef CONFIG_SOMETHING

	...

	#endif /* CONFIG_SOMETHING */

		Appendix I: References

Appendix I) References

----------------------

The C Programming Language, Second Edition

by Brian W. Kernighan and Dennis M. Ritchie.

Kernel CodingStyle, by greg@kroah.com at OLS 2002:

http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/