3 Linux kernel coding style
4 =========================
6 This is a short document describing the preferred coding style for the
7 linux kernel. Coding style is very personal, and I won't **force** my
8 views on anybody, but this is what goes for anything that I have to be
9 able to maintain, and I'd prefer it for most other things too. Please
10 at least consider the points made here.
12 First off, I'd suggest printing out a copy of the GNU coding standards,
13 and NOT read it. Burn them, it's a great symbolic gesture.
21 Tabs are 8 characters, and thus indentations are also 8 characters.
22 There are heretic movements that try to make indentations 4 (or even 2!)
23 characters deep, and that is akin to trying to define the value of PI to
26 Rationale: The whole idea behind indentation is to clearly define where
27 a block of control starts and ends. Especially when you've been looking
28 at your screen for 20 straight hours, you'll find it a lot easier to see
29 how the indentation works if you have large indentations.
31 Now, some people will claim that having 8-character indentations makes
32 the code move too far to the right, and makes it hard to read on a
33 80-character terminal screen. The answer to that is that if you need
34 more than 3 levels of indentation, you're screwed anyway, and should fix
37 In short, 8-char indents make things easier to read, and have the added
38 benefit of warning you when you're nesting your functions too deep.
41 The preferred way to ease multiple indentation levels in a switch statement is
42 to align the ``switch`` and its subordinate ``case`` labels in the same column
43 instead of ``double-indenting`` the ``case`` labels. E.g.:
64 Don't put multiple statements on a single line unless you have
69 if (condition) do_this;
70 do_something_everytime;
72 Don't use commas to avoid using braces:
79 Always uses braces for multiple statements:
88 Don't put multiple assignments on a single line either. Kernel coding style
89 is super simple. Avoid tricky expressions.
92 Outside of comments, documentation and except in Kconfig, spaces are never
93 used for indentation, and the above example is deliberately broken.
95 Get a decent editor and don't leave whitespace at the end of lines.
98 2) Breaking long lines and strings
99 ----------------------------------
101 Coding style is all about readability and maintainability using commonly
104 The preferred limit on the length of a single line is 80 columns.
106 Statements longer than 80 columns should be broken into sensible chunks,
107 unless exceeding 80 columns significantly increases readability and does
108 not hide information.
110 Descendants are always substantially shorter than the parent and
111 are placed substantially to the right. A very commonly used style
112 is to align descendants to a function open parenthesis.
114 These same rules are applied to function headers with a long argument list.
116 However, never break user-visible strings such as printk messages because
117 that breaks the ability to grep for them.
120 3) Placing Braces and Spaces
121 ----------------------------
123 The other issue that always comes up in C styling is the placement of
124 braces. Unlike the indent size, there are few technical reasons to
125 choose one placement strategy over the other, but the preferred way, as
126 shown to us by the prophets Kernighan and Ritchie, is to put the opening
127 brace last on the line, and put the closing brace first, thusly:
135 This applies to all non-function statement blocks (if, switch, for,
151 However, there is one special case, namely functions: they have the
152 opening brace at the beginning of the next line, thus:
161 Heretic people all over the world have claimed that this inconsistency
162 is ... well ... inconsistent, but all right-thinking people know that
163 (a) K&R are **right** and (b) K&R are right. Besides, functions are
164 special anyway (you can't nest them in C).
166 Note that the closing brace is empty on a line of its own, **except** in
167 the cases where it is followed by a continuation of the same statement,
168 ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
191 Also, note that this brace-placement also minimizes the number of empty
192 (or almost empty) lines, without any loss of readability. Thus, as the
193 supply of new-lines on your screen is not a renewable resource (think
194 25-line terminal screens here), you have more empty lines to put
197 Do not unnecessarily use braces where a single statement will do.
213 This does not apply if only one branch of a conditional statement is a single
214 statement; in the latter case use braces in both branches:
225 Also, use braces when a loop contains more than a single simple statement:
237 Linux kernel style for use of spaces depends (mostly) on
238 function-versus-keyword usage. Use a space after (most) keywords. The
239 notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
240 somewhat like functions (and are usually used with parentheses in Linux,
241 although they are not required in the language, as in: ``sizeof info`` after
242 ``struct fileinfo info;`` is declared).
244 So use a space after these keywords::
246 if, switch, case, for, do, while
248 but not with sizeof, typeof, alignof, or __attribute__. E.g.,
253 s = sizeof(struct file);
255 Do not add spaces around (inside) parenthesized expressions. This example is
261 s = sizeof( struct file );
263 When declaring pointer data or a function that returns a pointer type, the
264 preferred use of ``*`` is adjacent to the data name or function name and not
265 adjacent to the type name. Examples:
271 unsigned long long memparse(char *ptr, char **retptr);
272 char *match_strdup(substring_t *s);
274 Use one space around (on each side of) most binary and ternary operators,
275 such as any of these::
277 = + - < > * / % | & ^ <= >= == != ? :
279 but no space after unary operators::
281 & * + - ~ ! sizeof typeof alignof __attribute__ defined
283 no space before the postfix increment & decrement unary operators::
287 no space after the prefix increment & decrement unary operators::
291 and no space around the ``.`` and ``->`` structure member operators.
293 Do not leave trailing whitespace at the ends of lines. Some editors with
294 ``smart`` indentation will insert whitespace at the beginning of new lines as
295 appropriate, so you can start typing the next line of code right away.
296 However, some such editors do not remove the whitespace if you end up not
297 putting a line of code there, such as if you leave a blank line. As a result,
298 you end up with lines containing trailing whitespace.
300 Git will warn you about patches that introduce trailing whitespace, and can
301 optionally strip the trailing whitespace for you; however, if applying a series
302 of patches, this may make later patches in the series fail by changing their
309 C is a Spartan language, and your naming conventions should follow suit.
310 Unlike Modula-2 and Pascal programmers, C programmers do not use cute
311 names like ThisVariableIsATemporaryCounter. A C programmer would call that
312 variable ``tmp``, which is much easier to write, and not the least more
313 difficult to understand.
315 HOWEVER, while mixed-case names are frowned upon, descriptive names for
316 global variables are a must. To call a global function ``foo`` is a
319 GLOBAL variables (to be used only if you **really** need them) need to
320 have descriptive names, as do global functions. If you have a function
321 that counts the number of active users, you should call that
322 ``count_active_users()`` or similar, you should **not** call it ``cntusr()``.
324 Encoding the type of a function into the name (so-called Hungarian
325 notation) is asinine - the compiler knows the types anyway and can check
326 those, and it only confuses the programmer.
328 LOCAL variable names should be short, and to the point. If you have
329 some random integer loop counter, it should probably be called ``i``.
330 Calling it ``loop_counter`` is non-productive, if there is no chance of it
331 being mis-understood. Similarly, ``tmp`` can be just about any type of
332 variable that is used to hold a temporary value.
334 If you are afraid to mix up your local variable names, you have another
335 problem, which is called the function-growth-hormone-imbalance syndrome.
336 See chapter 6 (Functions).
338 For symbol names and documentation, avoid introducing new usage of
339 'master / slave' (or 'slave' independent of 'master') and 'blacklist /
342 Recommended replacements for 'master / slave' are:
343 '{primary,main} / {secondary,replica,subordinate}'
344 '{initiator,requester} / {target,responder}'
345 '{controller,host} / {device,worker,proxy}'
347 'director / performer'
349 Recommended replacements for 'blacklist/whitelist' are:
350 'denylist / allowlist'
351 'blocklist / passlist'
353 Exceptions for introducing new usage is to maintain a userspace ABI/API,
354 or when updating code for an existing (as of 2020) hardware or protocol
355 specification that mandates those terms. For new specifications
356 translate specification usage of the terminology to the kernel coding
357 standard where possible.
362 Please don't use things like ``vps_t``.
363 It's a **mistake** to use typedef for structures and pointers. When you see a
370 in the source, what does it mean?
371 In contrast, if it says
375 struct virtual_container *a;
377 you can actually tell what ``a`` is.
379 Lots of people think that typedefs ``help readability``. Not so. They are
382 (a) totally opaque objects (where the typedef is actively used to **hide**
385 Example: ``pte_t`` etc. opaque objects that you can only access using
386 the proper accessor functions.
390 Opaqueness and ``accessor functions`` are not good in themselves.
391 The reason we have them for things like pte_t etc. is that there
392 really is absolutely **zero** portably accessible information there.
394 (b) Clear integer types, where the abstraction **helps** avoid confusion
395 whether it is ``int`` or ``long``.
397 u8/u16/u32 are perfectly fine typedefs, although they fit into
398 category (d) better than here.
402 Again - there needs to be a **reason** for this. If something is
403 ``unsigned long``, then there's no reason to do
405 typedef unsigned long myflags_t;
407 but if there is a clear reason for why it under certain circumstances
408 might be an ``unsigned int`` and under other configurations might be
409 ``unsigned long``, then by all means go ahead and use a typedef.
411 (c) when you use sparse to literally create a **new** type for
414 (d) New types which are identical to standard C99 types, in certain
415 exceptional circumstances.
417 Although it would only take a short amount of time for the eyes and
418 brain to become accustomed to the standard types like ``uint32_t``,
419 some people object to their use anyway.
421 Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
422 signed equivalents which are identical to standard types are
423 permitted -- although they are not mandatory in new code of your
426 When editing existing code which already uses one or the other set
427 of types, you should conform to the existing choices in that code.
429 (e) Types safe for use in userspace.
431 In certain structures which are visible to userspace, we cannot
432 require C99 types and cannot use the ``u32`` form above. Thus, we
433 use __u32 and similar types in all structures which are shared
436 Maybe there are other cases too, but the rule should basically be to NEVER
437 EVER use a typedef unless you can clearly match one of those rules.
439 In general, a pointer, or a struct that has elements that can reasonably
440 be directly accessed should **never** be a typedef.
446 Functions should be short and sweet, and do just one thing. They should
447 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
448 as we all know), and do one thing and do that well.
450 The maximum length of a function is inversely proportional to the
451 complexity and indentation level of that function. So, if you have a
452 conceptually simple function that is just one long (but simple)
453 case-statement, where you have to do lots of small things for a lot of
454 different cases, it's OK to have a longer function.
456 However, if you have a complex function, and you suspect that a
457 less-than-gifted first-year high-school student might not even
458 understand what the function is all about, you should adhere to the
459 maximum limits all the more closely. Use helper functions with
460 descriptive names (you can ask the compiler to in-line them if you think
461 it's performance-critical, and it will probably do a better job of it
462 than you would have done).
464 Another measure of the function is the number of local variables. They
465 shouldn't exceed 5-10, or you're doing something wrong. Re-think the
466 function, and split it into smaller pieces. A human brain can
467 generally easily keep track of about 7 different things, anything more
468 and it gets confused. You know you're brilliant, but maybe you'd like
469 to understand what you did 2 weeks from now.
471 In source files, separate functions with one blank line. If the function is
472 exported, the **EXPORT** macro for it should follow immediately after the
473 closing function brace line. E.g.:
477 int system_is_up(void)
479 return system_state == SYSTEM_RUNNING;
481 EXPORT_SYMBOL(system_is_up);
483 6.1) Function prototypes
484 ************************
486 In function prototypes, include parameter names with their data types.
487 Although this is not required by the C language, it is preferred in Linux
488 because it is a simple way to add valuable information for the reader.
490 Do not use the ``extern`` keyword with function declarations as this makes
491 lines longer and isn't strictly necessary.
493 When writing function prototypes, please keep the `order of elements regular
494 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
495 For example, using this function declaration example::
497 __init void * __must_check action(enum magic value, size_t size, u8 count,
498 char *fmt, ...) __printf(4, 5) __malloc;
500 The preferred order of elements for a function prototype is:
502 - storage class (below, ``static __always_inline``, noting that ``__always_inline``
503 is technically an attribute but is treated like ``inline``)
504 - storage class attributes (here, ``__init`` -- i.e. section declarations, but also
505 things like ``__cold``)
506 - return type (here, ``void *``)
507 - return type attributes (here, ``__must_check``)
508 - function name (here, ``action``)
509 - function parameters (here, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
510 noting that parameter names should always be included)
511 - function parameter attributes (here, ``__printf(4, 5)``)
512 - function behavior attributes (here, ``__malloc``)
514 Note that for a function **definition** (i.e. the actual function body),
515 the compiler does not allow function parameter attributes after the
516 function parameters. In these cases, they should go after the storage
517 class attributes (e.g. note the changed position of ``__printf(4, 5)``
518 below, compared to the **declaration** example above)::
520 static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
521 size_t size, u8 count, char *fmt, ...) __malloc
526 7) Centralized exiting of functions
527 -----------------------------------
529 Albeit deprecated by some people, the equivalent of the goto statement is
530 used frequently by compilers in form of the unconditional jump instruction.
532 The goto statement comes in handy when a function exits from multiple
533 locations and some common work such as cleanup has to be done. If there is no
534 cleanup needed then just return directly.
536 Choose label names which say what the goto does or why the goto exists. An
537 example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
538 Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
539 renumber them if you ever add or remove exit paths, and they make correctness
540 difficult to verify anyway.
542 The rationale for using gotos is:
544 - unconditional statements are easier to understand and follow
546 - errors by not updating individual exit points when making
547 modifications are prevented
548 - saves the compiler work to optimize redundant code away ;)
557 buffer = kmalloc(SIZE, GFP_KERNEL);
566 goto out_free_buffer;
574 A common type of bug to be aware of is ``one err bugs`` which look like this:
583 The bug in this code is that on some exit paths ``foo`` is NULL. Normally the
584 fix for this is to split it up into two error labels ``err_free_bar:`` and
595 Ideally you should simulate errors to test all exit paths.
601 Comments are good, but there is also a danger of over-commenting. NEVER
602 try to explain HOW your code works in a comment: it's much better to
603 write the code so that the **working** is obvious, and it's a waste of
604 time to explain badly written code.
606 Generally, you want your comments to tell WHAT your code does, not HOW.
607 Also, try to avoid putting comments inside a function body: if the
608 function is so complex that you need to separately comment parts of it,
609 you should probably go back to chapter 6 for a while. You can make
610 small comments to note or warn about something particularly clever (or
611 ugly), but try to avoid excess. Instead, put the comments at the head
612 of the function, telling people what it does, and possibly WHY it does
615 When commenting the kernel API functions, please use the kernel-doc format.
616 See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
617 ``scripts/kernel-doc`` for details.
619 The preferred style for long (multi-line) comments is:
624 * This is the preferred style for multi-line
625 * comments in the Linux kernel source code.
626 * Please use it consistently.
628 * Description: A column of asterisks on the left side,
629 * with beginning and ending almost-blank lines.
632 For files in net/ and drivers/net/ the preferred style for long (multi-line)
633 comments is a little different.
637 /* The preferred comment style for files in net/ and drivers/net
640 * It is nearly the same as the generally preferred comment style,
641 * but there is no initial almost-blank line.
644 It's also important to comment data, whether they are basic types or derived
645 types. To this end, use just one data declaration per line (no commas for
646 multiple data declarations). This leaves you room for a small comment on each
647 item, explaining its use.
650 9) You've made a mess of it
651 ---------------------------
653 That's OK, we all do. You've probably been told by your long-time Unix
654 user helper that ``GNU emacs`` automatically formats the C sources for
655 you, and you've noticed that yes, it does do that, but the defaults it
656 uses are less than desirable (in fact, they are worse than random
657 typing - an infinite number of monkeys typing into GNU emacs would never
658 make a good program).
660 So, you can either get rid of GNU emacs, or change it to use saner
661 values. To do the latter, you can stick the following in your .emacs file:
663 .. code-block:: elisp
665 (defun c-lineup-arglist-tabs-only (ignored)
666 "Line up argument lists by tabs, not spaces"
667 (let* ((anchor (c-langelem-pos c-syntactic-element))
668 (column (c-langelem-2nd-pos c-syntactic-element))
669 (offset (- (1+ column) anchor))
670 (steps (floor offset c-basic-offset)))
674 (dir-locals-set-class-variables
678 (c-label-minimum-indentation . 0)
680 (arglist-close . c-lineup-arglist-tabs-only)
681 (arglist-cont-nonempty .
682 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
684 (brace-list-intro . +)
685 (c . c-lineup-C-comments)
687 (comment-intro . c-lineup-comment)
688 (cpp-define-intro . +)
691 (defun-block-intro . +)
695 (inher-cont . c-lineup-multi-inher)
696 (knr-argdecl-intro . 0)
699 (statement-block-intro . +)
700 (statement-case-intro . +)
704 (indent-tabs-mode . t)
705 (show-trailing-whitespace . t)
708 (dir-locals-set-directory-class
709 (expand-file-name "~/src/linux-trees")
712 This will make emacs go better with the kernel coding style for C
713 files below ``~/src/linux-trees``.
715 But even if you fail in getting emacs to do sane formatting, not
716 everything is lost: use ``indent``.
718 Now, again, GNU indent has the same brain-dead settings that GNU emacs
719 has, which is why you need to give it a few command line options.
720 However, that's not too bad, because even the makers of GNU indent
721 recognize the authority of K&R (the GNU people aren't evil, they are
722 just severely misguided in this matter), so you just give indent the
723 options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
724 ``scripts/Lindent``, which indents in the latest style.
726 ``indent`` has a lot of options, and especially when it comes to comment
727 re-formatting you may want to take a look at the man page. But
728 remember: ``indent`` is not a fix for bad programming.
730 Note that you can also use the ``clang-format`` tool to help you with
731 these rules, to quickly re-format parts of your code automatically,
732 and to review full files in order to spot coding style mistakes,
733 typos and possible improvements. It is also handy for sorting ``#includes``,
734 for aligning variables/macros, for reflowing text and other similar tasks.
735 See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
738 Some basic editor settings, such as indentation and line endings, will be
739 set automatically if you are using an editor that is compatible with
740 EditorConfig. See the official EditorConfig website for more information:
741 https://editorconfig.org/
743 10) Kconfig configuration files
744 -------------------------------
746 For all of the Kconfig* configuration files throughout the source tree,
747 the indentation is somewhat different. Lines under a ``config`` definition
748 are indented with one tab, while help text is indented an additional two
752 bool "Auditing support"
755 Enable auditing infrastructure that can be used with another
756 kernel subsystem, such as SELinux (which requires this for
757 logging of avc messages output). Does not do system-call
758 auditing without CONFIG_AUDITSYSCALL.
760 Seriously dangerous features (such as write support for certain
761 filesystems) should advertise this prominently in their prompt string::
764 bool "ADFS write support (DANGEROUS)"
768 For full documentation on the configuration files, see the file
769 Documentation/kbuild/kconfig-language.rst.
775 Data structures that have visibility outside the single-threaded
776 environment they are created and destroyed in should always have
777 reference counts. In the kernel, garbage collection doesn't exist (and
778 outside the kernel garbage collection is slow and inefficient), which
779 means that you absolutely **have** to reference count all your uses.
781 Reference counting means that you can avoid locking, and allows multiple
782 users to have access to the data structure in parallel - and not having
783 to worry about the structure suddenly going away from under them just
784 because they slept or did something else for a while.
786 Note that locking is **not** a replacement for reference counting.
787 Locking is used to keep data structures coherent, while reference
788 counting is a memory management technique. Usually both are needed, and
789 they are not to be confused with each other.
791 Many data structures can indeed have two levels of reference counting,
792 when there are users of different ``classes``. The subclass count counts
793 the number of subclass users, and decrements the global count just once
794 when the subclass count goes to zero.
796 Examples of this kind of ``multi-level-reference-counting`` can be found in
797 memory management (``struct mm_struct``: mm_users and mm_count), and in
798 filesystem code (``struct super_block``: s_count and s_active).
800 Remember: if another thread can find your data structure, and you don't
801 have a reference count on it, you almost certainly have a bug.
804 12) Macros, Enums and RTL
805 -------------------------
807 Names of macros defining constants and labels in enums are capitalized.
811 #define CONSTANT 0x12345
813 Enums are preferred when defining several related constants.
815 CAPITALIZED macro names are appreciated but macros resembling functions
816 may be named in lower case.
818 Generally, inline functions are preferable to macros resembling functions.
820 Macros with multiple statements should be enclosed in a do - while block:
824 #define macrofun(a, b, c) \
830 Function-like macros with unused parameters should be replaced by static
831 inline functions to avoid the issue of unused variables:
835 static inline void fun(struct foo *foo)
839 Due to historical practices, many files still employ the "cast to (void)"
840 approach to evaluate parameters. However, this method is not advisable.
841 Inline functions address the issue of "expression with side effects
842 evaluated more than once", circumvent unused-variable problems, and
843 are generally better documented than macros for some reason.
848 * Avoid doing this whenever possible and instead opt for static
851 #define macrofun(foo) do { (void) (foo); } while (0)
853 Things to avoid when using macros:
855 1) macros that affect control flow:
865 is a **very** bad idea. It looks like a function call but exits the ``calling``
866 function; don't break the internal parsers of those who will read the code.
868 2) macros that depend on having a local variable with a magic name:
872 #define FOO(val) bar(index, val)
874 might look like a good thing, but it's confusing as hell when one reads the
875 code and it's prone to breakage from seemingly innocent changes.
877 3) macros with arguments that are used as l-values: FOO(x) = y; will
878 bite you if somebody e.g. turns FOO into an inline function.
880 4) forgetting about precedence: macros defining constants using expressions
881 must enclose the expression in parentheses. Beware of similar issues with
882 macros using parameters.
886 #define CONSTANT 0x4000
887 #define CONSTEXP (CONSTANT | 3)
889 5) namespace collisions when defining local variables in macros resembling
901 ret is a common name for a local variable - __foo_ret is less likely
902 to collide with an existing variable.
904 The cpp manual deals with macros exhaustively. The gcc internals manual also
905 covers RTL which is used frequently with assembly language in the kernel.
908 13) Printing kernel messages
909 ----------------------------
911 Kernel developers like to be seen as literate. Do mind the spelling
912 of kernel messages to make a good impression. Do not use incorrect
913 contractions like ``dont``; use ``do not`` or ``don't`` instead. Make the
914 messages concise, clear, and unambiguous.
916 Kernel messages do not have to be terminated with a period.
918 Printing numbers in parentheses (%d) adds no value and should be avoided.
920 There are a number of driver model diagnostic macros in <linux/dev_printk.h>
921 which you should use to make sure messages are matched to the right device
922 and driver, and are tagged with the right level: dev_err(), dev_warn(),
923 dev_info(), and so forth. For messages that aren't associated with a
924 particular device, <linux/printk.h> defines pr_notice(), pr_info(),
925 pr_warn(), pr_err(), etc. When drivers are working properly they are quiet,
926 so prefer to use dev_dbg/pr_debug unless something is wrong.
928 Coming up with good debugging messages can be quite a challenge; and once
929 you have them, they can be a huge help for remote troubleshooting. However
930 debug message printing is handled differently than printing other non-debug
931 messages. While the other pr_XXX() functions print unconditionally,
932 pr_debug() does not; it is compiled out by default, unless either DEBUG is
933 defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also,
934 and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to
935 the ones already enabled by DEBUG.
937 Many subsystems have Kconfig debug options to turn on -DDEBUG in the
938 corresponding Makefile; in other cases specific files #define DEBUG. And
939 when a debug message should be unconditionally printed, such as if it is
940 already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
944 14) Allocating memory
945 ---------------------
947 The kernel provides the following general purpose memory allocators:
948 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
949 vzalloc(). Please refer to the API documentation for further information
950 about them. :ref:`Documentation/core-api/memory-allocation.rst
953 The preferred form for passing a size of a struct is the following:
957 p = kmalloc(sizeof(*p), ...);
959 The alternative form where struct name is spelled out hurts readability and
960 introduces an opportunity for a bug when the pointer variable type is changed
961 but the corresponding sizeof that is passed to a memory allocator is not.
963 Casting the return value which is a void pointer is redundant. The conversion
964 from void pointer to any other pointer type is guaranteed by the C programming
967 The preferred form for allocating an array is the following:
971 p = kmalloc_array(n, sizeof(...), ...);
973 The preferred form for allocating a zeroed array is the following:
977 p = kcalloc(n, sizeof(...), ...);
979 Both forms check for overflow on the allocation size n * sizeof(...),
980 and return NULL if that occurred.
982 These generic allocation functions all emit a stack dump on failure when used
983 without __GFP_NOWARN so there is no use in emitting an additional failure
984 message when NULL is returned.
986 15) The inline disease
987 ----------------------
989 There appears to be a common misperception that gcc has a magic "make me
990 faster" speedup option called ``inline``. While the use of inlines can be
991 appropriate (for example as a means of replacing macros, see Chapter 12), it
992 very often is not. Abundant use of the inline keyword leads to a much bigger
993 kernel, which in turn slows the system as a whole down, due to a bigger
994 icache footprint for the CPU and simply because there is less memory
995 available for the pagecache. Just think about it; a pagecache miss causes a
996 disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
997 that can go into these 5 milliseconds.
999 A reasonable rule of thumb is to not put inline at functions that have more
1000 than 3 lines of code in them. An exception to this rule are the cases where
1001 a parameter is known to be a compiletime constant, and as a result of this
1002 constantness you *know* the compiler will be able to optimize most of your
1003 function away at compile time. For a good example of this later case, see
1004 the kmalloc() inline function.
1006 Often people argue that adding inline to functions that are static and used
1007 only once is always a win since there is no space tradeoff. While this is
1008 technically correct, gcc is capable of inlining these automatically without
1009 help, and the maintenance issue of removing the inline when a second user
1010 appears outweighs the potential value of the hint that tells gcc to do
1011 something it would have done anyway.
1014 16) Function return values and names
1015 ------------------------------------
1017 Functions can return values of many different kinds, and one of the
1018 most common is a value indicating whether the function succeeded or
1019 failed. Such a value can be represented as an error-code integer
1020 (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
1021 non-zero = success).
1023 Mixing up these two sorts of representations is a fertile source of
1024 difficult-to-find bugs. If the C language included a strong distinction
1025 between integers and booleans then the compiler would find these mistakes
1026 for us... but it doesn't. To help prevent such bugs, always follow this
1029 If the name of a function is an action or an imperative command,
1030 the function should return an error-code integer. If the name
1031 is a predicate, the function should return a "succeeded" boolean.
1033 For example, ``add work`` is a command, and the add_work() function returns 0
1034 for success or -EBUSY for failure. In the same way, ``PCI device present`` is
1035 a predicate, and the pci_dev_present() function returns 1 if it succeeds in
1036 finding a matching device or 0 if it doesn't.
1038 All EXPORTed functions must respect this convention, and so should all
1039 public functions. Private (static) functions need not, but it is
1040 recommended that they do.
1042 Functions whose return value is the actual result of a computation, rather
1043 than an indication of whether the computation succeeded, are not subject to
1044 this rule. Generally they indicate failure by returning some out-of-range
1045 result. Typical examples would be functions that return pointers; they use
1046 NULL or the ERR_PTR mechanism to report failure.
1052 The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
1053 only evaluate to 0 or 1, and implicit or explicit conversion to bool
1054 automatically converts the value to true or false. When using bool types the
1055 !! construction is not needed, which eliminates a class of bugs.
1057 When working with bool values the true and false definitions should be used
1060 bool function return types and stack variables are always fine to use whenever
1061 appropriate. Use of bool is encouraged to improve readability and is often a
1062 better option than 'int' for storing boolean values.
1064 Do not use bool if cache line layout or size of the value matters, as its size
1065 and alignment varies based on the compiled architecture. Structures that are
1066 optimized for alignment and size should not use bool.
1068 If a structure has many true/false values, consider consolidating them into a
1069 bitfield with 1 bit members, or using an appropriate fixed width type, such as
1072 Similarly for function arguments, many true/false values can be consolidated
1073 into a single bitwise 'flags' argument and 'flags' can often be a more
1074 readable alternative if the call-sites have naked true/false constants.
1076 Otherwise limited use of bool in structures and arguments can improve
1079 18) Don't re-invent the kernel macros
1080 -------------------------------------
1082 The header file include/linux/kernel.h contains a number of macros that
1083 you should use, rather than explicitly coding some variant of them yourself.
1084 For example, if you need to calculate the length of an array, take advantage
1089 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
1091 Similarly, if you need to calculate the size of some structure member, use
1095 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1097 There are also min() and max() macros that do strict type checking if you
1098 need them. Feel free to peruse that header file to see what else is already
1099 defined that you shouldn't reproduce in your code.
1102 19) Editor modelines and other cruft
1103 ------------------------------------
1105 Some editors can interpret configuration information embedded in source files,
1106 indicated with special markers. For example, emacs interprets lines marked
1119 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1123 Vim interprets markers that look like this:
1127 /* vim:set sw=8 noet */
1129 Do not include any of these in source files. People have their own personal
1130 editor configurations, and your source files should not override them. This
1131 includes markers for indentation and mode configuration. People may use their
1132 own custom mode, or may have some other magic method for making indentation
1139 In architecture-specific code, you may need to use inline assembly to interface
1140 with CPU or platform functionality. Don't hesitate to do so when necessary.
1141 However, don't use inline assembly gratuitously when C can do the job. You can
1142 and should poke hardware from C when possible.
1144 Consider writing simple helper functions that wrap common bits of inline
1145 assembly, rather than repeatedly writing them with slight variations. Remember
1146 that inline assembly can use C parameters.
1148 Large, non-trivial assembly functions should go in .S files, with corresponding
1149 C prototypes defined in C header files. The C prototypes for assembly
1150 functions should use ``asmlinkage``.
1152 You may need to mark your asm statement as volatile, to prevent GCC from
1153 removing it if GCC doesn't notice any side effects. You don't always need to
1154 do so, though, and doing so unnecessarily can limit optimization.
1156 When writing a single inline assembly statement containing multiple
1157 instructions, put each instruction on a separate line in a separate quoted
1158 string, and end each string except the last with ``\n\t`` to properly indent
1159 the next instruction in the assembly output:
1163 asm ("magic %reg1, #42\n\t"
1164 "more_magic %reg2, %reg3"
1165 : /* outputs */ : /* inputs */ : /* clobbers */);
1168 21) Conditional Compilation
1169 ---------------------------
1171 Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
1172 files; doing so makes code harder to read and logic harder to follow. Instead,
1173 use such conditionals in a header file defining functions for use in those .c
1174 files, providing no-op stub versions in the #else case, and then call those
1175 functions unconditionally from .c files. The compiler will avoid generating
1176 any code for the stub calls, producing identical results, but the logic will
1177 remain easy to follow.
1179 Prefer to compile out entire functions, rather than portions of functions or
1180 portions of expressions. Rather than putting an ifdef in an expression, factor
1181 out part or all of the expression into a separate helper function and apply the
1182 conditional to that function.
1184 If you have a function or variable which may potentially go unused in a
1185 particular configuration, and the compiler would warn about its definition
1186 going unused, mark the definition as __maybe_unused rather than wrapping it in
1187 a preprocessor conditional. (However, if a function or variable *always* goes
1190 Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
1191 symbol into a C boolean expression, and use it in a normal C conditional:
1195 if (IS_ENABLED(CONFIG_SOMETHING)) {
1199 The compiler will constant-fold the conditional away, and include or exclude
1200 the block of code just as with an #ifdef, so this will not add any runtime
1201 overhead. However, this approach still allows the C compiler to see the code
1202 inside the block, and check it for correctness (syntax, types, symbol
1203 references, etc). Thus, you still have to use an #ifdef if the code inside the
1204 block references symbols that will not exist if the condition is not met.
1206 At the end of any non-trivial #if or #ifdef block (more than a few lines),
1207 place a comment after the #endif on the same line, noting the conditional
1208 expression used. For instance:
1212 #ifdef CONFIG_SOMETHING
1214 #endif /* CONFIG_SOMETHING */
1217 22) Do not crash the kernel
1218 ---------------------------
1220 In general, the decision to crash the kernel belongs to the user, rather
1221 than to the kernel developer.
1226 panic() should be used with care and primarily only during system boot.
1227 panic() is, for example, acceptable when running out of memory during boot and
1228 not being able to continue.
1230 Use WARN() rather than BUG()
1231 ****************************
1233 Do not add new code that uses any of the BUG() variants, such as BUG(),
1234 BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably
1235 WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not
1236 required if there is no reasonable way to at least partially recover.
1238 "I'm too lazy to do error handling" is not an excuse for using BUG(). Major
1239 internal corruptions with no way of continuing may still use BUG(), but need
1242 Use WARN_ON_ONCE() rather than WARN() or WARN_ON()
1243 **************************************************
1245 WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it
1246 is common for a given warning condition, if it occurs at all, to occur
1247 multiple times. This can fill up and wrap the kernel log, and can even slow
1248 the system enough that the excessive logging turns into its own, additional
1254 WARN*() is intended for unexpected, this-should-never-happen situations.
1255 WARN*() macros are not to be used for anything that is expected to happen
1256 during normal operation. These are not pre- or post-condition asserts, for
1257 example. Again: WARN*() must not be used for a condition that is expected
1258 to trigger easily, for example, by user space actions. pr_warn_once() is a
1259 possible alternative, if you need to notify the user of a problem.
1261 Do not worry about panic_on_warn users
1262 **************************************
1264 A few more words about panic_on_warn: Remember that ``panic_on_warn`` is an
1265 available kernel option, and that many users set this option. This is why
1266 there is a "Do not WARN lightly" writeup, above. However, the existence of
1267 panic_on_warn users is not a valid reason to avoid the judicious use
1268 WARN*(). That is because, whoever enables panic_on_warn has explicitly
1269 asked the kernel to crash if a WARN*() fires, and such users must be
1270 prepared to deal with the consequences of a system that is somewhat more
1273 Use BUILD_BUG_ON() for compile-time assertions
1274 **********************************************
1276 The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
1277 compile-time assertion that has no effect at runtime.
1279 Appendix I) References
1280 ----------------------
1282 The C Programming Language, Second Edition
1283 by Brian W. Kernighan and Dennis M. Ritchie.
1284 Prentice Hall, Inc., 1988.
1285 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1287 The Practice of Programming
1288 by Brian W. Kernighan and Rob Pike.
1289 Addison-Wesley, Inc., 1999.
1292 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
1293 gcc internals and indent, all available from https://www.gnu.org/manual/
1295 WG14 is the international standardization working group for the programming
1296 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
1298 Kernel CodingStyle, by greg@kroah.com at OLS 2002:
1299 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/