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