^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _codingstyle:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) Linux kernel coding style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) This is a short document describing the preferred coding style for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) linux kernel. Coding style is very personal, and I won't **force** my
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) views on anybody, but this is what goes for anything that I have to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) able to maintain, and I'd prefer it for most other things too. Please
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) at least consider the points made here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) First off, I'd suggest printing out a copy of the GNU coding standards,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) and NOT read it. Burn them, it's a great symbolic gesture.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Anyway, here goes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 1) Indentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) Tabs are 8 characters, and thus indentations are also 8 characters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) There are heretic movements that try to make indentations 4 (or even 2!)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) characters deep, and that is akin to trying to define the value of PI to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) be 3.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Rationale: The whole idea behind indentation is to clearly define where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) a block of control starts and ends. Especially when you've been looking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) at your screen for 20 straight hours, you'll find it a lot easier to see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) how the indentation works if you have large indentations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Now, some people will claim that having 8-character indentations makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) the code move too far to the right, and makes it hard to read on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 80-character terminal screen. The answer to that is that if you need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) more than 3 levels of indentation, you're screwed anyway, and should fix
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) your program.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) In short, 8-char indents make things easier to read, and have the added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) benefit of warning you when you're nesting your functions too deep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Heed that warning.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) The preferred way to ease multiple indentation levels in a switch statement is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) to align the ``switch`` and its subordinate ``case`` labels in the same column
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) instead of ``double-indenting`` the ``case`` labels. E.g.:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) switch (suffix) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) case 'G':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) case 'g':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) mem <<= 30;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) case 'M':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) case 'm':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) mem <<= 20;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) case 'K':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) case 'k':
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) mem <<= 10;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) fallthrough;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) default:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Don't put multiple statements on a single line unless you have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) something to hide:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) if (condition) do_this;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) do_something_everytime;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) Don't put multiple assignments on a single line either. Kernel coding style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) is super simple. Avoid tricky expressions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Outside of comments, documentation and except in Kconfig, spaces are never
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) used for indentation, and the above example is deliberately broken.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) Get a decent editor and don't leave whitespace at the end of lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) 2) Breaking long lines and strings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Coding style is all about readability and maintainability using commonly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) available tools.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) The preferred limit on the length of a single line is 80 columns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) Statements longer than 80 columns should be broken into sensible chunks,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) unless exceeding 80 columns significantly increases readability and does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) not hide information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Descendants are always substantially shorter than the parent and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) are placed substantially to the right. A very commonly used style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) is to align descendants to a function open parenthesis.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) These same rules are applied to function headers with a long argument list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) However, never break user-visible strings such as printk messages because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) that breaks the ability to grep for them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 3) Placing Braces and Spaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) The other issue that always comes up in C styling is the placement of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) braces. Unlike the indent size, there are few technical reasons to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) choose one placement strategy over the other, but the preferred way, as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) shown to us by the prophets Kernighan and Ritchie, is to put the opening
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) brace last on the line, and put the closing brace first, thusly:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) if (x is true) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) we do y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) This applies to all non-function statement blocks (if, switch, for,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) while, do). E.g.:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) switch (action) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) case KOBJ_ADD:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) return "add";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) case KOBJ_REMOVE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) return "remove";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) case KOBJ_CHANGE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) return "change";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) default:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) return NULL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) However, there is one special case, namely functions: they have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) opening brace at the beginning of the next line, thus:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) int function(int x)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) body of function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Heretic people all over the world have claimed that this inconsistency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) is ... well ... inconsistent, but all right-thinking people know that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) (a) K&R are **right** and (b) K&R are right. Besides, functions are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) special anyway (you can't nest them in C).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Note that the closing brace is empty on a line of its own, **except** in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) the cases where it is followed by a continuation of the same statement,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) do {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) body of do-loop
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) } while (condition);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) if (x == y) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) ..
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) } else if (x > y) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) } else {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) Rationale: K&R.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) Also, note that this brace-placement also minimizes the number of empty
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) (or almost empty) lines, without any loss of readability. Thus, as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) supply of new-lines on your screen is not a renewable resource (think
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 25-line terminal screens here), you have more empty lines to put
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) comments on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) Do not unnecessarily use braces where a single statement will do.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) if (condition)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) action();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) if (condition)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) do_this();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) do_that();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) This does not apply if only one branch of a conditional statement is a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) statement; in the latter case use braces in both branches:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) if (condition) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) do_this();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) do_that();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) } else {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) otherwise();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Also, use braces when a loop contains more than a single simple statement:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) while (condition) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) if (test)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) do_something();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) 3.1) Spaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) ***********
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) Linux kernel style for use of spaces depends (mostly) on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) function-versus-keyword usage. Use a space after (most) keywords. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) somewhat like functions (and are usually used with parentheses in Linux,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) although they are not required in the language, as in: ``sizeof info`` after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) ``struct fileinfo info;`` is declared).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) So use a space after these keywords::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) if, switch, case, for, do, while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) but not with sizeof, typeof, alignof, or __attribute__. E.g.,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) s = sizeof(struct file);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) Do not add spaces around (inside) parenthesized expressions. This example is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) **bad**:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) s = sizeof( struct file );
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) When declaring pointer data or a function that returns a pointer type, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) preferred use of ``*`` is adjacent to the data name or function name and not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) adjacent to the type name. Examples:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) char *linux_banner;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) unsigned long long memparse(char *ptr, char **retptr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) char *match_strdup(substring_t *s);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) Use one space around (on each side of) most binary and ternary operators,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) such as any of these::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) = + - < > * / % | & ^ <= >= == != ? :
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) but no space after unary operators::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) & * + - ~ ! sizeof typeof alignof __attribute__ defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) no space before the postfix increment & decrement unary operators::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) ++ --
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) no space after the prefix increment & decrement unary operators::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) ++ --
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) and no space around the ``.`` and ``->`` structure member operators.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) Do not leave trailing whitespace at the ends of lines. Some editors with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) ``smart`` indentation will insert whitespace at the beginning of new lines as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) appropriate, so you can start typing the next line of code right away.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) However, some such editors do not remove the whitespace if you end up not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) putting a line of code there, such as if you leave a blank line. As a result,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) you end up with lines containing trailing whitespace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) Git will warn you about patches that introduce trailing whitespace, and can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) optionally strip the trailing whitespace for you; however, if applying a series
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) of patches, this may make later patches in the series fail by changing their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) context lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) 4) Naming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) C is a Spartan language, and your naming conventions should follow suit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) Unlike Modula-2 and Pascal programmers, C programmers do not use cute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) names like ThisVariableIsATemporaryCounter. A C programmer would call that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) variable ``tmp``, which is much easier to write, and not the least more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) difficult to understand.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) HOWEVER, while mixed-case names are frowned upon, descriptive names for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) global variables are a must. To call a global function ``foo`` is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) shooting offense.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) GLOBAL variables (to be used only if you **really** need them) need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) have descriptive names, as do global functions. If you have a function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) that counts the number of active users, you should call that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) ``count_active_users()`` or similar, you should **not** call it ``cntusr()``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) Encoding the type of a function into the name (so-called Hungarian
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) notation) is asinine - the compiler knows the types anyway and can check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) those, and it only confuses the programmer. No wonder Microsoft makes buggy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) programs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) LOCAL variable names should be short, and to the point. If you have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) some random integer loop counter, it should probably be called ``i``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) Calling it ``loop_counter`` is non-productive, if there is no chance of it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) being mis-understood. Similarly, ``tmp`` can be just about any type of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) variable that is used to hold a temporary value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) If you are afraid to mix up your local variable names, you have another
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) problem, which is called the function-growth-hormone-imbalance syndrome.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) See chapter 6 (Functions).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) For symbol names and documentation, avoid introducing new usage of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) 'master / slave' (or 'slave' independent of 'master') and 'blacklist /
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) whitelist'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) Recommended replacements for 'master / slave' are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) '{primary,main} / {secondary,replica,subordinate}'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) '{initiator,requester} / {target,responder}'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) '{controller,host} / {device,worker,proxy}'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) 'leader / follower'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) 'director / performer'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) Recommended replacements for 'blacklist/whitelist' are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) 'denylist / allowlist'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) 'blocklist / passlist'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) Exceptions for introducing new usage is to maintain a userspace ABI/API,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) or when updating code for an existing (as of 2020) hardware or protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) specification that mandates those terms. For new specifications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) translate specification usage of the terminology to the kernel coding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) standard where possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) 5) Typedefs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) Please don't use things like ``vps_t``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) It's a **mistake** to use typedef for structures and pointers. When you see a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) vps_t a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) in the source, what does it mean?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) In contrast, if it says
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) struct virtual_container *a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) you can actually tell what ``a`` is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) Lots of people think that typedefs ``help readability``. Not so. They are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) useful only for:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) (a) totally opaque objects (where the typedef is actively used to **hide**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) what the object is).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) Example: ``pte_t`` etc. opaque objects that you can only access using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) the proper accessor functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) Opaqueness and ``accessor functions`` are not good in themselves.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) The reason we have them for things like pte_t etc. is that there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) really is absolutely **zero** portably accessible information there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) (b) Clear integer types, where the abstraction **helps** avoid confusion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) whether it is ``int`` or ``long``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) u8/u16/u32 are perfectly fine typedefs, although they fit into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) category (d) better than here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) Again - there needs to be a **reason** for this. If something is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) ``unsigned long``, then there's no reason to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) typedef unsigned long myflags_t;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) but if there is a clear reason for why it under certain circumstances
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) might be an ``unsigned int`` and under other configurations might be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) ``unsigned long``, then by all means go ahead and use a typedef.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) (c) when you use sparse to literally create a **new** type for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) type-checking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) (d) New types which are identical to standard C99 types, in certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) exceptional circumstances.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) Although it would only take a short amount of time for the eyes and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) brain to become accustomed to the standard types like ``uint32_t``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) some people object to their use anyway.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) signed equivalents which are identical to standard types are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) permitted -- although they are not mandatory in new code of your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) own.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) When editing existing code which already uses one or the other set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) of types, you should conform to the existing choices in that code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) (e) Types safe for use in userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) In certain structures which are visible to userspace, we cannot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) require C99 types and cannot use the ``u32`` form above. Thus, we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) use __u32 and similar types in all structures which are shared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) with userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) Maybe there are other cases too, but the rule should basically be to NEVER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) EVER use a typedef unless you can clearly match one of those rules.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) In general, a pointer, or a struct that has elements that can reasonably
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) be directly accessed should **never** be a typedef.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) 6) Functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) Functions should be short and sweet, and do just one thing. They should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) as we all know), and do one thing and do that well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) The maximum length of a function is inversely proportional to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) complexity and indentation level of that function. So, if you have a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) conceptually simple function that is just one long (but simple)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) case-statement, where you have to do lots of small things for a lot of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) different cases, it's OK to have a longer function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) However, if you have a complex function, and you suspect that a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) less-than-gifted first-year high-school student might not even
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) understand what the function is all about, you should adhere to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) maximum limits all the more closely. Use helper functions with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) descriptive names (you can ask the compiler to in-line them if you think
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) it's performance-critical, and it will probably do a better job of it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) than you would have done).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) Another measure of the function is the number of local variables. They
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) shouldn't exceed 5-10, or you're doing something wrong. Re-think the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) function, and split it into smaller pieces. A human brain can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) generally easily keep track of about 7 different things, anything more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) and it gets confused. You know you're brilliant, but maybe you'd like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) to understand what you did 2 weeks from now.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) In source files, separate functions with one blank line. If the function is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) exported, the **EXPORT** macro for it should follow immediately after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) closing function brace line. E.g.:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) int system_is_up(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) return system_state == SYSTEM_RUNNING;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) EXPORT_SYMBOL(system_is_up);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) In function prototypes, include parameter names with their data types.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) Although this is not required by the C language, it is preferred in Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) because it is a simple way to add valuable information for the reader.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) Do not use the ``extern`` keyword with function prototypes as this makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) lines longer and isn't strictly necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) 7) Centralized exiting of functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) -----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) Albeit deprecated by some people, the equivalent of the goto statement is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) used frequently by compilers in form of the unconditional jump instruction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) The goto statement comes in handy when a function exits from multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) locations and some common work such as cleanup has to be done. If there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) cleanup needed then just return directly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) Choose label names which say what the goto does or why the goto exists. An
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) renumber them if you ever add or remove exit paths, and they make correctness
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) difficult to verify anyway.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) The rationale for using gotos is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) - unconditional statements are easier to understand and follow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) - nesting is reduced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) - errors by not updating individual exit points when making
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) modifications are prevented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) - saves the compiler work to optimize redundant code away ;)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) int fun(int a)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) int result = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) char *buffer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) buffer = kmalloc(SIZE, GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) if (!buffer)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) if (condition1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) while (loop1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) result = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) goto out_free_buffer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) out_free_buffer:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) kfree(buffer);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) return result;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) A common type of bug to be aware of is ``one err bugs`` which look like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) err:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) kfree(foo->bar);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) kfree(foo);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) return ret;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) The bug in this code is that on some exit paths ``foo`` is NULL. Normally the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) fix for this is to split it up into two error labels ``err_free_bar:`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) ``err_free_foo:``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) err_free_bar:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) kfree(foo->bar);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) err_free_foo:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) kfree(foo);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) return ret;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) Ideally you should simulate errors to test all exit paths.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) 8) Commenting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) Comments are good, but there is also a danger of over-commenting. NEVER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) try to explain HOW your code works in a comment: it's much better to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) write the code so that the **working** is obvious, and it's a waste of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) time to explain badly written code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) Generally, you want your comments to tell WHAT your code does, not HOW.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) Also, try to avoid putting comments inside a function body: if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) function is so complex that you need to separately comment parts of it,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) you should probably go back to chapter 6 for a while. You can make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) small comments to note or warn about something particularly clever (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) ugly), but try to avoid excess. Instead, put the comments at the head
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) of the function, telling people what it does, and possibly WHY it does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) When commenting the kernel API functions, please use the kernel-doc format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) ``scripts/kernel-doc`` for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) The preferred style for long (multi-line) comments is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) * This is the preferred style for multi-line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) * comments in the Linux kernel source code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) * Please use it consistently.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) * Description: A column of asterisks on the left side,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) * with beginning and ending almost-blank lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) For files in net/ and drivers/net/ the preferred style for long (multi-line)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) comments is a little different.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) /* The preferred comment style for files in net/ and drivers/net
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) * looks like this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) * It is nearly the same as the generally preferred comment style,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) * but there is no initial almost-blank line.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) It's also important to comment data, whether they are basic types or derived
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) types. To this end, use just one data declaration per line (no commas for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) multiple data declarations). This leaves you room for a small comment on each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) item, explaining its use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) 9) You've made a mess of it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) That's OK, we all do. You've probably been told by your long-time Unix
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) user helper that ``GNU emacs`` automatically formats the C sources for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) you, and you've noticed that yes, it does do that, but the defaults it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) uses are less than desirable (in fact, they are worse than random
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) typing - an infinite number of monkeys typing into GNU emacs would never
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) make a good program).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) So, you can either get rid of GNU emacs, or change it to use saner
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) values. To do the latter, you can stick the following in your .emacs file:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) (defun c-lineup-arglist-tabs-only (ignored)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) "Line up argument lists by tabs, not spaces"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) (let* ((anchor (c-langelem-pos c-syntactic-element))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) (column (c-langelem-2nd-pos c-syntactic-element))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) (offset (- (1+ column) anchor))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) (steps (floor offset c-basic-offset)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) (* (max steps 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) c-basic-offset)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) (dir-locals-set-class-variables
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) 'linux-kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) '((c-mode . (
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) (c-basic-offset . 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) (c-label-minimum-indentation . 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) (c-offsets-alist . (
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) (arglist-close . c-lineup-arglist-tabs-only)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) (arglist-cont-nonempty .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) (arglist-intro . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) (brace-list-intro . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) (c . c-lineup-C-comments)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) (case-label . 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) (comment-intro . c-lineup-comment)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) (cpp-define-intro . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) (cpp-macro . -1000)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) (cpp-macro-cont . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) (defun-block-intro . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) (else-clause . 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) (func-decl-cont . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) (inclass . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) (inher-cont . c-lineup-multi-inher)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) (knr-argdecl-intro . 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) (label . -1000)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) (statement . 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) (statement-block-intro . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) (statement-case-intro . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) (statement-cont . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) (substatement . +)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) ))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) (indent-tabs-mode . t)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) (show-trailing-whitespace . t)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) ))))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657) (dir-locals-set-directory-class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) (expand-file-name "~/src/linux-trees")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) 'linux-kernel)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) This will make emacs go better with the kernel coding style for C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) files below ``~/src/linux-trees``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) But even if you fail in getting emacs to do sane formatting, not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) everything is lost: use ``indent``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) Now, again, GNU indent has the same brain-dead settings that GNU emacs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) has, which is why you need to give it a few command line options.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) However, that's not too bad, because even the makers of GNU indent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) recognize the authority of K&R (the GNU people aren't evil, they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) just severely misguided in this matter), so you just give indent the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) ``scripts/Lindent``, which indents in the latest style.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) ``indent`` has a lot of options, and especially when it comes to comment
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) re-formatting you may want to take a look at the man page. But
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) remember: ``indent`` is not a fix for bad programming.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) Note that you can also use the ``clang-format`` tool to help you with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) these rules, to quickly re-format parts of your code automatically,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) and to review full files in order to spot coding style mistakes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) typos and possible improvements. It is also handy for sorting ``#includes``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) for aligning variables/macros, for reflowing text and other similar tasks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) 10) Kconfig configuration files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) For all of the Kconfig* configuration files throughout the source tree,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) the indentation is somewhat different. Lines under a ``config`` definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) are indented with one tab, while help text is indented an additional two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) spaces. Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) config AUDIT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) bool "Auditing support"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) depends on NET
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) help
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) Enable auditing infrastructure that can be used with another
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) kernel subsystem, such as SELinux (which requires this for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) logging of avc messages output). Does not do system-call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) auditing without CONFIG_AUDITSYSCALL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) Seriously dangerous features (such as write support for certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) filesystems) should advertise this prominently in their prompt string::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) config ADFS_FS_RW
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) bool "ADFS write support (DANGEROUS)"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) depends on ADFS_FS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) For full documentation on the configuration files, see the file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) Documentation/kbuild/kconfig-language.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) 11) Data structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) Data structures that have visibility outside the single-threaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) environment they are created and destroyed in should always have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) reference counts. In the kernel, garbage collection doesn't exist (and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) outside the kernel garbage collection is slow and inefficient), which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) means that you absolutely **have** to reference count all your uses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) Reference counting means that you can avoid locking, and allows multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) users to have access to the data structure in parallel - and not having
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) to worry about the structure suddenly going away from under them just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) because they slept or did something else for a while.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) Note that locking is **not** a replacement for reference counting.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) Locking is used to keep data structures coherent, while reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) counting is a memory management technique. Usually both are needed, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) they are not to be confused with each other.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) Many data structures can indeed have two levels of reference counting,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) when there are users of different ``classes``. The subclass count counts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) the number of subclass users, and decrements the global count just once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) when the subclass count goes to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) Examples of this kind of ``multi-level-reference-counting`` can be found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) memory management (``struct mm_struct``: mm_users and mm_count), and in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) filesystem code (``struct super_block``: s_count and s_active).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) Remember: if another thread can find your data structure, and you don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) have a reference count on it, you almost certainly have a bug.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) 12) Macros, Enums and RTL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) Names of macros defining constants and labels in enums are capitalized.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) #define CONSTANT 0x12345
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) Enums are preferred when defining several related constants.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) CAPITALIZED macro names are appreciated but macros resembling functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) may be named in lower case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) Generally, inline functions are preferable to macros resembling functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) Macros with multiple statements should be enclosed in a do - while block:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) #define macrofun(a, b, c) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) do { \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771) if (a == 5) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) do_this(b, c); \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) } while (0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) Things to avoid when using macros:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) 1) macros that affect control flow:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) #define FOO(x) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) do { \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) if (blah(x) < 0) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) return -EBUGGERED; \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) } while (0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) is a **very** bad idea. It looks like a function call but exits the ``calling``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) function; don't break the internal parsers of those who will read the code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) 2) macros that depend on having a local variable with a magic name:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) #define FOO(val) bar(index, val)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) might look like a good thing, but it's confusing as hell when one reads the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) code and it's prone to breakage from seemingly innocent changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) 3) macros with arguments that are used as l-values: FOO(x) = y; will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) bite you if somebody e.g. turns FOO into an inline function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) 4) forgetting about precedence: macros defining constants using expressions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) must enclose the expression in parentheses. Beware of similar issues with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) macros using parameters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) #define CONSTANT 0x4000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) #define CONSTEXP (CONSTANT | 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) 5) namespace collisions when defining local variables in macros resembling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) functions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) #define FOO(x) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) ({ \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) typeof(x) ret; \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) ret = calc_ret(x); \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) (ret); \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) })
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) ret is a common name for a local variable - __foo_ret is less likely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) to collide with an existing variable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) The cpp manual deals with macros exhaustively. The gcc internals manual also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) covers RTL which is used frequently with assembly language in the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) 13) Printing kernel messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) Kernel developers like to be seen as literate. Do mind the spelling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) of kernel messages to make a good impression. Do not use incorrect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) contractions like ``dont``; use ``do not`` or ``don't`` instead. Make the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) messages concise, clear, and unambiguous.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) Kernel messages do not have to be terminated with a period.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) Printing numbers in parentheses (%d) adds no value and should be avoided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) There are a number of driver model diagnostic macros in <linux/device.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) which you should use to make sure messages are matched to the right device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) and driver, and are tagged with the right level: dev_err(), dev_warn(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) dev_info(), and so forth. For messages that aren't associated with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) particular device, <linux/printk.h> defines pr_notice(), pr_info(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) pr_warn(), pr_err(), etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) Coming up with good debugging messages can be quite a challenge; and once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) you have them, they can be a huge help for remote troubleshooting. However
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) debug message printing is handled differently than printing other non-debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) messages. While the other pr_XXX() functions print unconditionally,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) pr_debug() does not; it is compiled out by default, unless either DEBUG is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) the ones already enabled by DEBUG.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) Many subsystems have Kconfig debug options to turn on -DDEBUG in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) corresponding Makefile; in other cases specific files #define DEBUG. And
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) when a debug message should be unconditionally printed, such as if it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) 14) Allocating memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) The kernel provides the following general purpose memory allocators:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) vzalloc(). Please refer to the API documentation for further information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) about them. :ref:`Documentation/core-api/memory-allocation.rst
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) <memory_allocation>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) The preferred form for passing a size of a struct is the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) p = kmalloc(sizeof(*p), ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) The alternative form where struct name is spelled out hurts readability and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) introduces an opportunity for a bug when the pointer variable type is changed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) but the corresponding sizeof that is passed to a memory allocator is not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) Casting the return value which is a void pointer is redundant. The conversion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) from void pointer to any other pointer type is guaranteed by the C programming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) language.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) The preferred form for allocating an array is the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) p = kmalloc_array(n, sizeof(...), ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894) The preferred form for allocating a zeroed array is the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) p = kcalloc(n, sizeof(...), ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) Both forms check for overflow on the allocation size n * sizeof(...),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) and return NULL if that occurred.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) These generic allocation functions all emit a stack dump on failure when used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904) without __GFP_NOWARN so there is no use in emitting an additional failure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) message when NULL is returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) 15) The inline disease
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) There appears to be a common misperception that gcc has a magic "make me
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) faster" speedup option called ``inline``. While the use of inlines can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) appropriate (for example as a means of replacing macros, see Chapter 12), it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) very often is not. Abundant use of the inline keyword leads to a much bigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) kernel, which in turn slows the system as a whole down, due to a bigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) icache footprint for the CPU and simply because there is less memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916) available for the pagecache. Just think about it; a pagecache miss causes a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) that can go into these 5 milliseconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920) A reasonable rule of thumb is to not put inline at functions that have more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) than 3 lines of code in them. An exception to this rule are the cases where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) a parameter is known to be a compiletime constant, and as a result of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) constantness you *know* the compiler will be able to optimize most of your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924) function away at compile time. For a good example of this later case, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) the kmalloc() inline function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) Often people argue that adding inline to functions that are static and used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) only once is always a win since there is no space tradeoff. While this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) technically correct, gcc is capable of inlining these automatically without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) help, and the maintenance issue of removing the inline when a second user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) appears outweighs the potential value of the hint that tells gcc to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932) something it would have done anyway.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) 16) Function return values and names
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) Functions can return values of many different kinds, and one of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) most common is a value indicating whether the function succeeded or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) failed. Such a value can be represented as an error-code integer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942) non-zero = success).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) Mixing up these two sorts of representations is a fertile source of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945) difficult-to-find bugs. If the C language included a strong distinction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) between integers and booleans then the compiler would find these mistakes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947) for us... but it doesn't. To help prevent such bugs, always follow this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) convention::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950) If the name of a function is an action or an imperative command,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) the function should return an error-code integer. If the name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) is a predicate, the function should return a "succeeded" boolean.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) For example, ``add work`` is a command, and the add_work() function returns 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955) for success or -EBUSY for failure. In the same way, ``PCI device present`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956) a predicate, and the pci_dev_present() function returns 1 if it succeeds in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) finding a matching device or 0 if it doesn't.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) All EXPORTed functions must respect this convention, and so should all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960) public functions. Private (static) functions need not, but it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) recommended that they do.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963) Functions whose return value is the actual result of a computation, rather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964) than an indication of whether the computation succeeded, are not subject to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) this rule. Generally they indicate failure by returning some out-of-range
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) result. Typical examples would be functions that return pointers; they use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967) NULL or the ERR_PTR mechanism to report failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) 17) Using bool
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973) The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974) only evaluate to 0 or 1, and implicit or explicit conversion to bool
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) automatically converts the value to true or false. When using bool types the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976) !! construction is not needed, which eliminates a class of bugs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) When working with bool values the true and false definitions should be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979) instead of 1 and 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) bool function return types and stack variables are always fine to use whenever
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982) appropriate. Use of bool is encouraged to improve readability and is often a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) better option than 'int' for storing boolean values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) Do not use bool if cache line layout or size of the value matters, as its size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986) and alignment varies based on the compiled architecture. Structures that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987) optimized for alignment and size should not use bool.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) If a structure has many true/false values, consider consolidating them into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990) bitfield with 1 bit members, or using an appropriate fixed width type, such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) u8.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993) Similarly for function arguments, many true/false values can be consolidated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994) into a single bitwise 'flags' argument and 'flags' can often be a more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995) readable alternative if the call-sites have naked true/false constants.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997) Otherwise limited use of bool in structures and arguments can improve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) readability.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) 18) Don't re-invent the kernel macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001) -------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003) The header file include/linux/kernel.h contains a number of macros that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) you should use, rather than explicitly coding some variant of them yourself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005) For example, if you need to calculate the length of an array, take advantage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006) of the macro
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010) #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012) Similarly, if you need to calculate the size of some structure member, use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) #define sizeof_field(t, f) (sizeof(((t*)0)->f))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018) There are also min() and max() macros that do strict type checking if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) need them. Feel free to peruse that header file to see what else is already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020) defined that you shouldn't reproduce in your code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) 19) Editor modelines and other cruft
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026) Some editors can interpret configuration information embedded in source files,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) indicated with special markers. For example, emacs interprets lines marked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028) like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032) -*- mode: c -*-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034) Or like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) Local Variables:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040) compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041) End:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) Vim interprets markers that look like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1048) /* vim:set sw=8 noet */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1049)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1050) Do not include any of these in source files. People have their own personal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1051) editor configurations, and your source files should not override them. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1052) includes markers for indentation and mode configuration. People may use their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1053) own custom mode, or may have some other magic method for making indentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1054) work correctly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1055)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1056)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1057) 20) Inline assembly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1058) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1059)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1060) In architecture-specific code, you may need to use inline assembly to interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1061) with CPU or platform functionality. Don't hesitate to do so when necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1062) However, don't use inline assembly gratuitously when C can do the job. You can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1063) and should poke hardware from C when possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1064)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1065) Consider writing simple helper functions that wrap common bits of inline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1066) assembly, rather than repeatedly writing them with slight variations. Remember
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1067) that inline assembly can use C parameters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1068)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1069) Large, non-trivial assembly functions should go in .S files, with corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1070) C prototypes defined in C header files. The C prototypes for assembly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1071) functions should use ``asmlinkage``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1072)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1073) You may need to mark your asm statement as volatile, to prevent GCC from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1074) removing it if GCC doesn't notice any side effects. You don't always need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1075) do so, though, and doing so unnecessarily can limit optimization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1076)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1077) When writing a single inline assembly statement containing multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1078) instructions, put each instruction on a separate line in a separate quoted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1079) string, and end each string except the last with ``\n\t`` to properly indent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1080) the next instruction in the assembly output:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1081)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1082) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1083)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1084) asm ("magic %reg1, #42\n\t"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1085) "more_magic %reg2, %reg3"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1086) : /* outputs */ : /* inputs */ : /* clobbers */);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1087)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1088)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1089) 21) Conditional Compilation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1090) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1091)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1092) Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1093) files; doing so makes code harder to read and logic harder to follow. Instead,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1094) use such conditionals in a header file defining functions for use in those .c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1095) files, providing no-op stub versions in the #else case, and then call those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1096) functions unconditionally from .c files. The compiler will avoid generating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1097) any code for the stub calls, producing identical results, but the logic will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1098) remain easy to follow.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1099)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1100) Prefer to compile out entire functions, rather than portions of functions or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1101) portions of expressions. Rather than putting an ifdef in an expression, factor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1102) out part or all of the expression into a separate helper function and apply the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1103) conditional to that function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1105) If you have a function or variable which may potentially go unused in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1106) particular configuration, and the compiler would warn about its definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1107) going unused, mark the definition as __maybe_unused rather than wrapping it in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1108) a preprocessor conditional. (However, if a function or variable *always* goes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1109) unused, delete it.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1111) Within code, where possible, use the IS_ENABLED macro to convert a Kconfig
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1112) symbol into a C boolean expression, and use it in a normal C conditional:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1114) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1116) if (IS_ENABLED(CONFIG_SOMETHING)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1117) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1118) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1120) The compiler will constant-fold the conditional away, and include or exclude
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1121) the block of code just as with an #ifdef, so this will not add any runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1122) overhead. However, this approach still allows the C compiler to see the code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1123) inside the block, and check it for correctness (syntax, types, symbol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1124) references, etc). Thus, you still have to use an #ifdef if the code inside the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1125) block references symbols that will not exist if the condition is not met.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1127) At the end of any non-trivial #if or #ifdef block (more than a few lines),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1128) place a comment after the #endif on the same line, noting the conditional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1129) expression used. For instance:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1131) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1133) #ifdef CONFIG_SOMETHING
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1134) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1135) #endif /* CONFIG_SOMETHING */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1138) Appendix I) References
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1139) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1141) The C Programming Language, Second Edition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1142) by Brian W. Kernighan and Dennis M. Ritchie.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1143) Prentice Hall, Inc., 1988.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1144) ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1146) The Practice of Programming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1147) by Brian W. Kernighan and Rob Pike.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1148) Addison-Wesley, Inc., 1999.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1149) ISBN 0-201-61586-X.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1151) GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1152) gcc internals and indent, all available from https://www.gnu.org/manual/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1154) WG14 is the international standardization working group for the programming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1155) language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1157) Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1158) http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags