3.Early-stage.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  1. .. _development_early_stage:
  2. Early-stage planning
  3. ====================
  4. When contemplating a Linux kernel development project, it can be tempting
  5. to jump right in and start coding. As with any significant project,
  6. though, much of the groundwork for success is best laid before the first
  7. line of code is written. Some time spent in early planning and
  8. communication can save far more time later on.
  9. Specifying the problem
  10. ----------------------
  11. Like any engineering project, a successful kernel enhancement starts with a
  12. clear description of the problem to be solved. In some cases, this step is
  13. easy: when a driver is needed for a specific piece of hardware, for
  14. example. In others, though, it is tempting to confuse the real problem
  15. with the proposed solution, and that can lead to difficulties.
  16. Consider an example: some years ago, developers working with Linux audio
  17. sought a way to run applications without dropouts or other artifacts caused
  18. by excessive latency in the system. The solution they arrived at was a
  19. kernel module intended to hook into the Linux Security Module (LSM)
  20. framework; this module could be configured to give specific applications
  21. access to the realtime scheduler. This module was implemented and sent to
  22. the linux-kernel mailing list, where it immediately ran into problems.
  23. To the audio developers, this security module was sufficient to solve their
  24. immediate problem. To the wider kernel community, though, it was seen as a
  25. misuse of the LSM framework (which is not intended to confer privileges
  26. onto processes which they would not otherwise have) and a risk to system
  27. stability. Their preferred solutions involved realtime scheduling access
  28. via the rlimit mechanism for the short term, and ongoing latency reduction
  29. work in the long term.
  30. The audio community, however, could not see past the particular solution
  31. they had implemented; they were unwilling to accept alternatives. The
  32. resulting disagreement left those developers feeling disillusioned with the
  33. entire kernel development process; one of them went back to an audio list
  34. and posted this:
  35. There are a number of very good Linux kernel developers, but they
  36. tend to get outshouted by a large crowd of arrogant fools. Trying
  37. to communicate user requirements to these people is a waste of
  38. time. They are much too "intelligent" to listen to lesser mortals.
  39. (https://lwn.net/Articles/131776/).
  40. The reality of the situation was different; the kernel developers were far
  41. more concerned about system stability, long-term maintenance, and finding
  42. the right solution to the problem than they were with a specific module.
  43. The moral of the story is to focus on the problem - not a specific solution
  44. - and to discuss it with the development community before investing in the
  45. creation of a body of code.
  46. So, when contemplating a kernel development project, one should obtain
  47. answers to a short set of questions:
  48. - What, exactly, is the problem which needs to be solved?
  49. - Who are the users affected by this problem? Which use cases should the
  50. solution address?
  51. - How does the kernel fall short in addressing that problem now?
  52. Only then does it make sense to start considering possible solutions.
  53. Early discussion
  54. ----------------
  55. When planning a kernel development project, it makes great sense to hold
  56. discussions with the community before launching into implementation. Early
  57. communication can save time and trouble in a number of ways:
  58. - It may well be that the problem is addressed by the kernel in ways which
  59. you have not understood. The Linux kernel is large and has a number of
  60. features and capabilities which are not immediately obvious. Not all
  61. kernel capabilities are documented as well as one might like, and it is
  62. easy to miss things. Your author has seen the posting of a complete
  63. driver which duplicated an existing driver that the new author had been
  64. unaware of. Code which reinvents existing wheels is not only wasteful;
  65. it will also not be accepted into the mainline kernel.
  66. - There may be elements of the proposed solution which will not be
  67. acceptable for mainline merging. It is better to find out about
  68. problems like this before writing the code.
  69. - It's entirely possible that other developers have thought about the
  70. problem; they may have ideas for a better solution, and may be willing
  71. to help in the creation of that solution.
  72. Years of experience with the kernel development community have taught a
  73. clear lesson: kernel code which is designed and developed behind closed
  74. doors invariably has problems which are only revealed when the code is
  75. released into the community. Sometimes these problems are severe,
  76. requiring months or years of effort before the code can be brought up to
  77. the kernel community's standards. Some examples include:
  78. - The Devicescape network stack was designed and implemented for
  79. single-processor systems. It could not be merged into the mainline
  80. until it was made suitable for multiprocessor systems. Retrofitting
  81. locking and such into code is a difficult task; as a result, the merging
  82. of this code (now called mac80211) was delayed for over a year.
  83. - The Reiser4 filesystem included a number of capabilities which, in the
  84. core kernel developers' opinion, should have been implemented in the
  85. virtual filesystem layer instead. It also included features which could
  86. not easily be implemented without exposing the system to user-caused
  87. deadlocks. The late revelation of these problems - and refusal to
  88. address some of them - has caused Reiser4 to stay out of the mainline
  89. kernel.
  90. - The AppArmor security module made use of internal virtual filesystem
  91. data structures in ways which were considered to be unsafe and
  92. unreliable. This concern (among others) kept AppArmor out of the
  93. mainline for years.
  94. In each of these cases, a great deal of pain and extra work could have been
  95. avoided with some early discussion with the kernel developers.
  96. Who do you talk to?
  97. -------------------
  98. When developers decide to take their plans public, the next question will
  99. be: where do we start? The answer is to find the right mailing list(s) and
  100. the right maintainer. For mailing lists, the best approach is to look in
  101. the MAINTAINERS file for a relevant place to post. If there is a suitable
  102. subsystem list, posting there is often preferable to posting on
  103. linux-kernel; you are more likely to reach developers with expertise in the
  104. relevant subsystem and the environment may be more supportive.
  105. Finding maintainers can be a bit harder. Again, the MAINTAINERS file is
  106. the place to start. That file tends to not always be up to date, though,
  107. and not all subsystems are represented there. The person listed in the
  108. MAINTAINERS file may, in fact, not be the person who is actually acting in
  109. that role currently. So, when there is doubt about who to contact, a
  110. useful trick is to use git (and "git log" in particular) to see who is
  111. currently active within the subsystem of interest. Look at who is writing
  112. patches, and who, if anybody, is attaching Signed-off-by lines to those
  113. patches. Those are the people who will be best placed to help with a new
  114. development project.
  115. The task of finding the right maintainer is sometimes challenging enough
  116. that the kernel developers have added a script to ease the process:
  117. ::
  118. .../scripts/get_maintainer.pl
  119. This script will return the current maintainer(s) for a given file or
  120. directory when given the "-f" option. If passed a patch on the
  121. command line, it will list the maintainers who should probably receive
  122. copies of the patch. There are a number of options regulating how hard
  123. get_maintainer.pl will search for maintainers; please be careful about
  124. using the more aggressive options as you may end up including developers
  125. who have no real interest in the code you are modifying.
  126. If all else fails, talking to Andrew Morton can be an effective way to
  127. track down a maintainer for a specific piece of code.
  128. When to post?
  129. -------------
  130. If possible, posting your plans during the early stages can only be
  131. helpful. Describe the problem being solved and any plans that have been
  132. made on how the implementation will be done. Any information you can
  133. provide can help the development community provide useful input on the
  134. project.
  135. One discouraging thing which can happen at this stage is not a hostile
  136. reaction, but, instead, little or no reaction at all. The sad truth of the
  137. matter is (1) kernel developers tend to be busy, (2) there is no shortage
  138. of people with grand plans and little code (or even prospect of code) to
  139. back them up, and (3) nobody is obligated to review or comment on ideas
  140. posted by others. Beyond that, high-level designs often hide problems
  141. which are only revealed when somebody actually tries to implement those
  142. designs; for that reason, kernel developers would rather see the code.
  143. If a request-for-comments posting yields little in the way of comments, do
  144. not assume that it means there is no interest in the project.
  145. Unfortunately, you also cannot assume that there are no problems with your
  146. idea. The best thing to do in this situation is to proceed, keeping the
  147. community informed as you go.
  148. Getting official buy-in
  149. -----------------------
  150. If your work is being done in a corporate environment - as most Linux
  151. kernel work is - you must, obviously, have permission from suitably
  152. empowered managers before you can post your company's plans or code to a
  153. public mailing list. The posting of code which has not been cleared for
  154. release under a GPL-compatible license can be especially problematic; the
  155. sooner that a company's management and legal staff can agree on the posting
  156. of a kernel development project, the better off everybody involved will be.
  157. Some readers may be thinking at this point that their kernel work is
  158. intended to support a product which does not yet have an officially
  159. acknowledged existence. Revealing their employer's plans on a public
  160. mailing list may not be a viable option. In cases like this, it is worth
  161. considering whether the secrecy is really necessary; there is often no real
  162. need to keep development plans behind closed doors.
  163. That said, there are also cases where a company legitimately cannot
  164. disclose its plans early in the development process. Companies with
  165. experienced kernel developers may choose to proceed in an open-loop manner
  166. on the assumption that they will be able to avoid serious integration
  167. problems later. For companies without that sort of in-house expertise, the
  168. best option is often to hire an outside developer to review the plans under
  169. a non-disclosure agreement. The Linux Foundation operates an NDA program
  170. designed to help with this sort of situation; more information can be found
  171. at:
  172. https://www.linuxfoundation.org/nda/
  173. This kind of review is often enough to avoid serious problems later on
  174. without requiring public disclosure of the project.