sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/process/coding-stylemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/process/coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/process/coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/process/coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/process/coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/pt_BR/process/coding-stylemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/process/coding-stylemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhtarget)}(h.. _codingstyle:h]h}(h]h ]h"]h$]h&]refid codingstyleuh1hhKhhhhhB/var/lib/git/docbuild/linux/Documentation/process/coding-style.rstubhsection)}(hhh](htitle)}(hLinux kernel coding styleh]hLinux kernel coding style}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXCThis is a short document describing the preferred coding style for the linux kernel. Coding style is very personal, and I won't **force** my views on anybody, but this is what goes for anything that I have to be able to maintain, and I'd prefer it for most other things too. Please at least consider the points made here.h](hThis is a short document describing the preferred coding style for the linux kernel. Coding style is very personal, and I won’t }(hhhhhNhNubhstrong)}(h **force**h]hforce}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh my views on anybody, but this is what goes for anything that I have to be able to maintain, and I’d prefer it for most other things too. Please at least consider the points made here.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hFirst off, I'd suggest printing out a copy of the GNU coding standards, and NOT read it. Burn them, it's a great symbolic gesture.h]hFirst off, I’d suggest printing out a copy of the GNU coding standards, and NOT read it. Burn them, it’s a great symbolic gesture.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hAnyway, here goes:h]hAnyway, here goes:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h1) Indentationh]h1) Indentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hTabs are 8 characters, and thus indentations are also 8 characters. There are heretic movements that try to make indentations 4 (or even 2!) characters deep, and that is akin to trying to define the value of PI to be 3.h]hTabs are 8 characters, and thus indentations are also 8 characters. There are heretic movements that try to make indentations 4 (or even 2!) characters deep, and that is akin to trying to define the value of PI to be 3.}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXRationale: The whole idea behind indentation is to clearly define where a block of control starts and ends. Especially when you've been looking at your screen for 20 straight hours, you'll find it a lot easier to see how the indentation works if you have large indentations.h]hXRationale: The whole idea behind indentation is to clearly define where a block of control starts and ends. Especially when you’ve been looking at your screen for 20 straight hours, you’ll find it a lot easier to see how the indentation works if you have large indentations.}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX&Now, some people will claim that having 8-character indentations makes the code move too far to the right, and makes it hard to read on a 80-character terminal screen. The answer to that is that if you need more than 3 levels of indentation, you're screwed anyway, and should fix your program.h]hX(Now, some people will claim that having 8-character indentations makes the code move too far to the right, and makes it hard to read on a 80-character terminal screen. The answer to that is that if you need more than 3 levels of indentation, you’re screwed anyway, and should fix your program.}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hIn short, 8-char indents make things easier to read, and have the added benefit of warning you when you're nesting your functions too deep. Heed that warning.h]hIn short, 8-char indents make things easier to read, and have the added benefit of warning you when you’re nesting your functions too deep. Heed that warning.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hjhhubh)}(hThe preferred way to ease multiple indentation levels in a switch statement is to align the ``switch`` and its subordinate ``case`` labels in the same column instead of ``double-indenting`` the ``case`` labels. E.g.:h](h\The preferred way to ease multiple indentation levels in a switch statement is to align the }(hjbhhhNhNubhliteral)}(h ``switch``h]hswitch}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjbubh and its subordinate }(hjbhhhNhNubjk)}(h``case``h]hcase}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjbubh& labels in the same column instead of }(hjbhhhNhNubjk)}(h``double-indenting``h]hdouble-indenting}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjbubh the }(hjbhhhNhNubjk)}(h``case``h]hcase}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjbubh labels. E.g.:}(hjbhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK)hjhhubh literal_block)}(hswitch (suffix) { case 'G': case 'g': mem <<= 30; break; case 'M': case 'm': mem <<= 20; break; case 'K': case 'k': mem <<= 10; fallthrough; default: break; }h]hswitch (suffix) { case 'G': case 'g': mem <<= 30; break; case 'M': case 'm': mem <<= 20; break; case 'K': case 'k': mem <<= 10; fallthrough; default: break; }}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveforcelanguagechighlight_args}uh1jhhhK-hjhhubh)}(hQDon't put multiple statements on a single line unless you have something to hide:h]hSDon’t put multiple statements on a single line unless you have something to hide:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjhhubj)}(h1if (condition) do_this; do_something_everytime;h]h1if (condition) do_this; do_something_everytime;}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKChjhhubh)}(h'Don't use commas to avoid using braces:h]h)Don’t use commas to avoid using braces:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjhhubj)}(h,if (condition) do_this(), do_that();h]h,if (condition) do_this(), do_that();}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKJhjhhubh)}(h*Always use braces for multiple statements:h]h*Always use braces for multiple statements:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjhhubj)}(h8if (condition) { do_this(); do_that(); }h]h8if (condition) { do_this(); do_that(); }}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKQhjhhubh)}(hxDon't put multiple assignments on a single line either. Kernel coding style is super simple. Avoid tricky expressions.h]hzDon’t put multiple assignments on a single line either. Kernel coding style is super simple. Avoid tricky expressions.}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubh)}(hOutside of comments, documentation and except in Kconfig, spaces are never used for indentation, and the above example is deliberately broken.h]hOutside of comments, documentation and except in Kconfig, spaces are never used for indentation, and the above example is deliberately broken.}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hjhhubh)}(hCGet a decent editor and don't leave whitespace at the end of lines.h]hEGet a decent editor and don’t leave whitespace at the end of lines.}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hjhhubeh}(h] indentationah ]h"]1) indentationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h"2) Breaking long lines and stringsh]h"2) Breaking long lines and strings}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZhhhhhKcubh)}(hYCoding style is all about readability and maintainability using commonly available tools.h]hYCoding style is all about readability and maintainability using commonly available tools.}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKehjZhhubh)}(hAThe preferred limit on the length of a single line is 80 columns.h]hAThe preferred limit on the length of a single line is 80 columns.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjZhhubh)}(hStatements longer than 80 columns should be broken into sensible chunks, unless exceeding 80 columns significantly increases readability and does not hide information.h]hStatements longer than 80 columns should be broken into sensible chunks, unless exceeding 80 columns significantly increases readability and does not hide information.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjZhhubh)}(hDescendants are always substantially shorter than the parent and are placed substantially to the right. A very commonly used style is to align descendants to a function open parenthesis.h]hDescendants are always substantially shorter than the parent and are placed substantially to the right. A very commonly used style is to align descendants to a function open parenthesis.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjZhhubh)}(hKThese same rules are applied to function headers with a long argument list.h]hKThese same rules are applied to function headers with a long argument list.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhjZhhubh)}(hsHowever, never break user-visible strings such as printk messages because that breaks the ability to grep for them.h]hsHowever, never break user-visible strings such as printk messages because that breaks the ability to grep for them.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKthjZhhubeh}(h]breaking-long-lines-and-stringsah ]h"]"2) breaking long lines and stringsah$]h&]uh1hhhhhhhhKcubh)}(hhh](h)}(h3) Placing Braces and Spacesh]h3) Placing Braces and Spaces}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKyubh)}(hX[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 choose one placement strategy over the other, but the preferred way, as 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:h]hX[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 choose one placement strategy over the other, but the preferred way, as 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:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK{hjhhubj)}(h"if (x is true) { we do y }h]h"if (x is true) { we do y }}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(hVThis applies to all non-function statement blocks (if, switch, for, while, do). E.g.:h]hVThis applies to all non-function statement blocks (if, switch, for, while, do). E.g.:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hswitch (action) { case KOBJ_ADD: return "add"; case KOBJ_REMOVE: return "remove"; case KOBJ_CHANGE: return "change"; default: return NULL; }h]hswitch (action) { case KOBJ_ADD: return "add"; case KOBJ_REMOVE: return "remove"; case KOBJ_CHANGE: return "change"; default: return NULL; }}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(hzHowever, there is one special case, namely functions: they have the opening brace at the beginning of the next line, thus:h]hzHowever, there is one special case, namely functions: they have the opening brace at the beginning of the next line, thus:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h0int function(int x) { body of function }h]h0int function(int x) { body of function }}hj sbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(hHeretic people all over the world have claimed that this inconsistency is ... well ... inconsistent, but all right-thinking people know that (a) K&R are **right** and (b) K&R are right. Besides, functions are special anyway (you can't nest them in C).h](hHeretic people all over the world have claimed that this inconsistency is ... well ... inconsistent, but all right-thinking people know that (a) K&R are }(hj/hhhNhNubh)}(h **right**h]hright}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/ubh\ and (b) K&R are right. Besides, functions are special anyway (you can’t nest them in C).}(hj/hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hNote that the closing brace is empty on a line of its own, **except** in the cases where it is followed by a continuation of the same statement, ie a ``while`` in a do-statement or an ``else`` in an if-statement, like this:h](h;Note that the closing brace is empty on a line of its own, }(hjOhhhNhNubh)}(h **except**h]hexcept}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjOubhQ in the cases where it is followed by a continuation of the same statement, ie a }(hjOhhhNhNubjk)}(h ``while``h]hwhile}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjOubh in a do-statement or an }(hjOhhhNhNubjk)}(h``else``h]helse}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjOubh in an if-statement, like this:}(hjOhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h1do { body of do-loop } while (condition);h]h1do { body of do-loop } while (condition);}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(handh]hand}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hPif (x == y) { .. } else if (x > y) { ... } else { .... }h]hPif (x == y) { .. } else if (x > y) { ... } else { .... }}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(hRationale: K&R.h]hRationale: K&R.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX#Also, note that this brace-placement also minimizes the number of empty (or almost empty) lines, without any loss of readability. Thus, as the supply of new-lines on your screen is not a renewable resource (think 25-line terminal screens here), you have more empty lines to put comments on.h]hX#Also, note that this brace-placement also minimizes the number of empty (or almost empty) lines, without any loss of readability. Thus, as the supply of new-lines on your screen is not a renewable resource (think 25-line terminal screens here), you have more empty lines to put comments on.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hADo not unnecessarily use braces where a single statement will do.h]hADo not unnecessarily use braces where a single statement will do.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h if (condition) action();h]h if (condition) action();}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(handh]hand}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h9if (condition) do_this(); else do_that();h]h9if (condition) do_this(); else do_that();}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(hThis does not apply if only one branch of a conditional statement is a single statement; in the latter case use braces in both branches:h]hThis does not apply if only one branch of a conditional statement is a single statement; in the latter case use braces in both branches:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hVif (condition) { do_this(); do_that(); } else { otherwise(); }h]hVif (condition) { do_this(); do_that(); } else { otherwise(); }}hj#sbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(hJAlso, use braces when a loop contains more than a single simple statement:h]hJAlso, use braces when a loop contains more than a single simple statement:}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hGwhile (condition) { if (test) do_something(); }h]hGwhile (condition) { if (test) do_something(); }}hj@sbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjhhubh)}(hhh](h)}(h 3.1) Spacesh]h 3.1) Spaces}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjOhhhhhKubh)}(hXLinux 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).h](hXOLinux 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: }(hj`hhhNhNubjk)}(h``sizeof info``h]h sizeof info}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj`ubh after }(hj`hhhNhNubjk)}(h``struct fileinfo info;``h]hstruct fileinfo info;}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj`ubh is declared).}(hj`hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjOhhubh)}(h%So use a space after these keywords::h]h$So use a space after these keywords:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjOhhubj)}(h if, switch, case, for, do, whileh]h if, switch, case, for, do, while}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjOhhubh)}(h>but not with sizeof, typeof, alignof, or __attribute__. E.g.,h]h>but not with sizeof, typeof, alignof, or __attribute__. E.g.,}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjOhhubj)}(hs = sizeof(struct file);h]hs = sizeof(struct file);}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhKhjOhhubh)}(hVDo not add spaces around (inside) parenthesized expressions. This example is **bad**:h](hNDo not add spaces around (inside) parenthesized expressions. This example is }(hjhhhNhNubh)}(h**bad**h]hbad}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjOhhubj)}(hs = sizeof( struct file );h]hs = sizeof( struct file );}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMhjOhhubh)}(hWhen 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 adjacent to the type name. Examples:h](h\When declaring pointer data or a function that returns a pointer type, the preferred use of }(hjhhhNhNubjk)}(h``*``h]h*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh\ is adjacent to the data name or function name and not adjacent to the type name. Examples:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjOhhubj)}(hnchar *linux_banner; unsigned long long memparse(char *ptr, char **retptr); char *match_strdup(substring_t *s);h]hnchar *linux_banner; unsigned long long memparse(char *ptr, char **retptr); char *match_strdup(substring_t *s);}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhM hjOhhubh)}(h`Use one space around (on each side of) most binary and ternary operators, such as any of these::h]h_Use one space around (on each side of) most binary and ternary operators, such as any of these:}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjOhhubj)}(h5= + - < > * / % | & ^ <= >= == != ? :h]h5= + - < > * / % | & ^ <= >= == != ? :}hj7sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjOhhubh)}(h$but no space after unary operators::h]h#but no space after unary operators:}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjOhhubj)}(hA& * + - ~ ! sizeof typeof alignof __attribute__ definedh]hA& * + - ~ ! sizeof typeof alignof __attribute__ defined}hjSsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjOhhubh)}(hCno space before the postfix increment & decrement unary operators::h]hBno space before the postfix increment & decrement unary operators:}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjOhhubj)}(h++ --h]h++ --}hjosbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjOhhubh)}(hAno space after the prefix increment & decrement unary operators::h]h@no space after the prefix increment & decrement unary operators:}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjOhhubj)}(h++ --h]h++ --}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhM!hjOhhubh)}(hDand no space around the ``.`` and ``->`` structure member operators.h](hand no space around the }(hjhhhNhNubjk)}(h``.``h]h.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh and }(hjhhhNhNubjk)}(h``->``h]h->}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh structure member operators.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM#hjOhhubh)}(hXDo not leave trailing whitespace at the ends of lines. Some editors with ``smart`` indentation will insert whitespace at the beginning of new lines as appropriate, so you can start typing the next line of code right away. However, some such editors do not remove the whitespace if you end up not putting a line of code there, such as if you leave a blank line. As a result, you end up with lines containing trailing whitespace.h](hJDo not leave trailing whitespace at the ends of lines. Some editors with }(hjhhhNhNubjk)}(h ``smart``h]hsmart}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhXZ indentation will insert whitespace at the beginning of new lines as appropriate, so you can start typing the next line of code right away. However, some such editors do not remove the whitespace if you end up not putting a line of code there, such as if you leave a blank line. As a result, you end up with lines containing trailing whitespace.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM%hjOhhubh)}(hGit will warn you about patches that introduce trailing whitespace, and can optionally strip the trailing whitespace for you; however, if applying a series of patches, this may make later patches in the series fail by changing their context lines.h]hGit will warn you about patches that introduce trailing whitespace, and can optionally strip the trailing whitespace for you; however, if applying a series of patches, this may make later patches in the series fail by changing their context lines.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hjOhhubeh}(h]spacesah ]h"] 3.1) spacesah$]h&]uh1hhjhhhhhKubeh}(h]placing-braces-and-spacesah ]h"]3) placing braces and spacesah$]h&]uh1hhhhhhhhKyubh)}(hhh](h)}(h 4) Namingh]h 4) Naming}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM3ubh)}(hX:C is a Spartan language, and your naming conventions should follow suit. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like ThisVariableIsATemporaryCounter. A C programmer would call that variable ``tmp``, which is much easier to write, and not the least more difficult to understand.h](hC is a Spartan language, and your naming conventions should follow suit. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like ThisVariableIsATemporaryCounter. A C programmer would call that variable }(hjhhhNhNubjk)}(h``tmp``h]htmp}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhP, which is much easier to write, and not the least more difficult to understand.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM5hj hhubh)}(hHOWEVER, while mixed-case names are frowned upon, descriptive names for global variables are a must. To call a global function ``foo`` is a shooting offense.h](hHOWEVER, while mixed-case names are frowned upon, descriptive names for global variables are a must. To call a global function }(hj:hhhNhNubjk)}(h``foo``h]hfoo}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj:ubh is a shooting offense.}(hj:hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM;hj hhubh)}(hXGLOBAL variables (to be used only if you **really** need them) need to have descriptive names, as do global functions. If you have a function that counts the number of active users, you should call that ``count_active_users()`` or similar, you should **not** call it ``cntusr()``.h](h)GLOBAL variables (to be used only if you }(hjZhhhNhNubh)}(h **really**h]hreally}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZubh need them) need to have descriptive names, as do global functions. If you have a function that counts the number of active users, you should call that }(hjZhhhNhNubjk)}(h``count_active_users()``h]hcount_active_users()}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjZubh or similar, you should }(hjZhhhNhNubh)}(h**not**h]hnot}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZubh call it }(hjZhhhNhNubjk)}(h ``cntusr()``h]hcntusr()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjZubh.}(hjZhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM?hj hhubh)}(hEncoding the type of a function into the name (so-called Hungarian notation) is asinine - the compiler knows the types anyway and can check those, and it only confuses the programmer.h]hEncoding the type of a function into the name (so-called Hungarian notation) is asinine - the compiler knows the types anyway and can check those, and it only confuses the programmer.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhj hhubh)}(hXNLOCAL variable names should be short, and to the point. If you have some random integer loop counter, it should probably be called ``i``. Calling it ``loop_counter`` is non-productive, if there is no chance of it being mis-understood. Similarly, ``tmp`` can be just about any type of variable that is used to hold a temporary value.h](hLOCAL variable names should be short, and to the point. If you have some random integer loop counter, it should probably be called }(hjhhhNhNubjk)}(h``i``h]hi}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh . Calling it }(hjhhhNhNubjk)}(h``loop_counter``h]h loop_counter}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhR is non-productive, if there is no chance of it being mis-understood. Similarly, }(hjhhhNhNubjk)}(h``tmp``h]htmp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhO can be just about any type of variable that is used to hold a temporary value.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMHhj hhubh)}(hIf you are afraid to mix up your local variable names, you have another problem, which is called the function-growth-hormone-imbalance syndrome. See chapter 6 (Functions).h]hIf you are afraid to mix up your local variable names, you have another problem, which is called the function-growth-hormone-imbalance syndrome. See chapter 6 (Functions).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhj hhubh)}(hFor symbol names and documentation, avoid introducing new usage of 'master / slave' (or 'slave' independent of 'master') and 'blacklist / whitelist'.h]hFor symbol names and documentation, avoid introducing new usage of ‘master / slave’ (or ‘slave’ independent of ‘master’) and ‘blacklist / whitelist’.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhj hhubhdefinition_list)}(hhh](hdefinition_list_item)}(hRecommended replacements for 'master / slave' are: '{primary,main} / {secondary,replica,subordinate}' '{initiator,requester} / {target,responder}' '{controller,host} / {device,worker,proxy}' 'leader / follower' 'director / performer' h](hterm)}(h2Recommended replacements for 'master / slave' are:h]h6Recommended replacements for ‘master / slave’ are:}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1j)hhhM[hj%ubh definition)}(hhh]h)}(h'{primary,main} / {secondary,replica,subordinate}' '{initiator,requester} / {target,responder}' '{controller,host} / {device,worker,proxy}' 'leader / follower' 'director / performer'h]h‘{primary,main} / {secondary,replica,subordinate}’ ‘{initiator,requester} / {target,responder}’ ‘{controller,host} / {device,worker,proxy}’ ‘leader / follower’ ‘director / performer’}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhj;ubah}(h]h ]h"]h$]h&]uh1j9hj%ubeh}(h]h ]h"]h$]h&]uh1j#hhhM[hj ubj$)}(hfRecommended replacements for 'blacklist/whitelist' are: 'denylist / allowlist' 'blocklist / passlist' h](j*)}(h7Recommended replacements for 'blacklist/whitelist' are:h]h;Recommended replacements for ‘blacklist/whitelist’ are:}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1j)hhhM_hjXubj:)}(hhh]h)}(h-'denylist / allowlist' 'blocklist / passlist'h]h5‘denylist / allowlist’ ‘blocklist / passlist’}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hjjubah}(h]h ]h"]h$]h&]uh1j9hjXubeh}(h]h ]h"]h$]h&]uh1j#hhhM_hj hhubeh}(h]h ]h"]h$]h&]uh1jhj hhhhhNubh)}(hX/Exceptions for introducing new usage is to maintain a userspace ABI/API, or when updating code for an existing (as of 2020) hardware or protocol specification that mandates those terms. For new specifications translate specification usage of the terminology to the kernel coding standard where possible.h]hX/Exceptions for introducing new usage is to maintain a userspace ABI/API, or when updating code for an existing (as of 2020) hardware or protocol specification that mandates those terms. For new specifications translate specification usage of the terminology to the kernel coding standard where possible.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMahj hhubeh}(h]namingah ]h"] 4) namingah$]h&]uh1hhhhhhhhM3ubh)}(hhh](h)}(h 5) Typedefsh]h 5) Typedefs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMhubh)}(huPlease don't use things like ``vps_t``. It's a **mistake** to use typedef for structures and pointers. When you see ah](hPlease don’t use things like }(hjhhhNhNubjk)}(h ``vps_t``h]hvps_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh . It’s a }(hjhhhNhNubh)}(h **mistake**h]hmistake}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh; to use typedef for structures and pointers. When you see a}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMjhjhhubj)}(hvps_t a;h]hvps_t a;}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMmhjhhubh)}(h9in the source, what does it mean? In contrast, if it saysh]h9in the source, what does it mean? In contrast, if it says}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMrhjhhubj)}(hstruct virtual_container *a;h]hstruct virtual_container *a;}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMuhjhhubh)}(h$you can actually tell what ``a`` is.h](hyou can actually tell what }(hjhhhNhNubjk)}(h``a``h]ha}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh is.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMyhjhhubh)}(hZLots of people think that typedefs ``help readability``. Not so. They are useful only for:h](h#Lots of people think that typedefs }(hj2hhhNhNubjk)}(h``help readability``h]hhelp readability}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj2ubh#. Not so. They are useful only for:}(hj2hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM{hjhhubh block_quote)}(hX(a) totally opaque objects (where the typedef is actively used to **hide** what the object is). Example: ``pte_t`` etc. opaque objects that you can only access using the proper accessor functions. .. note:: Opaqueness and ``accessor functions`` are not good in themselves. The reason we have them for things like pte_t etc. is that there really is absolutely **zero** portably accessible information there. (b) Clear integer types, where the abstraction **helps** avoid confusion whether it is ``int`` or ``long``. u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here. .. note:: Again - there needs to be a **reason** for this. If something is ``unsigned long``, then there's no reason to do typedef unsigned long myflags_t; but if there is a clear reason for why it under certain circumstances might be an ``unsigned int`` and under other configurations might be ``unsigned long``, then by all means go ahead and use a typedef. (c) when you use sparse to literally create a **new** type for type-checking. (d) New types which are identical to standard C99 types, in certain exceptional circumstances. Although it would only take a short amount of time for the eyes and brain to become accustomed to the standard types like ``uint32_t``, some people object to their use anyway. Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their signed equivalents which are identical to standard types are permitted -- although they are not mandatory in new code of your own. When editing existing code which already uses one or the other set of types, you should conform to the existing choices in that code. (e) Types safe for use in userspace. In certain structures which are visible to userspace, we cannot require C99 types and cannot use the ``u32`` form above. Thus, we use __u32 and similar types in all structures which are shared with userspace. h]henumerated_list)}(hhh](h list_item)}(hXtotally opaque objects (where the typedef is actively used to **hide** what the object is). Example: ``pte_t`` etc. opaque objects that you can only access using the proper accessor functions. .. note:: Opaqueness and ``accessor functions`` are not good in themselves. The reason we have them for things like pte_t etc. is that there really is absolutely **zero** portably accessible information there. h](h)}(h[totally opaque objects (where the typedef is actively used to **hide** what the object is).h](h>totally opaque objects (where the typedef is actively used to }(hjchhhNhNubh)}(h**hide**h]hhide}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjcubh what the object is).}(hjchhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM~hj_ubh)}(hdExample: ``pte_t`` etc. opaque objects that you can only access using the proper accessor functions.h](h Example: }(hjhhhNhNubjk)}(h ``pte_t``h]hpte_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhR etc. opaque objects that you can only access using the proper accessor functions.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj_ubhnote)}(hOpaqueness and ``accessor functions`` are not good in themselves. The reason we have them for things like pte_t etc. is that there really is absolutely **zero** portably accessible information there.h]h)}(hOpaqueness and ``accessor functions`` are not good in themselves. The reason we have them for things like pte_t etc. is that there really is absolutely **zero** portably accessible information there.h](hOpaqueness and }(hjhhhNhNubjk)}(h``accessor functions``h]haccessor functions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhs are not good in themselves. The reason we have them for things like pte_t etc. is that there really is absolutely }(hjhhhNhNubh)}(h**zero**h]hzero}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh' portably accessible information there.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhj_ubeh}(h]h ]h"]h$]h&]uh1j]hjZubj^)}(hX:Clear integer types, where the abstraction **helps** avoid confusion whether it is ``int`` or ``long``. u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here. .. note:: Again - there needs to be a **reason** for this. If something is ``unsigned long``, then there's no reason to do typedef unsigned long myflags_t; but if there is a clear reason for why it under certain circumstances might be an ``unsigned int`` and under other configurations might be ``unsigned long``, then by all means go ahead and use a typedef. h](h)}(hgClear integer types, where the abstraction **helps** avoid confusion whether it is ``int`` or ``long``.h](h+Clear integer types, where the abstraction }(hjhhhNhNubh)}(h **helps**h]hhelps}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh avoid confusion whether it is }(hjhhhNhNubjk)}(h``int``h]hint}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh or }(hjhhhNhNubjk)}(h``long``h]hlong}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(h]u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here.h]h]u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here.}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubj)}(hAgain - there needs to be a **reason** for this. If something is ``unsigned long``, then there's no reason to do typedef unsigned long myflags_t;h](h)}(hpAgain - there needs to be a **reason** for this. If something is ``unsigned long``, then there's no reason to doh](hAgain - there needs to be a }(hjA hhhNhNubh)}(h **reason**h]hreason}(hjI hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjA ubh for this. If something is }(hjA hhhNhNubjk)}(h``unsigned long``h]h unsigned long}(hj[ hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjA ubh , then there’s no reason to do}(hjA hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj= ubjS)}(h typedef unsigned long myflags_t;h]h)}(hju h]h typedef unsigned long myflags_t;}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjs ubah}(h]h ]h"]h$]h&]uh1jRhhhMhj= ubeh}(h]h ]h"]h$]h&]uh1jhjubh)}(hbut if there is a clear reason for why it under certain circumstances might be an ``unsigned int`` and under other configurations might be ``unsigned long``, then by all means go ahead and use a typedef.h](hRbut if there is a clear reason for why it under certain circumstances might be an }(hj hhhNhNubjk)}(h``unsigned int``h]h unsigned int}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh) and under other configurations might be }(hj hhhNhNubjk)}(h``unsigned long``h]h unsigned long}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh/, then by all means go ahead and use a typedef.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubeh}(h]h ]h"]h$]h&]uh1j]hjZubj^)}(hJwhen you use sparse to literally create a **new** type for type-checking. h]h)}(hIwhen you use sparse to literally create a **new** type for type-checking.h](h*when you use sparse to literally create a }(hj hhhNhNubh)}(h**new**h]hnew}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh type for type-checking.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j]hjZubj^)}(hXXNew types which are identical to standard C99 types, in certain exceptional circumstances. Although it would only take a short amount of time for the eyes and brain to become accustomed to the standard types like ``uint32_t``, some people object to their use anyway. Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their signed equivalents which are identical to standard types are permitted -- although they are not mandatory in new code of your own. When editing existing code which already uses one or the other set of types, you should conform to the existing choices in that code. h](h)}(hZNew types which are identical to standard C99 types, in certain exceptional circumstances.h]hZNew types which are identical to standard C99 types, in certain exceptional circumstances.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hAlthough it would only take a short amount of time for the eyes and brain to become accustomed to the standard types like ``uint32_t``, some people object to their use anyway.h](hzAlthough it would only take a short amount of time for the eyes and brain to become accustomed to the standard types like }(hj hhhNhNubjk)}(h ``uint32_t``h]huint32_t}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh), some people object to their use anyway.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hTherefore, the Linux-specific ``u8/u16/u32/u64`` types and their signed equivalents which are identical to standard types are permitted -- although they are not mandatory in new code of your own.h](hTherefore, the Linux-specific }(hj$ hhhNhNubjk)}(h``u8/u16/u32/u64``h]hu8/u16/u32/u64}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj$ ubh types and their signed equivalents which are identical to standard types are permitted -- although they are not mandatory in new code of your own.}(hj$ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hWhen editing existing code which already uses one or the other set of types, you should conform to the existing choices in that code.h]hWhen editing existing code which already uses one or the other set of types, you should conform to the existing choices in that code.}(hjD hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1j]hjZubj^)}(hTypes safe for use in userspace. In certain structures which are visible to userspace, we cannot require C99 types and cannot use the ``u32`` form above. Thus, we use __u32 and similar types in all structures which are shared with userspace. h](h)}(h Types safe for use in userspace.h]h Types safe for use in userspace.}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjX ubh)}(hIn certain structures which are visible to userspace, we cannot require C99 types and cannot use the ``u32`` form above. Thus, we use __u32 and similar types in all structures which are shared with userspace.h](heIn certain structures which are visible to userspace, we cannot require C99 types and cannot use the }(hjj hhhNhNubjk)}(h``u32``h]hu32}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjj ubhd form above. Thus, we use __u32 and similar types in all structures which are shared with userspace.}(hjj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjX ubeh}(h]h ]h"]h$]h&]uh1j]hjZubeh}(h]h ]h"]h$]h&]enumtype loweralphaprefix(suffix)uh1jXhjTubah}(h]h ]h"]h$]h&]uh1jRhhhM~hjhhubh)}(hMaybe there are other cases too, but the rule should basically be to NEVER EVER use a typedef unless you can clearly match one of those rules.h]hMaybe there are other cases too, but the rule should basically be to NEVER EVER use a typedef unless you can clearly match one of those rules.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h|In general, a pointer, or a struct that has elements that can reasonably be directly accessed should **never** be a typedef.h](heIn general, a pointer, or a struct that has elements that can reasonably be directly accessed should }(hj hhhNhNubh)}(h **never**h]hnever}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh be a typedef.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]typedefsah ]h"] 5) typedefsah$]h&]uh1hhhhhhhhMhubh)}(hhh](h)}(h 6) Functionsh]h 6) Functions}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hFunctions 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, as we all know), and do one thing and do that well.h]hFunctions 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, as we all know), and do one thing and do that well.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXBThe maximum length of a function is inversely proportional to the complexity and indentation level of that function. So, if you have a conceptually simple function that is just one long (but simple) case-statement, where you have to do lots of small things for a lot of different cases, it's OK to have a longer function.h]hXDThe maximum length of a function is inversely proportional to the complexity and indentation level of that function. So, if you have a conceptually simple function that is just one long (but simple) case-statement, where you have to do lots of small things for a lot of different cases, it’s OK to have a longer function.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXHowever, if you have a complex function, and you suspect that a less-than-gifted first-year high-school student might not even understand what the function is all about, you should adhere to the maximum limits all the more closely. Use helper functions with descriptive names (you can ask the compiler to in-line them if you think it's performance-critical, and it will probably do a better job of it than you would have done).h]hXHowever, if you have a complex function, and you suspect that a less-than-gifted first-year high-school student might not even understand what the function is all about, you should adhere to the maximum limits all the more closely. Use helper functions with descriptive names (you can ask the compiler to in-line them if you think it’s performance-critical, and it will probably do a better job of it than you would have done).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXAnother measure of the function is the number of local variables. They shouldn't exceed 5-10, or you're doing something wrong. Re-think the function, and split it into smaller pieces. A human brain can generally easily keep track of about 7 different things, anything more and it gets confused. You know you're brilliant, but maybe you'd like to understand what you did 2 weeks from now.h]hXAnother measure of the function is the number of local variables. They shouldn’t exceed 5-10, or you’re doing something wrong. Re-think the function, and split it into smaller pieces. A human brain can generally easily keep track of about 7 different things, anything more and it gets confused. You know you’re brilliant, but maybe you’d like to understand what you did 2 weeks from now.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hIn 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.:h](h[In source files, separate functions with one blank line. If the function is exported, the }(hj! hhhNhNubh)}(h **EXPORT**h]hEXPORT}(hj) hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj! ubhU macro for it should follow immediately after the closing function brace line. E.g.:}(hj! hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hfint system_is_up(void) { return system_state == SYSTEM_RUNNING; } EXPORT_SYMBOL(system_is_up);h]hfint system_is_up(void) { return system_state == SYSTEM_RUNNING; } EXPORT_SYMBOL(system_is_up);}hjA sbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMhj hhubh)}(hhh](h)}(h6.1) Function prototypesh]h6.1) Function prototypes}(hjS hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjP hhhhhMubh)}(hIn function prototypes, include parameter names with their data types. Although this is not required by the C language, it is preferred in Linux because it is a simple way to add valuable information for the reader.h]hIn function prototypes, include parameter names with their data types. Although this is not required by the C language, it is preferred in Linux because it is a simple way to add valuable information for the reader.}(hja hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjP hhubh)}(huDo not use the ``extern`` keyword with function declarations as this makes lines longer and isn't strictly necessary.h](hDo not use the }(hjo hhhNhNubjk)}(h ``extern``h]hextern}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjo ubh^ keyword with function declarations as this makes lines longer and isn’t strictly necessary.}(hjo hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjP hhubh)}(hWhen writing function prototypes, please keep the `order of elements regular `_. For example, using this function declaration example::h](h2When writing function prototypes, please keep the }(hj hhhNhNubh reference)}(h`order of elements regular `_h]horder of elements regular}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameorder of elements regularrefurifhttps://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/uh1j hj ubh)}(hi h]h}(h]order-of-elements-regularah ]h"]order of elements regularah$]h&]refurij uh1h referencedKhj ubh7. For example, using this function declaration example:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjP hhubj)}(h__init void * __must_check action(enum magic value, size_t size, u8 count, char *fmt, ...) __printf(4, 5) __malloc;h]h__init void * __must_check action(enum magic value, size_t size, u8 count, char *fmt, ...) __printf(4, 5) __malloc;}hj sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjP hhubh)}(h hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj6 ubh4 -- i.e. section declarations, but also things like }(hj6 hhhNhNubjk)}(h ``__cold``h]h__cold}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj6 ubh)}(hj6 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj2 ubah}(h]h ]h"]h$]h&]uh1j]hj hhhhhNubj^)}(hreturn type (here, ``void *``)h]h)}(hjp h](hreturn type (here, }(hjr hhhNhNubjk)}(h ``void *``h]hvoid *}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjr ubh)}(hjr hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjn ubah}(h]h ]h"]h$]h&]uh1j]hj hhhhhNubj^)}(h/return type attributes (here, ``__must_check``)h]h)}(hj h](hreturn type attributes (here, }(hj hhhNhNubjk)}(h``__must_check``h]h __must_check}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j]hj hhhhhNubj^)}(h function name (here, ``action``)h]h)}(hj h](hfunction name (here, }(hj hhhNhNubjk)}(h ``action``h]haction}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j]hj hhhhhNubj^)}(hfunction parameters (here, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, noting that parameter names should always be included)h]h)}(hfunction parameters (here, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, noting that parameter names should always be included)h](hfunction parameters (here, }(hj hhhNhNubjk)}(h=``(enum magic value, size_t size, u8 count, char *fmt, ...)``h]h9(enum magic value, size_t size, u8 count, char *fmt, ...)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh8, noting that parameter names should always be included)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j]hj hhhhhNubj^)}(h8function parameter attributes (here, ``__printf(4, 5)``)h]h)}(hj h](h%function parameter attributes (here, }(hj hhhNhNubjk)}(h``__printf(4, 5)``h]h__printf(4, 5)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j]hj hhhhhNubj^)}(h2function behavior attributes (here, ``__malloc``) h]h)}(h1function behavior attributes (here, ``__malloc``)h](h$function behavior attributes (here, }(hj@ hhhNhNubjk)}(h ``__malloc``h]h__malloc}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj@ ubh)}(hj@ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj< ubah}(h]h ]h"]h$]h&]uh1j]hj hhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1j hhhMhjP hhubh)}(hXQNote that for a function **definition** (i.e. the actual function body), the compiler does not allow function parameter attributes after the function parameters. In these cases, they should go after the storage class attributes (e.g. note the changed position of ``__printf(4, 5)`` below, compared to the **declaration** example above)::h](hNote that for a function }(hjn hhhNhNubh)}(h**definition**h]h definition}(hjv hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjn ubh (i.e. the actual function body), the compiler does not allow function parameter attributes after the function parameters. In these cases, they should go after the storage class attributes (e.g. note the changed position of }(hjn hhhNhNubjk)}(h``__printf(4, 5)``h]h__printf(4, 5)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjn ubh below, compared to the }(hjn hhhNhNubh)}(h**declaration**h]h declaration}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjn ubh example above):}(hjn hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjP hhubj)}(hstatic __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, size_t size, u8 count, char *fmt, ...) __malloc { ... }h]hstatic __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, size_t size, u8 count, char *fmt, ...) __malloc { ... }}hj sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjP hhubeh}(h]function-prototypesah ]h"]6.1) function prototypesah$]h&]uh1hhj hhhhhMubeh}(h] functionsah ]h"] 6) functionsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h#7) Centralized exiting of functionsh]h#7) Centralized exiting of functions}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hAlbeit deprecated by some people, the equivalent of the goto statement is used frequently by compilers in form of the unconditional jump instruction.h]hAlbeit deprecated by some people, the equivalent of the goto statement is used frequently by compilers in form of the unconditional jump instruction.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hThe goto statement comes in handy when a function exits from multiple locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly.h]hThe goto statement comes in handy when a function exits from multiple locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXVChoose label names which say what the goto does or why the goto exists. An example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to renumber them if you ever add or remove exit paths, and they make correctness difficult to verify anyway.h](hlChoose label names which say what the goto does or why the goto exists. An example of a good name could be }(hj hhhNhNubjk)}(h``out_free_buffer:``h]hout_free_buffer:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh if the goto frees }(hj hhhNhNubjk)}(h ``buffer``h]hbuffer}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh". Avoid using GW-BASIC names like }(hj hhhNhNubjk)}(h ``err1:``h]herr1:}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh and }(hj hhhNhNubjk)}(h ``err2:``h]herr2:}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj ubh, as you would have to renumber them if you ever add or remove exit paths, and they make correctness difficult to verify anyway.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h!The rationale for using gotos is:h]h!The rationale for using gotos is:}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj )}(hhh](j^)}(hhj hhubj)}(hEerr: kfree(foo->bar); kfree(foo); return ret;h]hEerr: kfree(foo->bar); kfree(foo); return ret;}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhM@hj hhubh)}(hThe bug in this code is that on some exit paths ``foo`` is NULL. Normally the fix for this is to split it up into two error labels ``err_free_bar:`` and ``err_free_foo:``:h](h0The bug in this code is that on some exit paths }(hjhhhNhNubjk)}(h``foo``h]hfoo}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhM is NULL. Normally the fix for this is to split it up into two error labels }(hjhhhNhNubjk)}(h``err_free_bar:``h]h err_free_bar:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh and }(hjhhhNhNubjk)}(h``err_free_foo:``h]h err_free_foo:}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMGhj hhubj)}(h\err_free_bar: kfree(foo->bar); err_free_foo: kfree(foo); return ret;h]h\err_free_bar: kfree(foo->bar); err_free_foo: kfree(foo); return ret;}hjJsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMKhj hhubh)}(h:Ideally you should simulate errors to test all exit paths.h]h:Ideally you should simulate errors to test all exit paths.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMShj hhubeh}(h] centralized-exiting-of-functionsah ]h"]#7) centralized exiting of functionsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h 8) Commentingh]h 8) Commenting}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjohhhhhMWubh)}(hComments 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 write the code so that the **working** is obvious, and it's a waste of time to explain badly written code.h](hComments 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 write the code so that the }(hjhhhNhNubh)}(h **working**h]hworking}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhF is obvious, and it’s a waste of time to explain badly written code.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMYhjohhubh)}(hXGenerally, you want your comments to tell WHAT your code does, not HOW. Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, you should probably go back to chapter 6 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head of the function, telling people what it does, and possibly WHY it does it.h]hXGenerally, you want your comments to tell WHAT your code does, not HOW. Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, you should probably go back to chapter 6 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head of the function, telling people what it does, and possibly WHY it does it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hjohhubh)}(hXuWhen commenting the kernel API functions, please use the kernel-doc format. See the files at :ref:`Documentation/doc-guide/ ` and ``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting applies to kernel-doc comments all the same. Do not add boilerplate kernel-doc which simply reiterates what's obvious from the signature of the function.h](h]When commenting the kernel API functions, please use the kernel-doc format. See the files at }(hjhhhNhNubh)}(h+:ref:`Documentation/doc-guide/ `h]hinline)}(hjh]hDocumentation/doc-guide/}(hjhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocprocess/coding-style refdomainjreftyperef refexplicitrefwarn reftarget doc_guideuh1hhhhMghjubh and }(hjhhhNhNubjk)}(h``tools/docs/kernel-doc``h]htools/docs/kernel-doc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh for details. Note that the danger of over-commenting applies to kernel-doc comments all the same. Do not add boilerplate kernel-doc which simply reiterates what’s obvious from the signature of the function.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMghjohhubh)}(h6The preferred style for long (multi-line) comments is:h]h6The preferred style for long (multi-line) comments is:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMnhjohhubj)}(h/* * This is the preferred style for multi-line * comments in the Linux kernel source code. * Please use it consistently. * * Description: A column of asterisks on the left side, * with beginning and ending almost-blank lines. */h]h/* * This is the preferred style for multi-line * comments in the Linux kernel source code. * Please use it consistently. * * Description: A column of asterisks on the left side, * with beginning and ending almost-blank lines. */}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMphjohhubh)}(hXIt's also important to comment data, whether they are basic types or derived types. To this end, use just one data declaration per line (no commas for multiple data declarations). This leaves you room for a small comment on each item, explaining its use.h]hXIt’s also important to comment data, whether they are basic types or derived types. To this end, use just one data declaration per line (no commas for multiple data declarations). This leaves you room for a small comment on each item, explaining its use.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM{hjohhubeh}(h] commentingah ]h"] 8) commentingah$]h&]uh1hhhhhhhhMWubh)}(hhh](h)}(h9) You've made a mess of ith]h9) You’ve made a mess of it}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj*hhhhhMubh)}(hXvThat'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 you, and you've noticed that yes, it does do that, but the defaults it uses are less than desirable (in fact, they are worse than random typing - an infinite number of monkeys typing into GNU emacs would never make a good program).h](h]That’s OK, we all do. You’ve probably been told by your long-time Unix user helper that }(hj;hhhNhNubjk)}(h ``GNU emacs``h]h GNU emacs}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj;ubhX automatically formats the C sources for you, and you’ve noticed that yes, it does do that, but the defaults it uses are less than desirable (in fact, they are worse than random typing - an infinite number of monkeys typing into GNU emacs would never make a good program).}(hj;hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hSo, 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:h]hSo, 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:}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubj)}(hX(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)h]hX(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)}hjisbah}(h]h ]h"]h$]h&]jjjjelispj}uh1jhhhMhj*hhubh)}(hdThis will make emacs go better with the kernel coding style for C files below ``~/src/linux-trees``.h](hNThis will make emacs go better with the kernel coding style for C files below }(hjyhhhNhNubjk)}(h``~/src/linux-trees``h]h~/src/linux-trees}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjyubh.}(hjyhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hdBut even if you fail in getting emacs to do sane formatting, not everything is lost: use ``indent``.h](hYBut even if you fail in getting emacs to do sane formatting, not everything is lost: use }(hjhhhNhNubjk)}(h ``indent``h]hindent}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hXNow, again, GNU indent has the same brain-dead settings that GNU emacs has, which is why you need to give it a few command line options. However, that's not too bad, because even the makers of GNU indent recognize the authority of K&R (the GNU people aren't evil, they are just severely misguided in this matter), so you just give indent the options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use ``scripts/Lindent``, which indents in the latest style.h](hXbNow, again, GNU indent has the same brain-dead settings that GNU emacs has, which is why you need to give it a few command line options. However, that’s not too bad, because even the makers of GNU indent recognize the authority of K&R (the GNU people aren’t evil, they are just severely misguided in this matter), so you just give indent the options }(hjhhhNhNubjk)}(h ``-kr -i8``h]h-kr -i8}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh (stands for }(hjhhhNhNubjk)}(h``K&R, 8 character indents``h]hK&R, 8 character indents}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh ), or use }(hjhhhNhNubjk)}(h``scripts/Lindent``h]hscripts/Lindent}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh$, which indents in the latest style.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(h``indent`` has a lot of options, and especially when it comes to comment re-formatting you may want to take a look at the man page. But remember: ``indent`` is not a fix for bad programming.h](jk)}(h ``indent``h]hindent}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh has a lot of options, and especially when it comes to comment re-formatting you may want to take a look at the man page. But remember: }(hjhhhNhNubjk)}(h ``indent``h]hindent}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh" is not a fix for bad programming.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hXNote that you can also use the ``clang-format`` tool to help you with these rules, to quickly re-format parts of your code automatically, and to review full files in order to spot coding style mistakes, typos and possible improvements. It is also handy for sorting ``#includes``, for aligning variables/macros, for reflowing text and other similar tasks. See the file :ref:`Documentation/dev-tools/clang-format.rst ` for more details.h](hNote that you can also use the }(hj+hhhNhNubjk)}(h``clang-format``h]h clang-format}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj+ubh tool to help you with these rules, to quickly re-format parts of your code automatically, and to review full files in order to spot coding style mistakes, typos and possible improvements. It is also handy for sorting }(hj+hhhNhNubjk)}(h ``#includes``h]h #includes}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhj+ubhZ, for aligning variables/macros, for reflowing text and other similar tasks. See the file }(hj+hhhNhNubh)}(h=:ref:`Documentation/dev-tools/clang-format.rst `h]j)}(hjYh]h(Documentation/dev-tools/clang-format.rst}(hj[hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjWubah}(h]h ]h"]h$]h&]refdocj refdomainjereftyperef refexplicitrefwarnj clangformatuh1hhhhMhj+ubh for more details.}(hj+hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubh)}(hSome basic editor settings, such as indentation and line endings, will be set automatically if you are using an editor that is compatible with EditorConfig. See the official EditorConfig website for more information: https://editorconfig.org/h](hSome basic editor settings, such as indentation and line endings, will be set automatically if you are using an editor that is compatible with EditorConfig. See the official EditorConfig website for more information: }(hjhhhNhNubj )}(hhttps://editorconfig.org/h]hhttps://editorconfig.org/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1j hjubeh}(h]h ]h"]h$]h&]uh1hhhhMhj*hhubeh}(h]you-ve-made-a-mess-of-itah ]h"]9) you've made a mess of itah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h10) Kconfig configuration filesh]h10) Kconfig configuration files}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hFor 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::h](h~For all of the Kconfig* configuration files throughout the source tree, the indentation is somewhat different. Lines under a }(hjhhhNhNubjk)}(h ``config``h]hconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhf definition are indented with one tab, while help text is indented an additional two spaces. Example:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hXBconfig 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.h]hXBconfig 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.}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(hSeriously dangerous features (such as write support for certain filesystems) should advertise this prominently in their prompt string::h]hSeriously dangerous features (such as write support for certain filesystems) should advertise this prominently in their prompt string:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h`config ADFS_FS_RW bool "ADFS write support (DANGEROUS)" depends on ADFS_FS ...h]h`config ADFS_FS_RW bool "ADFS write support (DANGEROUS)" depends on ADFS_FS ...}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(hjFor full documentation on the configuration files, see the file Documentation/kbuild/kconfig-language.rst.h]hjFor full documentation on the configuration files, see the file Documentation/kbuild/kconfig-language.rst.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]kconfig-configuration-filesah ]h"]10) kconfig configuration filesah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h11) Data structuresh]h11) Data structures}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXTData structures that have visibility outside the single-threaded environment they are created and destroyed in should always have reference counts. In the kernel, garbage collection doesn't exist (and outside the kernel garbage collection is slow and inefficient), which means that you absolutely **have** to reference count all your uses.h](hX,Data structures that have visibility outside the single-threaded environment they are created and destroyed in should always have reference counts. In the kernel, garbage collection doesn’t exist (and outside the kernel garbage collection is slow and inefficient), which means that you absolutely }(hj(hhhNhNubh)}(h**have**h]hhave}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj(ubh" to reference count all your uses.}(hj(hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX Reference counting means that you can avoid locking, and allows multiple users to have access to the data structure in parallel - and not having to worry about the structure suddenly going away from under them just because they slept or did something else for a while.h]hX Reference counting means that you can avoid locking, and allows multiple users to have access to the data structure in parallel - and not having to worry about the structure suddenly going away from under them just because they slept or did something else for a while.}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hNote that locking is **not** a replacement for reference counting. Locking is used to keep data structures coherent, while reference counting is a memory management technique. Usually both are needed, and they are not to be confused with each other.h](hNote that locking is }(hjVhhhNhNubh)}(h**not**h]hnot}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjVubh a replacement for reference counting. Locking is used to keep data structures coherent, while reference counting is a memory management technique. Usually both are needed, and they are not to be confused with each other.}(hjVhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hMany data structures can indeed have two levels of reference counting, when there are users of different ``classes``. The subclass count counts the number of subclass users, and decrements the global count just once when the subclass count goes to zero.h](hiMany data structures can indeed have two levels of reference counting, when there are users of different }(hjvhhhNhNubjk)}(h ``classes``h]hclasses}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjvubh. The subclass count counts the number of subclass users, and decrements the global count just once when the subclass count goes to zero.}(hjvhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hExamples of this kind of ``multi-level-reference-counting`` can be found in memory management (``struct mm_struct``: mm_users and mm_count), and in filesystem code (``struct super_block``: s_count and s_active).h](hExamples of this kind of }(hjhhhNhNubjk)}(h"``multi-level-reference-counting``h]hmulti-level-reference-counting}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh$ can be found in memory management (}(hjhhhNhNubjk)}(h``struct mm_struct``h]hstruct mm_struct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh2: mm_users and mm_count), and in filesystem code (}(hjhhhNhNubjk)}(h``struct super_block``h]hstruct super_block}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh: s_count and s_active).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hRemember: if another thread can find your data structure, and you don't have a reference count on it, you almost certainly have a bug.h]hRemember: if another thread can find your data structure, and you don’t have a reference count on it, you almost certainly have a bug.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]data-structuresah ]h"]11) data structuresah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h12) Macros, Enums and RTLh]h12) Macros, Enums and RTL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hGNames of macros defining constants and labels in enums are capitalized.h]hGNames of macros defining constants and labels in enums are capitalized.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h#define CONSTANT 0x12345h]h#define CONSTANT 0x12345}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhM hjhhubh)}(hhjhhubj)}(h/* * Avoid doing this whenever possible and instead opt for static * inline functions */ #define macrofun(foo) do { (void) (foo); } while (0)h]h/* * Avoid doing this whenever possible and instead opt for static * inline functions */ #define macrofun(foo) do { (void) (foo); } while (0)}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMDhjhhubh)}(h"Things to avoid when using macros:h]h"Things to avoid when using macros:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjhhubjY)}(hhh]j^)}(h!macros that affect control flow: h]h)}(h macros that affect control flow:h]h macros that affect control flow:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhjubah}(h]h ]h"]h$]h&]uh1j]hjhhhhhNubah}(h]h ]h"]h$]h&]j arabicj hj j uh1jXhjhhhhhMNubj)}(h#define FOO(x) \ do { \ if (blah(x) < 0) \ return -EBUGGERED; \ } while (0)h]h#define FOO(x) \ do { \ if (blah(x) < 0) \ return -EBUGGERED; \ } while (0)}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMPhjhhubh)}(his a **very** bad idea. It looks like a function call but exits the ``calling`` function; don't break the internal parsers of those who will read the code.h](his a }(hjhhhNhNubh)}(h**very**h]hvery}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh8 bad idea. It looks like a function call but exits the }(hjhhhNhNubjk)}(h ``calling``h]hcalling}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhN function; don’t break the internal parsers of those who will read the code.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMXhjhhubjY)}(hhh]j^)}(hAmacros that depend on having a local variable with a magic name: h]h)}(h@macros that depend on having a local variable with a magic name:h]h@macros that depend on having a local variable with a magic name:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM[hjubah}(h]h ]h"]h$]h&]uh1j]hjhhhhhNubah}(h]h ]h"]h$]h&]j jj hj j startKuh1jXhjhhhhhM[ubj)}(h #define FOO(val) bar(index, val)h]h #define FOO(val) bar(index, val)}hj2sbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhM]hjhhubh)}(hmight look like a good thing, but it's confusing as hell when one reads the code and it's prone to breakage from seemingly innocent changes.h]hmight look like a good thing, but it’s confusing as hell when one reads the code and it’s prone to breakage from seemingly innocent changes.}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMahjhhubh)}(h3) macros with arguments that are used as l-values: FOO(x) = y; will bite you if somebody e.g. turns FOO into an inline function.h]h3) macros with arguments that are used as l-values: FOO(x) = y; will bite you if somebody e.g. turns FOO into an inline function.}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMdhjhhubh)}(h4) forgetting about precedence: macros defining constants using expressions must enclose the expression in parentheses. Beware of similar issues with macros using parameters.h]h4) forgetting about precedence: macros defining constants using expressions must enclose the expression in parentheses. Beware of similar issues with macros using parameters.}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMghjhhubj)}(h7#define CONSTANT 0x4000 #define CONSTEXP (CONSTANT | 3)h]h7#define CONSTANT 0x4000 #define CONSTEXP (CONSTANT | 3)}hjksbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMkhjhhubh)}(hU5) namespace collisions when defining local variables in macros resembling functions:h]hU5) namespace collisions when defining local variables in macros resembling functions:}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMphjhhubj)}(h#define FOO(x) \ ({ \ typeof(x) ret; \ ret = calc_ret(x); \ (ret); \ })h]h#define FOO(x) \ ({ \ typeof(x) ret; \ ret = calc_ret(x); \ (ret); \ })}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMshjhhubh)}(hjret is a common name for a local variable - __foo_ret is less likely to collide with an existing variable.h]hjret is a common name for a local variable - __foo_ret is less likely to collide with an existing variable.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM|hjhhubh)}(hThe cpp manual deals with macros exhaustively. The gcc internals manual also covers RTL which is used frequently with assembly language in the kernel.h]hThe cpp manual deals with macros exhaustively. The gcc internals manual also covers RTL which is used frequently with assembly language in the kernel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]macros-enums-and-rtlah ]h"]12) macros, enums and rtlah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h13) Printing kernel messagesh]h13) Printing kernel messages}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hKernel developers like to be seen as literate. Do mind the spelling of kernel messages to make a good impression. Do not use incorrect contractions like ``dont``; use ``do not`` or ``don't`` instead. Make the messages concise, clear, and unambiguous.h](hKernel developers like to be seen as literate. Do mind the spelling of kernel messages to make a good impression. Do not use incorrect contractions like }(hjhhhNhNubjk)}(h``dont``h]hdont}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh; use }(hjhhhNhNubjk)}(h ``do not``h]hdo not}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh or }(hjhhhNhNubjk)}(h ``don't``h]hdon't}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh< instead. Make the messages concise, clear, and unambiguous.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h;Kernel messages do not have to be terminated with a period.h]h;Kernel messages do not have to be terminated with a period.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hIPrinting numbers in parentheses (%d) adds no value and should be avoided.h]hIPrinting numbers in parentheses (%d) adds no value and should be avoided.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXThere are a number of driver model diagnostic macros in which you should use to make sure messages are matched to the right device and driver, and are tagged with the right level: dev_err(), dev_warn(), dev_info(), and so forth. For messages that aren't associated with a particular device, defines pr_notice(), pr_info(), pr_warn(), pr_err(), etc. When drivers are working properly they are quiet, so prefer to use dev_dbg/pr_debug unless something is wrong.h]hXThere are a number of driver model diagnostic macros in which you should use to make sure messages are matched to the right device and driver, and are tagged with the right level: dev_err(), dev_warn(), dev_info(), and so forth. For messages that aren’t associated with a particular device, defines pr_notice(), pr_info(), pr_warn(), pr_err(), etc. When drivers are working properly they are quiet, so prefer to use dev_dbg/pr_debug unless something is wrong.}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX(Coming up with good debugging messages can be quite a challenge; and once you have them, they can be a huge help for remote troubleshooting. However debug message printing is handled differently than printing other non-debug messages. While the other pr_XXX() functions print unconditionally, pr_debug() does not; it is compiled out by default, unless either DEBUG is defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the ones already enabled by DEBUG.h]hX(Coming up with good debugging messages can be quite a challenge; and once you have them, they can be a huge help for remote troubleshooting. However debug message printing is handled differently than printing other non-debug messages. While the other pr_XXX() functions print unconditionally, pr_debug() does not; it is compiled out by default, unless either DEBUG is defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the ones already enabled by DEBUG.}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX*Many subsystems have Kconfig debug options to turn on -DDEBUG in the corresponding Makefile; in other cases specific files #define DEBUG. And when a debug message should be unconditionally printed, such as if it is already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be used.h]hX*Many subsystems have Kconfig debug options to turn on -DDEBUG in the corresponding Makefile; in other cases specific files #define DEBUG. And when a debug message should be unconditionally printed, such as if it is already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be used.}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]printing-kernel-messagesah ]h"]13) printing kernel messagesah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h14) Allocating memoryh]h14) Allocating memory}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^hhhhhMubh)}(hX(The kernel provides the following general purpose memory allocators: kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and vzalloc(). Please refer to the API documentation for further information about them. :ref:`Documentation/core-api/memory-allocation.rst `h](hThe kernel provides the following general purpose memory allocators: kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and vzalloc(). Please refer to the API documentation for further information about them. }(hjohhhNhNubh)}(hG:ref:`Documentation/core-api/memory-allocation.rst `h]j)}(hjyh]h,Documentation/core-api/memory-allocation.rst}(hj{hhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1jhjwubah}(h]h ]h"]h$]h&]refdocj refdomainjreftyperef refexplicitrefwarnjmemory_allocationuh1hhhhMhjoubeh}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubh)}(hCThe preferred form for passing a size of a struct is the following:h]hCThe preferred form for passing a size of a struct is the following:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubj)}(hp = kmalloc_obj(*p, ...);h]hp = kmalloc_obj(*p, ...);}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMhj^hhubh)}(hThe alternative form where struct name is spelled out hurts readability and introduces an opportunity for a bug when the pointer variable type is changed but the corresponding sizeof that is passed to a memory allocator is not.h]hThe alternative form where struct name is spelled out hurts readability and introduces an opportunity for a bug when the pointer variable type is changed but the corresponding sizeof that is passed to a memory allocator is not.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubh)}(hCasting the return value which is a void pointer is redundant. The conversion from void pointer to any other pointer type is guaranteed by the C programming language.h]hCasting the return value which is a void pointer is redundant. The conversion from void pointer to any other pointer type is guaranteed by the C programming language.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj^hhubh)}(hf))h]h/#define sizeof_field(t, f) (sizeof(((t*)0)->f))}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhM>hjhhubh)}(hwhich is defined in stddef.h.h]hwhich is defined in stddef.h.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMBhjhhubh)}(hThere are also min() and max() macros defined in minmax.h that do strict type checking if you need them. Feel free to peruse the header files to see what else is already defined that you shouldn't reproduce in your code.h]hThere are also min() and max() macros defined in minmax.h that do strict type checking if you need them. Feel free to peruse the header files to see what else is already defined that you shouldn’t reproduce in your code.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhjhhubeh}(h]!don-t-re-invent-the-kernel-macrosah ]h"]%18) don't re-invent the kernel macrosah$]h&]uh1hhhhhhhhM/ubh)}(hhh](h)}(h$19) Editor modelines and other crufth]h$19) Editor modelines and other cruft}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj8hhhhhMJubh)}(hSome editors can interpret configuration information embedded in source files, indicated with special markers. For example, emacs interprets lines marked like this:h]hSome editors can interpret configuration information embedded in source files, indicated with special markers. For example, emacs interprets lines marked like this:}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhj8hhubj)}(h-*- mode: c -*-h]h-*- mode: c -*-}hjWsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMPhj8hhubh)}(h Or like this:h]h Or like this:}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMThj8hhubj)}(hK/* Local Variables: compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" End: */h]hK/* Local Variables: compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" End: */}hjtsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMVhj8hhubh)}(h+Vim interprets markers that look like this:h]h+Vim interprets markers that look like this:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hj8hhubj)}(h/* vim:set sw=8 noet */h]h/* vim:set sw=8 noet */}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhM`hj8hhubh)}(hXDDo not include any of these in source files. People have their own personal editor configurations, and your source files should not override them. This includes markers for indentation and mode configuration. People may use their own custom mode, or may have some other magic method for making indentation work correctly.h]hXDDo not include any of these in source files. People have their own personal editor configurations, and your source files should not override them. This includes markers for indentation and mode configuration. People may use their own custom mode, or may have some other magic method for making indentation work correctly.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMdhj8hhubeh}(h] editor-modelines-and-other-cruftah ]h"]$19) editor modelines and other cruftah$]h&]uh1hhhhhhhhMJubh)}(hhh](h)}(h20) Inline assemblyh]h20) Inline assembly}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMlubh)}(hXIn 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. However, don't use inline assembly gratuitously when C can do the job. You can and should poke hardware from C when possible.h]hXIn 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. However, don’t use inline assembly gratuitously when C can do the job. You can and should poke hardware from C when possible.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMnhjhhubh)}(hConsider writing simple helper functions that wrap common bits of inline assembly, rather than repeatedly writing them with slight variations. Remember that inline assembly can use C parameters.h]hConsider writing simple helper functions that wrap common bits of inline assembly, rather than repeatedly writing them with slight variations. Remember that inline assembly can use C parameters.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMshjhhubh)}(hLarge, non-trivial assembly functions should go in .S files, with corresponding C prototypes defined in C header files. The C prototypes for assembly functions should use ``asmlinkage``.h](hLarge, non-trivial assembly functions should go in .S files, with corresponding C prototypes defined in C header files. The C prototypes for assembly functions should use }(hjhhhNhNubjk)}(h``asmlinkage``h]h asmlinkage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh.}(hjhhhNhNubehP}(h]h ]h"]h$]h&]uh1hhhhMwhjhhubh)}(hYou may need to mark your asm statement as volatile, to prevent GCC from removing it if GCC doesn't notice any side effects. You don't always need to do so, though, and doing so unnecessarily can limit optimization.h]hYou may need to mark your asm statement as volatile, to prevent GCC from removing it if GCC doesn’t notice any side effects. You don’t always need to do so, though, and doing so unnecessarily can limit optimization.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM{hjhhubh)}(hXWhen writing a single inline assembly statement containing multiple instructions, put each instruction on a separate line in a separate quoted string, and end each string except the last with ``\n\t`` to properly indent the next instruction in the assembly output:h](hWhen writing a single inline assembly statement containing multiple instructions, put each instruction on a separate line in a separate quoted string, and end each string except the last with }(hjhhhNhNubjk)}(h``\n\t``h]h\n\t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubh@ to properly indent the next instruction in the assembly output:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hqasm ("magic %reg1, #42\n\t" "more_magic %reg2, %reg3" : /* outputs */ : /* inputs */ : /* clobbers */);h]hqasm ("magic %reg1, #42\n\t" "more_magic %reg2, %reg3" : /* outputs */ : /* inputs */ : /* clobbers */);}hj1sbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMhjhhubeh}(h]inline-assemblyah ]h"]20) inline assemblyah$]h&]uh1hhhhhhhhMlubh)}(hhh](h)}(h21) Conditional Compilationh]h21) Conditional Compilation}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjHhhhhhMubh)}(hXWherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c files; doing so makes code harder to read and logic harder to follow. Instead, use such conditionals in a header file defining functions for use in those .c files, providing no-op stub versions in the #else case, and then call those functions unconditionally from .c files. The compiler will avoid generating any code for the stub calls, producing identical results, but the logic will remain easy to follow.h]hXWherever possible, don’t use preprocessor conditionals (#if, #ifdef) in .c files; doing so makes code harder to read and logic harder to follow. Instead, use such conditionals in a header file defining functions for use in those .c files, providing no-op stub versions in the #else case, and then call those functions unconditionally from .c files. The compiler will avoid generating any code for the stub calls, producing identical results, but the logic will remain easy to follow.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjHhhubh)}(hX Prefer to compile out entire functions, rather than portions of functions or portions of expressions. Rather than putting an ifdef in an expression, factor out part or all of the expression into a separate helper function and apply the conditional to that function.h]hX Prefer to compile out entire functions, rather than portions of functions or portions of expressions. Rather than putting an ifdef in an expression, factor out part or all of the expression into a separate helper function and apply the conditional to that function.}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjHhhubh)}(hXDIf you have a function or variable which may potentially go unused in a particular configuration, and the compiler would warn about its definition going unused, mark the definition as __maybe_unused rather than wrapping it in a preprocessor conditional. (However, if a function or variable *always* goes unused, delete it.)h](hX#If you have a function or variable which may potentially go unused in a particular configuration, and the compiler would warn about its definition going unused, mark the definition as __maybe_unused rather than wrapping it in a preprocessor conditional. (However, if a function or variable }(hjuhhhNhNubjn)}(h*always*h]halways}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1jmhjuubh goes unused, delete it.)}(hjuhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjHhhubh)}(hWithin 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:h]hWithin 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:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjHhhubj)}(h1if (IS_ENABLED(CONFIG_SOMETHING)) { ... }h]h1if (IS_ENABLED(CONFIG_SOMETHING)) { ... }}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMhjHhhubh)}(hXThe compiler will constant-fold the conditional away, and include or exclude the block of code just as with an #ifdef, so this will not add any runtime overhead. However, this approach still allows the C compiler to see the code inside the block, and check it for correctness (syntax, types, symbol references, etc). Thus, you still have to use an #ifdef if the code inside the block references symbols that will not exist if the condition is not met.h]hXThe compiler will constant-fold the conditional away, and include or exclude the block of code just as with an #ifdef, so this will not add any runtime overhead. However, this approach still allows the C compiler to see the code inside the block, and check it for correctness (syntax, types, symbol references, etc). Thus, you still have to use an #ifdef if the code inside the block references symbols that will not exist if the condition is not met.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjHhhubh)}(hAt the end of any non-trivial #if or #ifdef block (more than a few lines), place a comment after the #endif on the same line, noting the conditional expression used. For instance:h]hAt the end of any non-trivial #if or #ifdef block (more than a few lines), place a comment after the #endif on the same line, noting the conditional expression used. For instance:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjHhhubj)}(h9#ifdef CONFIG_SOMETHING ... #endif /* CONFIG_SOMETHING */h]h9#ifdef CONFIG_SOMETHING ... #endif /* CONFIG_SOMETHING */}hjsbah}(h]h ]h"]h$]h&]jjjjjj}uh1jhhhMhjHhhubeh}(h]conditional-compilationah ]h"]21) conditional compilationah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h22) Do not crash the kernelh]h22) Do not crash the kernel}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hfIn general, the decision to crash the kernel belongs to the user, rather than to the kernel developer.h]hfIn general, the decision to crash the kernel belongs to the user, rather than to the kernel developer.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(h Avoid panic()h]h Avoid panic()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hpanic() should be used with care and primarily only during system boot. panic() is, for example, acceptable when running out of memory during boot and not being able to continue.h]hpanic() should be used with care and primarily only during system boot. panic() is, for example, acceptable when running out of memory during boot and not being able to continue.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h] avoid-panicah ]h"] avoid panic()ah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hUse WARN() rather than BUG()h]hUse WARN() rather than BUG()}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+hhhhhMubh)}(hXDo not add new code that uses any of the BUG() variants, such as BUG(), BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not required if there is no reasonable way to at least partially recover.h]hXDo not add new code that uses any of the BUG() variants, such as BUG(), BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not required if there is no reasonable way to at least partially recover.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+hhubh)}(h"I'm too lazy to do error handling" is not an excuse for using BUG(). Major internal corruptions with no way of continuing may still use BUG(), but need good justification.h]h“I’m too lazy to do error handling” is not an excuse for using BUG(). Major internal corruptions with no way of continuing may still use BUG(), but need good justification.}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj+hhubeh}(h]use-warn-rather-than-bugah ]h"]use warn() rather than bug()ah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h2Use WARN_ON_ONCE() rather than WARN() or WARN_ON()h]h2Use WARN_ON_ONCE() rather than WARN() or WARN_ON()}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhj`hhhhhMubh)}(hX2WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it is common for a given warning condition, if it occurs at all, to occur multiple times. This can fill up and wrap the kernel log, and can even slow the system enough that the excessive logging turns into its own, additional problem.h]hX2WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it is common for a given warning condition, if it occurs at all, to occur multiple times. This can fill up and wrap the kernel log, and can even slow the system enough that the excessive logging turns into its own, additional problem.}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj`hhubeh}(h],use-warn-on-once-rather-than-warn-or-warn-onah ]h"]2use warn_on_once() rather than warn() or warn_on()ah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hDo not WARN lightlyh]hDo not WARN lightly}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXWARN*() is intended for unexpected, this-should-never-happen situations. WARN*() macros are not to be used for anything that is expected to happen during normal operation. These are not pre- or post-condition asserts, for example. Again: WARN*() must not be used for a condition that is expected to trigger easily, for example, by user space actions. pr_warn_once() is a possible alternative, if you need to notify the user of a problem.h]hXWARN*() is intended for unexpected, this-should-never-happen situations. WARN*() macros are not to be used for anything that is expected to happen during normal operation. These are not pre- or post-condition asserts, for example. Again: WARN*() must not be used for a condition that is expected to trigger easily, for example, by user space actions. pr_warn_once() is a possible alternative, if you need to notify the user of a problem.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]do-not-warn-lightlyah ]h"]do not warn lightlyah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h&Do not worry about panic_on_warn usersh]h&Do not worry about panic_on_warn users}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hX A few more words about panic_on_warn: Remember that ``panic_on_warn`` is an available kernel option, and that many users set this option. This is why there is a "Do not WARN lightly" writeup, above. However, the existence of panic_on_warn users is not a valid reason to avoid the judicious use WARN*(). That is because, whoever enables panic_on_warn has explicitly asked the kernel to crash if a WARN*() fires, and such users must be prepared to deal with the consequences of a system that is somewhat more likely to crash.h](h4A few more words about panic_on_warn: Remember that }(hjhhhNhNubjk)}(h``panic_on_warn``h]h panic_on_warn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jjhjubhX is an available kernel option, and that many users set this option. This is why there is a “Do not WARN lightly” writeup, above. However, the existence of panic_on_warn users is not a valid reason to avoid the judicious use WARN*(). That is because, whoever enables panic_on_warn has explicitly asked the kernel to crash if a WARN*() fires, and such users must be prepared to deal with the consequences of a system that is somewhat more likely to crash.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]&do-not-worry-about-panic-on-warn-usersah ]h"]&do not worry about panic_on_warn usersah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h.Use BUILD_BUG_ON() for compile-time assertionsh]h.Use BUILD_BUG_ON() for compile-time assertions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(h}The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a compile-time assertion that has no effect at runtime.h]h}The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a compile-time assertion that has no effect at runtime.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h],use-build-bug-on-for-compile-time-assertionsah ]h"].use build_bug_on() for compile-time assertionsah$]h&]uh1hhjhhhhhMubeh}(h]do-not-crash-the-kernelah ]h"]22) do not crash the kernelah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hAppendix I) Referencesh]hAppendix I) References}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hThe C Programming Language, Second Edition by Brian W. Kernighan and Dennis M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).h]hThe C Programming Language, Second Edition by Brian W. Kernighan and Dennis M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hoThe Practice of Programming by Brian W. Kernighan and Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X.h]hoThe Practice of Programming by Brian W. Kernighan and Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X.}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hGNU manuals - where in compliance with K&R and this text - for cpp, gcc, gcc internals and indent, all available from https://www.gnu.org/manual/h](hvGNU manuals - where in compliance with K&R and this text - for cpp, gcc, gcc internals and indent, all available from }(hjChhhNhNubj )}(hhttps://www.gnu.org/manual/h]hhttps://www.gnu.org/manual/}(hjKhhhNhNubah}(h]h ]h"]h$]h&]refurijMuh1j hjCubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hWG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/h](h]WG14 is the international standardization working group for the programming language C, URL: }(hj`hhhNhNubj )}(h'http://www.open-std.org/JTC1/SC22/WG14/h]h'http://www.open-std.org/JTC1/SC22/WG14/}(hjhhhhNhNubah}(h]h ]h"]h$]h&]refurijjuh1j hj`ubeh}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hzKernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/h](hKernel CodingStyle, by }(hj}hhhNhNubj )}(hgreg@kroah.comh]hgreg@kroah.com}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurimailto:greg@kroah.comuh1j hj}ubh at OLS 2002: }(hj}hhhNhNubj )}(hGhttp://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/h]hGhttp://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1j hj}ubeh}(h]h ]h"]h$]h&]uh1hhhhM hjhhubeh}(h]appendix-i-referencesah ]h"]appendix i) referencesah$]h&]uh1hhhhhhhhMubeh}(h](linux-kernel-coding-styleheh ]h"](linux kernel coding style codingstyleeh$]h&]uh1hhhhhhhhKexpect_referenced_by_name}jhsexpect_referenced_by_id}hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehÌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}h]hasnameids}(jhjjjWjTjjjjjjjjj j j j j j j j jljij'j$jjjjjjjjj[jXj1j.jjj=j:jjj5j2jjjEjBjjjjj(j%j]jZjjjjjjj jjju nametypes}(jjjWjjjjj j j j jlj'jjjjj[j1jj=jj5jjEjjj(j]jjjj juh}(hhjhjTjjjZjjjjOjj j jj j j jP j j jij j$jojj*jjjjjjjXjj.j^jj4j:jjj@j2jjj8jBjjjHjjj%jjZj+jj`jjjjjjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]hsystem_message)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "2" (ordinal 2)h]h>Enumerated list start value not ordinal-1: “2” (ordinal 2)}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjKubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehÌlineKuh1jIhjhhhhhM[ubatransform_messages]jJ)}(hhh]h)}(hhh]h1Hyperlink target "codingstyle" is not referenced.}hjlsbah}(h]h ]h"]h$]h&]uh1hhjiubah}(h]h ]h"]h$]h&]levelKtypejdsourcehÌlineKuh1jIuba transformerN include_log] decorationNhhub.