diff options
Diffstat (limited to 'Documentation/process')
| -rw-r--r-- | Documentation/process/changes.rst | 11 | ||||
| -rw-r--r-- | Documentation/process/coding-style.rst | 23 | ||||
| -rw-r--r-- | Documentation/process/handling-regressions.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/maintainer-netdev.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/maintainer-tip.rst | 18 | ||||
| -rw-r--r-- | Documentation/process/stable-kernel-rules.rst | 236 |
6 files changed, 155 insertions, 137 deletions
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 7ef8de58f7..5685d7bfe4 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,7 +31,7 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 13.0.1 clang --version -Rust (optional) 1.76.0 rustc --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 @@ -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 9c7cf73473..7e768c65aa 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -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: diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index ce6753a674..49ba1410cf 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -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 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 497bb39727..64739968af 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -409,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. 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. |