Linux Kernel Documentation

https://www.kernel.org/doc/Documentation/
Admin
This project provides comprehensive documentation for the Linux Kernel, covering its architecture,...
Tokens:4,803
Snippets:76
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Define Kconfig Configuration

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Example of defining a kernel configuration option with dependencies and help text.

```kconfig
config AUDIT
	bool "Auditing support"
	depends on NET
	help
	  Enable auditing infrastructure that can be used with another
	  kernel subsystem, such as SELinux (which requires this for
	  logging of avc messages output).  Does not do system-call
	  auditing without CONFIG_AUDITSYSCALL.
```

```kconfig
config ADFS_FS_RW
	bool "ADFS write support (DANGEROUS)"
	depends on ADFS_FS
	...
```

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

### Function Prototype Declaration

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Example of a function prototype following the preferred order of storage classes, attributes, and parameters.

```c
__init void * __must_check action(enum magic value, size_t size, u8 count,
				   char *fmt, ...) __printf(4, 5) __malloc;
```

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

### Vim Editor Modeline

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Example of a Vim-specific configuration marker that should not be included in source files.

```c
/* vim:set sw=8 noet */
```

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

### Function Definition Structure

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Example of a function definition where attributes are placed before the function parameters.

```c
static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
		size_t size, u8 count, char *fmt, ...) __malloc
 {
	...
 }
```

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

### One Error Bug Example

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

An example of a common bug where an error label attempts to free a pointer that might be NULL.

```c
err:
		kfree(foo->bar);
		kfree(foo);
		return ret;
```

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

### Emacs Editor Modelines

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Examples of editor-specific configuration markers that should not be included in source files.

```c
-*- mode: c -*-
```

```c
/*
Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
End:
*/
```

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

### Configure Emacs for Linux Kernel Coding Style

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Add this configuration to your .emacs file to set up indentation and syntactic rules for C files within the specified directory.

```elisp
(defun c-lineup-arglist-tabs-only (ignored)
  "Line up argument lists by tabs, not spaces"
  (let* ((anchor (c-langelem-pos c-syntactic-element))
         (column (c-langelem-2nd-pos c-syntactic-element))
         (offset (- (1+ column) anchor))
         (steps (floor offset c-basic-offset)))
    (* (max steps 1)
       c-basic-offset)))

(dir-locals-set-class-variables
 'linux-kernel
 '((c-mode . (
        (c-basic-offset . 8)
        (c-label-minimum-indentation . 0)
        (c-offsets-alist . (
                (arglist-close         . c-lineup-arglist-tabs-only)
                (arglist-cont-nonempty .
                    (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
                (arglist-intro         . +)
                (brace-list-intro      . +)
                (c                     . c-lineup-C-comments)
                (case-label            . 0)
                (comment-intro         . c-lineup-comment)
                (cpp-define-intro      . +)
                (cpp-macro             . -1000)
                (cpp-macro-cont        . +)
                (defun-block-intro     . +)
                (else-clause           . 0)
                (func-decl-cont        . +)
                (inclass               . +)
                (inher-cont            . c-lineup-multi-inher)
                (knr-argdecl-intro     . 0)
                (label                 . -1000)
                (statement             . 0)
                (statement-block-intro . +)
                (statement-case-intro  . +)
                (statement-cont        . +)
                (substatement          . +)
                ))
        (indent-tabs-mode . t)
        (show-trailing-whitespace . t)
        ))))

(dir-locals-set-directory-class
 (expand-file-name "~/src/linux-trees")
 'linux-kernel)
```

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

### Centralized Function Exiting with Goto

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Using goto for centralized cleanup when a function has multiple exit paths.

```c
int fun(int a)
	{
		int result = 0;
		char *buffer;

		buffer = kmalloc(SIZE, GFP_KERNEL);
		if (!buffer)
			return -ENOMEM;

		if (condition1) {
			while (loop1) {
				...
			}
			result = 1;
			goto out_free_buffer;
		}
		...
	out_free_buffer:
		kfree(buffer);
		return result;
	}
```

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

### Function brace placement

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Functions require the opening brace to be placed at the beginning of the next line.

```c
int function(int x)
{
	body of function
}
```

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

### Define Constant Macro

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Standard format for defining a constant macro in C.

```c
#define CONSTANT 0x12345
```

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

### Compare Typedef vs Struct Declaration

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Demonstrates the difference in readability between using a typedef and a direct struct pointer declaration.

```c
vps_t a;
```

```c
struct virtual_container *a;
```

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

### Standard brace placement for control blocks

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Place the opening brace at the end of the line for non-function statement blocks.

```c
if (x is true) {
	we do y
}
```

```c
switch (action) {
case KOBJ_ADD:
	return "add";
case KOBJ_REMOVE:
	return "remove";
case KOBJ_CHANGE:
	return "change";
default:
	return NULL;
}
```

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

### Format multi-line inline assembly

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use separate quoted strings with newline and tab escape sequences to ensure proper indentation in the generated assembly output.

```c
asm ("magic %reg1, #42\n\t"
     "more_magic %reg2, %reg3"
     : /* outputs */ : /* inputs */ : /* clobbers */);
```

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

### Brace placement for do-while and if-else

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Closing braces are followed by statement continuations like while or else on the same line.

```c
do {
	body of do-loop
} while (condition);
```

```c
if (x == y) {
	..
} else if (x > y) {
	...
} else {
	....
}
```

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

### Allocate a structure with kmalloc_obj

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use this pattern to allocate memory for a structure to avoid bugs when pointer types change.

```c
p = kmalloc_obj(*p, ...);
```

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

### Use IS_ENABLED for conditional logic

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Convert Kconfig symbols into C boolean expressions to allow the compiler to constant-fold the conditional while maintaining syntax checking.

```c
if (IS_ENABLED(CONFIG_SOMETHING)) {
	...
}
```

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

### Keyword Spacing

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use a space after keywords like if, switch, case, for, do, and while, but not after sizeof, typeof, alignof, or __attribute__.

```c
s = sizeof(struct file);
```

```c
s = sizeof( struct file );
```

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

### Allocate an array with kmalloc_objs

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use this pattern for array allocation to ensure overflow checks on the allocation size.

```c
p = kmalloc_objs(*p, n, ...);
```

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

### Pointer Declaration Style

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Place the asterisk adjacent to the data or function name rather than the type name.

```c
char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);
```

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

### Allocate a zeroed array with kzalloc_objs

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use this pattern for zeroed array allocation to ensure overflow checks on the allocation size.

```c
p = kzalloc_objs(*p, n, ...);
```

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

### Exporting Kernel Functions

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Shows the standard practice of placing the EXPORT_SYMBOL macro immediately after the closing brace of an exported function.

```c
int system_is_up(void)
{
	return system_state == SYSTEM_RUNNING;
}
EXPORT_SYMBOL(system_is_up);
```

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

### Loop Brace Usage

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use braces when a loop contains more than a single simple statement.

```c
while (condition) {
	if (test)
		do_something();
}
```

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

### Define Multi-statement Macro

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Macros containing multiple statements must be wrapped in a do-while(0) block.

```c
#define macrofun(a, b, c)			\
	do {					\
		if (a == 5)			\
			do_this(b, c);		\
	} while (0)
```

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

### Calculate Array Size Macro

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use this macro to determine the number of elements in an array instead of manual calculation.

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

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

### Corrected Error Label Pattern

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Splitting error labels to handle potential NULL pointers safely.

```c
err_free_bar:
		kfree(foo->bar);
	err_free_foo:
		kfree(foo);
		return ret;
```

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

### Define Static Inline Function

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use static inline functions instead of macros to handle unused parameters or side effects.

```c
static inline void fun(struct foo *foo)
{
}
```

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

### Required braces for multiple statements

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Always use braces when a block contains multiple statements.

```c
if (condition) {
	do_this();
	do_that();
}
```

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

### Aligning switch case labels

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Align switch and case labels in the same column to avoid excessive indentation.

```c
switch (suffix) {
case 'G':
case 'g':
	mem <<= 30;
	break;
case 'M':
case 'm':
	mem <<= 20;
	break;
case 'K':
case 'k':
	mem <<= 10;
	fallthrough;
default:
	break;
}
```

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

### Define Constant Expression Macro

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Macros defining constants using expressions must enclose the expression in parentheses.

```c
#define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3)
```

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

### Avoid Control Flow Macros

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Macros that exit the calling function are considered bad practice.

```c
#define FOO(x)					\
	do {					\
		if (blah(x) < 0)		\
			return -EBUGGERED;	\
	} while (0)
```

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

### Calculate Structure Member Size Macro

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use this macro to determine the size of a specific member within a structure.

```c
#define sizeof_field(t, f) (sizeof(((t*)0)->f))
```

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

### Comment non-trivial preprocessor blocks

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Append a comment to the #endif directive for blocks spanning multiple lines to improve readability.

```c
#ifdef CONFIG_SOMETHING
...
#endif /* CONFIG_SOMETHING */
```

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

### Prohibited single-line statements

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Avoid placing multiple statements on a single line.

```c
if (condition) do_this;
  do_something_everytime;
```

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

### Avoid Implicit Variable Macros

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Macros relying on local variables with magic names are prone to breakage.

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

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

### Conditional Statement Brace Usage

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use braces for single-statement branches if the other branch contains multiple statements. Omit braces for single-statement conditionals.

```c
if (condition)
	action();
```

```c
if (condition)
	do_this();
else
	do_that();
```

```c
if (condition) {
	do_this();
	do_that();
} else {
	otherwise();
}
```

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

### Avoid Namespace Collisions in Macros

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Use unique variable names within macros to prevent collisions with existing variables.

```c
#define FOO(x)				\
({					\
	typeof(x) ret;			\
	ret = calc_ret(x);		\
	(ret);				\
})
```

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

### Avoid Void Cast Macro

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Discouraged approach for handling unused parameters in macros.

```c
/*
 * Avoid doing this whenever possible and instead opt for static
 * inline functions
 */
#define macrofun(foo) do { (void) (foo); } while (0)
```

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

### Prohibited comma usage for braces

Source: https://www.kernel.org/doc/Documentation/process/coding-style.rst

Do not use commas to bypass the requirement for braces in conditional blocks.

```c
if (condition)
	do_this(), do_that();
```
Tokens:
Raw