1 .. _development_coding:
2
3 Getting the code right
4 ======================
5
6 While there is much to be said for a solid and
7 process, the proof of any kernel development p
8 code. It is the code which will be examined b
9 (or not) into the mainline tree. So it is the
10 will determine the ultimate success of the pro
11
12 This section will examine the coding process.
13 number of ways in which kernel developers can
14 will shift toward doing things right and the t
15 quest.
16
17
18 Pitfalls
19 ---------
20
21 Coding style
22 ************
23
24 The kernel has long had a standard coding styl
25 :ref:`Documentation/process/coding-style.rst <
26 that time, the policies described in that file
27 advisory. As a result, there is a substantial
28 which does not meet the coding style guideline
29 leads to two independent hazards for kernel de
30
31 The first of these is to believe that the kern
32 matter and are not enforced. The truth of the
33 code to the kernel is very difficult if that c
34 the standard; many developers will request tha
35 before they will even review it. A code base
36 requires some uniformity of code to make it po
37 quickly understand any part of it. So there i
38 strangely-formatted code.
39
40 Occasionally, the kernel's coding style will r
41 employer's mandated style. In such cases, the
42 win before the code can be merged. Putting co
43 giving up a degree of control in a number of w
44 how the code is formatted.
45
46 The other trap is to assume that code which is
47 urgently in need of coding style fixes. Devel
48 reformatting patches as a way of gaining famil
49 as a way of getting their name into the kernel
50 pure coding style fixes are seen as noise by t
51 they tend to get a chilly reception. So this
52 avoided. It is natural to fix the style of a
53 on it for other reasons, but coding style chan
54 their own sake.
55
56 The coding style document also should not be r
57 can never be transgressed. If there is a good
58 style (a line which becomes far less readable
59 80-column limit, for example), just do it.
60
61 Note that you can also use the ``clang-format`
62 these rules, to quickly re-format parts of you
63 and to review full files in order to spot codi
64 typos and possible improvements. It is also ha
65 for aligning variables/macros, for reflowing t
66 See the file :ref:`Documentation/dev-tools/cla
67 for more details.
68
69 Some basic editor settings, such as indentatio
70 set automatically if you are using an editor t
71 EditorConfig. See the official EditorConfig we
72 https://editorconfig.org/
73
74 Abstraction layers
75 ******************
76
77 Computer Science professors teach students to
78 abstraction layers in the name of flexibility
79 Certainly the kernel makes extensive use of ab
80 involving several million lines of code could
81 But experience has shown that excessive or pre
82 just as harmful as premature optimization. Ab
83 the level required and no further.
84
85 At a simple level, consider a function which h
86 always passed as zero by all callers. One cou
87 in case somebody eventually needs to use the e
88 provides. By that time, though, chances are g
89 implements this extra argument has been broken
90 never noticed - because it has never been used
91 extra flexibility arises, it does not do so in
92 programmer's early expectation. Kernel develo
93 patches to remove unused arguments; they shoul
94 in the first place.
95
96 Abstraction layers which hide access to hardwa
97 of a driver to be used with multiple operating
98 frowned upon. Such layers obscure the code an
99 penalty; they do not belong in the Linux kerne
100
101 On the other hand, if you find yourself copyin
102 from another kernel subsystem, it is time to a
103 make sense to pull out some of that code into
104 implement that functionality at a higher level
105 replicating the same code throughout the kerne
106
107
108 #ifdef and preprocessor use in general
109 **************************************
110
111 The C preprocessor seems to present a powerful
112 programmers, who see it as a way to efficientl
113 flexibility into a source file. But the prepr
114 use of it results in code which is much harder
115 harder for the compiler to check for correctne
116 is almost always a sign of code which needs so
117
118 Conditional compilation with #ifdef is, indeed
119 is used within the kernel. But there is littl
120 sprinkled liberally with #ifdef blocks. As a
121 should be confined to header files whenever po
122 Conditionally-compiled code can be confined to
123 is not to be present, simply become empty. Th
124 optimize out the call to the empty function.
125 code which is easier to follow.
126
127 C preprocessor macros present a number of haza
128 multiple evaluation of expressions with side e
129 If you are tempted to define a macro, consider
130 instead. The code which results will be the s
131 easier to read, do not evaluate their argument
132 the compiler to perform type checking on the a
133
134
135 Inline functions
136 ****************
137
138 Inline functions present a hazard of their own
139 become enamored of the perceived efficiency in
140 call and fill a source file with inline functi
141 however, can actually reduce performance. Sin
142 at each call site, they end up bloating the si
143 That, in turn, creates pressure on the process
144 slow execution dramatically. Inline functions
145 small and relatively rare. The cost of a func
146 that high; the creation of large numbers of in
147 example of premature optimization.
148
149 In general, kernel programmers ignore cache ef
150 classic time/space tradeoff taught in beginnin
151 often does not apply to contemporary hardware.
152 larger program will run slower than one which
153
154 More recent compilers take an increasingly act
155 a given function should actually be inlined or
156 placement of "inline" keywords may not just be
157 irrelevant.
158
159
160 Locking
161 *******
162
163 In May, 2006, the "Devicescape" networking sta
164 fanfare, released under the GPL and made avail
165 mainline kernel. This donation was welcome ne
166 networking in Linux was considered substandard
167 stack offered the promise of fixing that situa
168 actually make it into the mainline until June,
169 happened?
170
171 This code showed a number of signs of having b
172 corporate doors. But one large problem in par
173 designed to work on multiprocessor systems. B
174 (now called mac80211) could be merged, a locki
175 retrofitted onto it.
176
177 Once upon a time, Linux kernel code could be d
178 about the concurrency issues presented by mult
179 however, this document is being written on a d
180 single-processor systems, work being done to i
181 raise the level of concurrency within the kern
182 code could be written without thinking about l
183
184 Any resource (data structures, hardware regist
185 accessed concurrently by more than one thread
186 New code should be written with this requireme
187 locking after the fact is a rather more diffic
188 should take the time to understand the availab
189 enough to pick the right tool for the job. Co
190 attention to concurrency will have a difficult
191
192
193 Regressions
194 ***********
195
196 One final hazard worth mentioning is this: it
197 change (which may bring big improvements) whic
198 for existing users. This kind of change is ca
199 regressions have become most unwelcome in the
200 exceptions, changes which cause regressions wi
201 regression cannot be fixed in a timely manner.
202 regression in the first place.
203
204 It is often argued that a regression can be ju
205 to work for more people than it creates proble
206 change if it brings new functionality to ten s
207 breaks? The best answer to this question was
208 2007:
209
210 ::
211
212 So we don't fix bugs by introducing ne
213 madness, and nobody ever knows if you
214 progress at all. Is it two steps forwa
215 step forward and two steps back?
216
217 (https://lwn.net/Articles/243460/).
218
219 An especially unwelcome type of regression is
220 user-space ABI. Once an interface has been ex
221 be supported indefinitely. This fact makes th
222 interfaces particularly challenging: since the
223 incompatible ways, they must be done right the
224 reason, a great deal of thought, clear documen
225 user-space interfaces is always required.
226
227
228 Code checking tools
229 -------------------
230
231 For now, at least, the writing of error-free c
232 of us can reach. What we can hope to do, thou
233 many of those errors as possible before our co
234 kernel. To that end, the kernel developers ha
235 array of tools which can catch a wide variety
236 automated way. Any problem caught by the comp
237 not afflict a user later on, so it stands to r
238 tools should be used whenever possible.
239
240 The first step is simply to heed the warnings
241 Contemporary versions of gcc can detect (and w
242 potential errors. Quite often, these warnings
243 Code submitted for review should, as a rule, n
244 warnings. When silencing warnings, take care
245 and try to avoid "fixes" which make the warnin
246 its cause.
247
248 Note that not all compiler warnings are enable
249 kernel with "make KCFLAGS=-W" to get the full
250
251 The kernel provides several configuration opti
252 features; most of these are found in the "kern
253 of these options should be turned on for any k
254 testing purposes. In particular, you should t
255
256 - FRAME_WARN to get warnings for stack frames
257 The output generated can be verbose, but on
258 warnings from other parts of the kernel.
259
260 - DEBUG_OBJECTS will add code to track the li
261 created by the kernel and warn when things
262 you are adding a subsystem which creates (a
263 of its own, consider adding support for the
264 infrastructure.
265
266 - DEBUG_SLAB can find a variety of memory all
267 should be used on most development kernels.
268
269 - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEB
270 number of common locking errors.
271
272 There are quite a few other debugging options,
273 discussed below. Some of them have a signific
274 should not be used all of the time. But some
275 available options will likely be paid back man
276
277 One of the heavier debugging tools is the lock
278 This tool will track the acquisition and relea
279 mutex) in the system, the order in which locks
280 each other, the current interrupt environment,
281 ensure that locks are always acquired in the s
282 interrupt assumptions apply in all situations,
283 lockdep can find a number of scenarios in whic
284 occasion, deadlock. This kind of problem can
285 developers and users) in a deployed system; lo
286 in an automated manner ahead of time. Code wi
287 locking should be run with lockdep enabled bef
288 inclusion.
289
290 As a diligent kernel programmer, you will, bey
291 status of any operation (such as a memory allo
292 fact of the matter, though, is that the result
293 are, probably, completely untested. Untested
294 you could be much more confident of your code
295 paths had been exercised a few times.
296
297 The kernel provides a fault injection framewor
298 especially where memory allocations are involv
299 enabled, a configurable percentage of memory a
300 fail; these failures can be restricted to a sp
301 Running with fault injection enabled allows th
302 code responds when things go badly. See
303 Documentation/fault-injection/fault-injection.
304 how to use this facility.
305
306 Other kinds of errors can be found with the "s
307 With sparse, the programmer can be warned abou
308 user-space and kernel-space addresses, mixture
309 small-endian quantities, the passing of intege
310 flags is expected, and so on. Sparse must be
311 be found at https://sparse.wiki.kernel.org/ind
312 distributor does not package it); it can then
313 "C=1" to your make command.
314
315 The "Coccinelle" tool (http://coccinelle.lip6.
316 variety of potential coding problems; it can a
317 problems. Quite a few "semantic patches" for
318 under the scripts/coccinelle directory; runnin
319 through those semantic patches and report on a
320 :ref:`Documentation/dev-tools/coccinelle.rst <
321 for more information.
322
323 Other kinds of portability errors are best fou
324 other architectures. If you do not happen to
325 Blackfin development board handy, you can stil
326 step. A large set of cross compilers for x86
327
328 https://www.kernel.org/pub/tools/cross
329
330 Some time spent installing and using these com
331 embarrassment later.
332
333
334 Documentation
335 -------------
336
337 Documentation has often been more the exceptio
338 development. Even so, adequate documentation
339 of new code into the kernel, make life easier
340 will be helpful for your users. In many cases
341 documentation has become essentially mandatory
342
343 The first piece of documentation for any patch
344 changelog. Log entries should describe the pr
345 of the solution, the people who worked on the
346 effects on performance, and anything else that
347 understand the patch. Be sure that the change
348 worth applying; a surprising number of develop
349 information.
350
351 Any code which adds a new user-space interface
352 /proc files - should include documentation of
353 user-space developers to know what they are wo
354 Documentation/ABI/README for a description of
355 be formatted and what information needs to be
356
357 The file :ref:`Documentation/admin-guide/kerne
358 <kernelparameters>` describes all of the kerne
359 Any patch which adds new parameters should add
360 this file.
361
362 Any new configuration options must be accompan
363 clearly explains the options and when the user
364
365 Internal API information for many subsystems i
366 specially-formatted comments; these comments c
367 in a number of ways by the "kernel-doc" script
368 a subsystem which has kerneldoc comments, you
369 them, as appropriate, for externally-available
370 which have not been so documented, there is no
371 comments for the future; indeed, this can be a
372 beginning kernel developers. The format of th
373 information on how to create kerneldoc templat
374 :ref:`Documentation/doc-guide/ <doc_guide>`.
375
376 Anybody who reads through a significant amount
377 note that, often, comments are most notable by
378 the expectations for new code are higher than
379 merging uncommented code will be harder. That
380 for verbosely-commented code. The code should
381 comments explaining the more subtle aspects.
382
383 Certain things should always be commented. Us
384 be accompanied by a line explaining why the ba
385 locking rules for data structures generally ne
386 Major data structures need comprehensive docum
387 Non-obvious dependencies between separate bits
388 out. Anything which might tempt a code janito
389 "cleanup" needs a comment saying why it is don
390
391
392 Internal API changes
393 --------------------
394
395 The binary interface provided by the kernel to
396 except under the most severe circumstances. T
397 programming interfaces, instead, are highly fl
398 the need arises. If you find yourself having
399 or simply not using a specific functionality b
400 needs, that may be a sign that the API needs t
401 developer, you are empowered to make such chan
402
403 There are, of course, some catches. API chang
404 to be well justified. So any patch making an
405 accompanied by a description of what the chang
406 necessary. This kind of change should also be
407 patch, rather than buried within a larger patc
408
409 The other catch is that a developer who change
410 generally charged with the task of fixing any
411 which is broken by the change. For a widely-u
412 lead to literally hundreds or thousands of cha
413 likely to conflict with work being done by oth
414 say, this can be a large job, so it is best to
415 justification is solid. Note that the Coccine
416 wide-ranging API changes.
417
418 When making an incompatible API change, one sh
419 ensure that code which has not been updated is
420 This will help you to be sure that you have fo
421 interface. It will also alert developers of o
422 a change that they need to respond to. Suppor
423 something that kernel developers need to be wo
424 not have to make life harder for out-of-tree d
425 be.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.