123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652 |
- HOWTO do Linux kernel development
- =================================
- This is the be-all, end-all document on this topic. It contains
- instructions on how to become a Linux kernel developer and how to learn
- to work with the Linux kernel development community. It tries to not
- contain anything related to the technical aspects of kernel programming,
- but will help point you in the right direction for that.
- If anything in this document becomes out of date, please send in patches
- to the maintainer of this file, who is listed at the bottom of the
- document.
- Introduction
- ------------
- So, you want to learn how to become a Linux kernel developer? Or you
- have been told by your manager, "Go write a Linux driver for this
- device." This document's goal is to teach you everything you need to
- know to achieve this by describing the process you need to go through,
- and hints on how to work with the community. It will also try to
- explain some of the reasons why the community works like it does.
- The kernel is written mostly in C, with some architecture-dependent
- parts written in assembly. A good understanding of C is required for
- kernel development. Assembly (any architecture) is not required unless
- you plan to do low-level development for that architecture. Though they
- are not a good substitute for a solid C education and/or years of
- experience, the following books are good for, if anything, reference:
- - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- - "Practical C Programming" by Steve Oualline [O'Reilly]
- - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
- The kernel is written using GNU C and the GNU toolchain. While it
- adheres to the ISO C89 standard, it uses a number of extensions that are
- not featured in the standard. The kernel is a freestanding C
- environment, with no reliance on the standard C library, so some
- portions of the C standard are not supported. Arbitrary long long
- divisions and floating point are not allowed. It can sometimes be
- difficult to understand the assumptions the kernel has on the toolchain
- and the extensions that it uses, and unfortunately there is no
- definitive reference for them. Please check the gcc info pages (`info
- gcc`) for some information on them.
- Please remember that you are trying to learn how to work with the
- existing development community. It is a diverse group of people, with
- high standards for coding, style and procedure. These standards have
- been created over time based on what they have found to work best for
- such a large and geographically dispersed team. Try to learn as much as
- possible about these standards ahead of time, as they are well
- documented; do not expect people to adapt to you or your company's way
- of doing things.
- Legal Issues
- ------------
- The Linux kernel source code is released under the GPL. Please see the
- file, COPYING, in the main directory of the source tree, for details on
- the license. If you have further questions about the license, please
- contact a lawyer, and do not ask on the Linux kernel mailing list. The
- people on the mailing lists are not lawyers, and you should not rely on
- their statements on legal matters.
- For common questions and answers about the GPL, please see:
- https://www.gnu.org/licenses/gpl-faq.html
- Documentation
- -------------
- The Linux kernel source tree has a large range of documents that are
- invaluable for learning how to interact with the kernel community. When
- new features are added to the kernel, it is recommended that new
- documentation files are also added which explain how to use the feature.
- When a kernel change causes the interface that the kernel exposes to
- userspace to change, it is recommended that you send the information or
- a patch to the manual pages explaining the change to the manual pages
- maintainer at mtk.manpages
- vger.kernel.org.
- Here is a list of files that are in the kernel source tree that are
- required reading:
- README
- This file gives a short background on the Linux kernel and describes
- what is necessary to do to configure and build the kernel. People
- who are new to the kernel should start here.
- :ref:`Documentation/Changes <changes>`
- This file gives a list of the minimum levels of various software
- packages that are necessary to build and run the kernel
- successfully.
- :ref:`Documentation/CodingStyle <codingstyle>`
- This describes the Linux kernel coding style, and some of the
- rationale behind it. All new code is expected to follow the
- guidelines in this document. Most maintainers will only accept
- patches if these rules are followed, and many people will only
- review code if it is in the proper style.
- :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>`
- These files describe in explicit detail how to successfully create
- and send a patch, including (but not limited to):
- - Email contents
- - Email format
- - Who to send it to
- Following these rules will not guarantee success (as all patches are
- subject to scrutiny for content and style), but not following them
- will almost always prevent it.
- Other excellent descriptions of how to create patches properly are:
- "The Perfect Patch"
- https://www.ozlabs.org/~akpm/stuff/tpp.txt
- "Linux kernel patch submission format"
- http://linux.yyz.us/patch-format.html
- :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
- This file describes the rationale behind the conscious decision to
- not have a stable API within the kernel, including things like:
- - Subsystem shim-layers (for compatibility?)
- - Driver portability between Operating Systems.
- - Mitigating rapid change within the kernel source tree (or
- preventing rapid change)
- This document is crucial for understanding the Linux development
- philosophy and is very important for people moving to Linux from
- development on other Operating Systems.
- :ref:`Documentation/SecurityBugs <securitybugs>`
- If you feel you have found a security problem in the Linux kernel,
- please follow the steps in this document to help notify the kernel
- developers, and help solve the issue.
- :ref:`Documentation/ManagementStyle <managementstyle>`
- This document describes how Linux kernel maintainers operate and the
- shared ethos behind their methodologies. This is important reading
- for anyone new to kernel development (or anyone simply curious about
- it), as it resolves a lot of common misconceptions and confusion
- about the unique behavior of kernel maintainers.
- :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
- This file describes the rules on how the stable kernel releases
- happen, and what to do if you want to get a change into one of these
- releases.
- :ref:`Documentation/kernel-docs.txt <kernel_docs>`
- A list of external documentation that pertains to kernel
- development. Please consult this list if you do not find what you
- are looking for within the in-kernel documentation.
- :ref:`Documentation/applying-patches.txt <applying_patches>`
- A good introduction describing exactly what a patch is and how to
- apply it to the different development branches of the kernel.
- The kernel also has a large number of documents that can be
- automatically generated from the source code itself or from
- ReStructuredText markups (ReST), like this one. This includes a
- full description of the in-kernel API, and rules on how to handle
- locking properly.
- All such documents can be generated as PDF or HTML by running::
- make pdfdocs
- make htmldocs
- respectively from the main kernel source directory.
- The documents that uses ReST markup will be generated at Documentation/output.
- They can also be generated on LaTeX and ePub formats with::
- make latexdocs
- make epubdocs
- Currently, there are some documents written on DocBook that are in
- the process of conversion to ReST. Such documents will be created in the
- Documentation/DocBook/ directory and can be generated also as
- Postscript or man pages by running::
- make psdocs
- make mandocs
- Becoming A Kernel Developer
- ---------------------------
- If you do not know anything about Linux kernel development, you should
- look at the Linux KernelNewbies project:
- https://kernelnewbies.org
- It consists of a helpful mailing list where you can ask almost any type
- of basic kernel development question (make sure to search the archives
- first, before asking something that has already been answered in the
- past.) It also has an IRC channel that you can use to ask questions in
- real-time, and a lot of helpful documentation that is useful for
- learning about Linux kernel development.
- The website has basic information about code organization, subsystems,
- and current projects (both in-tree and out-of-tree). It also describes
- some basic logistical information, like how to compile a kernel and
- apply a patch.
- If you do not know where you want to start, but you want to look for
- some task to start doing to join into the kernel development community,
- go to the Linux Kernel Janitor's project:
- https://kernelnewbies.org/KernelJanitors
- It is a great place to start. It describes a list of relatively simple
- problems that need to be cleaned up and fixed within the Linux kernel
- source tree. Working with the developers in charge of this project, you
- will learn the basics of getting your patch into the Linux kernel tree,
- and possibly be pointed in the direction of what to go work on next, if
- you do not already have an idea.
- If you already have a chunk of code that you want to put into the kernel
- tree, but need some help getting it in the proper form, the
- kernel-mentors project was created to help you out with this. It is a
- mailing list, and can be found at:
- https://selenic.com/mailman/listinfo/kernel-mentors
- Before making any actual modifications to the Linux kernel code, it is
- imperative to understand how the code in question works. For this
- purpose, nothing is better than reading through it directly (most tricky
- bits are commented well), perhaps even with the help of specialized
- tools. One such tool that is particularly recommended is the Linux
- Cross-Reference project, which is able to present source code in a
- self-referential, indexed webpage format. An excellent up-to-date
- repository of the kernel code may be found at:
- http://lxr.free-electrons.com/
- The development process
- -----------------------
- Linux kernel development process currently consists of a few different
- main kernel "branches" and lots of different subsystem-specific kernel
- branches. These different branches are:
- - main 4.x kernel tree
- - 4.x.y -stable kernel tree
- - 4.x -git kernel patches
- - subsystem specific kernel trees and patches
- - the 4.x -next kernel tree for integration tests
- 4.x kernel tree
- -----------------
- 4.x kernels are maintained by Linus Torvalds, and can be found on
- https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
- process is as follows:
- - As soon as a new kernel is released a two weeks window is open,
- during this period of time maintainers can submit big diffs to
- Linus, usually the patches that have already been included in the
- -next kernel for a few weeks. The preferred way to submit big changes
- is using git (the kernel's source management tool, more information
- can be found at https://git-scm.com/) but plain patches are also just
- fine.
- - After two weeks a -rc1 kernel is released it is now possible to push
- only patches that do not include new features that could affect the
- stability of the whole kernel. Please note that a whole new driver
- (or filesystem) might be accepted after -rc1 because there is no
- risk of causing regressions with such a change as long as the change
- is self-contained and does not affect areas outside of the code that
- is being added. git can be used to send patches to Linus after -rc1
- is released, but the patches need to also be sent to a public
- mailing list for review.
- - A new -rc is released whenever Linus deems the current git tree to
- be in a reasonably sane state adequate for testing. The goal is to
- release a new -rc kernel every week.
- - Process continues until the kernel is considered "ready", the
- process should last around 6 weeks.
- It is worth mentioning what Andrew Morton wrote on the linux-kernel
- mailing list about kernel releases:
- *"Nobody knows when a kernel will be released, because it's
- released according to perceived bug status, not according to a
- preconceived timeline."*
- 4.x.y -stable kernel tree
- -------------------------
- Kernels with 3-part versions are -stable kernels. They contain
- relatively small and critical fixes for security problems or significant
- regressions discovered in a given 4.x kernel.
- This is the recommended branch for users who want the most recent stable
- kernel and are not interested in helping test development/experimental
- versions.
- If no 4.x.y kernel is available, then the highest numbered 4.x
- kernel is the current stable kernel.
- 4.x.y are maintained by the "stable" team <stable
- kroah.com>
|