diff options
Diffstat (limited to 'Documentation/process')
| -rw-r--r-- | Documentation/process/changes.rst | 17 | ||||
| -rw-r--r-- | Documentation/process/coding-style.rst | 36 | ||||
| -rw-r--r-- | Documentation/process/embargoed-hardware-issues.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/handling-regressions.rst | 14 | ||||
| -rw-r--r-- | Documentation/process/howto.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/maintainer-netdev.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/maintainer-tip.rst | 52 | ||||
| -rw-r--r-- | Documentation/process/researcher-guidelines.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/stable-kernel-rules.rst | 236 | ||||
| -rw-r--r-- | Documentation/process/submit-checklist.rst | 161 |
10 files changed, 295 insertions, 233 deletions
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 50b3d1cb11..5685d7bfe4 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -30,8 +30,8 @@ you probably needn't concern yourself with pcmciautils. Program Minimal version Command to check the version ====================== =============== ======================================== GNU C 5.1 gcc --version -Clang/LLVM (optional) 11.0.0 clang --version -Rust (optional) 1.74.1 rustc --version +Clang/LLVM (optional) 13.0.1 clang --version +Rust (optional) 1.78.0 rustc --version bindgen (optional) 0.65.1 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version @@ -62,6 +62,7 @@ Sphinx\ [#f1]_ 2.4.4 sphinx-build --version cpio any cpio --version GNU tar 1.28 tar --version gtags (optional) 6.6.5 gtags --version +mkimage (optional) 2017.01 mkimage --version ====================== =============== ======================================== .. [#f1] Sphinx is needed only to build the Kernel documentation @@ -144,8 +145,8 @@ Bison Since Linux 4.16, the build system generates parsers during build. This requires bison 2.0 or later. -pahole: -------- +pahole +------ Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel @@ -189,6 +190,14 @@ The kernel build requires GNU GLOBAL version 6.6.5 or later to generate tag files through ``make gtags``. This is due to its use of the gtags ``-C (--directory)`` flag. +mkimage +------- + +This tool is used when building a Flat Image Tree (FIT), commonly used on ARM +platforms. The tool is available via the ``u-boot-tools`` package or can be +built from the U-Boot source code. See the instructions at +https://docs.u-boot.org/en/latest/build/tools.html#building-tools-for-linux + System utilities **************** diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index c48382c6b4..7e768c65aa 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -203,7 +203,7 @@ Do not unnecessarily use braces where a single statement will do. and -.. code-block:: none +.. code-block:: c if (condition) do_this(); @@ -586,9 +586,9 @@ fix for this is to split it up into two error labels ``err_free_bar:`` and .. code-block:: c - err_free_bar: + err_free_bar: kfree(foo->bar); - err_free_foo: + err_free_foo: kfree(foo); return ret; @@ -660,7 +660,7 @@ make a good program). So, you can either get rid of GNU emacs, or change it to use saner values. To do the latter, you can stick the following in your .emacs file: -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -679,7 +679,7 @@ values. To do the latter, you can stick the following in your .emacs file: (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) @@ -827,6 +827,29 @@ Macros with multiple statements should be enclosed in a do - while block: do_this(b, c); \ } while (0) +Function-like macros with unused parameters should be replaced by static +inline functions to avoid the issue of unused variables: + +.. code-block:: c + + static inline void fun(struct foo *foo) + { + } + +Due to historical practices, many files still employ the "cast to (void)" +approach to evaluate parameters. However, this method is not advisable. +Inline functions address the issue of "expression with side effects +evaluated more than once", circumvent unused-variable problems, and +are generally better documented than macros for some reason. + +.. code-block:: c + + /* + * Avoid doing this whenever possible and instead opt for static + * inline functions + */ + #define macrofun(foo) do { (void) (foo); } while (0) + Things to avoid when using macros: 1) macros that affect control flow: @@ -899,7 +922,8 @@ which you should use to make sure messages are matched to the right device and driver, and are tagged with the right level: dev_err(), dev_warn(), dev_info(), and so forth. For messages that aren't associated with a particular device, <linux/printk.h> defines pr_notice(), pr_info(), -pr_warn(), pr_err(), etc. +pr_warn(), pr_err(), etc. When drivers are working properly they are quiet, +so prefer to use dev_dbg/pr_debug unless something is wrong. Coming up with good debugging messages can be quite a challenge; and once you have them, they can be a huge help for remote troubleshooting. However diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index 31000f0757..6e9a4597bf 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -252,10 +252,10 @@ an involved disclosed party. The current ambassadors list: AMD Tom Lendacky <thomas.lendacky@amd.com> Ampere Darren Hart <darren@os.amperecomputing.com> ARM Catalin Marinas <catalin.marinas@arm.com> - IBM Power Anton Blanchard <anton@linux.ibm.com> + IBM Power Michael Ellerman <ellerman@au.ibm.com> IBM Z Christian Borntraeger <borntraeger@de.ibm.com> Intel Tony Luck <tony.luck@intel.com> - Qualcomm Trilok Soni <tsoni@codeaurora.org> + Qualcomm Trilok Soni <quic_tsoni@quicinc.com> RISC-V Palmer Dabbelt <palmer@dabbelt.com> Samsung Javier González <javier.gonz@samsung.com> diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index 5d3c3de3f4..49ba1410cf 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -27,11 +27,11 @@ The important bits (aka "The TL;DR") is optional, but recommended): * For mailed reports, check if the reporter included a line like ``#regzbot - introduced v5.13..v5.14-rc1``. If not, send a reply (with the regressions + introduced: v5.13..v5.14-rc1``. If not, send a reply (with the regressions list in CC) containing a paragraph like the following, which tells regzbot when the issue started to happen:: - #regzbot ^introduced 1f2e3d4c5b6a + #regzbot ^introduced: 1f2e3d4c5b6a * When forwarding reports from a bug tracker to the regressions list (see above), include a paragraph like the following:: @@ -79,7 +79,7 @@ When doing either, consider making the Linux kernel regression tracking bot "regzbot" immediately start tracking the issue: * For mailed reports, check if the reporter included a "regzbot command" like - ``#regzbot introduced 1f2e3d4c5b6a``. If not, send a reply (with the + ``#regzbot introduced: 1f2e3d4c5b6a``. If not, send a reply (with the regressions list in CC) with a paragraph like the following::: #regzbot ^introduced: v5.13..v5.14-rc1 @@ -284,7 +284,7 @@ What else is there to known about regressions? Check out Documentation/admin-guide/reporting-regressions.rst, it covers a lot of other aspects you want might want to be aware of: - * the purpose of the "no regressions rule" + * the purpose of the "no regressions" rule * what issues actually qualify as regression @@ -398,9 +398,9 @@ By using a 'regzbot command' in a direct or indirect reply to the mail with the regression report. These commands need to be in their own paragraph (IOW: they need to be separated from the rest of the mail using blank lines). -One such command is ``#regzbot introduced <version or commit>``, which makes +One such command is ``#regzbot introduced: <version or commit>``, which makes regzbot consider your mail as a regressions report added to the tracking, as -already described above; ``#regzbot ^introduced <version or commit>`` is another +already described above; ``#regzbot ^introduced: <version or commit>`` is another such command, which makes regzbot consider the parent mail as a report for a regression which it starts to track. @@ -432,7 +432,7 @@ or itself is a reply to that mail: * Mark a regression as fixed by a commit that is heading upstream or already landed:: - #regzbot fixed-by: 1f2e3d4c5d + #regzbot fix: 1f2e3d4c5d * Mark a regression as a duplicate of another one already tracked by regzbot:: diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 6c73889c98..eebda4910a 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -351,8 +351,8 @@ Managing bug reports -------------------- One of the best ways to put into practice your hacking skills is by fixing -bugs reported by other people. Not only you will help to make the kernel -more stable, but you'll also learn to fix real world problems and you will +bugs reported by other people. Not only will you help to make the kernel +more stable, but you'll also learn to fix real-world problems and you will improve your skills, and other developers will be aware of your presence. Fixing bugs is one of the best ways to get merits among other developers, because not many people like wasting time fixing other people's bugs. diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index fd96e4a3ce..5e1fcfad1c 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -227,7 +227,7 @@ preferably including links to previous postings, for example:: The amount of mooing will depend on packet rate so should match the diurnal cycle quite well. - Signed-of-by: Joe Defarmer <joe@barn.org> + Signed-off-by: Joe Defarmer <joe@barn.org> --- v3: - add a note about time-of-day mooing fluctuation to the commit message diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 08dd0f8044..64739968af 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -304,13 +304,15 @@ following tag ordering scheme: - Reported-by: ``Reporter <reporter@mail>`` + - Closes: ``URL or Message-ID of the bug report this is fixing`` + - Originally-by: ``Original author <original-author@mail>`` - Suggested-by: ``Suggester <suggester@mail>`` - Co-developed-by: ``Co-author <co-author@mail>`` - Signed-off: ``Co-author <co-author@mail>`` + Signed-off-by: ``Co-author <co-author@mail>`` Note, that Co-developed-by and Signed-off-by of the co-author(s) must come in pairs. @@ -407,20 +409,20 @@ See :ref:`resend_reminders`. Merge window ^^^^^^^^^^^^ -Please do not expect large patch series to be handled during the merge -window or even during the week before. Such patches should be submitted in -mergeable state *at* *least* a week before the merge window opens. -Exceptions are made for bug fixes and *sometimes* for small standalone -drivers for new hardware or minimally invasive patches for hardware -enablement. +Please do not expect patches to be reviewed or merged by tip +maintainers around or during the merge window. The trees are closed +to all but urgent fixes during this time. They reopen once the merge +window closes and a new -rc1 kernel has been released. + +Large series should be submitted in mergeable state *at* *least* a week +before the merge window opens. Exceptions are made for bug fixes and +*sometimes* for small standalone drivers for new hardware or minimally +invasive patches for hardware enablement. During the merge window, the maintainers instead focus on following the upstream changes, fixing merge window fallout, collecting bug fixes, and allowing themselves a breath. Please respect that. -The release candidate -rc1 is the starting point for new patches to be -applied which are targeted for the next merge window. - So called _urgent_ branches will be merged into mainline during the stabilization phase of each release. @@ -478,7 +480,7 @@ Multi-line comments:: * Larger multi-line comments should be split into paragraphs. */ -No tail comments: +No tail comments (see below): Please refrain from using tail comments. Tail comments disturb the reading flow in almost all contexts, but especially in code:: @@ -499,6 +501,34 @@ No tail comments: /* This magic initialization needs a comment. Maybe not? */ seed = MAGIC_CONSTANT; + Use C++ style, tail comments when documenting structs in headers to + achieve a more compact layout and better readability:: + + // eax + u32 x2apic_shift : 5, // Number of bits to shift APIC ID right + // for the topology ID at the next level + : 27; // Reserved + // ebx + u32 num_processors : 16, // Number of processors at current level + : 16; // Reserved + + versus:: + + /* eax */ + /* + * Number of bits to shift APIC ID right for the topology ID + * at the next level + */ + u32 x2apic_shift : 5, + /* Reserved */ + : 27; + + /* ebx */ + /* Number of processors at current level */ + u32 num_processors : 16, + /* Reserved */ + : 16; + Comment the important things: Comments should be added where the operation is not obvious. Documenting diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst index d159cd4f5e..beb484c596 100644 --- a/Documentation/process/researcher-guidelines.rst +++ b/Documentation/process/researcher-guidelines.rst @@ -167,4 +167,4 @@ If no one can be found to internally review patches and you need help finding such a person, or if you have any other questions related to this document and the developer community's expectations, please reach out to the private Technical Advisory Board mailing list: -<tech-board@lists.linux-foundation.org>. +<tech-board@groups.linuxfoundation.org>. diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 1704f1c686..edf90bbe30 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -6,29 +6,29 @@ Everything you ever wanted to know about Linux -stable releases Rules on what kind of patches are accepted, and which ones are not, into the "-stable" tree: - - It or an equivalent fix must already exist in Linus' tree (upstream). - - It must be obviously correct and tested. - - It cannot be bigger than 100 lines, with context. - - It must follow the - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` - rules. - - It must either fix a real bug that bothers people or just add a device ID. - To elaborate on the former: - - - It fixes a problem like an oops, a hang, data corruption, a real security - issue, a hardware quirk, a build error (but not for things marked - CONFIG_BROKEN), or some "oh, that's not good" issue. - - Serious issues as reported by a user of a distribution kernel may also - be considered if they fix a notable performance or interactivity issue. - As these fixes are not as obvious and have a higher risk of a subtle - regression they should only be submitted by a distribution kernel - maintainer and include an addendum linking to a bugzilla entry if it - exists and additional information on the user-visible impact. - - No "This could be a problem..." type of things like a "theoretical race - condition", unless an explanation of how the bug can be exploited is also - provided. - - No "trivial" fixes without benefit for users (spelling changes, whitespace - cleanups, etc). +- It or an equivalent fix must already exist in Linux mainline (upstream). +- It must be obviously correct and tested. +- It cannot be bigger than 100 lines, with context. +- It must follow the + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + rules. +- It must either fix a real bug that bothers people or just add a device ID. + To elaborate on the former: + + - It fixes a problem like an oops, a hang, data corruption, a real security + issue, a hardware quirk, a build error (but not for things marked + CONFIG_BROKEN), or some "oh, that's not good" issue. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issue. + As these fixes are not as obvious and have a higher risk of a subtle + regression they should only be submitted by a distribution kernel + maintainer and include an addendum linking to a bugzilla entry if it + exists and additional information on the user-visible impact. + - No "This could be a problem..." type of things like a "theoretical race + condition", unless an explanation of how the bug can be exploited is also + provided. + - No "trivial" fixes without benefit for users (spelling changes, whitespace + cleanups, etc). Procedure for submitting patches to the -stable tree @@ -42,11 +42,11 @@ Procedure for submitting patches to the -stable tree There are three options to submit a change to -stable trees: - 1. Add a 'stable tag' to the description of a patch you then submit for - mainline inclusion. - 2. Ask the stable team to pick up a patch already mainlined. - 3. Submit a patch to the stable team that is equivalent to a change already - mainlined. +1. Add a 'stable tag' to the description of a patch you then submit for + mainline inclusion. +2. Ask the stable team to pick up a patch already mainlined. +3. Submit a patch to the stable team that is equivalent to a change already + mainlined. The sections below describe each of the options in more detail. @@ -68,82 +68,72 @@ Option 1 ******** To have a patch you submit for mainline inclusion later automatically picked up -for stable trees, add the tag +for stable trees, add this tag in the sign-off area:: -.. code-block:: none + Cc: stable@vger.kernel.org - Cc: stable@vger.kernel.org +Use ``Cc: stable@kernel.org`` instead when fixing unpublished vulnerabilities: +it reduces the chance of accidentally exposing the fix to the public by way of +'git send-email', as mails sent to that address are not delivered anywhere. -in the sign-off area. Once the patch is mainlined it will be applied to the -stable tree without anything else needing to be done by the author or -subsystem maintainer. +Once the patch is mainlined it will be applied to the stable tree without +anything else needing to be done by the author or subsystem maintainer. -To sent additional instructions to the stable team, use a shell-style inline -comment: +To send additional instructions to the stable team, use a shell-style inline +comment to pass arbitrary or predefined notes: - * To specify any additional patch prerequisites for cherry picking use the - following format in the sign-off area: +* Specify any additional patch prerequisites for cherry picking:: - .. code-block:: none + Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle + Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle + Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic + Cc: <stable@vger.kernel.org> # 3.3.x + Signed-off-by: Ingo Molnar <mingo@elte.hu> - Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle - Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle - Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic - Cc: <stable@vger.kernel.org> # 3.3.x - Signed-off-by: Ingo Molnar <mingo@elte.hu> + The tag sequence has the meaning of:: - The tag sequence has the meaning of: + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick <this commit> - .. code-block:: none + Note that for a patch series, you do not have to list as prerequisites the + patches present in the series itself. For example, if you have the following + patch series:: - git cherry-pick a1f84a3 - git cherry-pick 1b9508f - git cherry-pick fd21073 - git cherry-pick <this commit> + patch1 + patch2 - Note that for a patch series, you do not have to list as prerequisites the - patches present in the series itself. For example, if you have the following - patch series: + where patch2 depends on patch1, you do not have to list patch1 as + prerequisite of patch2 if you have already marked patch1 for stable + inclusion. - .. code-block:: none +* Point out kernel version prerequisites:: - patch1 - patch2 + Cc: <stable@vger.kernel.org> # 3.3.x - where patch2 depends on patch1, you do not have to list patch1 as - prerequisite of patch2 if you have already marked patch1 for stable - inclusion. + The tag has the meaning of:: - * For patches that may have kernel version prerequisites specify them using - the following format in the sign-off area: + git cherry-pick <this commit> - .. code-block:: none + For each "-stable" tree starting with the specified version. - Cc: <stable@vger.kernel.org> # 3.3.x + Note, such tagging is unnecessary if the stable team can derive the + appropriate versions from Fixes: tags. - The tag has the meaning of: +* Delay pick up of patches:: - .. code-block:: none + Cc: <stable@vger.kernel.org> # after -rc3 - git cherry-pick <this commit> +* Point out known problems:: - For each "-stable" tree starting with the specified version. + Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3 - Note, such tagging is unnecessary if the stable team can derive the - appropriate versions from Fixes: tags. +There furthermore is a variant of the stable tag you can use to make the stable +team's backporting tools (e.g AUTOSEL or scripts that look for commits +containing a 'Fixes:' tag) ignore a change:: - * To delay pick up of patches, use the following format: - - .. code-block:: none - - Cc: <stable@vger.kernel.org> # after 4 weeks in mainline - - * For any other requests, just add a note to the stable tag. This for example - can be used to point out known problems: - - .. code-block:: none - - Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3 + Cc: <stable+noautosel@kernel.org> # reason goes here, and must be present .. _option_2: @@ -163,17 +153,13 @@ Option 3 Send the patch, after verifying that it follows the above rules, to stable@vger.kernel.org and mention the kernel versions you wish it to be applied to. When doing so, you must note the upstream commit ID in the changelog of your -submission with a separate line above the commit text, like this: - -.. code-block:: none - - commit <sha1> upstream. +submission with a separate line above the commit text, like this:: -or alternatively: + commit <sha1> upstream. -.. code-block:: none +Or alternatively:: - [ Upstream commit <sha1> ] + [ Upstream commit <sha1> ] If the submitted patch deviates from the original upstream patch (for example because it had to be adjusted for the older API), this must be very clearly @@ -194,55 +180,55 @@ developers and by the relevant subsystem maintainer. Review cycle ------------ - - When the -stable maintainers decide for a review cycle, the patches will be - sent to the review committee, and the maintainer of the affected area of - the patch (unless the submitter is the maintainer of the area) and CC: to - the linux-kernel mailing list. - - The review committee has 48 hours in which to ACK or NAK the patch. - - If the patch is rejected by a member of the committee, or linux-kernel - members object to the patch, bringing up issues that the maintainers and - members did not realize, the patch will be dropped from the queue. - - The ACKed patches will be posted again as part of release candidate (-rc) - to be tested by developers and testers. - - Usually only one -rc release is made, however if there are any outstanding - issues, some patches may be modified or dropped or additional patches may - be queued. Additional -rc releases are then released and tested until no - issues are found. - - Responding to the -rc releases can be done on the mailing list by sending - a "Tested-by:" email with any testing information desired. The "Tested-by:" - tags will be collected and added to the release commit. - - At the end of the review cycle, the new -stable release will be released - containing all the queued and tested patches. - - Security patches will be accepted into the -stable tree directly from the - security kernel team, and not go through the normal review cycle. - Contact the kernel security team for more details on this procedure. +- When the -stable maintainers decide for a review cycle, the patches will be + sent to the review committee, and the maintainer of the affected area of + the patch (unless the submitter is the maintainer of the area) and CC: to + the linux-kernel mailing list. +- The review committee has 48 hours in which to ACK or NAK the patch. +- If the patch is rejected by a member of the committee, or linux-kernel + members object to the patch, bringing up issues that the maintainers and + members did not realize, the patch will be dropped from the queue. +- The ACKed patches will be posted again as part of release candidate (-rc) + to be tested by developers and testers. +- Usually only one -rc release is made, however if there are any outstanding + issues, some patches may be modified or dropped or additional patches may + be queued. Additional -rc releases are then released and tested until no + issues are found. +- Responding to the -rc releases can be done on the mailing list by sending + a "Tested-by:" email with any testing information desired. The "Tested-by:" + tags will be collected and added to the release commit. +- At the end of the review cycle, the new -stable release will be released + containing all the queued and tested patches. +- Security patches will be accepted into the -stable tree directly from the + security kernel team, and not go through the normal review cycle. + Contact the kernel security team for more details on this procedure. Trees ----- - - The queues of patches, for both completed versions and in progress - versions can be found at: +- The queues of patches, for both completed versions and in progress + versions can be found at: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git + https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git - - The finalized and tagged releases of all stable kernels can be found - in separate branches per version at: +- The finalized and tagged releases of all stable kernels can be found + in separate branches per version at: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git - - The release candidate of all stable kernel versions can be found at: +- The release candidate of all stable kernel versions can be found at: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ - .. warning:: - The -stable-rc tree is a snapshot in time of the stable-queue tree and - will change frequently, hence will be rebased often. It should only be - used for testing purposes (e.g. to be consumed by CI systems). + .. warning:: + The -stable-rc tree is a snapshot in time of the stable-queue tree and + will change frequently, hence will be rebased often. It should only be + used for testing purposes (e.g. to be consumed by CI systems). Review committee ---------------- - - This is made up of a number of kernel developers who have volunteered for - this task, and a few that haven't. +- This is made up of a number of kernel developers who have volunteered for + this task, and a few that haven't. diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index b1bc2d37bd..e531dd504b 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -1,7 +1,8 @@ .. _submitchecklist: +======================================= Linux Kernel patch submission checklist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +======================================= Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. @@ -10,111 +11,123 @@ These are all above and beyond the documentation that is provided in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and elsewhere regarding submitting Linux kernel patches. +Review your code +================ 1) If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones that you use. -2) Builds cleanly: +2) Check your patch for general style as detailed in + :ref:`Documentation/process/coding-style.rst <codingstyle>`. - a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and - ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. +3) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a + comment in the source code that explains the logic of what they are doing + and why. - b) Passes ``allnoconfig``, ``allmodconfig`` +Review Kconfig changes +====================== - c) Builds successfully when using ``O=builddir`` +1) Any new or modified ``CONFIG`` options do not muck up the config menu and + default to off unless they meet the exception criteria documented in + ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. - d) Any Documentation/ changes build successfully without new warnings/errors. - Use ``make htmldocs`` or ``make pdfdocs`` to check the build and - fix any issues. +2) All new ``Kconfig`` options have help text. -3) Builds on multiple CPU architectures by using local cross-compile tools - or some other build farm. +3) Has been carefully reviewed with respect to relevant ``Kconfig`` + combinations. This is very hard to get right with testing---brainpower + pays off here. -4) ppc64 is a good architecture for cross-compilation checking because it - tends to use ``unsigned long`` for 64-bit quantities. +Provide documentation +===================== -5) Check your patch for general style as detailed in - :ref:`Documentation/process/coding-style.rst <codingstyle>`. - Check for trivial violations with the patch style checker prior to - submission (``scripts/checkpatch.pl``). - You should be able to justify all violations that remain in - your patch. +1) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs. + (Not required for static functions, but OK there also.) -6) Any new or modified ``CONFIG`` options do not muck up the config menu and - default to off unless they meet the exception criteria documented in - ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. +2) All new ``/proc`` entries are documented under ``Documentation/`` -7) All new ``Kconfig`` options have help text. +3) All new kernel boot parameters are documented in + ``Documentation/admin-guide/kernel-parameters.rst``. -8) Has been carefully reviewed with respect to relevant ``Kconfig`` - combinations. This is very hard to get right with testing -- brainpower - pays off here. +4) All new module parameters are documented with ``MODULE_PARM_DESC()`` -9) Check cleanly with sparse. +5) All new userspace interfaces are documented in ``Documentation/ABI/``. + See ``Documentation/ABI/README`` for more information. + Patches that change userspace interfaces should be CCed to + linux-api@vger.kernel.org. -10) Use ``make checkstack`` and fix any problems that it finds. +6) If any ioctl's are added by the patch, then also update + ``Documentation/userspace-api/ioctl/ioctl-number.rst``. - .. note:: +Check your code with tools +========================== - ``checkstack`` does not point out problems explicitly, - but any one function that uses more than 512 bytes on the stack is a - candidate for change. +1) Check for trivial violations with the patch style checker prior to + submission (``scripts/checkpatch.pl``). + You should be able to justify all violations that remain in + your patch. -11) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs. - (Not required for static functions, but OK there also.) Use - ``make htmldocs`` or ``make pdfdocs`` to check the - :ref:`kernel-doc <kernel_doc>` and fix any issues. +2) Check cleanly with sparse. -12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, - ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, - ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all - simultaneously enabled. +3) Use ``make checkstack`` and fix any problems that it finds. + Note that ``checkstack`` does not point out problems explicitly, + but any one function that uses more than 512 bytes on the stack is a + candidate for change. -13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and - ``CONFIG_PREEMPT.`` +Build your code +=============== -14) All codepaths have been exercised with all lockdep features enabled. +1) Builds cleanly: -15) All new ``/proc`` entries are documented under ``Documentation/`` + a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and + ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. -16) All new kernel boot parameters are documented in - ``Documentation/admin-guide/kernel-parameters.rst``. + b) Passes ``allnoconfig``, ``allmodconfig`` + + c) Builds successfully when using ``O=builddir`` + + d) Any Documentation/ changes build successfully without new warnings/errors. + Use ``make htmldocs`` or ``make pdfdocs`` to check the build and + fix any issues. -17) All new module parameters are documented with ``MODULE_PARM_DESC()`` +2) Builds on multiple CPU architectures by using local cross-compile tools + or some other build farm. Note that ppc64 is a good architecture for + cross-compilation checking because it tends to use ``unsigned long`` for + 64-bit quantities. -18) All new userspace interfaces are documented in ``Documentation/ABI/``. - See ``Documentation/ABI/README`` for more information. - Patches that change userspace interfaces should be CCed to - linux-api@vger.kernel.org. +3) Newly-added code has been compiled with ``gcc -W`` (use + ``make KCFLAGS=-W``). This will generate lots of noise, but is good + for finding bugs like "warning: comparison between signed and unsigned". -19) Has been checked with injection of at least slab and page-allocation - failures. See ``Documentation/fault-injection/``. +4) If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following ``Kconfig`` symbols, + then test multiple builds with the related ``Kconfig`` symbols disabled + and/or ``=m`` (if that option is available) [not all of these at the + same time, just various/random combinations of them]: - If the new code is substantial, addition of subsystem-specific fault - injection might be appropriate. + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). -20) Newly-added code has been compiled with ``gcc -W`` (use - ``make KCFLAGS=-W``). This will generate lots of noise, but is good - for finding bugs like "warning: comparison between signed and unsigned". +Test your code +============== -21) Tested after it has been merged into the -mm patchset to make sure - that it still works with all of the other queued patches and various - changes in the VM, VFS, and other subsystems. +1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all + simultaneously enabled. -22) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a - comment in the source code that explains the logic of what they are doing - and why. +2) Has been build- and runtime tested with and without ``CONFIG_SMP`` and + ``CONFIG_PREEMPT.`` -23) If any ioctl's are added by the patch, then also update - ``Documentation/userspace-api/ioctl/ioctl-number.rst``. +3) All codepaths have been exercised with all lockdep features enabled. -24) If your modified source code depends on or uses any of the kernel - APIs or features that are related to the following ``Kconfig`` symbols, - then test multiple builds with the related ``Kconfig`` symbols disabled - and/or ``=m`` (if that option is available) [not all of these at the - same time, just various/random combinations of them]: +4) Has been checked with injection of at least slab and page-allocation + failures. See ``Documentation/fault-injection/``. + If the new code is substantial, addition of subsystem-specific fault + injection might be appropriate. - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). +5) Tested with the most recent tag of linux-next to make sure that it still + works with all of the other queued patches and various changes in the VM, + VFS, and other subsystems. |