Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. _development_coding:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) Getting the code right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) While there is much to be said for a solid and community-oriented design
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) process, the proof of any kernel development project is in the resulting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) code.  It is the code which will be examined by other developers and merged
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) (or not) into the mainline tree.  So it is the quality of this code which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) will determine the ultimate success of the project.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) This section will examine the coding process.  We'll start with a look at a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) number of ways in which kernel developers can go wrong.  Then the focus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) will shift toward doing things right and the tools which can help in that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) quest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) Pitfalls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) Coding style
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) ************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) The kernel has long had a standard coding style, described in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) :ref:`Documentation/process/coding-style.rst <codingstyle>`.  For much of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) that time, the policies described in that file were taken as being, at most,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) advisory.  As a result, there is a substantial amount of code in the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) which does not meet the coding style guidelines.  The presence of that code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) leads to two independent hazards for kernel developers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) The first of these is to believe that the kernel coding standards do not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) matter and are not enforced.  The truth of the matter is that adding new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) code to the kernel is very difficult if that code is not coded according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) the standard; many developers will request that the code be reformatted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) before they will even review it.  A code base as large as the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) requires some uniformity of code to make it possible for developers to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) quickly understand any part of it.  So there is no longer room for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) strangely-formatted code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) Occasionally, the kernel's coding style will run into conflict with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) employer's mandated style.  In such cases, the kernel's style will have to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) win before the code can be merged.  Putting code into the kernel means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) giving up a degree of control in a number of ways - including control over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) how the code is formatted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) The other trap is to assume that code which is already in the kernel is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) urgently in need of coding style fixes.  Developers may start to generate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) reformatting patches as a way of gaining familiarity with the process, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) as a way of getting their name into the kernel changelogs - or both.  But
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) pure coding style fixes are seen as noise by the development community;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) they tend to get a chilly reception.  So this type of patch is best
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) avoided.  It is natural to fix the style of a piece of code while working
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) on it for other reasons, but coding style changes should not be made for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) their own sake.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) The coding style document also should not be read as an absolute law which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) can never be transgressed.  If there is a good reason to go against the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) style (a line which becomes far less readable if split to fit within the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 80-column limit, for example), just do it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) Note that you can also use the ``clang-format`` tool to help you with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) these rules, to quickly re-format parts of your code automatically,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) and to review full files in order to spot coding style mistakes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) typos and possible improvements. It is also handy for sorting ``#includes``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) for aligning variables/macros, for reflowing text and other similar tasks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) Abstraction layers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) ******************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) Computer Science professors teach students to make extensive use of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) abstraction layers in the name of flexibility and information hiding.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) Certainly the kernel makes extensive use of abstraction; no project
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) involving several million lines of code could do otherwise and survive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) But experience has shown that excessive or premature abstraction can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) just as harmful as premature optimization.  Abstraction should be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) the level required and no further.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) At a simple level, consider a function which has an argument which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) always passed as zero by all callers.  One could retain that argument just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) in case somebody eventually needs to use the extra flexibility that it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) provides.  By that time, though, chances are good that the code which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) implements this extra argument has been broken in some subtle way which was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) never noticed - because it has never been used.  Or, when the need for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) extra flexibility arises, it does not do so in a way which matches the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) programmer's early expectation.  Kernel developers will routinely submit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) patches to remove unused arguments; they should, in general, not be added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) in the first place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) Abstraction layers which hide access to hardware - often to allow the bulk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) of a driver to be used with multiple operating systems - are especially
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) frowned upon.  Such layers obscure the code and may impose a performance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) penalty; they do not belong in the Linux kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) On the other hand, if you find yourself copying significant amounts of code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) from another kernel subsystem, it is time to ask whether it would, in fact,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) make sense to pull out some of that code into a separate library or to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) implement that functionality at a higher level.  There is no value in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) replicating the same code throughout the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) #ifdef and preprocessor use in general
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) **************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The C preprocessor seems to present a powerful temptation to some C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) programmers, who see it as a way to efficiently encode a great deal of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) flexibility into a source file.  But the preprocessor is not C, and heavy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) use of it results in code which is much harder for others to read and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) harder for the compiler to check for correctness.  Heavy preprocessor use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) is almost always a sign of code which needs some cleanup work.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Conditional compilation with #ifdef is, indeed, a powerful feature, and it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) is used within the kernel.  But there is little desire to see code which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) sprinkled liberally with #ifdef blocks.  As a general rule, #ifdef use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) should be confined to header files whenever possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Conditionally-compiled code can be confined to functions which, if the code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) is not to be present, simply become empty.  The compiler will then quietly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) optimize out the call to the empty function.  The result is far cleaner
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) code which is easier to follow.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) C preprocessor macros present a number of hazards, including possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) multiple evaluation of expressions with side effects and no type safety.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) If you are tempted to define a macro, consider creating an inline function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) instead.  The code which results will be the same, but inline functions are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) easier to read, do not evaluate their arguments multiple times, and allow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) the compiler to perform type checking on the arguments and return value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) Inline functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) ****************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) Inline functions present a hazard of their own, though.  Programmers can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) become enamored of the perceived efficiency inherent in avoiding a function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) call and fill a source file with inline functions.  Those functions,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) however, can actually reduce performance.  Since their code is replicated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) at each call site, they end up bloating the size of the compiled kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) That, in turn, creates pressure on the processor's memory caches, which can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) slow execution dramatically.  Inline functions, as a rule, should be quite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) small and relatively rare.  The cost of a function call, after all, is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) that high; the creation of large numbers of inline functions is a classic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) example of premature optimization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) In general, kernel programmers ignore cache effects at their peril.  The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) classic time/space tradeoff taught in beginning data structures classes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) often does not apply to contemporary hardware.  Space *is* time, in that a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) larger program will run slower than one which is more compact.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) More recent compilers take an increasingly active role in deciding whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) a given function should actually be inlined or not.  So the liberal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) placement of "inline" keywords may not just be excessive; it could also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) irrelevant.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) Locking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) *******
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) In May, 2006, the "Devicescape" networking stack was, with great
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) fanfare, released under the GPL and made available for inclusion in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) mainline kernel.  This donation was welcome news; support for wireless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) networking in Linux was considered substandard at best, and the Devicescape
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) stack offered the promise of fixing that situation.  Yet, this code did not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) actually make it into the mainline until June, 2007 (2.6.22).  What
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) happened?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) This code showed a number of signs of having been developed behind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) corporate doors.  But one large problem in particular was that it was not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) designed to work on multiprocessor systems.  Before this networking stack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) (now called mac80211) could be merged, a locking scheme needed to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) retrofitted onto it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) Once upon a time, Linux kernel code could be developed without thinking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) about the concurrency issues presented by multiprocessor systems.  Now,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) however, this document is being written on a dual-core laptop.  Even on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) single-processor systems, work being done to improve responsiveness will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) raise the level of concurrency within the kernel.  The days when kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) code could be written without thinking about locking are long past.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) Any resource (data structures, hardware registers, etc.) which could be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) accessed concurrently by more than one thread must be protected by a lock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) New code should be written with this requirement in mind; retrofitting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) locking after the fact is a rather more difficult task.  Kernel developers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) should take the time to understand the available locking primitives well
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) enough to pick the right tool for the job.  Code which shows a lack of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) attention to concurrency will have a difficult path into the mainline.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Regressions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) ***********
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) One final hazard worth mentioning is this: it can be tempting to make a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) change (which may bring big improvements) which causes something to break
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) for existing users.  This kind of change is called a "regression," and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) regressions have become most unwelcome in the mainline kernel.  With few
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) exceptions, changes which cause regressions will be backed out if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) regression cannot be fixed in a timely manner.  Far better to avoid the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) regression in the first place.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) It is often argued that a regression can be justified if it causes things
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) to work for more people than it creates problems for.  Why not make a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) change if it brings new functionality to ten systems for each one it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) breaks?  The best answer to this question was expressed by Linus in July,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) 2007:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 	So we don't fix bugs by introducing new problems.  That way lies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) 	madness, and nobody ever knows if you actually make any real
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) 	progress at all. Is it two steps forwards, one step back, or one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) 	step forward and two steps back?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) (https://lwn.net/Articles/243460/).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) An especially unwelcome type of regression is any sort of change to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) user-space ABI.  Once an interface has been exported to user space, it must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) be supported indefinitely.  This fact makes the creation of user-space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) interfaces particularly challenging: since they cannot be changed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) incompatible ways, they must be done right the first time.  For this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) reason, a great deal of thought, clear documentation, and wide review for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) user-space interfaces is always required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) Code checking tools
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) For now, at least, the writing of error-free code remains an ideal that few
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) of us can reach.  What we can hope to do, though, is to catch and fix as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) many of those errors as possible before our code goes into the mainline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) kernel.  To that end, the kernel developers have put together an impressive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) array of tools which can catch a wide variety of obscure problems in an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) automated way.  Any problem caught by the computer is a problem which will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) not afflict a user later on, so it stands to reason that the automated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) tools should be used whenever possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) The first step is simply to heed the warnings produced by the compiler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) Contemporary versions of gcc can detect (and warn about) a large number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) potential errors.  Quite often, these warnings point to real problems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) Code submitted for review should, as a rule, not produce any compiler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) warnings.  When silencing warnings, take care to understand the real cause
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) and try to avoid "fixes" which make the warning go away without addressing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) its cause.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) Note that not all compiler warnings are enabled by default.  Build the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) kernel with "make EXTRA_CFLAGS=-W" to get the full set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) The kernel provides several configuration options which turn on debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) features; most of these are found in the "kernel hacking" submenu.  Several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) of these options should be turned on for any kernel used for development or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) testing purposes.  In particular, you should turn on:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)  - ENABLE_MUST_CHECK and FRAME_WARN to get an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)    extra set of warnings for problems like the use of deprecated interfaces
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)    or ignoring an important return value from a function.  The output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)    generated by these warnings can be verbose, but one need not worry about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)    warnings from other parts of the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)  - DEBUG_OBJECTS will add code to track the lifetime of various objects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)    created by the kernel and warn when things are done out of order.  If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)    you are adding a subsystem which creates (and exports) complex objects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)    of its own, consider adding support for the object debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)    infrastructure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)  - DEBUG_SLAB can find a variety of memory allocation and use errors; it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)    should be used on most development kernels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)  - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)    number of common locking errors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) There are quite a few other debugging options, some of which will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) discussed below.  Some of them have a significant performance impact and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) should not be used all of the time.  But some time spent learning the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) available options will likely be paid back many times over in short order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) One of the heavier debugging tools is the locking checker, or "lockdep."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) This tool will track the acquisition and release of every lock (spinlock or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) mutex) in the system, the order in which locks are acquired relative to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) each other, the current interrupt environment, and more.  It can then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) ensure that locks are always acquired in the same order, that the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) interrupt assumptions apply in all situations, and so on.  In other words,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) lockdep can find a number of scenarios in which the system could, on rare
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) occasion, deadlock.  This kind of problem can be painful (for both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) developers and users) in a deployed system; lockdep allows them to be found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) in an automated manner ahead of time.  Code with any sort of non-trivial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) locking should be run with lockdep enabled before being submitted for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) inclusion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) As a diligent kernel programmer, you will, beyond doubt, check the return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) status of any operation (such as a memory allocation) which can fail.  The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) fact of the matter, though, is that the resulting failure recovery paths
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) are, probably, completely untested.  Untested code tends to be broken code;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) you could be much more confident of your code if all those error-handling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) paths had been exercised a few times.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) The kernel provides a fault injection framework which can do exactly that,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) especially where memory allocations are involved.  With fault injection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) enabled, a configurable percentage of memory allocations will be made to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) fail; these failures can be restricted to a specific range of code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) Running with fault injection enabled allows the programmer to see how the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) code responds when things go badly.  See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) Documentation/fault-injection/fault-injection.rst for more information on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) how to use this facility.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) Other kinds of errors can be found with the "sparse" static analysis tool.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) With sparse, the programmer can be warned about confusion between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) user-space and kernel-space addresses, mixture of big-endian and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) small-endian quantities, the passing of integer values where a set of bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) flags is expected, and so on.  Sparse must be installed separately (it can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) distributor does not package it); it can then be run on the code by adding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) "C=1" to your make command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) variety of potential coding problems; it can also propose fixes for those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) problems.  Quite a few "semantic patches" for the kernel have been packaged
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) under the scripts/coccinelle directory; running "make coccicheck" will run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) through those semantic patches and report on any problems found.  See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) :ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) for more information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) Other kinds of portability errors are best found by compiling your code for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) other architectures.  If you do not happen to have an S/390 system or a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) Blackfin development board handy, you can still perform the compilation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) step.  A large set of cross compilers for x86 systems can be found at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) 	https://www.kernel.org/pub/tools/crosstool/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) Some time spent installing and using these compilers will help avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) embarrassment later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) Documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) Documentation has often been more the exception than the rule with kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) development.  Even so, adequate documentation will help to ease the merging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) of new code into the kernel, make life easier for other developers, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) will be helpful for your users.  In many cases, the addition of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) documentation has become essentially mandatory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) The first piece of documentation for any patch is its associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) changelog.  Log entries should describe the problem being solved, the form
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) of the solution, the people who worked on the patch, any relevant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) effects on performance, and anything else that might be needed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) understand the patch.  Be sure that the changelog says *why* the patch is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) worth applying; a surprising number of developers fail to provide that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) Any code which adds a new user-space interface - including new sysfs or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) /proc files - should include documentation of that interface which enables
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) user-space developers to know what they are working with.  See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) Documentation/ABI/README for a description of how this documentation should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) be formatted and what information needs to be provided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) The file :ref:`Documentation/admin-guide/kernel-parameters.rst
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) <kernelparameters>` describes all of the kernel's boot-time parameters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) Any patch which adds new parameters should add the appropriate entries to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) this file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) Any new configuration options must be accompanied by help text which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) clearly explains the options and when the user might want to select them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) Internal API information for many subsystems is documented by way of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) specially-formatted comments; these comments can be extracted and formatted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) in a number of ways by the "kernel-doc" script.  If you are working within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) a subsystem which has kerneldoc comments, you should maintain them and add
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) them, as appropriate, for externally-available functions.  Even in areas
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) which have not been so documented, there is no harm in adding kerneldoc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) comments for the future; indeed, this can be a useful activity for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) beginning kernel developers.  The format of these comments, along with some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) information on how to create kerneldoc templates can be found at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) :ref:`Documentation/doc-guide/ <doc_guide>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) Anybody who reads through a significant amount of existing kernel code will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) note that, often, comments are most notable by their absence.  Once again,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) the expectations for new code are higher than they were in the past;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) merging uncommented code will be harder.  That said, there is little desire
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) for verbosely-commented code.  The code should, itself, be readable, with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) comments explaining the more subtle aspects.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) Certain things should always be commented.  Uses of memory barriers should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) be accompanied by a line explaining why the barrier is necessary.  The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) locking rules for data structures generally need to be explained somewhere.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) Major data structures need comprehensive documentation in general.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) Non-obvious dependencies between separate bits of code should be pointed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) out.  Anything which might tempt a code janitor to make an incorrect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) "cleanup" needs a comment saying why it is done the way it is.  And so on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) Internal API changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) The binary interface provided by the kernel to user space cannot be broken
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) except under the most severe circumstances.  The kernel's internal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) programming interfaces, instead, are highly fluid and can be changed when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) the need arises.  If you find yourself having to work around a kernel API,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) or simply not using a specific functionality because it does not meet your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) needs, that may be a sign that the API needs to change.  As a kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) developer, you are empowered to make such changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) There are, of course, some catches.  API changes can be made, but they need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) to be well justified.  So any patch making an internal API change should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) accompanied by a description of what the change is and why it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) necessary.  This kind of change should also be broken out into a separate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) patch, rather than buried within a larger patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) The other catch is that a developer who changes an internal API is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) generally charged with the task of fixing any code within the kernel tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) which is broken by the change.  For a widely-used function, this duty can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) lead to literally hundreds or thousands of changes - many of which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) likely to conflict with work being done by other developers.  Needless to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) say, this can be a large job, so it is best to be sure that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) justification is solid.  Note that the Coccinelle tool can help with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) wide-ranging API changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) When making an incompatible API change, one should, whenever possible,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) ensure that code which has not been updated is caught by the compiler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) This will help you to be sure that you have found all in-tree uses of that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) interface.  It will also alert developers of out-of-tree code that there is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) a change that they need to respond to.  Supporting out-of-tree code is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) something that kernel developers need to be worried about, but we also do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) not have to make life harder for out-of-tree developers than it needs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) be.