^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. _process_howto:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) HOWTO do Linux kernel development
^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) This is the be-all, end-all document on this topic. It contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) instructions on how to become a Linux kernel developer and how to learn
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) to work with the Linux kernel development community. It tries to not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) contain anything related to the technical aspects of kernel programming,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) but will help point you in the right direction for that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) If anything in this document becomes out of date, please send in patches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) to the maintainer of this file, who is listed at the bottom of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) So, you want to learn how to become a Linux kernel developer? Or you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) have been told by your manager, "Go write a Linux driver for this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) device." This document's goal is to teach you everything you need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) know to achieve this by describing the process you need to go through,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) and hints on how to work with the community. It will also try to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) explain some of the reasons why the community works like it does.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) The kernel is written mostly in C, with some architecture-dependent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) parts written in assembly. A good understanding of C is required for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) kernel development. Assembly (any architecture) is not required unless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) you plan to do low-level development for that architecture. Though they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) are not a good substitute for a solid C education and/or years of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) experience, the following books are good for, if anything, reference:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) - "Practical C Programming" by Steve Oualline [O'Reilly]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) The kernel is written using GNU C and the GNU toolchain. While it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) adheres to the ISO C89 standard, it uses a number of extensions that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) not featured in the standard. The kernel is a freestanding C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) environment, with no reliance on the standard C library, so some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) portions of the C standard are not supported. Arbitrary long long
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) divisions and floating point are not allowed. It can sometimes be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) difficult to understand the assumptions the kernel has on the toolchain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) and the extensions that it uses, and unfortunately there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) definitive reference for them. Please check the gcc info pages (`info
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) gcc`) for some information on them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) Please remember that you are trying to learn how to work with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) existing development community. It is a diverse group of people, with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) high standards for coding, style and procedure. These standards have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) been created over time based on what they have found to work best for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) such a large and geographically dispersed team. Try to learn as much as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) possible about these standards ahead of time, as they are well
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) documented; do not expect people to adapt to you or your company's way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) of doing things.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Legal Issues
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) The Linux kernel source code is released under the GPL. Please see the file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) COPYING in the main directory of the source tree. The Linux kernel licensing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) If you have further questions about the license, please contact a lawyer, and do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) not ask on the Linux kernel mailing list. The people on the mailing lists are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) not lawyers, and you should not rely on their statements on legal matters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) For common questions and answers about the GPL, please see:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) https://www.gnu.org/licenses/gpl-faq.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) The Linux kernel source tree has a large range of documents that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) invaluable for learning how to interact with the kernel community. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) new features are added to the kernel, it is recommended that new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) documentation files are also added which explain how to use the feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) When a kernel change causes the interface that the kernel exposes to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) userspace to change, it is recommended that you send the information or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) a patch to the manual pages explaining the change to the manual pages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) maintainer at mtk.manpages@gmail.com, and CC the list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) linux-api@vger.kernel.org.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) Here is a list of files that are in the kernel source tree that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) required reading:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) :ref:`Documentation/admin-guide/README.rst <readme>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) This file gives a short background on the Linux kernel and describes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) what is necessary to do to configure and build the kernel. People
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) who are new to the kernel should start here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) :ref:`Documentation/process/changes.rst <changes>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) This file gives a list of the minimum levels of various software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) packages that are necessary to build and run the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) successfully.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) :ref:`Documentation/process/coding-style.rst <codingstyle>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) This describes the Linux kernel coding style, and some of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) rationale behind it. All new code is expected to follow the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) guidelines in this document. Most maintainers will only accept
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) patches if these rules are followed, and many people will only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) review code if it is in the proper style.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) These files describe in explicit detail how to successfully create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) and send a patch, including (but not limited to):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) - Email contents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) - Email format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) - Who to send it to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Following these rules will not guarantee success (as all patches are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) subject to scrutiny for content and style), but not following them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) will almost always prevent it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Other excellent descriptions of how to create patches properly are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) "The Perfect Patch"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) https://www.ozlabs.org/~akpm/stuff/tpp.txt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) "Linux kernel patch submission format"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) This file describes the rationale behind the conscious decision to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) not have a stable API within the kernel, including things like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) - Subsystem shim-layers (for compatibility?)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) - Driver portability between Operating Systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) - Mitigating rapid change within the kernel source tree (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) preventing rapid change)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) This document is crucial for understanding the Linux development
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) philosophy and is very important for people moving to Linux from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) development on other Operating Systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) If you feel you have found a security problem in the Linux kernel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) please follow the steps in this document to help notify the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) developers, and help solve the issue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) :ref:`Documentation/process/management-style.rst <managementstyle>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) This document describes how Linux kernel maintainers operate and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) shared ethos behind their methodologies. This is important reading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) for anyone new to kernel development (or anyone simply curious about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) it), as it resolves a lot of common misconceptions and confusion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) about the unique behavior of kernel maintainers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) This file describes the rules on how the stable kernel releases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) happen, and what to do if you want to get a change into one of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) releases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) :ref:`Documentation/process/kernel-docs.rst <kernel_docs>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) A list of external documentation that pertains to kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) development. Please consult this list if you do not find what you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) are looking for within the in-kernel documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) :ref:`Documentation/process/applying-patches.rst <applying_patches>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) A good introduction describing exactly what a patch is and how to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) apply it to the different development branches of the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) The kernel also has a large number of documents that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) automatically generated from the source code itself or from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) ReStructuredText markups (ReST), like this one. This includes a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) full description of the in-kernel API, and rules on how to handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) locking properly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) All such documents can be generated as PDF or HTML by running::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) make pdfdocs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) make htmldocs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) respectively from the main kernel source directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) The documents that uses ReST markup will be generated at Documentation/output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) They can also be generated on LaTeX and ePub formats with::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) make latexdocs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) make epubdocs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) Becoming A Kernel Developer
^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) If you do not know anything about Linux kernel development, you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) look at the Linux KernelNewbies project:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) https://kernelnewbies.org
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) It consists of a helpful mailing list where you can ask almost any type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) of basic kernel development question (make sure to search the archives
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) first, before asking something that has already been answered in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) past.) It also has an IRC channel that you can use to ask questions in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) real-time, and a lot of helpful documentation that is useful for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) learning about Linux kernel development.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) The website has basic information about code organization, subsystems,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) and current projects (both in-tree and out-of-tree). It also describes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) some basic logistical information, like how to compile a kernel and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) apply a patch.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) If you do not know where you want to start, but you want to look for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) some task to start doing to join into the kernel development community,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) go to the Linux Kernel Janitor's project:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) https://kernelnewbies.org/KernelJanitors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) It is a great place to start. It describes a list of relatively simple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) problems that need to be cleaned up and fixed within the Linux kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) source tree. Working with the developers in charge of this project, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) will learn the basics of getting your patch into the Linux kernel tree,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) and possibly be pointed in the direction of what to go work on next, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) you do not already have an idea.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) Before making any actual modifications to the Linux kernel code, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) imperative to understand how the code in question works. For this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) purpose, nothing is better than reading through it directly (most tricky
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) bits are commented well), perhaps even with the help of specialized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) tools. One such tool that is particularly recommended is the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) Cross-Reference project, which is able to present source code in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) self-referential, indexed webpage format. An excellent up-to-date
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) repository of the kernel code may be found at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) https://elixir.bootlin.com/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) The development process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) Linux kernel development process currently consists of a few different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) main kernel "branches" and lots of different subsystem-specific kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) branches. These different branches are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) - Linus's mainline tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) - Various stable trees with multiple major numbers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) - Subsystem-specific trees
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) - linux-next integration testing tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) Mainline tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) ~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) The mainline tree is maintained by Linus Torvalds, and can be found at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) https://kernel.org or in the repo. Its development process is as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) - As soon as a new kernel is released a two week window is open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) during this period of time maintainers can submit big diffs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) Linus, usually the patches that have already been included in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) linux-next for a few weeks. The preferred way to submit big changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) is using git (the kernel's source management tool, more information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) can be found at https://git-scm.com/) but plain patches are also just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) fine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) - After two weeks a -rc1 kernel is released and the focus is on making the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) new kernel as rock solid as possible. Most of the patches at this point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) should fix a regression. Bugs that have always existed are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) regressions, so only push these kinds of fixes if they are important.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) Please note that a whole new driver (or filesystem) might be accepted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) after -rc1 because there is no risk of causing regressions with such a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) change as long as the change is self-contained and does not affect areas
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) outside of the code that is being added. git can be used to send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) patches to Linus after -rc1 is released, but the patches need to also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) sent to a public mailing list for review.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) - A new -rc is released whenever Linus deems the current git tree to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) be in a reasonably sane state adequate for testing. The goal is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) release a new -rc kernel every week.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) - Process continues until the kernel is considered "ready", the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) process should last around 6 weeks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) It is worth mentioning what Andrew Morton wrote on the linux-kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) mailing list about kernel releases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) *"Nobody knows when a kernel will be released, because it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) released according to perceived bug status, not according to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) preconceived timeline."*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) Various stable trees with multiple major numbers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) Kernels with 3-part versions are -stable kernels. They contain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) relatively small and critical fixes for security problems or significant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) regressions discovered in a given major mainline release. Each release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) in a major stable series increments the third part of the version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) number, keeping the first two parts the same.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) This is the recommended branch for users who want the most recent stable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) kernel and are not interested in helping test development/experimental
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) versions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) Stable trees are maintained by the "stable" team <stable@vger.kernel.org>, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) are released as needs dictate. The normal release period is approximately
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) two weeks, but it can be longer if there are no pressing problems. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) security-related problem, instead, can cause a release to happen almost
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) instantly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) in the kernel tree documents what kinds of changes are acceptable for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) the -stable tree, and how the release process works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) Subsystem-specific trees
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) ~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) The maintainers of the various kernel subsystems --- and also many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) kernel subsystem developers --- expose their current state of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) development in source repositories. That way, others can see what is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) happening in the different areas of the kernel. In areas where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) development is rapid, a developer may be asked to base his submissions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) onto such a subsystem kernel tree so that conflicts between the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) submission and other already ongoing work are avoided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) Most of these repositories are git trees, but there are also other SCMs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) in use, or patch queues being published as quilt series. Addresses of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) these subsystem repositories are listed in the MAINTAINERS file. Many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) of them can be browsed at https://git.kernel.org/.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) Before a proposed patch is committed to such a subsystem tree, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) subject to review which primarily happens on mailing lists (see the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) respective section below). For several kernel subsystems, this review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) process is tracked with the tool patchwork. Patchwork offers a web
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) interface which shows patch postings, any comments on a patch or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) revisions to it, and maintainers can mark patches as under review,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) accepted, or rejected. Most of these patchwork sites are listed at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) https://patchwork.kernel.org/.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) linux-next integration testing tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) Before updates from subsystem trees are merged into the mainline tree,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) they need to be integration-tested. For this purpose, a special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) testing repository exists into which virtually all subsystem trees are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) pulled on an almost daily basis:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) This way, the linux-next gives a summary outlook onto what will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) expected to go into the mainline kernel at the next merge period.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) Adventurous testers are very welcome to runtime-test the linux-next.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) Bug Reporting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) https://bugzilla.kernel.org is where the Linux kernel developers track kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) bugs. Users are encouraged to report all bugs that they find in this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) tool. For details on how to use the kernel bugzilla, please see:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) https://bugzilla.kernel.org/page.cgi?id=faq.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) The file :ref:`admin-guide/reporting-bugs.rst <reportingbugs>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) in the main kernel source directory has a good
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) template for how to report a possible kernel bug, and details what kind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) of information is needed by the kernel developers to help track down the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) problem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) Managing bug reports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) One of the best ways to put into practice your hacking skills is by fixing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) bugs reported by other people. Not only you will help to make the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) more stable, but you'll also learn to fix real world problems and you will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) improve your skills, and other developers will be aware of your presence.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) Fixing bugs is one of the best ways to get merits among other developers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) because not many people like wasting time fixing other people's bugs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) To work in the already reported bug reports, go to https://bugzilla.kernel.org.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) Mailing lists
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) As some of the above documents describe, the majority of the core kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) developers participate on the Linux Kernel Mailing list. Details on how
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) to subscribe and unsubscribe from the list can be found at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) http://vger.kernel.org/vger-lists.html#linux-kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) There are archives of the mailing list on the web in many different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) places. Use a search engine to find these archives. For example:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) http://dir.gmane.org/gmane.linux.kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) It is highly recommended that you search the archives about the topic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) you want to bring up, before you post it to the list. A lot of things
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) already discussed in detail are only recorded at the mailing list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) archives.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) Most of the individual kernel subsystems also have their own separate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) mailing list where they do their development efforts. See the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) MAINTAINERS file for a list of what these lists are for the different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) groups.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) Many of the lists are hosted on kernel.org. Information on them can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) found at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) http://vger.kernel.org/vger-lists.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) Please remember to follow good behavioral habits when using the lists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) Though a bit cheesy, the following URL has some simple guidelines for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) interacting with the list (or any list):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) http://www.albion.com/netiquette/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) If multiple people respond to your mail, the CC: list of recipients may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) get pretty large. Don't remove anybody from the CC: list without a good
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) reason, or don't reply only to the list address. Get used to receiving the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) mail twice, one from the sender and the one from the list, and don't try
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) to tune that by adding fancy mail-headers, people will not like it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) Remember to keep the context and the attribution of your replies intact,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) add your statements between the individual quoted sections instead of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) writing at the top of the mail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) If you add patches to your mail, make sure they are plain readable text
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) as stated in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) Kernel developers don't want to deal with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) attachments or compressed patches; they may want to comment on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) individual lines of your patch, which works only that way. Make sure you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) use a mail program that does not mangle spaces and tab characters. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) good first test is to send the mail to yourself and try to apply your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) own patch by yourself. If that doesn't work, get your mail program fixed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) or change it until it works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) Above all, please remember to show respect to other subscribers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) Working with the community
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) The goal of the kernel community is to provide the best possible kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) there is. When you submit a patch for acceptance, it will be reviewed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) on its technical merits and those alone. So, what should you be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) expecting?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) - criticism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) - comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) - requests for change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) - requests for justification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) - silence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) Remember, this is part of getting your patch into the kernel. You have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) to be able to take criticism and comments about your patches, evaluate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) them at a technical level and either rework your patches or provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) clear and concise reasoning as to why those changes should not be made.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) If there are no responses to your posting, wait a few days and try
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) again, sometimes things get lost in the huge volume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) What should you not do?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) - expect your patch to be accepted without question
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) - become defensive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) - ignore comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) - resubmit the patch without making any of the requested changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) In a community that is looking for the best technical solution possible,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) there will always be differing opinions on how beneficial a patch is.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) You have to be cooperative, and willing to adapt your idea to fit within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) the kernel. Or at least be willing to prove your idea is worth it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) Remember, being wrong is acceptable as long as you are willing to work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) toward a solution that is right.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) It is normal that the answers to your first patch might simply be a list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) of a dozen things you should correct. This does **not** imply that your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) patch will not be accepted, and it is **not** meant against you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) personally. Simply correct all issues raised against your patch and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) resend it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) Differences between the kernel community and corporate structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) -----------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) The kernel community works differently than most traditional corporate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) development environments. Here are a list of things that you can try to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) do to avoid problems:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) Good things to say regarding your proposed changes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) - "This solves multiple problems."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) - "This deletes 2000 lines of code."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) - "Here is a patch that explains what I am trying to describe."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) - "I tested it on 5 different architectures..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) - "Here is a series of small patches that..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) - "This increases performance on typical machines..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) Bad things you should avoid saying:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) - "We did it this way in AIX/ptx/Solaris, so therefore it must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) good..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) - "I've being doing this for 20 years, so..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) - "This is required for my company to make money"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) - "This is for our Enterprise product line."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) - "Here is my 1000 page design document that describes my idea"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) - "I've been working on this for 6 months..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) - "Here's a 5000 line patch that..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) - "I rewrote all of the current mess, and here it is..."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) - "I have a deadline, and this patch needs to be applied now."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) Another way the kernel community is different than most traditional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) software engineering work environments is the faceless nature of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) interaction. One benefit of using email and irc as the primary forms of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) communication is the lack of discrimination based on gender or race.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) The Linux kernel work environment is accepting of women and minorities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) because all you are is an email address. The international aspect also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) helps to level the playing field because you can't guess gender based on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) a person's name. A man may be named Andrea and a woman may be named Pat.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) Most women who have worked in the Linux kernel and have expressed an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) opinion have had positive experiences.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) The language barrier can cause problems for some people who are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) comfortable with English. A good grasp of the language can be needed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) order to get ideas across properly on mailing lists, so it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) recommended that you check your emails to make sure they make sense in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) English before sending them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) Break up your changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) The Linux kernel community does not gladly accept large chunks of code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) dropped on it all at once. The changes need to be properly introduced,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) discussed, and broken up into tiny, individual portions. This is almost
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) the exact opposite of what companies are used to doing. Your proposal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) should also be introduced very early in the development process, so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) you can receive feedback on what you are doing. It also lets the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) community feel that you are working with them, and not simply using them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) as a dumping ground for your feature. However, don't send 50 emails at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) one time to a mailing list, your patch series should be smaller than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) that almost all of the time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) The reasons for breaking things up are the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) 1) Small patches increase the likelihood that your patches will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) applied, since they don't take much time or effort to verify for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) correctness. A 5 line patch can be applied by a maintainer with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) barely a second glance. However, a 500 line patch may take hours to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) review for correctness (the time it takes is exponentially
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) proportional to the size of the patch, or something).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) Small patches also make it very easy to debug when something goes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) wrong. It's much easier to back out patches one by one than it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) to dissect a very large patch after it's been applied (and broken
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) something).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) 2) It's important not only to send small patches, but also to rewrite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) and simplify (or simply re-order) patches before submitting them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) Here is an analogy from kernel developer Al Viro:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) *"Think of a teacher grading homework from a math student. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) teacher does not want to see the student's trials and errors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) before they came up with the solution. They want to see the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) cleanest, most elegant answer. A good student knows this, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) would never submit her intermediate work before the final
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) solution.*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) *The same is true of kernel development. The maintainers and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) reviewers do not want to see the thought process behind the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) solution to the problem one is solving. They want to see a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) simple and elegant solution."*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) It may be challenging to keep the balance between presenting an elegant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) solution and working together with the community and discussing your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) unfinished work. Therefore it is good to get early in the process to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) get feedback to improve your work, but also keep your changes in small
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) chunks that they may get already accepted, even when your whole task is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) not ready for inclusion now.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) Also realize that it is not acceptable to send patches for inclusion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) that are unfinished and will be "fixed up later."
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) Justify your change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) Along with breaking up your patches, it is very important for you to let
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) the Linux community know why they should add this change. New features
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) must be justified as being needed and useful.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) Document your change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) When sending in your patches, pay special attention to what you say in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) the text in your email. This information will become the ChangeLog
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) information for the patch, and will be preserved for everyone to see for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) all time. It should describe the patch completely, containing:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) - why the change is necessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) - the overall design approach in the patch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) - implementation details
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) - testing results
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) For more details on what this should all look like, please see the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) ChangeLog section of the document:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) "The Perfect Patch"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) https://www.ozlabs.org/~akpm/stuff/tpp.txt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) All of these things are sometimes very hard to do. It can take years to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) perfect these practices (if at all). It's a continuous process of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) improvement that requires a lot of patience and determination. But
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) don't give up, it's possible. Many have done it before, and each had to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) start exactly where you are now.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) Thanks to Paolo Ciarrocchi who allowed the "Development Process"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) (https://lwn.net/Articles/94386/) section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) to be based on text he had written, and to Randy Dunlap and Gerrit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) Huizenga for some of the list of things you should and should not say.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) their review, comments, and contributions. Without their help, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) document would not have been possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) Maintainer: Greg Kroah-Hartman <greg@kroah.com>
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags