-
- Linux kernel coding style
+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.
- unconditional statements are easier to understand and follow
- nesting is reduced
- errors by not updating individual exit points when making
- modifications are prevented
+ 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:
-(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)))
-
-(add-hook 'c-mode-common-hook
- (lambda ()
- ;; Add kernel style
- (c-add-style
- "linux-tabs-only"
- '("linux" (c-offsets-alist
- (arglist-cont-nonempty
- c-lineup-gcc-asm-reg
- c-lineup-arglist-tabs-only))))))
-
-(add-hook 'c-mode-hook
- (lambda ()
- (let ((filename (buffer-file-name)))
- ;; Enable kernel mode for the appropriate files
- (when (and filename
- (string-match (expand-file-name "~/src/linux-trees")
- filename))
- (setq indent-tabs-mode t)
- (setq show-trailing-whitespace t)
- (c-set-style "linux-tabs-only")))))
+.. 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))
+ (column (c-langelem-2nd-pos c-syntactic-element))
+ (offset (- (1+ column) anchor))
+ (steps (floor offset c-basic-offset)))
+ (* (max steps 1)
+ c-basic-offset)))
+
+ (add-hook 'c-mode-common-hook
+ (lambda ()
+ ;; Add kernel style
+ (c-add-style
+ "linux-tabs-only"
+ '("linux" (c-offsets-alist
+ (arglist-cont-nonempty
+ c-lineup-gcc-asm-reg
+ c-lineup-arglist-tabs-only))))))
+
+ (add-hook 'c-mode-hook
+ (lambda ()
+ (let ((filename (buffer-file-name)))
+ ;; Enable kernel mode for the appropriate files
+ (when (and filename
+ (string-match (expand-file-name "~/src/linux-trees")
+ filename))
+ (setq indent-tabs-mode t)
+ (setq show-trailing-whitespace t)
+ (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
+ config AUDIT
bool "Auditing support"
depends on NET
help
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
+ config ADFS_FS_RW
bool "ADFS write support (DANGEROUS)"
depends on ADFS_FS
...
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:
- #define macrofun(a, b, c) \
+.. code-block:: c
+
+ #define macrofun(a, b, c) \
do { \
if (a == 5) \
do_this(b, c); \
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:
-#define FOO(x) \
-({ \
- typeof(x) ret; \
- ret = calc_ret(x); \
- (ret); \
-})
+.. code-block:: c
+
+ #define FOO(x) \
+ ({ \
+ typeof(x) ret; \
+ ret = calc_ret(x); \
+ (ret); \
+ })
ret is a common name for a local variable - __foo_ret is less likely
to collide with an existing variable.
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/
-
projects / GitHub / MotorolaMobilityLLC / kernel-slsi.git / commitdiff