Documentation/process/4.Coding.rst

6 While there is much to be said for a solid and community-oriented design
19 ---------
25 :ref:`Documentation/process/coding-style.rst <codingstyle>`.  For much of
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
34 the standard; many developers will request that the code be reformatted
36 requires some uniformity of code to make it possible for developers to
38 strangely-formatted code.
41 employer's mandated style.  In such cases, the kernel's style will have to
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
51 they tend to get a chilly reception.  So this type of patch is best
52 avoided.  It is natural to fix the style of a piece of code while working
57 can never be transgressed.  If there is a good reason to go against the
58 style (a line which becomes far less readable if split to fit within the
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>`
77 Computer Science professors teach students to make extensive use of
82 just as harmful as premature optimization.  Abstraction should be used to
86 always passed as zero by all callers.  One could retain that argument just
87 in case somebody eventually needs to use the extra flexibility that it
90 never noticed - because it has never been used.  Or, when the need for
93 patches to remove unused arguments; they should, in general, not be added
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
102 from another kernel subsystem, it is time to ask whether it would, in fact,
103 make sense to pull out some of that code into a separate library or to
111 The C preprocessor seems to present a powerful temptation to some C
112 programmers, who see it as a way to efficiently encode a great deal of
114 use of it results in code which is much harder for others to read and
115 harder for the compiler to check for correctness.  Heavy preprocessor use
119 is used within the kernel.  But there is little desire to see code which is
121 should be confined to header files whenever possible.
122 Conditionally-compiled code can be confined to functions which, if the code
123 is not to be present, simply become empty.  The compiler will then quietly
124 optimize out the call to the empty function.  The result is far cleaner
125 code which is easier to follow.
129 If you are tempted to define a macro, consider creating an inline function
131 easier to read, do not evaluate their arguments multiple times, and allow
132 the compiler to perform type checking on the arguments and return value.
151 often does not apply to contemporary hardware.  Space *is* time, in that a
152 larger program will run slower than one which is more compact.
172 corporate doors.  But one large problem in particular was that it was not
173 designed to work on multiprocessor systems.  Before this networking stack
174 (now called mac80211) could be merged, a locking scheme needed to be
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
185 accessed concurrently by more than one thread must be protected by a lock.
188 should take the time to understand the available locking primitives well
189 enough to pick the right tool for the job.  Code which shows a lack of
190 attention to concurrency will have a difficult path into the mainline.
196 One final hazard worth mentioning is this: it can be tempting to make a
197 change (which may bring big improvements) which causes something to break
201 regression cannot be fixed in a timely manner.  Far better to avoid the
205 to work for more people than it creates problems for.  Why not make a
206 change if it brings new functionality to ten systems for each one it
207 breaks?  The best answer to this question was expressed by Linus in July,
214 	progress at all. Is it two steps forwards, one step back, or one
219 An especially unwelcome type of regression is any sort of change to the
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
225 user-space interfaces is always required.
229 -------------------
231 For now, at least, the writing of error-free code remains an ideal that few
232 of us can reach.  What we can hope to do, though, is to catch and fix as
233 many of those errors as possible before our code goes into the mainline
234 kernel.  To that end, the kernel developers have put together an impressive
237 not afflict a user later on, so it stands to reason that the automated
240 The first step is simply to heed the warnings produced by the compiler.
242 potential errors.  Quite often, these warnings point to real problems.
244 warnings.  When silencing warnings, take care to understand the real cause
245 and try to avoid "fixes" which make the warning go away without addressing
249 kernel with "make KCFLAGS=-W" to get the full set.
256  - FRAME_WARN to get warnings for stack frames larger than a given amount.
257    The output generated can be verbose, but one need not worry about
260  - DEBUG_OBJECTS will add code to track the lifetime of various objects
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.
277 One of the heavier debugging tools is the locking checker, or "lockdep."
279 mutex) in the system, the order in which locks are acquired relative to
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
293 are, probably, completely untested.  Untested code tends to be broken code;
294 you could be much more confident of your code if all those error-handling
299 enabled, a configurable percentage of memory allocations will be made to
300 fail; these failures can be restricted to a specific range of code.
301 Running with fault injection enabled allows the programmer to see how the
303 Documentation/fault-injection/fault-injection.rst for more information on
304 how to use this facility.
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
313 "C=1" to your make command.
315 The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide
320 :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
324 other architectures.  If you do not happen to have an S/390 system or a
335 -------------
338 development.  Even so, adequate documentation will help to ease the merging
340 will be helpful for your users.  In many cases, the addition of
346 effects on performance, and anything else that might be needed to
348 worth applying; a surprising number of developers fail to provide that
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
355 be formatted and what information needs to be provided.
357 The file :ref:`Documentation/admin-guide/kernel-parameters.rst
358 <kernelparameters>` describes all of the kernel's boot-time parameters.
359 Any patch which adds new parameters should add the appropriate entries to
363 clearly explains the options and when the user might want to select them.
365 Internal API information for many subsystems is documented by way of
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
373 information on how to create kerneldoc templates can be found at
374 :ref:`Documentation/doc-guide/ <doc_guide>`.
380 for verbosely-commented code.  The code should, itself, be readable, with
385 locking rules for data structures generally need to be explained somewhere.
387 Non-obvious dependencies between separate bits of code should be pointed
388 out.  Anything which might tempt a code janitor to make an incorrect
393 --------------------
395 The binary interface provided by the kernel to user space cannot be broken
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
401 developer, you are empowered to make such changes.
404 to be well justified.  So any patch making an internal API change should be
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
413 likely to conflict with work being done by other developers.  Needless to
414 say, this can be a large job, so it is best to be sure that the
416 wide-ranging API changes.
418 When making an incompatible API change, one should, whenever possible,
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