Documentation/process/4.Coding.rst

6 While there is much to be said for a solid and community-oriented design
7 process, the proof of any kernel development project is in the resulting
13 number of ways in which kernel developers can go wrong.  Then the focus
14 will shift toward doing things right and the tools which can help in that
19 ---------
24 The kernel has long had a standard coding style, described in
25 :ref:`Documentation/process/coding-style.rst <codingstyle>`.  For much of
26 that time, the policies described in that file were taken as being, at most,
27 advisory.  As a result, there is a substantial amount of code in the kernel
29 leads to two independent hazards for kernel developers.
31 The first of these is to believe that the kernel coding standards do not
33 code to the kernel is very difficult if that code is not coded according to
35 before they will even review it.  A code base as large as the kernel
38 strangely-formatted code.
40 Occasionally, the kernel's coding style will run into conflict with an
41 employer's mandated style.  In such cases, the kernel's style will have to
42 win before the code can be merged.  Putting code into the kernel means
43 giving up a degree of control in a number of ways - including control over
46 The other trap is to assume that code which is already in the kernel is
47 urgently in need of coding style fixes.  Developers may start to generate
49 as a way of getting their name into the kernel changelogs - or both.  But
59 80-column limit, for example), just do it.
61 Note that you can also use the ``clang-format`` tool to help you with
62 these rules, to quickly re-format parts of your code automatically,
63 and to review full files in order to spot coding style mistakes,
66 See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
78 abstraction layers in the name of flexibility and information hiding.
79 Certainly the kernel makes extensive use of abstraction; no project
87 in case somebody eventually needs to use the extra flexibility that it
89 implements this extra argument has been broken in some subtle way which was
90 never noticed - because it has never been used.  Or, when the need for
91 extra flexibility arises, it does not do so in a way which matches the
92 programmer's early expectation.  Kernel developers will routinely submit
93 patches to remove unused arguments; they should, in general, not be added
94 in the first place.
96 Abstraction layers which hide access to hardware - often to allow the bulk
97 of a driver to be used with multiple operating systems - are especially
99 penalty; they do not belong in the Linux kernel.
102 from another kernel subsystem, it is time to ask whether it would, in fact,
104 implement that functionality at a higher level.  There is no value in
105 replicating the same code throughout the kernel.
108 #ifdef and preprocessor use in general
114 use of it results in code which is much harder for others to read and
119 is used within the kernel.  But there is little desire to see code which is
122 Conditionally-compiled code can be confined to functions which, if the code
139 become enamored of the perceived efficiency inherent in avoiding a function
142 at each call site, they end up bloating the size of the compiled kernel.
143 That, in turn, creates pressure on the processor's memory caches, which can
149 In general, kernel programmers ignore cache effects at their peril.  The
150 classic time/space tradeoff taught in beginning data structures classes
151 often does not apply to contemporary hardware.  Space *is* time, in that a
154 More recent compilers take an increasingly active role in deciding whether
163 In May, 2006, the "Devicescape" networking stack was, with great
164 fanfare, released under the GPL and made available for inclusion in the
165 mainline kernel.  This donation was welcome news; support for wireless
166 networking in Linux was considered substandard at best, and the Devicescape
172 corporate doors.  But one large problem in particular was that it was not
177 Once upon a time, Linux kernel code could be developed without thinking
179 however, this document is being written on a dual-core laptop.  Even on
180 single-processor systems, work being done to improve responsiveness will
181 raise the level of concurrency within the kernel.  The days when kernel
186 New code should be written with this requirement in mind; retrofitting
187 locking after the fact is a rather more difficult task.  Kernel developers
199 regressions have become most unwelcome in the mainline kernel.  With few
201 regression cannot be fixed in a timely manner.  Far better to avoid the
202 regression in the first place.
207 breaks?  The best answer to this question was expressed by Linus in July,
220 user-space ABI.  Once an interface has been exported to user space, it must
221 be supported indefinitely.  This fact makes the creation of user-space
222 interfaces particularly challenging: since they cannot be changed in
225 user-space interfaces is always required.
229 -------------------
231 For now, at least, the writing of error-free code remains an ideal that few
234 kernel.  To that end, the kernel developers have put together an impressive
235 array of tools which can catch a wide variety of obscure problems in an
249 kernel with "make KCFLAGS=-W" to get the full set.
251 The kernel provides several configuration options which turn on debugging
252 features; most of these are found in the "kernel hacking" submenu.  Several
253 of these options should be turned on for any kernel used for development or
254 testing purposes.  In particular, you should turn on:
256  - FRAME_WARN to get warnings for stack frames larger than a given amount.
258    warnings from other parts of the kernel.
260  - DEBUG_OBJECTS will add code to track the lifetime of various objects
261    created by the kernel and warn when things are done out of order.  If
266  - DEBUG_SLAB can find a variety of memory allocation and use errors; it
269  - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a
275 available options will likely be paid back many times over in short order.
279 mutex) in the system, the order in which locks are acquired relative to
281 ensure that locks are always acquired in the same order, that the same
282 interrupt assumptions apply in all situations, and so on.  In other words,
283 lockdep can find a number of scenarios in which the system could, on rare
285 developers and users) in a deployed system; lockdep allows them to be found
286 in an automated manner ahead of time.  Code with any sort of non-trivial
290 As a diligent kernel programmer, you will, beyond doubt, check the return
294 you could be much more confident of your code if all those error-handling
297 The kernel provides a fault injection framework which can do exactly that,
303 Documentation/fault-injection/fault-injection.rst for more information on
308 user-space and kernel-space addresses, mixture of big-endian and
309 small-endian quantities, the passing of integer values where a set of bit
311 be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your
317 problems.  Quite a few "semantic patches" for the kernel have been packaged
320 :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
328 	https://www.kernel.org/pub/tools/crosstool/
335 -------------
337 Documentation has often been more the exception than the rule with kernel
339 of new code into the kernel, make life easier for other developers, and
340 will be helpful for your users.  In many cases, the addition of
351 Any code which adds a new user-space interface - including new sysfs or
352 /proc files - should include documentation of that interface which enables
353 user-space developers to know what they are working with.  See
357 The file :ref:`Documentation/admin-guide/kernel-parameters.rst
358 <kernelparameters>` describes all of the kernel's boot-time parameters.
366 specially-formatted comments; these comments can be extracted and formatted
367 in a number of ways by the "kernel-doc" script.  If you are working within
369 them, as appropriate, for externally-available functions.  Even in areas
370 which have not been so documented, there is no harm in adding kerneldoc
372 beginning kernel developers.  The format of these comments, along with some
374 :ref:`Documentation/doc-guide/ <doc_guide>`.
376 Anybody who reads through a significant amount of existing kernel code will
378 the expectations for new code are higher than they were in the past;
380 for verbosely-commented code.  The code should, itself, be readable, with
386 Major data structures need comprehensive documentation in general.
387 Non-obvious dependencies between separate bits of code should be pointed
393 --------------------
395 The binary interface provided by the kernel to user space cannot be broken
396 except under the most severe circumstances.  The kernel's internal
398 the need arises.  If you find yourself having to work around a kernel API,
400 needs, that may be a sign that the API needs to change.  As a kernel
410 generally charged with the task of fixing any code within the kernel tree
411 which is broken by the change.  For a widely-used function, this duty can
412 lead to literally hundreds or thousands of changes - many of which are
416 wide-ranging API changes.
420 This will help you to be sure that you have found all in-tree uses of that
421 interface.  It will also alert developers of out-of-tree code that there is
422 a change that they need to respond to.  Supporting out-of-tree code is not
423 something that kernel developers need to be worried about, but we also do
424 not have to make life harder for out-of-tree developers than it needs to