diff options
Diffstat (limited to 'Documentation/process')
35 files changed, 1675 insertions, 569 deletions
diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst index c3d0270bbfb3..2c93caea069f 100644 --- a/Documentation/process/1.Intro.rst +++ b/Documentation/process/1.Intro.rst @@ -194,7 +194,7 @@ include: are cloudy at best; quite a few kernel copyright holders believe that most binary-only modules are derived products of the kernel and that, as a result, their distribution is a violation of the GNU General Public - license (about which more will be said below). Your author is not a + License (about which more will be said below). Your author is not a lawyer, and nothing in this document can possibly be considered to be legal advice. The true legal status of closed-source modules can only be determined by the courts. But the uncertainty which haunts those modules @@ -251,12 +251,12 @@ there is no prospect of a migration to version 3 of the GPL in the foreseeable future. It is imperative that all code contributed to the kernel be legitimately -free software. For that reason, code from anonymous (or pseudonymous) -contributors will not be accepted. All contributors are required to "sign -off" on their code, stating that the code can be distributed with the -kernel under the GPL. Code which has not been licensed as free software by -its owner, or which risks creating copyright-related problems for the -kernel (such as code which derives from reverse-engineering efforts lacking +free software. For that reason, code from contributors without a known +identity or anonymous contributors will not be accepted. All contributors are +required to "sign off" on their code, stating that the code can be distributed +with the kernel under the GPL. Code which has not been licensed as free +software by its owner, or which risks creating copyright-related problems for +the kernel (such as code which derives from reverse-engineering efforts lacking proper safeguards) cannot be contributed. Questions about copyright-related issues are common on Linux development diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index ef3b116492df..77f3f80e7cd7 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -3,7 +3,7 @@ How the development process works ================================= -Linux kernel development in the early 1990's was a pretty loose affair, +Linux kernel development in the early 1990s was a pretty loose affair, with relatively small numbers of users and developers involved. With a user base in the millions and with some 2,000 developers involved over the course of one year, the kernel has since had to evolve a number of @@ -13,24 +13,19 @@ how the process works is required in order to be an effective part of it. The big picture --------------- -The kernel developers use a loosely time-based release process, with a new -major kernel release happening every two or three months. The recent -release history looks like this: - - ====== ================= - 5.0 March 3, 2019 - 5.1 May 5, 2019 - 5.2 July 7, 2019 - 5.3 September 15, 2019 - 5.4 November 24, 2019 - 5.5 January 6, 2020 - ====== ================= - -Every 5.x release is a major kernel release with new features, internal -API changes, and more. A typical release can contain about 13,000 -changesets with changes to several hundred thousand lines of code. 5.x is -the leading edge of Linux kernel development; the kernel uses a -rolling development model which is continually integrating major changes. +The Linux kernel uses a loosely time-based, rolling release development +model. A new major kernel release (which we will call, as an example, 9.x) +[1]_ happens every two or three months, which comes with new features, +internal API changes, and more. A typical release can contain about 13,000 +changesets with changes to several hundred thousand lines of code. Recent +releases, along with their dates, can be found at `Wikipedia +<https://en.wikipedia.org/wiki/Linux_kernel_version_history>`_. + +.. [1] Strictly speaking, the Linux kernel does not use semantic versioning + number scheme, but rather the 9.x pair identifies major release + version as a whole number. For each release, x is incremented, + but 9 is incremented only if x is deemed large enough (e.g. + Linux 5.0 is released following Linux 4.20). A relatively straightforward discipline is followed with regard to the merging of patches for each release. At the beginning of each development @@ -48,9 +43,9 @@ detail later on). The merge window lasts for approximately two weeks. At the end of this time, Linus Torvalds will declare that the window is closed and release the -first of the "rc" kernels. For the kernel which is destined to be 5.6, +first of the "rc" kernels. For the kernel which is destined to be 9.x, for example, the release which happens at the end of the merge window will -be called 5.6-rc1. The -rc1 release is the signal that the time to +be called 9.x-rc1. The -rc1 release is the signal that the time to merge new features has passed, and that the time to stabilize the next kernel has begun. @@ -99,13 +94,15 @@ release is made. In the real world, this kind of perfection is hard to achieve; there are just too many variables in a project of this size. There comes a point where delaying the final release just makes the problem worse; the pile of changes waiting for the next merge window will grow -larger, creating even more regressions the next time around. So most 5.x -kernels go out with a handful of known regressions though, hopefully, none -of them are serious. +larger, creating even more regressions the next time around. So most kernels +go out with a handful of known regressions, though, hopefully, none of them +are serious. Once a stable release is made, its ongoing maintenance is passed off to the -"stable team," currently Greg Kroah-Hartman. The stable team will release -occasional updates to the stable release using the 5.x.y numbering scheme. +"stable team," currently consists of Greg Kroah-Hartman and Sasha Levin. The +stable team will release occasional updates to the stable release using the +9.x.y numbering scheme. + To be considered for an update release, a patch must (1) fix a significant bug, and (2) already be merged into the mainline for the next development kernel. Kernels will typically receive stable updates for a little more @@ -294,7 +291,7 @@ Use of the MMOTM tree is likely to be a frustrating experience, though; there is a definite chance that it will not even compile. The primary tree for next-cycle patch merging is linux-next, maintained by -Stephen Rothwell. The linux-next tree is, by design, a snapshot of what +Mark Brown. The linux-next tree is, by design, a snapshot of what the mainline is expected to look like after the next merge window closes. Linux-next trees are announced on the linux-kernel and linux-next mailing lists when they are assembled; they can be downloaded from: diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 80bcc1cabc23..c0f57d0c4f73 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -160,12 +160,12 @@ irrelevant. Locking ******* -In May, 2006, the "Devicescape" networking stack was, with great +In May 2006, the "Devicescape" networking stack was, with great fanfare, released under the GPL and made available for inclusion in the mainline kernel. This donation was welcome news; support for wireless networking in Linux was considered substandard at best, and the Devicescape stack offered the promise of fixing that situation. Yet, this code did not -actually make it into the mainline until June, 2007 (2.6.22). What +actually make it into the mainline until June 2007 (2.6.22). What happened? This code showed a number of signs of having been developed behind @@ -204,7 +204,7 @@ regression in the first place. It is often argued that a regression can be justified if it causes things to work for more people than it creates problems for. Why not make a change if it brings new functionality to ten systems for each one it -breaks? The best answer to this question was expressed by Linus in July, +breaks? The best answer to this question was expressed by Linus in July 2007: :: diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index dbb763a8de90..07d7dbed13ec 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -40,7 +40,12 @@ sending patches to the development community. These include: - Test the code to the extent that you can. Make use of the kernel's debugging tools, ensure that the kernel will build with all reasonable combinations of configuration options, use cross-compilers to build for - different architectures, etc. + different architectures, etc. Add tests, likely using an existing + testing framework like KUnit, and include them as a separate member + of your series (see the next section for more about patch series). + Note that this may be mandatory when affecting some subsystems. For + example, library functions (resides under lib/) are extensively used + almost everywhere and expected to be tested appropriately. - Make sure your code is compliant with the kernel coding style guidelines. @@ -207,10 +212,9 @@ document with a specification implemented by the patch:: Link: https://example.com/somewhere.html optional-other-stuff -Many maintainers when applying a patch also add this tag to link to the -latest public review posting of the patch; often this is automatically done -by tools like b4 or a git hook like the one described in -'Documentation/maintainer/configure-git.rst'. +As per guidance from the Chief Penguin, a Link: tag should only be added to +a commit if it leads to useful information that is not found in the commit +itself. If the URL points to a public bug report being fixed by the patch, use the "Closes:" tag instead:: @@ -268,10 +272,15 @@ The tags in common use are: - Cc: the named person received a copy of the patch and had the opportunity to comment on it. -Be careful in the addition of tags to your patches, as only Cc: is appropriate -for addition without the explicit permission of the person named; using -Reported-by: is fine most of the time as well, but ask for permission if -the bug was reported in private. +Be careful in the addition of the aforementioned tags to your patches, as all +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the +person named. For those three implicit permission is sufficient if the person +contributed to the Linux kernel using that name and email address according +to the lore archives or the commit history -- and in case of Reported-by: +and Suggested-by: did the reporting or suggestion in public. Note, +bugzilla.kernel.org is a public place in this sense, but email addresses +used there are private; so do not expose them in tags, unless the person +used them in earlier contributions. Sending the patch diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst index 43291704338e..185651d87f2a 100644 --- a/Documentation/process/7.AdvancedTopics.rst +++ b/Documentation/process/7.AdvancedTopics.rst @@ -53,7 +53,7 @@ When you are ready to start putting up git trees for others to look at, you will, of course, need a server that can be pulled from. Setting up such a server with git-daemon is relatively straightforward if you have a system which is accessible to the Internet. Otherwise, free, public hosting sites -(Github, for example) are starting to appear on the net. Established +(GitHub, for example) are starting to appear on the net. Established developers can get an account on kernel.org, but those are not easy to come by; see https://kernel.org/faq/ for more information. diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index 906c47f1a9e5..91fc88681b1e 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -111,13 +111,13 @@ should use a file descriptor as the handle for that object -- don't invent a new type of userspace object handle when the kernel already has mechanisms and well-defined semantics for using file descriptors. -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, +If your new xyzzy(2) system call does return a new file descriptor, then the flags argument should include a value that is equivalent to setting ``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close the timing window between ``xyzzy()`` and calling ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and ``execve()`` in another thread could leak a descriptor to -the exec'ed program. (However, resist the temptation to re-use the actual value +the exec'ed program. (However, resist the temptation to reuse the actual value of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a numbering space of ``O_*`` flags that is fairly full.) @@ -127,18 +127,18 @@ descriptor. Making a file descriptor ready for reading or writing is the normal way for the kernel to indicate to userspace that an event has occurred on the corresponding kernel object. -If your new :manpage:`xyzzy(2)` system call involves a filename argument:: +If your new xyzzy(2) system call involves a filename argument:: int sys_xyzzy(const char __user *path, ..., unsigned int flags); -you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: +you should also consider whether an xyzzyat(2) version is more appropriate:: int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); This allows more flexibility for how userspace specifies the file in question; in particular it allows userspace to request the functionality for an already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively -giving an :manpage:`fxyzzy(3)` operation for free:: +giving an fxyzzy(3) operation for free:: - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) @@ -147,11 +147,11 @@ giving an :manpage:`fxyzzy(3)` operation for free:: :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the :manpage:`fstatat(2)` man page.) -If your new :manpage:`xyzzy(2)` system call involves a parameter describing an +If your new xyzzy(2) system call involves a parameter describing an offset within a file, make its type ``loff_t`` so that 64-bit offsets can be supported even on 32-bit architectures. -If your new :manpage:`xyzzy(2)` system call involves privileged functionality, +If your new xyzzy(2) system call involves privileged functionality, it needs to be governed by the appropriate Linux capability bit (checked with a call to ``capable()``), as described in the :manpage:`capabilities(7)` man page. Choose an existing capability bit that governs related functionality, @@ -160,7 +160,7 @@ under the same bit, as this goes against capabilities' purpose of splitting the power of root. In particular, avoid adding new uses of the already overly-general ``CAP_SYS_ADMIN`` capability. -If your new :manpage:`xyzzy(2)` system call manipulates a process other than +If your new xyzzy(2) system call manipulates a process other than the calling process, it should be restricted (using a call to ``ptrace_may_access()``) so that only a calling process with the same permissions as the target process, or with the necessary capabilities, can @@ -196,7 +196,7 @@ be cc'ed to linux-api@vger.kernel.org. Generic System Call Implementation ---------------------------------- -The main entry point for your new :manpage:`xyzzy(2)` system call will be called +The main entry point for your new xyzzy(2) system call will be called ``sys_xyzzy()``, but you add this entry point with the appropriate ``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the number of arguments to the system call, and the macro takes the system call name @@ -248,6 +248,52 @@ To summarize, you need a commit that includes: - fallback stub in ``kernel/sys_ni.c`` +.. _syscall_generic_6_11: + +Since 6.11 +~~~~~~~~~~ + +Starting with kernel version 6.11, general system call implementation for the +following architectures no longer requires modifications to +``include/uapi/asm-generic/unistd.h``: + + - arc + - arm64 + - csky + - hexagon + - loongarch + - nios2 + - openrisc + - riscv + +Instead, you need to update ``scripts/syscall.tbl`` and, if applicable, adjust +``arch/*/kernel/Makefile.syscalls``. + +As ``scripts/syscall.tbl`` serves as a common syscall table across multiple +architectures, a new entry is required in this table:: + + 468 common xyzzy sys_xyzzy + +Note that adding an entry to ``scripts/syscall.tbl`` with the "common" ABI +also affects all architectures that share this table. For more limited or +architecture-specific changes, consider using an architecture-specific ABI or +defining a new one. + +If a new ABI, say ``xyz``, is introduced, the corresponding updates should be +made to ``arch/*/kernel/Makefile.syscalls`` as well:: + + syscall_abis_{32,64} += xyz (...) + +To summarize, you need a commit that includes: + + - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` + - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point + - corresponding prototype in ``include/linux/syscalls.h`` + - new entry in ``scripts/syscall.tbl`` + - (if needed) Makefile updates in ``arch/*/kernel/Makefile.syscalls`` + - fallback stub in ``kernel/sys_ni.c`` + + x86 System Call Implementation ------------------------------ @@ -353,6 +399,41 @@ To summarize, you need: ``include/uapi/asm-generic/unistd.h`` +Since 6.11 +~~~~~~~~~~ + +This applies to all the architectures listed in :ref:`Since 6.11<syscall_generic_6_11>` +under "Generic System Call Implementation", except arm64. See +:ref:`Compatibility System Calls (arm64)<compat_arm64>` for more information. + +You need to extend the entry in ``scripts/syscall.tbl`` with an extra column +to indicate that a 32-bit userspace program running on a 64-bit kernel should +hit the compat entry point:: + + 468 common xyzzy sys_xyzzy compat_sys_xyzzy + +To summarize, you need: + + - ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point + - corresponding prototype in ``include/linux/compat.h`` + - modification of the entry in ``scripts/syscall.tbl`` to include an extra + "compat" column + - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` + + +.. _compat_arm64: + +Compatibility System Calls (arm64) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On arm64, there is a dedicated syscall table for compatibility system calls +targeting 32-bit (AArch32) userspace: ``arch/arm64/tools/syscall_32.tbl``. +You need to add an additional line to this table specifying the compat +entry point:: + + 468 common xyzzy sys_xyzzy compat_sys_xyzzy + + Compatibility System Calls (x86) -------------------------------- @@ -378,7 +459,7 @@ the compatibility wrapper:: ... 555 x32 xyzzy __x32_compat_sys_xyzzy -If no pointers are involved, then it is preferable to re-use the 64-bit system +If no pointers are involved, then it is preferable to reuse the 64-bit system call for the x32 ABI (and consequently the entry in arch/x86/entry/syscalls/syscall_64.tbl is unchanged). @@ -575,3 +656,6 @@ References and Sources - Recommendation from Linus Torvalds that x32 system calls should prefer compatibility with 64-bit versions rather than 32-bit versions: https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com + - Patch series revising system call table infrastructure to use + scripts/syscall.tbl across multiple architectures: + https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.org diff --git a/Documentation/process/backporting.rst b/Documentation/process/backporting.rst index c42779fbcd33..0de9eacd46a7 100644 --- a/Documentation/process/backporting.rst +++ b/Documentation/process/backporting.rst @@ -432,7 +432,7 @@ The same goes for added ``return``, ``break``, and ``continue`` statements. Error handling is typically located at the bottom of the function, so it -may not be part of the conflict even though could have been changed by +may not be part of the conflict even though it could have been changed by other patches. A good way to ensure that you review the error paths is to always use diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index a0beca805362..9a99037270ff 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -19,51 +19,52 @@ Current Minimal Requirements Upgrade to at **least** these software revisions before thinking you've encountered a bug! If you're unsure what version you're currently -running, the suggested command should tell you. +running, the suggested command should tell you. For a list of the programs +on your system including their version execute ./scripts/ver_linux Again, keep in mind that this list assumes you are already functionally running a Linux kernel. Also, not all tools are necessary on all systems; obviously, if you don't have any PC Card hardware, for example, -you probably needn't concern yourself with pcmciautils. +you probably do not need to concern yourself with pcmciautils. ====================== =============== ======================================== Program Minimal version Command to check the version ====================== =============== ======================================== -GNU C 5.1 gcc --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 4.0 make --version bash 4.2 bash --version -binutils 2.25 ld -v -flex 2.5.35 flex --version +bc 1.06.95 bc --version +bindgen (optional) 0.71.1 bindgen --version +binutils 2.30 ld -v bison 2.0 bison --version -pahole 1.16 pahole --version -util-linux 2.10o mount --version -kmod 13 depmod -V +btrfs-progs 0.18 btrfs --version +Clang/LLVM (optional) 15.0.0 clang --version e2fsprogs 1.41.4 e2fsck -V +flex 2.5.35 flex --version +gdb 7.2 gdb --version +GNU awk (optional) 5.1.0 gawk --version +GNU C 8.1 gcc --version +GNU make 4.0 make --version +GNU tar 1.28 tar --version +GRUB 0.93 grub --version || grub-install --version +gtags (optional) 6.6.5 gtags --version +iptables 1.4.2 iptables -V jfsutils 1.1.3 fsck.jfs -V -reiserfsprogs 3.6.3 reiserfsck -V -xfsprogs 2.6.0 xfs_db -V -squashfs-tools 4.0 mksquashfs -version -btrfs-progs 0.18 btrfs --version +kmod 13 kmod -V +mcelog 0.6 mcelog --version +mkimage (optional) 2017.01 mkimage --version +nfs-utils 1.0.5 showmount --version +openssl & libcrypto 1.0.0 openssl version +pahole 1.22 pahole --version pcmciautils 004 pccardctl -V -quota-tools 3.09 quota -V PPP 2.4.0 pppd --version -nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version -udev 081 udevd --version -grub 0.93 grub --version || grub-install --version -mcelog 0.6 mcelog --version -iptables 1.4.2 iptables -V -openssl & libcrypto 1.0.0 openssl version -bc 1.06.95 bc --version -Sphinx\ [#f1]_ 2.4.4 sphinx-build --version -GNU tar 1.28 tar --version -gtags (optional) 6.6.5 gtags --version -mkimage (optional) 2017.01 mkimage --version -Python (optional) 3.5.x python3 --version -GNU AWK (optional) 5.1.0 gawk --version +Python 3.9.x python3 --version +quota-tools 3.09 quota -V +Rust (optional) 1.85.0 rustc --version +Sphinx\ [#f1]_ 3.4.3 sphinx-build --version +squashfs-tools 4.0 mksquashfs -version +udev 081 udevadm --version +util-linux 2.10o mount --version +xfsprogs 2.6.0 xfs_db -V ====================== =============== ======================================== .. [#f1] Sphinx is needed only to build the Kernel documentation @@ -116,7 +117,7 @@ Bash 4.2 or newer is needed. Binutils -------- -Binutils 2.25 or newer is needed to build the kernel. +Binutils 2.30 or newer is needed to build the kernel. pkg-config ---------- @@ -144,7 +145,7 @@ 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 -modules as well. This requires pahole v1.16 or later. +modules as well. This requires pahole v1.22 or later. It is found in the 'dwarves' or 'pahole' distro packages or from https://fedorapeople.org/~acme/dwarves/. @@ -155,6 +156,13 @@ Perl You will need perl 5 and the following modules: ``Getopt::Long``, ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. +Python +------ + +Several config options require it: it is required for arm/arm64 +default configs, CONFIG_LTO_CLANG, some DRM optional configs, +the kernel-doc tool, and docs build (Sphinx), among others. + BC -- @@ -212,7 +220,7 @@ DevFS has been obsoleted in favour of udev Linux documentation for functions is transitioning to inline documentation via specially-formatted comments near their definitions in the source. These comments can be combined with ReST -files the Documentation/ directory to make enriched documentation, which can +files in the Documentation/ directory to make enriched documentation, which can then be converted to PostScript, HTML, LaTex, ePUB and PDF files. In order to convert from ReST format to a format of your choice, you'll need Sphinx. @@ -262,14 +270,6 @@ The following utilities are available: - other file system utilities are also available in this package. -Reiserfsprogs -------------- - -The reiserfsprogs package should be used for reiserfs-3.6.x -(Linux kernels 2.4.x). It is a combined package and contains working -versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and -``reiserfsck``. These utils work on both i386 and alpha platforms. - Xfsprogs -------- @@ -393,7 +393,7 @@ Kernel documentation Sphinx ------ -Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>` +Please see :ref:`sphinx_install` in Documentation/doc-guide/sphinx.rst for details about Sphinx requirements. rustdoc @@ -493,11 +493,6 @@ JFSutils - <https://jfs.sourceforge.net/> -Reiserfsprogs -------------- - -- <https://git.kernel.org/pub/scm/linux/kernel/git/jeffm/reiserfsprogs.git/> - Xfsprogs -------- diff --git a/Documentation/process/code-of-conduct-interpretation.rst b/Documentation/process/code-of-conduct-interpretation.rst index 1d1150954be3..4cdef8360698 100644 --- a/Documentation/process/code-of-conduct-interpretation.rst +++ b/Documentation/process/code-of-conduct-interpretation.rst @@ -145,13 +145,16 @@ kernel community. Any decisions regarding enforcement recommendations will be brought to the TAB for implementation of enforcement with the relevant maintainers -if needed. A decision by the Code of Conduct Committee can be overturned -by the TAB by a two-thirds vote. +if needed. Once the TAB approves one or more of the measures outlined +in the scope of the ban by two-thirds of the members voting for the +measures, the Code of Conduct Committee will enforce the TAB approved +measures. Any Code of Conduct Committee members serving on the TAB will +not vote on the measures. At quarterly intervals, the Code of Conduct Committee and TAB will provide a report summarizing the anonymised reports that the Code of Conduct committee has received and their status, as well details of any -overridden decisions including complete and identifiable voting details. +TAB approved decisions including complete and identifiable voting details. Because how we interpret and enforce the Code of Conduct will evolve over time, this document will be updated when necessary to reflect any @@ -227,9 +230,11 @@ The scope of the ban for a period of time could include: such as mailing lists and social media sites Once the TAB approves one or more of the measures outlined in the scope of -the ban by a two-thirds vote, the Code of Conduct Committee will enforce -the TAB approved measure(s) in collaboration with the community, maintainers, -sub-maintainers, and kernel.org administrators. +the ban by two-thirds of the members voting for the measures, the Code of +Conduct Committee will enforce the TAB approved measure(s) in collaboration +with the community, maintainers, sub-maintainers, and kernel.org +administrators. Any Code of Conduct Committee members serving on the TAB +will not vote on the measures. The Code of Conduct Committee is mindful of the negative impact of seeking public apology and instituting ban could have on individuals. It is also diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst new file mode 100644 index 000000000000..899f4459c52d --- /dev/null +++ b/Documentation/process/coding-assistants.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _coding_assistants: + +AI Coding Assistants +++++++++++++++++++++ + +This document provides guidance for AI tools and developers using AI +assistance when contributing to the Linux kernel. + +AI tools helping with Linux kernel development should follow the standard +kernel development process: + +* Documentation/process/development-process.rst +* Documentation/process/coding-style.rst +* Documentation/process/submitting-patches.rst + +Licensing and Legal Requirements +================================ + +All contributions must comply with the kernel's licensing requirements: + +* All code must be compatible with GPL-2.0-only +* Use appropriate SPDX license identifiers +* See Documentation/process/license-rules.rst for details + +Signed-off-by and Developer Certificate of Origin +================================================= + +AI agents MUST NOT add Signed-off-by tags. Only humans can legally +certify the Developer Certificate of Origin (DCO). The human submitter +is responsible for: + +* Reviewing all AI-generated code +* Ensuring compliance with licensing requirements +* Adding their own Signed-off-by tag to certify the DCO +* Taking full responsibility for the contribution + +Attribution +=========== + +When AI tools contribute to kernel development, proper attribution +helps track the evolving role of AI in the development process. +Contributions should include an Assisted-by tag in the following format:: + + Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2] + +Where: + +* ``AGENT_NAME`` is the name of the AI tool or framework +* ``MODEL_VERSION`` is the specific model version used +* ``[TOOL1] [TOOL2]`` are optional specialized analysis tools used + (e.g., coccinelle, sparse, smatch, clang-tidy) + +Basic development tools (git, gcc, make, editors) should not be listed. + +Example:: + + Assisted-by: Claude:claude-3-opus coccinelle sparse diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 19d2ed47ff79..35b381230f6e 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -76,7 +76,7 @@ Don't use commas to avoid using braces: if (condition) do_this(), do_that(); -Always uses braces for multiple statements: +Always use braces for multiple statements: .. code-block:: c @@ -614,7 +614,10 @@ it. When commenting the kernel API functions, please use the kernel-doc format. See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and -``scripts/kernel-doc`` for details. +``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting +applies to kernel-doc comments all the same. Do not add boilerplate +kernel-doc which simply reiterates what's obvious from the signature +of the function. The preferred style for long (multi-line) comments is: @@ -1067,7 +1070,7 @@ readability. 18) Don't re-invent the kernel macros ------------------------------------- -The header file include/linux/kernel.h contains a number of macros that +There are many header files in include/linux/ that contain a number of macros that you should use, rather than explicitly coding some variant of them yourself. For example, if you need to calculate the length of an array, take advantage of the macro @@ -1076,14 +1079,18 @@ of the macro #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) +which is defined in array_size.h. + Similarly, if you need to calculate the size of some structure member, use .. code-block:: c #define sizeof_field(t, f) (sizeof(((t*)0)->f)) -There are also min() and max() macros that do strict type checking if you -need them. Feel free to peruse that header file to see what else is already +which is defined in stddef.h. + +There are also min() and max() macros defined in minmax.h that do strict type checking +if you need them. Feel free to peruse the header files to see what else is already defined that you shouldn't reproduce in your code. diff --git a/Documentation/process/conclave.rst b/Documentation/process/conclave.rst new file mode 100644 index 000000000000..6a1234f54612 --- /dev/null +++ b/Documentation/process/conclave.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux kernel project continuity +=============================== + +The Linux kernel development project is widely distributed, with over +100 maintainers each working to keep changes moving through their own +repositories. The final step, though, is a centralized one where changes +are pulled into the mainline repository. That is normally done by Linus +Torvalds but, as was demonstrated by the 4.19 release in 2018, there are +others who can do that work when the need arises. + +Should the maintainers of that repository become unwilling or unable to +do that work going forward (including facilitating a transition), the +project will need to find one or more replacements without delay. The +process by which that will be done is listed below. $ORGANIZER is the +last Maintainer Summit organizer or the current Linux Foundation (LF) +Technical Advisory Board (TAB) Chair as a backup. + +- Within 72 hours, $ORGANIZER will open a discussion with the invitees + of the most recently concluded Maintainers Summit. A meeting of those + invitees and the TAB, either online or in-person, will be set as soon + as possible in a way that maximizes the number of people who can + participate. + +- If there has been no Maintainers Summit in the last 15 months, the set of + invitees for this meeting will be determined by the TAB. + +- The invitees to this meeting may bring in other maintainers as needed. + +- This meeting, chaired by $ORGANIZER, will consider options for the + ongoing management of the top-level kernel repository consistent with + the expectation that it maximizes the long term health of the project + and its community. + +- Within two weeks, a representative of this group will communicate to the + broader community, using the ksummit@lists.linux.dev mailing list, what + the next steps will be. + +The Linux Foundation, as guided by the TAB, will take the steps +necessary to support and implement this plan. diff --git a/Documentation/process/debugging/driver_development_debugging_guide.rst b/Documentation/process/debugging/driver_development_debugging_guide.rst index 46becda8764b..aca08f457793 100644 --- a/Documentation/process/debugging/driver_development_debugging_guide.rst +++ b/Documentation/process/debugging/driver_development_debugging_guide.rst @@ -155,7 +155,7 @@ The general idea is: ``my_variable`` - Clean up the directory when removing the device - (``debugfs_remove_recursive(parent);``) + (``debugfs_remove(parent);``) For the full documentation see :doc:`/filesystems/debugfs`. diff --git a/Documentation/process/debugging/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst index 895285c037c7..53e225760a4d 100644 --- a/Documentation/process/debugging/gdb-kernel-debugging.rst +++ b/Documentation/process/debugging/gdb-kernel-debugging.rst @@ -127,35 +127,31 @@ Examples of using the Linux-provided gdb helpers - Make use of the per-cpu function for the current or a specified CPU:: - (gdb) p $lx_per_cpu("runqueues").nr_running + (gdb) p $lx_per_cpu(runqueues).nr_running $3 = 1 - (gdb) p $lx_per_cpu("runqueues", 2).nr_running + (gdb) p $lx_per_cpu(runqueues, 2).nr_running $4 = 0 - Dig into hrtimers using the container_of helper:: - (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next - (gdb) p *$container_of($next, "struct hrtimer", "node") + (gdb) set $leftmost = $lx_per_cpu(hrtimer_bases).clock_base[0].active.rb_root.rb_leftmost + (gdb) p *$container_of($leftmost, "struct hrtimer", "node") $5 = { node = { node = { - __rb_parent_color = 18446612133355256072, - rb_right = 0x0 <irq_stack_union>, - rb_left = 0x0 <irq_stack_union> + __rb_parent_color = 18446612686384860673, + rb_right = 0xffff888231da8b00, + rb_left = 0x0 }, - expires = { - tv64 = 1835268000000 - } + expires = 1228461000000 }, - _softexpires = { - tv64 = 1835268000000 - }, - function = 0xffffffff81078232 <tick_sched_timer>, - base = 0xffff88003fd0d6f0, - state = 1, - start_pid = 0, - start_site = 0xffffffff81055c1f <hrtimer_start_range_ns+20>, - start_comm = "swapper/2\000\000\000\000\000\000" + _softexpires = 1228461000000, + function = 0xffffffff8137ab20 <tick_nohz_handler>, + base = 0xffff888231d9b4c0, + state = 1 '\001', + is_rel = 0 '\000', + is_soft = 0 '\000', + is_hard = 1 '\001' } @@ -177,3 +173,12 @@ this is just a snapshot of the initial version:: Detailed help can be obtained via "help <command-name>" for commands and "help function <function-name>" for convenience functions. + +Debugging GDB scripts +--------------------- + +GDB does not enable a full Python backtrace which can make debugging GDB +scripts more difficult than necessary. The following will allow for printing a +full backtrace of the python environment:: + + (gdb) set python print-stack full diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst index 387d33d16f5e..357243e184e1 100644 --- a/Documentation/process/debugging/index.rst +++ b/Documentation/process/debugging/index.rst @@ -15,8 +15,6 @@ general guides kgdb userspace_debugging_guide -.. only:: subproject and html - subsystem specific guides ------------------------- @@ -25,13 +23,6 @@ subsystem specific guides media_specific_debugging_guide -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` - General debugging advice ======================== diff --git a/Documentation/process/debugging/kgdb.rst b/Documentation/process/debugging/kgdb.rst index b29b0aac2717..dd6a103073fa 100644 --- a/Documentation/process/debugging/kgdb.rst +++ b/Documentation/process/debugging/kgdb.rst @@ -380,6 +380,13 @@ virtual address where the kernel image is mapped and confuses gdb which resolves addresses of kernel symbols from the symbol table of vmlinux. +Kernel parameter: ``rodata`` +---------------------------- + +``CONFIG_STRICT_KERNEL_RWX`` is turned on by default and is not +visible to menuconfig on some architectures (arm64 for example), +you can pass ``rodata=off`` to the kernel in this case. + Using kdb ========= @@ -889,34 +896,6 @@ in the virtual console layer. On resuming kernel execution, the kernel debugger calls kgdboc_post_exp_handler() which in turn calls con_debug_leave(). -Any video driver that wants to be compatible with the kernel debugger -and the atomic kms callbacks must implement the ``mode_set_base_atomic``, -``fb_debug_enter`` and ``fb_debug_leave operations``. For the -``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the -generic drm fb helper functions or implement something custom for the -hardware. The following example shows the initialization of the -.mode_set_base_atomic operation in -drivers/gpu/drm/i915/intel_display.c:: - - - static const struct drm_crtc_helper_funcs intel_helper_funcs = { - [...] - .mode_set_base_atomic = intel_pipe_set_base_atomic, - [...] - }; - - -Here is an example of how the i915 driver initializes the -fb_debug_enter and fb_debug_leave functions to use the generic drm -helpers in ``drivers/gpu/drm/i915/intel_fb.c``:: - - - static struct fb_ops intelfb_ops = { - [...] - .fb_debug_enter = drm_fb_helper_debug_enter, - .fb_debug_leave = drm_fb_helper_debug_leave, - [...] - }; Credits diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 1f7f3e6c9cda..fed56864d036 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -372,3 +372,34 @@ The helper must be used:: DECLARE_FLEX_ARRAY(struct type2, two); }; }; + +Open-coded kmalloc assignments for struct objects +------------------------------------------------- +Performing open-coded kmalloc()-family allocation assignments prevents +the kernel (and compiler) from being able to examine the type of the +variable being assigned, which limits any related introspection that +may help with alignment, wrap-around, or additional hardening. The +kmalloc_obj()-family of macros provide this introspection, which can be +used for the common code patterns for single, array, and flexible object +allocations. For example, these open coded assignments:: + + ptr = kmalloc(sizeof(*ptr), gfp); + ptr = kzalloc(sizeof(*ptr), gfp); + ptr = kmalloc_array(count, sizeof(*ptr), gfp); + ptr = kcalloc(count, sizeof(*ptr), gfp); + ptr = kmalloc(struct_size(ptr, flex_member, count), gfp); + ptr = kmalloc(sizeof(struct foo, gfp); + +become, respectively:: + + ptr = kmalloc_obj(*ptr, gfp); + ptr = kzalloc_obj(*ptr, gfp); + ptr = kmalloc_objs(*ptr, count, gfp); + ptr = kzalloc_objs(*ptr, count, gfp); + ptr = kmalloc_flex(*ptr, flex_member, count, gfp); + __auto_type ptr = kmalloc_obj(struct foo, gfp); + +If `ptr->flex_member` is annotated with __counted_by(), the allocation +will automatically fail if `count` is larger than the maximum +representable value that can be stored in the counter member associated +with `flex_member`. diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 84a2450bb6ec..b5377630a648 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -324,7 +324,14 @@ To beat some sense out of the internal editor, do this: - Set ``mailnews.send_plaintext_flowed`` to ``false`` - - Set ``mailnews.wraplength`` from ``72`` to ``0`` + - Set ``mailnews.wraplength`` from ``72`` to ``0`` **or** install the + "Toggle Line Wrap" extension + + https://github.com/jan-kiszka/togglelinewrap + + https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap + + to control this registry on the fly. - Don't write HTML messages! Go to the main window :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`! diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index 0e19d2f0d6bb..34e00848e0da 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -290,7 +290,7 @@ 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 Michael Ellerman <ellerman@au.ibm.com> + IBM Power Madhavan Srinivasan <maddy@linux.ibm.com> IBM Z Christian Borntraeger <borntraeger@de.ibm.com> Intel Tony Luck <tony.luck@intel.com> Qualcomm Trilok Soni <quic_tsoni@quicinc.com> diff --git a/Documentation/process/generated-content.rst b/Documentation/process/generated-content.rst new file mode 100644 index 000000000000..08621e50a462 --- /dev/null +++ b/Documentation/process/generated-content.rst @@ -0,0 +1,109 @@ +============================================ +Kernel Guidelines for Tool-Generated Content +============================================ + +Purpose +======= + +Kernel contributors have been using tooling to generate contributions +for a long time. These tools can increase the volume of contributions. +At the same time, reviewer and maintainer bandwidth is a scarce +resource. Understanding which portions of a contribution come from +humans versus tools is helpful to maintain those resources and keep +kernel development healthy. + +The goal here is to clarify community expectations around tools. This +lets everyone become more productive while also maintaining high +degrees of trust between submitters and reviewers. + +Out of Scope +============ + +These guidelines do not apply to tools that make trivial tweaks to +preexisting content. Nor do they pertain to tooling that helps with +menial tasks. Some examples: + + - Spelling and grammar fix ups, like rephrasing to imperative voice + - Typing aids like identifier completion, common boilerplate or + trivial pattern completion + - Purely mechanical transformations like variable renaming + - Reformatting, like running Lindent, ``clang-format`` or + ``rust-fmt`` + +Even whenever your tool use is out of scope, you should still always +consider if it would help reviewing your contribution if the reviewer +knows about the tool that you used. + +In Scope +======== + +These guidelines apply when a meaningful amount of content in a kernel +contribution was not written by a person in the Signed-off-by chain, +but was instead created by a tool. + +Detection of a problem and testing the fix for it is also part of the +development process; if a tool was used to find a problem addressed by +a change, that should be noted in the changelog. This not only gives +credit where it is due, it also helps fellow developers find out about +these tools. + +Some examples: + - Any tool-suggested fix such as ``checkpatch.pl --fix`` + - Coccinelle scripts + - A chatbot generated a new function in your patch to sort list entries. + - A .c file in the patch was originally generated by a coding + assistant but cleaned up by hand. + - The changelog was generated by handing the patch to a generative AI + tool and asking it to write the changelog. + - The changelog was translated from another language. + +If in doubt, choose transparency and assume these guidelines apply to +your contribution. + +Guidelines +========== + +First, read the Developer's Certificate of Origin: +Documentation/process/submitting-patches.rst. Its rules are simple +and have been in place for a long time. They have covered many +tool-generated contributions. Ensure that you understand your entire +submission and are prepared to respond to review comments. + +Second, when making a contribution, be transparent about the origin of +content in cover letters and changelogs. You can be more transparent +by adding information like this: + + - What tools were used? + - The input to the tools you used, like the Coccinelle source script. + - If code was largely generated from a single or short set of + prompts, include those prompts. For longer sessions, include a + summary of the prompts and the nature of resulting assistance. + - Which portions of the content were affected by that tool? + - How is the submission tested and what tools were used to test the + fix? + +As with all contributions, individual maintainers have discretion to +choose how they handle the contribution. For example, they might: + + - Treat it just like any other contribution. + - Reject it outright. + - Treat the contribution specially, for example, asking for extra + testing, reviewing with extra scrutiny, or reviewing at a lower + priority than human-generated content. + - Ask for some other special steps, like asking the contributor to + elaborate on how the tool or model was trained. + - Ask the submitter to explain in more detail about the contribution + so that the maintainer can be assured that the submitter fully + understands how the code works. + - Suggest a better prompt instead of suggesting specific code changes. + +If tools permit you to generate a contribution automatically, expect +additional scrutiny in proportion to how much of it was generated. + +As with the output of any tooling, the result may be incorrect or +inappropriate. You are expected to understand and to be able to defend +everything you submit. If you are unable to do so, then do not submit +the resulting changes. + +If you do so anyway, maintainers are entitled to reject your series +without detailed review. diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index 1f5ab49c48a4..c71b5d403f0c 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -461,325 +461,556 @@ which both cover more details than the above section. Quotes from Linus about regression ---------------------------------- -Find below a few real life examples of how Linus Torvalds expects regressions to -be handled: +The following statements from Linus Torvalds provide some insight into Linux +"no regressions" rule and how he expects regressions to be handled: - * From `2017-10-26 (1/2) - <https://lore.kernel.org/lkml/CA+55aFwiiQYJ+YoLKCXjN_beDVfu38mg=Ggg5LFOcqHE8Qi7Zw@mail.gmail.com/>`_:: +On how quickly regressions should be fixed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - If you break existing user space setups THAT IS A REGRESSION. +* From `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_:: - It's not ok to say "but we'll fix the user space setup". + But a user complaining should basically result in an immediate fix - + possibly a "revert and rethink". - Really. NOT OK. + With a later clarification on `2026-01-28 <https://lore.kernel.org/all/CAHk-%3Dwi86AosXs66-yi54%2BmpQjPu0upxB8ZAfG%2BLsMyJmcuMSA@mail.gmail.com/>`_:: - [...] + It's also worth noting that "immediate" obviously doesn't mean "right + this *second* when the problem has been reported". - The first rule is: + But if it's a regression with a known commit that caused it, I think + the rule of thumb should generally be "within a week", preferably + before the next rc. - - we don't cause regressions +* From `2023-04-21 <https://lore.kernel.org/all/CAHk-=wgD98pmSK3ZyHk_d9kZ2bhgN6DuNZMAJaV0WTtbkf=RDw@mail.gmail.com/>`_:: - and the corollary is that when regressions *do* occur, we admit to - them and fix them, instead of blaming user space. + Known-broken commits either + (a) get a timely fix that doesn't have other questions + or + (b) get reverted - The fact that you have apparently been denying the regression now for - three weeks means that I will revert, and I will stop pulling apparmor - requests until the people involved understand how kernel development - is done. +* From `2021-09-20(2) <https://lore.kernel.org/all/CAHk-=wgOvmtRw1TNbMC1rn5YqyTKyn0hz+sc4k0DGNn++u9aYw@mail.gmail.com/>`_:: - * From `2017-10-26 (2/2) - <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: + [...] review shouldn't hold up reported regressions of existing code. That's + just basic _testing_ - either the fix should be applied, or - if the fix is + too invasive or too ugly - the problematic source of the regression should + be reverted. - People should basically always feel like they can update their kernel - and simply not have to worry about it. + Review should be about new code, it shouldn't be holding up "there's a + bug report, here's the obvious fix". - I refuse to introduce "you can only update the kernel if you also - update that other program" kind of limitations. If the kernel used to - work for you, the rule is that it continues to work for you. +* From `2023-05-08 <https://lore.kernel.org/all/CAHk-=wgzU8_dGn0Yg+DyX7ammTkDUCyEJ4C=NvnHRhxKWC7Wpw@mail.gmail.com/>`_:: - There have been exceptions, but they are few and far between, and they - generally have some major and fundamental reasons for having happened, - that were basically entirely unavoidable, and people _tried_hard_ to - avoid them. Maybe we can't practically support the hardware any more - after it is decades old and nobody uses it with modern kernels any - more. Maybe there's a serious security issue with how we did things, - and people actually depended on that fundamentally broken model. Maybe - there was some fundamental other breakage that just _had_ to have a - flag day for very core and fundamental reasons. + If something doesn't even build, it should damn well be fixed ASAP. - And notice that this is very much about *breaking* peoples environments. +On how fixing regressions with reverts can help prevent maintainer burnout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Behavioral changes happen, and maybe we don't even support some - feature any more. There's a number of fields in /proc/<pid>/stat that - are printed out as zeroes, simply because they don't even *exist* in - the kernel any more, or because showing them was a mistake (typically - an information leak). But the numbers got replaced by zeroes, so that - the code that used to parse the fields still works. The user might not - see everything they used to see, and so behavior is clearly different, - but things still _work_, even if they might no longer show sensitive - (or no longer relevant) information. +* From `2026-01-28 <https://lore.kernel.org/all/CAHk-%3Dwi86AosXs66-yi54%2BmpQjPu0upxB8ZAfG%2BLsMyJmcuMSA@mail.gmail.com/>`_:: - But if something actually breaks, then the change must get fixed or - reverted. And it gets fixed in the *kernel*. Not by saying "well, fix - your user space then". It was a kernel change that exposed the - problem, it needs to be the kernel that corrects for it, because we - have a "upgrade in place" model. We don't have a "upgrade with new - user space". + > So how can I/we make "immediate fixes" happen more often without + > contributing to maintainer burnout? - And I seriously will refuse to take code from people who do not - understand and honor this very simple rule. + [...] the "revert and rethink" model [...] often a good idea in general [...] - This rule is also not going to change. + Exactly so that maintainers don't get stressed out over having a pending + problem report that people keep pestering them about. - And yes, I realize that the kernel is "special" in this respect. I'm - proud of it. + I think people are sometimes a bit too bought into whatever changes + they made, and reverting is seen as "too drastic", but I think it's + often the quick and easy solution for when there isn't some obvious + response to a regression report. - I have seen, and can point to, lots of projects that go "We need to - break that use case in order to make progress" or "you relied on - undocumented behavior, it sucks to be you" or "there's a better way to - do what you want to do, and you have to change to that new better - way", and I simply don't think that's acceptable outside of very early - alpha releases that have experimental users that know what they signed - up for. The kernel hasn't been in that situation for the last two - decades. +On mainlining fixes when the last -rc or a new release is close +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - We do API breakage _inside_ the kernel all the time. We will fix - internal problems by saying "you now need to do XYZ", but then it's - about internal kernel API's, and the people who do that then also - obviously have to fix up all the in-kernel users of that API. Nobody - can say "I now broke the API you used, and now _you_ need to fix it - up". Whoever broke something gets to fix it too. +* From `2026-02-01 <https://lore.kernel.org/all/CAHk-%3DwhXTw1oPsa%2BTLuY1Rc9D1OAiPVOdR_-R2xG45kwDObKdA@mail.gmail.com/>`_:: - And we simply do not break user space. + So I think I'd rather see them hit rc8 (later today) and have a week + of testing in my tree and be reverted if they cause problems, than + have them go in after rc8 and then cause problems in the 6.19 release + instead. - * From `2020-05-21 - <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_:: +* From `2023-04-20 <https://lore.kernel.org/all/CAHk-=wis_qQy4oDNynNKi5b7Qhosmxtoj1jxo5wmB6SRUwQUBQ@mail.gmail.com/>`_:: - The rules about regressions have never been about any kind of - documented behavior, or where the code lives. + But something like this, where the regression was in the previous release + and it's just a clear fix with no semantic subtlety, I consider to be just a + regular regression that should be expedited - partly to make it into stable, + and partly to avoid having to put the fix into _another_ stable kernel. - The rules about regressions are always about "breaks user workflow". +On sending merge requests with just one fix +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Users are literally the _only_ thing that matters. +* From `2024-04-24 <https://lore.kernel.org/all/CAHk-=wjy_ph9URuFt-pq+2AJ__p7gFDx=yzVSCsx16xAYvNw9g@mail.gmail.com/>`_:: - No amount of "you shouldn't have used this" or "that behavior was - undefined, it's your own fault your app broke" or "that used to work - simply because of a kernel bug" is at all relevant. + If the issue is just that there's nothing else happening, I think people + should just point me to the patch and say "can you apply this single fix?" - Now, reality is never entirely black-and-white. So we've had things - like "serious security issue" etc that just forces us to make changes - that may break user space. But even then the rule is that we don't - really have other options that would allow things to continue. +* From `2023-04-20 <https://lore.kernel.org/all/CAHk-=wis_qQy4oDNynNKi5b7Qhosmxtoj1jxo5wmB6SRUwQUBQ@mail.gmail.com/>`_:: - And obviously, if users take years to even notice that something - broke, or if we have sane ways to work around the breakage that - doesn't make for too much trouble for users (ie "ok, there are a - handful of users, and they can use a kernel command line to work - around it" kind of things) we've also been a bit less strict. + I'm always open to direct fixes when there is no controversy about the fix. + No problem. I still happily deal with individual patches. - But no, "that was documented to be broken" (whether it's because the - code was in staging or because the man-page said something else) is - irrelevant. If staging code is so useful that people end up using it, - that means that it's basically regular kernel code with a flag saying - "please clean this up". +On the importance of pointing to bug reports using Link:/Closes: tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The other side of the coin is that people who talk about "API - stability" are entirely wrong. API's don't matter either. You can make - any changes to an API you like - as long as nobody notices. +* From `2025-07-29(1) <https://lore.kernel.org/all/CAHk-=wj2kJRPWx8B09AAtzj+_g+T6UBX11TP0ebs1WJdTtv=WQ@mail.gmail.com/>`_:: - Again, the regression rule is not about documentation, not about - API's, and not about the phase of the moon. + [...] revert like this, it really would be good to link to the problems, so + that when people try to re-enable it, they have the history for why it + didn't work the first time. - It's entirely about "we caused problems for user space that used to work". +* From `2022-05-08 <https://lore.kernel.org/all/CAHk-=wjMmSZzMJ3Xnskdg4+GGz=5p5p+GSYyFBTh0f-DgvdBWg@mail.gmail.com/>`_:: - * From `2017-11-05 - <https://lore.kernel.org/all/CA+55aFzUvbGjD8nQ-+3oiMBx14c_6zOj2n7KLN3UsJ-qsd4Dcw@mail.gmail.com/>`_:: + So I have to once more complain [...] - And our regression rule has never been "behavior doesn't change". - That would mean that we could never make any changes at all. + [...] There's no link to the actual problem the patch fixes. - For example, we do things like add new error handling etc all the - time, which we then sometimes even add tests for in our kselftest - directory. +* From `2022-06-22 <https://lore.kernel.org/all/CAHk-=wjxzafG-=J8oT30s7upn4RhBs6TX-uVFZ5rME+L5_DoJA@mail.gmail.com/>`_:: - So clearly behavior changes all the time and we don't consider that a - regression per se. + See, *that* link [to the report] would have been useful in the commit. - The rule for a regression for the kernel is that some real user - workflow breaks. Not some test. Not a "look, I used to be able to do - X, now I can't". +On why the "no regressions" rule exists +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * From `2018-08-03 - <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_:: +* From `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_:: - YOU ARE MISSING THE #1 KERNEL RULE. + But the basic rule is: be so good about backwards compatibility that + users never have to worry about upgrading. They should absolutely feel + confident that any kernel-reported problem will either be solved, or + have an easy solution that is appropriate for *them* (ie a + non-technical user shouldn't be expected to be able to do a lot). - We do not regress, and we do not regress exactly because your are 100% wrong. + Because the last thing we want is people holding back from trying new + kernels. - And the reason you state for your opinion is in fact exactly *WHY* you - are wrong. +* From `2024-05-28 <https://lore.kernel.org/all/CAHk-=wgtb7y-bEh7tPDvDWru7ZKQ8-KMjZ53Tsk37zsPPdwXbA@mail.gmail.com/>`_:: - Your "good reasons" are pure and utter garbage. + I introduced that "no regressions" rule something like two decades + ago, because people need to be able to update their kernel without + fear of something they relied on suddenly stopping to work. - The whole point of "we do not regress" is so that people can upgrade - the kernel and never have to worry about it. +* From `2018-08-03 <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_:: - > Kernel had a bug which has been fixed + The whole point of "we do not regress" is so that people can upgrade + the kernel and never have to worry about it. - That is *ENTIRELY* immaterial. + [...] - Guys, whether something was buggy or not DOES NOT MATTER. + Because the only thing that matters IS THE USER. - Why? +* From `2017-10-26(1) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: - Bugs happen. That's a fact of life. Arguing that "we had to break - something because we were fixing a bug" is completely insane. We fix - tens of bugs every single day, thinking that "fixing a bug" means that - we can break something is simply NOT TRUE. + If the kernel used to work for you, the rule is that it continues to work + for you. - So bugs simply aren't even relevant to the discussion. They happen, - they get found, they get fixed, and it has nothing to do with "we - break users". + [...] - Because the only thing that matters IS THE USER. + People should basically always feel like they can update their kernel + and simply not have to worry about it. - How hard is that to understand? + I refuse to introduce "you can only update the kernel if you also + update that other program" kind of limitations. If the kernel used to + work for you, the rule is that it continues to work for you. - Anybody who uses "but it was buggy" as an argument is entirely missing - the point. As far as the USER was concerned, it wasn't buggy - it - worked for him/her. +On exceptions to the "no regressions" rule +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Maybe it worked *because* the user had taken the bug into account, - maybe it worked because the user didn't notice - again, it doesn't - matter. It worked for the user. +* From `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_:: - Breaking a user workflow for a "bug" is absolutely the WORST reason - for breakage you can imagine. + There are _very_ few exceptions to that rule, the main one being "the + problem was a fundamental huge and gaping security issue and we *had* to + make that change, and we couldn't even make your limited use-case just + continue to work". - It's basically saying "I took something that worked, and I broke it, - but now it's better". Do you not see how f*cking insane that statement - is? + The other exception is "the problem was reported years after it was + introduced, and now most people rely on the new behavior". - And without users, your program is not a program, it's a pointless - piece of code that you might as well throw away. + [...] - Seriously. This is *why* the #1 rule for kernel development is "we - don't break users". Because "I fixed a bug" is absolutely NOT AN - ARGUMENT if that bug fix broke a user setup. You actually introduced a - MUCH BIGGER bug by "fixing" something that the user clearly didn't - even care about. + Now, if it's one or two users and you can just get them to recompile, + that's one thing. Niche hardware and odd use-cases can sometimes be + solved that way, and regressions can sometimes be fixed by handholding + every single reporter if the reporter is willing and able to change + his or her workflow. - And dammit, we upgrade the kernel ALL THE TIME without upgrading any - other programs at all. It is absolutely required, because flag-days - and dependencies are horribly bad. +* From `2023-04-20 <https://lore.kernel.org/all/CAHk-=wis_qQy4oDNynNKi5b7Qhosmxtoj1jxo5wmB6SRUwQUBQ@mail.gmail.com/>`_:: - And it is also required simply because I as a kernel developer do not - upgrade random other tools that I don't even care about as I develop - the kernel, and I want any of my users to feel safe doing the same - time. + And yes, I do consider "regression in an earlier release" to be a + regression that needs fixing. - So no. Your rule is COMPLETELY wrong. If you cannot upgrade a kernel - without upgrading some other random binary, then we have a problem. + There's obviously a time limit: if that "regression in an earlier + release" was a year or more ago, and just took forever for people to + notice, and it had semantic changes that now mean that fixing the + regression could cause a _new_ regression, then that can cause me to + go "Oh, now the new semantics are what we have to live with". - * From `2021-06-05 - <https://lore.kernel.org/all/CAHk-=wiUVqHN76YUwhkjZzwTdjMMJf_zN4+u7vEJjmEGh3recw@mail.gmail.com/>`_:: +* From `2017-10-26(2) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: - THERE ARE NO VALID ARGUMENTS FOR REGRESSIONS. + There have been exceptions, but they are few and far between, and they + generally have some major and fundamental reasons for having happened, + that were basically entirely unavoidable, and people _tried_hard_ to + avoid them. Maybe we can't practically support the hardware any more + after it is decades old and nobody uses it with modern kernels any + more. Maybe there's a serious security issue with how we did things, + and people actually depended on that fundamentally broken model. Maybe + there was some fundamental other breakage that just _had_ to have a + flag day for very core and fundamental reasons. - Honestly, security people need to understand that "not working" is not - a success case of security. It's a failure case. +On situations where updating something in userspace can resolve regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Yes, "not working" may be secure. But security in that case is *pointless*. +* From `2018-08-03 <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_:: - * From `2011-05-06 (1/3) - <https://lore.kernel.org/all/BANLkTim9YvResB+PwRp7QTK-a5VNg2PvmQ@mail.gmail.com/>`_:: + And dammit, we upgrade the kernel ALL THE TIME without upgrading any + other programs at all. It is absolutely required, because flag-days + and dependencies are horribly bad. - Binary compatibility is more important. + And it is also required simply because I as a kernel developer do not + upgrade random other tools that I don't even care about as I develop the + kernel, and I want any of my users to feel safe doing the same time. - And if binaries don't use the interface to parse the format (or just - parse it wrongly - see the fairly recent example of adding uuid's to - /proc/self/mountinfo), then it's a regression. +* From `2017-10-26(3) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: - And regressions get reverted, unless there are security issues or - similar that makes us go "Oh Gods, we really have to break things". + But if something actually breaks, then the change must get fixed or + reverted. And it gets fixed in the *kernel*. Not by saying "well, fix your + user space then". It was a kernel change that exposed the problem, it needs + to be the kernel that corrects for it, because we have a "upgrade in place" + model. We don't have a "upgrade with new user space". - I don't understand why this simple logic is so hard for some kernel - developers to understand. Reality matters. Your personal wishes matter - NOT AT ALL. + And I seriously will refuse to take code from people who do not understand + and honor this very simple rule. - If you made an interface that can be used without parsing the - interface description, then we're stuck with the interface. Theory - simply doesn't matter. + This rule is also not going to change. - You could help fix the tools, and try to avoid the compatibility - issues that way. There aren't that many of them. + And yes, I realize that the kernel is "special" in this respect. I'm proud + of it. - From `2011-05-06 (2/3) - <https://lore.kernel.org/all/BANLkTi=KVXjKR82sqsz4gwjr+E0vtqCmvA@mail.gmail.com/>`_:: +* From `2017-10-26(4) <https://lore.kernel.org/all/CA+55aFwiiQYJ+YoLKCXjN_beDVfu38mg=Ggg5LFOcqHE8Qi7Zw@mail.gmail.com/>`_:: - it's clearly NOT an internal tracepoint. By definition. It's being - used by powertop. + If you break existing user space setups THAT IS A REGRESSION. - From `2011-05-06 (3/3) - <https://lore.kernel.org/all/BANLkTinazaXRdGovYL7rRVp+j6HbJ7pzhg@mail.gmail.com/>`_:: + It's not ok to say "but we'll fix the user space setup". - We have programs that use that ABI and thus it's a regression if they break. + Really. NOT OK. - * From `2012-07-06 <https://lore.kernel.org/all/CA+55aFwnLJ+0sjx92EGREGTWOx84wwKaraSzpTNJwPVV8edw8g@mail.gmail.com/>`_:: +On what qualifies as userspace interface, ABI, API, documented interfaces, etc. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - > Now this got me wondering if Debian _unstable_ actually qualifies as a - > standard distro userspace. +* From `2026-01-20 <https://lore.kernel.org/all/CAHk-=wga8Qu0-OSE9VZbviq9GuqwhPhLUXeAt-S7_9+fMCLkKg@mail.gmail.com/>`_:: - Oh, if the kernel breaks some standard user space, that counts. Tons - of people run Debian unstable + So I absolutely detest the whole notion of "ABI changes". It's a + meaningless concept, and I hate it with a passion, [...] - * From `2019-09-15 - <https://lore.kernel.org/lkml/CAHk-=wiP4K8DRJWsCo=20hn_6054xBamGKF2kPgUzpB5aMaofA@mail.gmail.com/>`_:: + The Linux rule for regressions is basically based on the philosophical + question of "If a tree falls in the forest, and nobody is around to + hear it, does it make a sound?". - One _particularly_ last-minute revert is the top-most commit (ignoring - the version change itself) done just before the release, and while - it's very annoying, it's perhaps also instructive. + So the only thing that matters is if something breaks user-*conscious* + behavior. - What's instructive about it is that I reverted a commit that wasn't - actually buggy. In fact, it was doing exactly what it set out to do, - and did it very well. In fact it did it _so_ well that the much - improved IO patterns it caused then ended up revealing a user-visible - regression due to a real bug in a completely unrelated area. + And when that happens, the distinction between "bug fix" and "new + feature" and "ABI change" matters not one whit, and the change needs + to be done differently. - The actual details of that regression are not the reason I point that - revert out as instructive, though. It's more that it's an instructive - example of what counts as a regression, and what the whole "no - regressions" kernel rule means. The reverted commit didn't change any - API's, and it didn't introduce any new bugs. But it ended up exposing - another problem, and as such caused a kernel upgrade to fail for a - user. So it got reverted. + [...] - The point here being that we revert based on user-reported _behavior_, - not based on some "it changes the ABI" or "it caused a bug" concept. - The problem was really pre-existing, and it just didn't happen to - trigger before. The better IO patterns introduced by the change just - happened to expose an old bug, and people had grown to depend on the - previously benign behavior of that old issue. + I just wanted to point out that the argument about whether it's an ABI + change or not is irrelevant. If it turns out that some program - not a test + script, but something with relevance to conscious user expectations ~ + depended on the old broken behavior, then it needs to be done some other + way. - And never fear, we'll re-introduce the fix that improved on the IO - patterns once we've decided just how to handle the fact that we had a - bad interaction with an interface that people had then just happened - to rely on incidental behavior for before. It's just that we'll have - to hash through how to do that (there are no less than three different - patches by three different developers being discussed, and there might - be more coming...). In the meantime, I reverted the thing that exposed - the problem to users for this release, even if I hope it will be - re-introduced (perhaps even backported as a stable patch) once we have - consensus about the issue it exposed. +* From `2026-02-13 <https://lore.kernel.org/all/CAHk-=whY-N8kjm8kiFUV5Ei-8AuYw--EPGD-AR3Pd+5GTx2sAQ@mail.gmail.com/>`_:: - Take-away from the whole thing: it's not about whether you change the - kernel-userspace ABI, or fix a bug, or about whether the old code - "should never have worked in the first place". It's about whether - something breaks existing users' workflow. + > [...] this should not fall under the don't break user space rule [...] - Anyway, that was my little aside on the whole regression thing. Since - it's that "first rule of kernel programming", I felt it is perhaps - worth just bringing it up every once in a while + Note that the rule is about breaking *users*, not breaking user space per + se. [...] + + If some user setup breaks, things need fixing. + + [...] but I want to make it very clear that there are no excuses about "user + space applications". + +* From `2021-09-20(4) <https://lore.kernel.org/all/CAHk-=wi7DB2SJ-wngVvsJ7Ak2cM556Q8437sOXo4EJt2BWPdEg@mail.gmail.com/>`_:: + + [...] a regression is a bit like Schrödinger's cat - if nobody is around + to notice it and it doesn't actually affect any real workload, then you + can treat the regression as if it doesn't exist. + +* From `2020-05-21 <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_:: + + The rules about regressions have never been about any kind of documented + behavior, or where the code lives. + + The rules about regressions are always about "breaks user workflow". + + Users are literally the _only_ thing that matters. + +* From `2019-09-15 <https://lore.kernel.org/lkml/CAHk-=wiP4K8DRJWsCo=20hn_6054xBamGKF2kPgUzpB5aMaofA@mail.gmail.com/>`_:: + + One _particularly_ last-minute revert is the top-most commit (ignoring + the version change itself) done just before the release, and while + it's very annoying, it's perhaps also instructive. + + What's instructive about it is that I reverted a commit that wasn't + actually buggy. In fact, it was doing exactly what it set out to do, + and did it very well. In fact it did it _so_ well that the much + improved IO patterns it caused then ended up revealing a user-visible + regression due to a real bug in a completely unrelated area. + + The actual details of that regression are not the reason I point that + revert out as instructive, though. It's more that it's an instructive + example of what counts as a regression, and what the whole "no + regressions" kernel rule means. + + [...] The reverted commit didn't change any API's, and it didn't introduce + any new bugs. But it ended up exposing another problem, and as such caused + a kernel upgrade to fail for a user. So it got reverted. + + The point here being that we revert based on user-reported _behavior_, not + based on some "it changes the ABI" or "it caused a bug" concept. The problem + was really pre-existing, and it just didn't happen to trigger before. [...] + + Take-away from the whole thing: it's not about whether you change the + kernel-userspace ABI, or fix a bug, or about whether the old code + "should never have worked in the first place". It's about whether + something breaks existing users' workflow. + +* From `2017-11-05 <https://lore.kernel.org/all/CA+55aFzUvbGjD8nQ-+3oiMBx14c_6zOj2n7KLN3UsJ-qsd4Dcw@mail.gmail.com/>`_:: + + And our regression rule has never been "behavior doesn't change". + That would mean that we could never make any changes at all. + +* From `2020-05-21 <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_:: + + No amount of "you shouldn't have used this" or "that behavior was + undefined, it's your own fault your app broke" or "that used to work + simply because of a kernel bug" is at all relevant. + +* From `2021-05-21 <https://lore.kernel.org/all/CAHk-=wiVi7mSrsMP=fLXQrXK_UimybW=ziLOwSzFTtoXUacWVQ@mail.gmail.com/>`_:: + + But no, "that was documented to be broken" (whether it's because the code + was in staging or because the man-page said something else) is irrelevant. + If staging code is so useful that people end up using it, that means that + it's basically regular kernel code with a flag saying "please clean this + up". + + [...] + + The other side of the coin is that people who talk about "API stability" are + entirely wrong. API's don't matter either. You can make any changes to an + API you like - as long as nobody notices. + + Again, the regression rule is not about documentation, not about API's, and + not about the phase of the moon. + +* From `2012-07-06 <https://lore.kernel.org/all/CA+55aFwnLJ+0sjx92EGREGTWOx84wwKaraSzpTNJwPVV8edw8g@mail.gmail.com/>`_:: + + > Now this got me wondering if Debian _unstable_ actually qualifies as a + > standard distro userspace. + + Oh, if the kernel breaks some standard user space, that counts. Tons + of people run Debian unstable + +* From `2011-05-06 <https://lore.kernel.org/all/BANLkTi=KVXjKR82sqsz4gwjr+E0vtqCmvA@mail.gmail.com/>`_:: + + It's clearly NOT an internal tracepoint. By definition. It's being + used by powertop. + +On regressions noticed by users or test-suites/CIs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_:: + + Users complaining is the only real line in the end. + + [...] a test-suite complaining is then often a *very* good indication that + maybe users will hit some problem, and test suite issues should be taken + very seriously [...] + + But a test-suite error isn't necessarily where you have to draw the + line - it's a big red flag [...] + +* From `2024-29-01 <https://lore.kernel.org/all/CAHk-=wg8BrZEzjJ5kUyZzHPZmFqH6ooMN1gRBCofxxCfucgjaw@mail.gmail.com/>`_:: + + The "no regressions" rule is not about made-up "if I do this, behavior + changes". + + The "no regressions" rule is about *users*. + + If you have an actual user that has been doing insane things, and we + change something, and now the insane thing no longer works, at that + point it's a regression, and we'll sigh, and go "Users are insane" and + have to fix it. + + But if you have some random test that now behaves differently, it's + not a regression. It's a *warning* sign, sure: tests are useful. + +On accepting when a regression occurred +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2026-01-22 <https://lore.kernel.org/all/CAHk-=wheQNiW_WtHGO7bKkT7Uib-p+ai2JP9M+z+FYcZ6CAxYA@mail.gmail.com/>`_:: + + But starting to argue about users reporting breaking changes is + basically the final line for me. I have a couple of people that I have + in my spam block-list and refuse to have anything to do with, and they + have generally been about exactly that. + + Note how it's not about making mistakes and _causing_ the regression. + That's normal. That's development. But then arguing about it is a + no-no. + +* From `2024-06-23 <https://lore.kernel.org/all/CAHk-=wi_KMO_rJ6OCr8mAWBRg-irziM=T9wxGC+J1VVoQb39gw@mail.gmail.com/>`_:: + + We don't introduce regressions and then blame others. + + There's a very clear rule in kernel development: things that break + other things ARE NOT FIXES. + + EVER. + + They get reverted, or the thing they broke gets fixed. + +* From `2021-06-05 <https://lore.kernel.org/all/CAHk-=wiUVqHN76YUwhkjZzwTdjMMJf_zN4+u7vEJjmEGh3recw@mail.gmail.com/>`_:: + + THERE ARE NO VALID ARGUMENTS FOR REGRESSIONS. + + Honestly, security people need to understand that "not working" is not + a success case of security. It's a failure case. + + Yes, "not working" may be secure. But security in that case is *pointless*. + +* From `2017-10-26(5) <https://lore.kernel.org/lkml/CA+55aFwiiQYJ+YoLKCXjN_beDVfu38mg=Ggg5LFOcqHE8Qi7Zw@mail.gmail.com/>`_:: + + [...] when regressions *do* occur, we admit to them and fix them, instead of + blaming user space. + + The fact that you have apparently been denying the regression now for + three weeks means that I will revert, and I will stop pulling apparmor + requests until the people involved understand how kernel development + is done. + +On back-and-forth +~~~~~~~~~~~~~~~~~ + +* From `2024-05-28 <https://lore.kernel.org/all/CAHk-=wgtb7y-bEh7tPDvDWru7ZKQ8-KMjZ53Tsk37zsPPdwXbA@mail.gmail.com/>`_:: + + The "no regressions" rule is that we do not introduce NEW bugs. + + It *literally* came about because we had an endless dance of "fix two + bugs, introduce one new one", and that then resulted in a system that + you cannot TRUST. + +* From `2021-09-20(1) <https://lore.kernel.org/all/CAHk-=wi7DB2SJ-wngVvsJ7Ak2cM556Q8437sOXo4EJt2BWPdEg@mail.gmail.com/>`_:: + + And the thing that makes regressions special is that back when I + wasn't so strict about these things, we'd end up in endless "seesaw + situations" where somebody would fix something, it would break + something else, then that something else would break, and it would + never actually converge on anything reliable at all. + +* From `2015-08-13 <https://lore.kernel.org/all/CA+55aFxk8-BsiKwr_S-c+4G6wihKPQVMLE34H9wOZpeua6W9+Q@mail.gmail.com/>`_:: + + The strict policy of no regressions actually originally started mainly wrt + suspend/resume issues, where the "fix one machine, break another" kind of + back-and-forth caused endless problems, and meant that we didn't actually + necessarily make any forward progress, just moving a problem around. + +On changes with a risk of causing regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2023-06-02 <https://lore.kernel.org/all/CAHk-=wgyAGUMHmQM-5Eb556z5xiHZB7cF05qjrtUH4F7P-1rSA@mail.gmail.com/>`_:: + + So what I think you should do is to fix the bug right, with a clean + patch, and no crazy hacks. That is something we can then apply and + test. All the while knowing full well that "uhhuh, this is a visible + change, we may have to revert it". + + If then some *real* load ends up showing a regression, we may just be + screwed. Our current behavior may be buggy, but we have the rule that + once user space depends on kernel bugs, they become features pretty + much by definition, however much we might dislike it. + +On in-kernel workarounds to avoid regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2017-10-26(6) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: + + Behavioral changes happen, and maybe we don't even support some + feature any more. There's a number of fields in /proc/<pid>/stat that + are printed out as zeroes, simply because they don't even *exist* in + the kernel any more, or because showing them was a mistake (typically + an information leak). But the numbers got replaced by zeroes, so that + the code that used to parse the fields still works. The user might not + see everything they used to see, and so behavior is clearly different, + but things still _work_, even if they might no longer show sensitive + (or no longer relevant) information. + +On regressions caused by bugfixes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2018-08-03 <https://lore.kernel.org/all/CA+55aFwWZX=CXmWDTkDGb36kf12XmTehmQjbiMPCqCRG2hi9kw@mail.gmail.com/>`_:: + + > Kernel had a bug which has been fixed + + That is *ENTIRELY* immaterial. + + Guys, whether something was buggy or not DOES NOT MATTER. + + [...] + + It's basically saying "I took something that worked, and I broke it, + but now it's better". Do you not see how f*cking insane that statement + is? + +On internal API changes +~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2017-10-26(7) <https://lore.kernel.org/lkml/CA+55aFxW7NMAMvYhkvz1UPbUTUJewRt6Yb51QAx5RtrWOwjebg@mail.gmail.com/>`_:: + + We do API breakage _inside_ the kernel all the time. We will fix + internal problems by saying "you now need to do XYZ", but then it's + about internal kernel API's, and the people who do that then also + obviously have to fix up all the in-kernel users of that API. Nobody + can say "I now broke the API you used, and now _you_ need to fix it + up". Whoever broke something gets to fix it too. + +On regressions only found after a long time +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2024-03-28 <https://lore.kernel.org/all/CAHk-=wgFuoHpMk_Z_R3qMXVDgq0N1592+bABkyGjwwSL4zBtHA@mail.gmail.com/>`_:: + + I'm definitely not reverting a patch from almost a decade ago as a + regression. + + If it took that long to find, it can't be that critical of a regression. + + So yes, let's treat it as a regular bug. + +On testing regressions fixes in linux-next +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* On `maintainers summit 2024 <https://lwn.net/Articles/990599/>`_:: + + So running fixes though linux-next is just a waste of time. + +On a few other aspects related to regressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* From `2025-07-29(2) <https://lore.kernel.org/all/CAHk-=wjj9DvOZtmTkoLtyfHmy5mNKy6q_96d9=4FUEDXre=cww@mail.gmail.com/>`_ + [which `is not quite a regression, but a huge inconvenience <https://lore.kernel.org/all/CAHk-=wgO0Rx2LcYT4f75Xs46orbJ4JxO2jbAFQnVKDYAjV5HeQ@mail.gmail.com/>`_]:: + + I no longer have sound. + + I also suspect that it's purely because "make oldconfig" doesn't work, + and probably turned off my old Intel HDA settings. Or something. + + Renaming config parameters is *bad*. I've harped on the Kconfig phase + of the kernel build probably being our nastiest point, and a real pain + point to people getting involved with development simply because + building your own kernel can be so daunting with hundreds of fairly + esoteric questions. .. end-of-content diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index aa12f2660194..aa7c959a52b8 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -68,6 +68,9 @@ beyond). stable-kernel-rules management-style researcher-guidelines + generated-content + coding-assistants + conclave Dealing with bugs ----------------- @@ -83,6 +86,7 @@ regressions and security problems. debugging/index handling-regressions security-bugs + threat-model cve embargoed-hardware-issues @@ -108,10 +112,3 @@ developers: kernel-docs deprecated - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 3b5b5983fea8..c67ac12cf789 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -75,6 +75,17 @@ On-line docs Published books --------------- + * Title: **The Linux Memory Manager** + + :Author: Lorenzo Stoakes + :Publisher: No Starch Press + :Date: February 2025 + :Pages: 1300 + :ISBN: 978-1718504462 + :Notes: Memory management. Full draft available as early access for + pre-order, full release scheduled for Fall 2025. See + https://nostarch.com/linux-memory-manager for further info. + * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** :Author: Kenneth Hess diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst index 59a7832df7d0..b0176bb8a465 100644 --- a/Documentation/process/license-rules.rst +++ b/Documentation/process/license-rules.rst @@ -63,8 +63,11 @@ License identifier syntax The SPDX license identifier in kernel files shall be added at the first possible line in a file which can contain a comment. For the majority of files this is the first line, except for scripts which require the - '#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX - identifier goes into the second line. + '#!PATH_TO_INTERPRETER' in the first line. For those scripts, the SPDX + license identifier goes into the second line. + + The license identifier line can then be followed by one or multiple + SPDX-FileCopyrightText lines if desired. | diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst index 976391cec528..3d72ad25fc6a 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _maintainer_handbooks_main: - Subsystem and maintainer tree specific development process notes ================================================================ diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index e497729525d5..ec7b9aa2877f 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -311,6 +311,14 @@ to the mailing list, e.g.:: Posting as one thread is discouraged because it confuses patchwork (as of patchwork 2.2.2). +Co-posting selftests +~~~~~~~~~~~~~~~~~~~~ + +Selftests should be part of the same series as the code changes. +Specifically for fixes both code change and related test should go into +the same tree (the tests may lack a Fixes tag, which is expected). +Mixing code changes and test changes in a single commit is discouraged. + Preparing changes ----------------- @@ -355,6 +363,18 @@ just do it. As a result, a sequence of smaller series gets merged quicker and with better review coverage. Re-posting large series also increases the mailing list traffic. +Limit patches outstanding on mailing list +----------------------------------------- + +Avoid having more than 15 patches, across all series, outstanding for +review on the mailing list for a single tree. In other words, a maximum of +15 patches under review on net, and a maximum of 15 patches under review on +net-next. + +This limit is intended to focus developer effort on testing patches before +upstream review. Aiding the quality of upstream submissions, and easing the +load on reviewers. + .. _rcs: Local variable ordering ("reverse xmas tree", "RCS") @@ -399,7 +419,7 @@ Clean-up patches Netdev discourages patches which perform simple clean-ups, which are not in the context of other work. For example: -* Addressing ``checkpatch.pl`` warnings +* Addressing ``checkpatch.pl``, and other trivial coding style warnings * Addressing :ref:`Local variable ordering<rcs>` issues * Conversions to device-managed APIs (``devm_`` helpers) @@ -459,8 +479,14 @@ netdevsim ``netdevsim`` is a test driver which can be used to exercise driver configuration APIs without requiring capable hardware. -Mock-ups and tests based on ``netdevsim`` are strongly encouraged when -adding new APIs, but ``netdevsim`` in itself is **not** considered +Mock-ups and tests based on ``netdevsim`` are encouraged when +adding new APIs with complex logic in the stack. The tests should +be written so that they can run both against ``netdevsim`` and a real +device (see ``tools/testing/selftests/drivers/net/README.rst``). +``netdevsim``-only tests should focus on testing corner cases +and failure paths in the core which are hard to exercise with a real driver. + +``netdevsim`` in itself is **not** considered a use case/user. You must also implement the new APIs in a real driver. We give no guarantees that ``netdevsim`` won't change in the future @@ -502,7 +528,7 @@ The exact rules a driver must follow to acquire the ``Supported`` status: status will be withdrawn. 5. Test failures due to bugs either in the driver or the test itself, - or lack of support for the feature the test is targgeting are + or lack of support for the feature the test is targeting are *not* a basis for losing the ``Supported`` status. netdev CI will maintain an official page of supported devices, listing their @@ -525,10 +551,12 @@ helpful tips please see :ref:`development_advancedtopics_reviews`. It's safe to assume that netdev maintainers know the community and the level of expertise of the reviewers. The reviewers should not be concerned about -their comments impeding or derailing the patch flow. +their comments impeding or derailing the patch flow. A Reviewed-by tag +is understood to mean "I have reviewed this code to the best of my ability" +rather than "I can attest this code is correct". -Less experienced reviewers are highly encouraged to do more in-depth -review of submissions and not focus exclusively on trivial or subjective +Reviewers are highly encouraged to do more in-depth review of submissions +and not focus exclusively on process issues, trivial or subjective matters like code formatting, tags etc. Testimonials / feedback diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index f5277993b195..652dfbe64102 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _pgpguide: =========================== @@ -49,7 +51,7 @@ hosting infrastructure, regardless of how good the security practices for the latter may be. The above guiding principle is the reason why this guide is needed. We -want to make sure that by placing trust into developers we do not simply +want to make sure that by placing trust into developers we do not merely shift the blame for potential future security incidents to someone else. The goal is to provide a set of guidelines developers can use to create a secure working environment and safeguard the PGP keys used to @@ -60,7 +62,7 @@ establish the integrity of the Linux kernel itself. PGP tools ========= -Use GnuPG 2.2 or later +Use GnuPG 2.4 or later ---------------------- Your distro should already have GnuPG installed by default, you just @@ -69,9 +71,9 @@ To check, run:: $ gpg --version | head -n1 -If you have version 2.2 or above, then you are good to go. If you have a -version that is prior than 2.2, then some commands from this guide may -not work. +If you have version 2.4 or above, then you are good to go. If you have +an earlier version, then you are using a release of GnuPG that is no +longer maintained and some commands from this guide may not work. Configure gpg-agent options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -199,13 +201,6 @@ separate signing subkey:: $ gpg --quick-addkey [fpr] ed25519 sign -.. note:: ECC support in GnuPG - - Note, that if you intend to use a hardware token that does not - support ED25519 ECC keys, you should choose "nistp256" instead or - "ed25519." See the section below on recommended hardware devices. - - Back up your Certify key for disaster recovery ---------------------------------------------- @@ -213,7 +208,7 @@ The more signatures you have on your PGP key from other developers, the more reasons you have to create a backup version that lives on something other than digital media, for disaster recovery reasons. -The best way to create a printable hardcopy of your private key is by +A good way to create a printable hardcopy of your private key is by using the ``paperkey`` software written for this very purpose. See ``man paperkey`` for more details on the output format and its benefits over other solutions. Paperkey should already be packaged for most @@ -224,11 +219,11 @@ key:: $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt -Print out that file (or pipe the output straight to lpr), then take a -pen and write your passphrase on the margin of the paper. **This is -strongly recommended** because the key printout is still encrypted with -that passphrase, and if you ever change it you will not remember what it -used to be when you had created the backup -- *guaranteed*. +Print out that file, then take a pen and write your passphrase on the +margin of the paper. **This is strongly recommended** because the key +printout is still encrypted with that passphrase, and if you ever change +it you will not remember what it used to be when you had created the +backup -- *guaranteed*. Put the resulting printout and the hand-written passphrase into an envelope and store in a secure and well-protected place, preferably away from your @@ -236,10 +231,9 @@ home, such as your bank vault. .. note:: - Your printer is probably no longer a simple dumb device connected to - your parallel port, but since the output is still encrypted with - your passphrase, printing out even to "cloud-integrated" modern - printers should remain a relatively safe operation. + The key is still encrypted with your passphrase, so printing out + even to "cloud-integrated" modern printers should remain a + relatively safe operation. Back up your whole GnuPG directory ---------------------------------- @@ -255,16 +249,17 @@ on these external copies whenever you need to use your Certify key -- such as when making changes to your own key or signing other people's keys after conferences and summits. -Start by getting a small USB "thumb" drive (preferably two!) that you -will use for backup purposes. You will need to encrypt them using LUKS --- refer to your distro's documentation on how to accomplish this. +Start by getting an external media card (preferably two!) that you will +use for backup purposes. You will need to create an encrypted partition +on this device using LUKS -- refer to your distro's documentation on how +to accomplish this. For the encryption passphrase, you can use the same one as on your PGP key. -Once the encryption process is over, re-insert the USB drive and make -sure it gets properly mounted. Copy your entire ``.gnupg`` directory -over to the encrypted storage:: +Once the encryption process is over, re-insert your device and make sure +it gets properly mounted. Copy your entire ``.gnupg`` directory over to +the encrypted storage:: $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup @@ -273,11 +268,10 @@ You should now test to make sure everything still works:: $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] If you don't get any errors, then you should be good to go. Unmount the -USB drive, distinctly label it so you don't blow it away next time you -need to use a random USB drive, and put in a safe place -- but not too -far away, because you'll need to use it every now and again for things -like editing identities, adding or revoking subkeys, or signing other -people's keys. +device, distinctly label it so you don't overwrite it by accident, and +put in a safe place -- but not too far away, because you'll need to use +it every now and again for things like editing identities, adding or +revoking subkeys, or signing other people's keys. Remove the Certify key from your homedir ---------------------------------------- @@ -303,7 +297,7 @@ and store it on offline storage. your GnuPG directory in its entirety. What we are about to do will render your key useless if you do not have a usable backup! -First, identify the keygrip of your Certify key:: +First, identify the "keygrip" of your Certify key:: $ gpg --with-keygrip --list-key [fpr] @@ -328,8 +322,8 @@ Certify key fingerprint). This will correspond directly to a file in your 2222000000000000000000000000000000000000.key 3333000000000000000000000000000000000000.key -All you have to do is simply remove the .key file that corresponds to -the Certify key keygrip:: +It is sufficient to remove the .key file that corresponds to the Certify +key keygrip:: $ cd ~/.gnupg/private-keys-v1.d $ rm 1111000000000000000000000000000000000000.key @@ -372,7 +366,7 @@ GnuPG operation is performed, the keys are loaded into system memory and can be stolen from there by sufficiently advanced malware (think Meltdown and Spectre). -The best way to completely protect your keys is to move them to a +A good way to completely protect your keys is to move them to a specialized hardware device that is capable of smartcard operations. The benefits of smartcards @@ -383,11 +377,11 @@ private keys and performing crypto operations directly on the card itself. Because the key contents never leave the smartcard, the operating system of the computer into which you plug in the hardware device is not able to retrieve the private keys themselves. This is very -different from the encrypted USB storage device we used earlier for -backup purposes -- while that USB device is plugged in and mounted, the +different from the encrypted media storage device we used earlier for +backup purposes -- while that device is plugged in and mounted, the operating system is able to access the private key contents. -Using external encrypted USB media is not a substitute to having a +Using external encrypted media is not a substitute to having a smartcard-capable device. Available smartcard devices @@ -398,29 +392,27 @@ easiest is to get a specialized USB device that implements smartcard functionality. There are several options available: - `Nitrokey Start`_: Open hardware and Free Software, based on FSI - Japan's `Gnuk`_. One of the few available commercial devices that - support ED25519 ECC keys, but offer fewest security features (such as - resistance to tampering or some side-channel attacks). -- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more - tamper-resistant and offers more security features. Pro 2 supports ECC - cryptography (NISTP). + Japan's `Gnuk`_. One of the cheapest options, but offers fewest + security features (such as resistance to tampering or some + side-channel attacks). +- `Nitrokey 3`_: Similar to the Nitrokey Start, but more + tamper-resistant and offers more security features and USB + form-factors. Supports ECC cryptography (ED25519 and NISTP). - `Yubikey 5`_: proprietary hardware and software, but cheaper than - Nitrokey Pro and comes available in the USB-C form that is more useful - with newer laptops. Offers additional security features such as FIDO - U2F, among others, and now finally supports NISTP and ED25519 ECC - keys. + Nitrokey with a similar set of features. Supports ECC cryptography + (ED25519 and NISTP). Your choice will depend on cost, shipping availability in your geographical region, and open/proprietary hardware considerations. .. note:: - If you are listed in MAINTAINERS or have an account at kernel.org, - you `qualify for a free Nitrokey Start`_ courtesy of The Linux + If you are listed in an `M:` entry in MAINTAINERS or have an account at + kernel.org, you `qualify for a free Nitrokey Start`_ courtesy of The Linux Foundation. -.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 -.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 +.. _`Nitrokey Start`: https://www.nitrokey.com/products/nitrokeys +.. _`Nitrokey 3`: https://www.nitrokey.com/products/nitrokeys .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html @@ -455,7 +447,7 @@ the smartcard). You so rarely need to use the Admin PIN, that you will inevitably forget what it is if you do not record it. Getting back to the main card menu, you can also set other values (such -as name, sex, login data, etc), but it's not necessary and will +as name, gender, login data, etc), but it's not necessary and will additionally leak information about your smartcard should you lose it. .. note:: @@ -615,7 +607,7 @@ run:: You can also use a specific date if that is easier to remember (e.g. your birthday, January 1st, or Canada Day):: - $ gpg --quick-set-expire [fpr] 2025-07-01 + $ gpg --quick-set-expire [fpr] 2038-07-01 Remember to send the updated key back to keyservers:: @@ -656,9 +648,9 @@ hundreds of cloned repositories floating around, how does anyone verify that their copy of linux.git has not been tampered with by a malicious third party? -Or what happens if a backdoor is discovered in the code and the "Author" -line in the commit says it was done by you, while you're pretty sure you -had `nothing to do with it`_? +Or what happens if malicious code is discovered in the kernel and the +"Author" line in the commit says it was done by you, while you're pretty +sure you had `nothing to do with it`_? To address both of these issues, Git introduced PGP integration. Signed tags prove the repository integrity by assuring that its contents are @@ -681,8 +673,7 @@ should be used (``[fpr]`` is the fingerprint of your key):: How to work with signed tags ---------------------------- -To create a signed tag, simply pass the ``-s`` switch to the tag -command:: +To create a signed tag, pass the ``-s`` switch to the tag command:: $ git tag -s [tagname] @@ -693,7 +684,7 @@ not been maliciously altered. How to verify signed tags ~~~~~~~~~~~~~~~~~~~~~~~~~ -To verify a signed tag, simply use the ``verify-tag`` command:: +To verify a signed tag, use the ``verify-tag`` command:: $ git verify-tag [tagname] @@ -712,9 +703,9 @@ The merge message will contain something like this:: # gpg: Signature made [...] # gpg: Good signature from [...] -If you are verifying someone else's git tag, then you will need to -import their PGP key. Please refer to the -":ref:`verify_identities`" section below. +If you are verifying someone else's git tag, you will first need to +import their PGP key. Please refer to the ":ref:`verify_identities`" +section below. Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -728,16 +719,16 @@ configuration option:: How to work with signed commits ------------------------------- -It is easy to create signed commits, but it is much more difficult to -use them in Linux kernel development, since it relies on patches sent to -the mailing list, and this workflow does not preserve PGP commit -signatures. Furthermore, when rebasing your repository to match -upstream, even your own PGP commit signatures will end up discarded. For -this reason, most kernel developers don't bother signing their commits -and will ignore signed commits in any external repositories that they -rely upon in their work. +It is also possible to create signed commits, but they have limited +usefulness in Linux kernel development. The kernel contribution workflow +relies on sending in patches, and converting commits to patches does not +preserve git commit signatures. Furthermore, when rebasing your own +repository on a newer upstream, PGP commit signatures will end up +discarded. For this reason, most kernel developers don't bother signing +their commits and will ignore signed commits in any external +repositories that they rely upon in their work. -However, if you have your working git tree publicly available at some +That said, if you have your working git tree publicly available at some git hosting service (kernel.org, infradead.org, ozlabs.org, or others), then the recommendation is that you sign all your git commits even if upstream developers do not directly benefit from this practice. @@ -748,7 +739,7 @@ We recommend this for the following reasons: provenance, even externally maintained trees carrying PGP commit signatures will be valuable for such purposes. 2. If you ever need to re-clone your local repository (for example, - after a disk failure), this lets you easily verify the repository + after reinstalling your system), this lets you verify the repository integrity before resuming your work. 3. If someone needs to cherry-pick your commits, this allows them to quickly verify their integrity before applying them. @@ -756,9 +747,8 @@ We recommend this for the following reasons: Creating signed commits ~~~~~~~~~~~~~~~~~~~~~~~ -To create a signed commit, you just need to pass the ``-S`` flag to the -``git commit`` command (it's capital ``-S`` due to collision with -another flag):: +To create a signed commit, pass the ``-S`` flag to the ``git commit`` +command (it's capital ``-S`` due to collision with another flag):: $ git commit -S @@ -775,7 +765,6 @@ You can tell git to always sign commits:: .. _verify_identities: - How to work with signed patches ------------------------------- @@ -793,6 +782,11 @@ headers (a-la DKIM): Installing and configuring patatt ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + + If you use B4 to send in your patches, patatt is already installed + and integrated into your workflow. + Patatt is packaged for many distributions already, so please check there first. You can also install it from pypi using "``pip install patatt``". @@ -835,9 +829,9 @@ encounters, for example:: How to verify kernel developer identities ========================================= -Signing tags and commits is easy, but how does one go about verifying -that the key used to sign something belongs to the actual kernel -developer and not to a malicious imposter? +Signing tags and commits is straightforward, but how does one go about +verifying that the key used to sign something belongs to the actual +kernel developer and not to a malicious imposter? Configure auto-key-retrieval using WKD and DANE ----------------------------------------------- @@ -872,7 +866,7 @@ don't already have them):: If you have a kernel.org account, then you should `add the kernel.org UID to your key`_ to make WKD more useful to other kernel developers. -.. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key +.. _`add the kernel.org UID to your key`: https://korg.docs.kernel.org/mail.html#adding-a-kernel-org-uid-to-your-pgp-key Web of Trust (WOT) vs. Trust on First Use (TOFU) ------------------------------------------------ @@ -884,7 +878,7 @@ various software makers dictating who should be your trusted certifying entity, PGP leaves this responsibility to each user. Unfortunately, very few people understand how the Web of Trust works. -While it remains an important aspect of the OpenPGP specification, +While it is still an important part of the OpenPGP specification, recent versions of GnuPG (2.2 and above) have implemented an alternative mechanism called "Trust on First Use" (TOFU). You can think of TOFU as "the SSH-like approach to trust." With SSH, the first time you connect @@ -894,8 +888,8 @@ to connect, forcing you to make a decision on whether you choose to trust the changed key or not. Similarly, the first time you import someone's PGP key, it is assumed to be valid. If at any point in the future GnuPG comes across another key with the same identity, both the -previously imported key and the new key will be marked as invalid and -you will need to manually figure out which one to keep. +previously imported key and the new key will be marked for verification +and you will need to manually figure out which one to keep. We recommend that you use the combined TOFU+PGP trust model (which is the new default in GnuPG v2). To set it, add (or modify) the @@ -903,6 +897,8 @@ the new default in GnuPG v2). To set it, add (or modify) the trust-model tofu+pgp +.. _kernel_org_trust_repository: + Using the kernel.org web of trust repository -------------------------------------------- diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst index 1b32430d0cfc..5423fb7d6047 100644 --- a/Documentation/process/maintainer-soc-clean-dts.rst +++ b/Documentation/process/maintainer-soc-clean-dts.rst @@ -17,8 +17,9 @@ Strict DTS DT Schema and dtc Compliance No changes to the SoC platform Devicetree sources (DTS files) should introduce new ``make dtbs_check W=1`` warnings. Warnings in a new board DTS, which are results of issues in an included DTSI file, are considered existing, not new -warnings. The platform maintainers have automation in place which should point -out any new warnings. +warnings. For series split between different trees (DT bindings go via driver +subsystem tree), warnings on linux-next are decisive. The platform maintainers +have automation in place which should point out any new warnings. If a commit introducing new warnings gets accepted somehow, the resulting issues shall be fixed in reasonable time (e.g. within one release) or the diff --git a/Documentation/process/maintainer-soc.rst b/Documentation/process/maintainer-soc.rst index fe9d8bcfbd2b..a3a90a7d4c68 100644 --- a/Documentation/process/maintainer-soc.rst +++ b/Documentation/process/maintainer-soc.rst @@ -10,7 +10,7 @@ Overview The SoC subsystem is a place of aggregation for SoC-specific code. The main components of the subsystem are: -* devicetrees for 32- & 64-bit ARM and RISC-V +* devicetrees (DTS) for 32- & 64-bit ARM and RISC-V * 32-bit ARM board files (arch/arm/mach*) * 32- & 64-bit ARM defconfigs * SoC-specific drivers across architectures, in particular for 32- & 64-bit @@ -57,8 +57,10 @@ Submitting Patches for Given SoC All typical platform related patches should be sent via SoC submaintainers (platform-specific maintainers). This includes also changes to per-platform or -shared defconfigs (scripts/get_maintainer.pl might not provide correct -addresses in such case). +shared defconfigs. Note that scripts/get_maintainer.pl might not provide +correct addresses for the shared defconfig, so ignore its output and manually +create CC-list based on MAINTAINERS file or use something like +``scripts/get_maintainer.pl -f drivers/soc/FOO/``). Submitting Patches to the Main SoC Maintainers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -97,8 +99,8 @@ Perhaps one of the most important things to highlight is that dt-bindings document the ABI between the devicetree and the kernel. Please read Documentation/devicetree/bindings/ABI.rst. -If changes are being made to a devicetree that are incompatible with old -kernels, the devicetree patch should not be applied until the driver is, or an +If changes are being made to a DTS that are incompatible with old +kernels, the DTS patch should not be applied until the driver is, or an appropriate time later. Most importantly, any incompatible changes should be clearly pointed out in the patch description and pull request, along with the expected impact on existing users, such as bootloaders or other operating @@ -114,9 +116,9 @@ coordinating how the changes get merged through different maintainer trees. Usually the branch that includes a driver change will also include the corresponding change to the devicetree binding description, to ensure they are in fact compatible. This means that the devicetree branch can end up causing -warnings in the "make dtbs_check" step. If a devicetree change depends on +warnings in the ``make dtbs_check`` step. If a devicetree change depends on missing additions to a header file in include/dt-bindings/, it will fail the -"make dtbs" step and not get merged. +``make dtbs`` step and not get merged. There are multiple ways to deal with this: @@ -167,8 +169,6 @@ more information on the validation of devicetrees. For new platforms, or additions to existing ones, ``make dtbs_check`` should not add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is required to not add any new warnings. -If in any doubt about a devicetree change, reach out to the devicetree -maintainers. Branches and Pull Requests ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -207,3 +207,13 @@ The subject line of a pull request should begin with "[GIT PULL]" and made using a signed tag, rather than a branch. This tag should contain a short description summarising the changes in the pull request. For more detail on sending pull requests, please see Documentation/maintainer/pull-requests.rst. + +Defconfigs purpose +~~~~~~~~~~~~~~~~~~ + +Defconfigs are primarily used by the kernel developers, because distros have +their own configs. A change adding new CONFIG options to a defconfig should +explain why the kernel developers in general would want such option, e.g. by +providing a name of an upstream-supported machine/board using that new option. +This implies that enabling options in defconfig for non-upstream machines shall +not be accepted. diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 41d5855700cd..b2b14439be22 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -352,7 +352,7 @@ following tag ordering scheme: Changelog text starts here.... so the authorship is preserved. The 'From:' line has to be followed - by a empty newline. If that 'From:' line is missing, then the patch + by an empty newline. If that 'From:' line is missing, then the patch would be attributed to the person who sent (transported, handled) it. The 'From:' line is automatically removed when the patch is applied and does not show up in the final git changelog. It merely affects diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst index bc56dee6d0bc..c18e307ccb56 100644 --- a/Documentation/process/programming-language.rst +++ b/Documentation/process/programming-language.rst @@ -3,10 +3,10 @@ Programming Language ==================== -The kernel is written in the C programming language [c-language]_. -More precisely, the kernel is typically compiled with ``gcc`` [gcc]_ +The Linux kernel is written in the C programming language [c-language]_. +More precisely, it is typically compiled with ``gcc`` [gcc]_ under ``-std=gnu11`` [gcc-c-dialect-options]_: the GNU dialect of ISO C11. -``clang`` [clang]_ is also supported, see docs on +``clang`` [clang]_ is also supported; see documentation on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`. This dialect contains many extensions to the language [gnu-extensions]_, @@ -34,7 +34,7 @@ Please refer to ``include/linux/compiler_attributes.h`` for more information. Rust ---- -The kernel has experimental support for the Rust programming language +The kernel has support for the Rust programming language [rust-language]_ under ``CONFIG_RUST``. It is compiled with ``rustc`` [rustc]_ under ``--edition=2021`` [rust-editions]_. Editions are a way to introduce small changes to the language that are not backwards compatible. diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst index 56c560a00b37..3c51ddde31dd 100644 --- a/Documentation/process/security-bugs.rst +++ b/Documentation/process/security-bugs.rst @@ -5,33 +5,270 @@ Security bugs Linux kernel developers take security very seriously. As such, we'd like to know when a security bug is found so that it can be fixed and -disclosed as quickly as possible. Please report security bugs to the -Linux kernel security team. +disclosed as quickly as possible. -Contact -------- +Preparing your report +--------------------- +Like with any bug report, a security bug report requires a lot of analysis work +from the developers, so the more information you can share about the issue, the +better. Please review the procedure outlined in +Documentation/admin-guide/reporting-issues.rst if you are unclear about what +information is helpful. The following information are absolutely necessary in +**any** security bug report: + + * **affected kernel version range**: with no version indication, your report + will not be processed. A significant part of reports are for bugs that + have already been fixed, so it is extremely important that vulnerabilities + are verified on recent versions (development tree or latest stable + version), at least by verifying that the code has not changed since the + version where it was detected. + + * **description of the problem**: a detailed description of the problem, with + traces showing its manifestation, and why you consider that the observed + behavior as a problem in the kernel, is necessary. + + * **reproducer**: developers will need to be able to reproduce the problem to + consider a fix as effective. This includes both a way to trigger the issue + and a way to confirm it happens. A reproducer with low complexity + dependencies will be needed (source code, shell script, sequence of + instructions, file-system image etc). Binary-only executables are not + accepted. Working exploits are extremely helpful and will not be released + without consent from the reporter, unless they are already public. By + definition if an issue cannot be reproduced, it is not exploitable, thus it + is not a security bug. + + * **conditions**: if the bug depends on certain configuration options, + sysctls, permissions, timing, code modifications etc, these should be + indicated. + +In addition, the following information are highly desirable: + + * **suspected location of the bug**: the file names and functions where the + bug is suspected to be present are very important, at least to help forward + the report to the appropriate maintainers. When not possible (for example, + "system freezes each time I run this command"), the security team will help + identify the source of the bug. + + * **a proposed fix**: bug reporters who have analyzed the cause of a bug in + the source code almost always have an accurate idea on how to fix it, + because they spent a long time studying it and its implications. Proposing + a tested fix will save maintainers a lot of time, even if the fix ends up + not being the right one, because it helps understand the bug. When + proposing a tested fix, please always format it in a way that can be + immediately merged (see Documentation/process/submitting-patches.rst). + This will save some back-and-forth exchanges if it is accepted, and you + will be credited for finding and fixing this issue. Note that in this case + only a ``Signed-off-by:`` tag is needed, without ``Reported-by:`` when the + reporter and author are the same. + + * **mitigations**: very often during a bug analysis, some ways of mitigating + the issue appear. It is useful to share them, as they can be helpful to + keep end users protected during the time it takes them to apply the fix. + +What qualifies as a security bug +-------------------------------- + +It is important that most bugs are handled publicly so as to involve the widest +possible audience and find the best solution. By nature, bugs that are handled +in closed discussions between a small set of participants are less likely to +produce the best possible fix (e.g., risk of missing valid use cases, limited +testing abilities). + +It turns out that the majority of the bugs reported via the security team are +just regular bugs that have been improperly qualified as security bugs due to +a lack of awareness of the Linux kernel's threat model, as described in +Documentation/process/threat-model.rst, and ought to have been sent through +the normal channels described in Documentation/admin-guide/reporting-issues.rst +instead. + +The security list exists for urgent bugs that grant an attacker a capability +they are not supposed to have on a correctly configured production system, and +can be easily exploited, representing an imminent threat to many users. Before +reporting, consider whether the issue actually crosses a trust boundary on such +a system. + +**If you resorted to AI assistance to identify a bug, you must treat it as +public**. While you may have valid reasons to believe it is not, the security +team's experience shows that bugs discovered this way systematically surface +simultaneously across multiple researchers, often on the same day. In this +case, do not publicly share a reproducer, as this could cause unintended harm; +just mention that one is available and maintainers might ask for it privately +if they need it. + +If you are unsure whether an issue qualifies, err on the side of reporting +privately: the security team would rather triage a borderline report than miss +a real vulnerability. Reporting ordinary bugs to the security list, however, +does not make them move faster and consumes triage capacity that other reports +need. + +Identifying contacts +-------------------- + +The most effective way to report a security bug is to send it directly to the +affected subsystem's maintainers and Cc: the Linux kernel security team. Do +not send it to a public list at this stage, unless you have good reasons to +consider the issue as being public or trivial to discover (e.g. result of a +widely available automated vulnerability scanning tool that can be repeated by +anyone, or use of AI-based tools). + +If you're sending a report for issues affecting multiple parts in the kernel, +even if they're fairly similar issues, please send individual messages (think +that maintainers will not all work on the issues at the same time). The only +exception is when an issue concerns closely related parts maintained by the +exact same subset of maintainers, and these parts are expected to be fixed all +at once by the same commit, then it may be acceptable to report them at once. + +One difficulty for most first-time reporters is to figure the right list of +recipients to send a report to. In the Linux kernel, all official maintainers +are trusted, so the consequences of accidentally including the wrong maintainer +are essentially a bit more noise for that person, i.e. nothing dramatic. As +such, a suitable method to figure the list of maintainers (which kernel +security officers use) is to rely on the get_maintainer.pl script, tuned to +only report maintainers. This script, when passed a file name, will look for +its path in the MAINTAINERS file to figure a hierarchical list of relevant +maintainers. Calling it a first time with the finest level of filtering will +most of the time return a short list of this specific file's maintainers:: + + $ ./scripts/get_maintainer.pl --no-l --no-r --pattern-depth 1 \ + drivers/example.c + Developer One <dev1@example.com> (maintainer:example driver) + Developer Two <dev2@example.org> (maintainer:example driver) + +These two maintainers should then receive the message. If the command does not +return anything, it means the affected file is part of a wider subsystem, so we +should be less specific:: + + $ ./scripts/get_maintainer.pl --no-l --no-r drivers/example.c + Developer One <dev1@example.com> (maintainer:example subsystem) + Developer Two <dev2@example.org> (maintainer:example subsystem) + Developer Three <dev3@example.com> (maintainer:example subsystem [GENERAL]) + Developer Four <dev4@example.org> (maintainer:example subsystem [GENERAL]) + +Here, picking the first, most specific ones, is sufficient. When the list is +long, it is possible to produce a comma-delimited e-mail address list on a +single line suitable for use in the To: field of a mailer like this:: + + $ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \ + --no-git-fallback --no-substatus --no-rolestats --no-multiline \ + --pattern-depth 1 drivers/example.c + dev1@example.com, dev2@example.org + +or this for the wider list:: + + $ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \ + --no-git-fallback --no-substatus --no-rolestats --no-multiline \ + drivers/example.c + dev1@example.com, dev2@example.org, dev3@example.com, dev4@example.org + +If at this point you're still facing difficulties spotting the right +maintainers, **and only in this case**, it's possible to send your report to +the Linux kernel security team only. Your message will be triaged, and you +will receive instructions about whom to contact, if needed. Your message may +equally be forwarded as-is to the relevant maintainers. + +Responsible use of AI to find bugs +---------------------------------- + +A significant fraction of bug reports submitted to the security team are +actually the result of code reviews assisted by AI tools. While this can be an +efficient means to find bugs in rarely explored areas, it causes an overload on +maintainers, who are sometimes forced to ignore such reports due to their poor +quality or accuracy. As such, reporters must be particularly cautious about a +number of points which tend to make these reports needlessly difficult to +handle: + + * **Length**: AI-generated reports tend to be excessively long, containing + multiple sections and excessive detail. This makes it difficult to spot + important information such as affected files, versions, and impact. Please + ensure that a clear summary of the problem and all critical details are + presented first. Do not require triage engineers to scan multiple pages of + text. Configure your tools to produce concise, human-style reports. + + * **Formatting**: Most AI-generated reports are littered with Markdown tags. + These decorations complicate the search for important information and do + not survive the quoting processes involved in forwarding or replying. + Please **always convert your report to plain text** without any formatting + decorations before sending it. + + * **Impact Evaluation**: Many AI-generated reports lack an understanding + of the kernel's threat model (see Documentation/process/threat-model.rst) + and go to great lengths inventing theoretical consequences. This adds + noise and complicates triage. Please stick to verifiable facts (e.g., + "this bug permits any user to gain CAP_NET_ADMIN") without enumerating + speculative implications. Have your tool read this documentation as + part of the evaluation process. + + * **Reproducer**: AI-based tools are often capable of generating reproducers. + Please always ensure your tool provides one and **test it thoroughly**. If + the reproducer does not work, or if the tool cannot produce one, the + validity of the report should be seriously questioned. Note that since the + report will be posted to a public list, the reproducer should only be + shared upon maintainers' request. + + * **Propose a Fix**: Many AI tools are actually better at writing code than + evaluating it. Please ask your tool to propose a fix and **test it** before + reporting the problem. If the fix cannot be tested because it relies on + rare hardware or almost extinct network protocols, the issue is likely not + a security bug. In any case, if a fix is proposed, it must adhere to + Documentation/process/submitting-patches.rst and include a 'Fixes:' tag + designating the commit that introduced the bug. + +Failure to consider these points exposes your report to the risk of being +ignored. + +Use common sense when evaluating the report. If the affected file has not been +touched for more than one year and is maintained by a single individual, it is +likely that usage has declined and exposed users are virtually non-existent +(e.g., drivers for very old hardware, obsolete filesystems). In such cases, +there is no need to consume a maintainer's time with an unimportant report. If +the issue is clearly trivial and publicly discoverable, you should report it +directly to the public mailing lists. + +Sending the report +------------------ + +Reports are to be sent over e-mail exclusively. Please use a working e-mail +address, preferably the same that you want to appear in ``Reported-by`` tags +if any. If unsure, send your report to yourself first. + +The security team and maintainers almost always require additional +information beyond what was initially provided in a report and rely on +active and efficient collaboration with the reporter to perform further +testing (e.g., verifying versions, configuration options, mitigations, or +patches). Before contacting the security team, the reporter must ensure +they are available to explain their findings, engage in discussions, and +run additional tests. Reports where the reporter does not respond promptly +or cannot effectively discuss their findings may be abandoned if the +communication does not quickly improve. + +The report must be sent to maintainers. If there are two or fewer +recipients in your message, you must also always Cc: the Linux kernel +security team who will ensure the message is delivered to the proper +people, and will be able to assist small maintainer teams with processes +they may not be familiar with. For larger teams, Cc: the Linux kernel +security team for your first few reports or when seeking specific help, +such as when resending a message which got no response within a week. +Once you have become comfortable with the process for a few reports, it is +no longer necessary to Cc: the security list when sending to large teams. The Linux kernel security team can be contacted by email at <security@kernel.org>. This is a private list of security officers -who will help verify the bug report and develop and release a fix. -If you already have a fix, please include it with your report, as -that can speed up the process considerably. It is possible that the -security team will bring in extra help from area maintainers to -understand and fix the security vulnerability. - -As it is with any bug, the more information provided the easier it -will be to diagnose and fix. Please review the procedure outlined in -'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what -information is helpful. Any exploit code is very helpful and will not -be released without consent from the reporter unless it has already been -made public. - -Please send plain text emails without attachments where possible. +who will help verify the bug report and assist developers working on a fix. +It is possible that the security team will bring in extra help from area +maintainers to understand and fix the security vulnerability. + +Please send **plain text** emails without attachments where possible. It is much harder to have a context-quoted discussion about a complex issue if all the details are hidden away in attachments. Think of it like a :doc:`regular patch submission <../process/submitting-patches>` (even if you don't have a patch yet): describe the problem and impact, list reproduction steps, and follow it with a proposed fix, all in plain text. +Markdown, HTML and RST formatted reports are particularly frowned upon since +they're quite hard to read for humans and encourage to use dedicated viewers, +sometimes online, which by definition is not acceptable for a confidential +security report. Note that some mailers tend to mangle formatting of plain +text by default, please consult Documentation/process/email-clients.rst for +more info. Disclosure and embargoed information ------------------------------------ diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index e531dd504b6c..beb7f94279fd 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -52,7 +52,8 @@ Provide documentation 4) All new module parameters are documented with ``MODULE_PARM_DESC()`` 5) All new userspace interfaces are documented in ``Documentation/ABI/``. - See ``Documentation/ABI/README`` for more information. + See Documentation/admin-guide/abi.rst (or ``Documentation/ABI/README``) + for more information. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. @@ -91,9 +92,12 @@ Build your code fix any issues. 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. + or some other build farm. + Note that testing against architectures of different word sizes + (32- and 64-bit) and different endianness (big- and little-) is effective + in catching various portability issues due to false assumptions on + representable quantity range, data alignment, or endianness, among + others. 3) Newly-added code has been compiled with ``gcc -W`` (use ``make KCFLAGS=-W``). This will generate lots of noise, but is good diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 8fdc0ef3e604..d7290e208e72 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -23,7 +23,7 @@ easier. Some subsystems and maintainer trees have additional information about their workflow and expectations, see -:ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`. +Documentation/process/maintainer-handbooks.rst. Obtain a current source tree ---------------------------- @@ -343,7 +343,7 @@ https://en.wikipedia.org/wiki/Posting_style#Interleaved_style As is frequently quoted on the mailing list:: A: http://en.wikipedia.org/wiki/Top_post - Q: Were do I find info about this thing called top-posting? + Q: Where do I find info about this thing called top-posting? A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing? A: Top-posting. @@ -495,10 +495,10 @@ list archives. A "# Suffix" may also be used in this case to clarify. If a person has had the opportunity to comment on a patch, but has not provided such comments, you may optionally add a ``Cc:`` tag to the patch. -This is the only tag which might be added without an explicit action by the -person it names - but it should indicate that this person was copied on the -patch. This tag documents that potentially interested parties -have been included in the discussion. +This tag documents that potentially interested parties have been included in +the discussion. Note, this is one of only three tags you might be able to use +without explicit permission of the person named (see 'Tagging people requires +permission' below for details). Co-developed-by: states that the patch was co-created by multiple developers; it is used to give attribution to co-authors (in addition to the author @@ -544,9 +544,9 @@ hopefully inspires them to help us again in the future. The tag is intended for bugs; please do not use it to credit feature requests. The tag should be followed by a Closes: tag pointing to the report, unless the report is not available on the web. The Link: tag can be used instead of Closes: if the patch -fixes a part of the issue(s) being reported. Please note that if the bug was -reported in private, then ask for permission first before using the Reported-by -tag. +fixes a part of the issue(s) being reported. Note, the Reported-by tag is one +of only three tags you might be able to use without explicit permission of the +person named (see 'Tagging people requires permission' below for details). A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. This tag informs maintainers that @@ -592,18 +592,19 @@ Both Tested-by and Reviewed-by tags, once received on mailing list from tester or reviewer, should be added by author to the applicable patches when sending next versions. However if the patch has changed substantially in following version, these tags might not be applicable anymore and thus should be removed. -Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned -in the patch changelog (after the '---' separator). +Usually removal of someone's Acked-by, Tested-by or Reviewed-by tags should be +mentioned in the patch changelog with an explanation (after the '---' +separator). A Suggested-by: tag indicates that the patch idea is suggested by the person -named and ensures credit to the person for the idea. Please note that this -tag should not be added without the reporter's permission, especially if the -idea was not posted in a public forum. That said, if we diligently credit our -idea reporters, they will, hopefully, be inspired to help us again in the -future. - -A Fixes: tag indicates that the patch fixes an issue in a previous commit. It -is used to make it easy to determine where a bug originated, which can help +named and ensures credit to the person for the idea: if we diligently credit +our idea reporters, they will, hopefully, be inspired to help us again in the +future. Note, this is one of only three tags you might be able to use without +explicit permission of the person named (see 'Tagging people requires +permission' below for details). + +A Fixes: tag indicates that the patch fixes a bug in a previous commit. It +is used to make it easy to determine where an issue originated, which can help review a bug fix. This tag also assists the stable kernel team in determining which stable kernel versions should receive your fix. This is the preferred method for indicating a bug fixed by the patch. See :ref:`describe_changes` @@ -618,6 +619,31 @@ Finally, while providing tags is welcome and typically very appreciated, please note that signers (i.e. submitters and maintainers) may use their discretion in applying offered tags. +.. _tagging_people: + +Tagging people requires permission +---------------------------------- + +Be careful in the addition of the aforementioned tags to your patches, as all +except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the +person named. For those three implicit permission is sufficient if the person +contributed to the Linux kernel using that name and email address according +to the lore archives or the commit history -- and in case of Reported-by: +and Suggested-by: did the reporting or suggestion in public. Note, +bugzilla.kernel.org is a public place in this sense, but email addresses +used there are private; so do not expose them in tags, unless the person +used them in earlier contributions. + +Using Assisted-by: +------------------ + +If you used any sort of advanced coding tool in the creation of your patch, +you need to acknowledge that use by adding an Assisted-by tag. Failure to +do so may impede the acceptance of your work. Please see +Documentation/process/coding-assistants.rst for details regarding the +acknowledgment of coding assistants. + + .. _the_canonical_patch_format: The canonical patch format @@ -717,6 +743,12 @@ patch in the permanent changelog. If the ``from`` line is missing, then the ``From:`` line from the email header will be used to determine the patch author in the changelog. +The author may indicate their affiliation or the sponsor of the work +by adding the name of an organization to the ``from`` and ``SoB`` lines, +e.g.: + + From: Patch Author (Company) <author@example.com> + Explanation Body ^^^^^^^^^^^^^^^^ @@ -783,7 +815,8 @@ not part of the changelog which gets committed to the git tree. It is additional information for the reviewers. If it's placed above the commit tags, it needs manual interaction to remove it. If it is below the separator line, it gets automatically stripped off when applying the -patch:: +patch. If available, adding links to previous versions of the patch (e.g., +lore.kernel.org archive link) is recommended to help reviewers:: <commit message> ... @@ -792,6 +825,9 @@ patch:: V2 -> V3: Removed redundant helper function V1 -> V2: Cleaned up coding style and addressed review comments + v2: https://lore.kernel.org/bar + v1: https://lore.kernel.org/foo + path/to/file | 5+++-- ... diff --git a/Documentation/process/threat-model.rst b/Documentation/process/threat-model.rst new file mode 100644 index 000000000000..f177b8d3c1ca --- /dev/null +++ b/Documentation/process/threat-model.rst @@ -0,0 +1,235 @@ +The Linux Kernel threat model +============================= + +There are a lot of assumptions regarding what the kernel does and does not +protect against. These assumptions tend to cause confusion for bug reports +(:doc:`security-related ones <security-bugs>` vs :doc:`non-security ones +<../admin-guide/reporting-issues>`), and can complicate security enforcement +when the responsibilities for some boundaries is not clear between the kernel, +distros, administrators and users. + +This document tries to clarify the responsibilities of the kernel in this +domain. + +The kernel's responsibilities +----------------------------- + +The kernel abstracts access to local hardware resources and to remote systems +in a way that allows multiple local users to get a fair share of the available +resources granted to them, and, when the underlying hardware permits, to assign +a level of confidentiality to their communications and to the data they are +processing or storing. + +The kernel assumes that the underlying hardware behaves according to its +specifications. This includes the integrity of the CPU's instruction set, the +transparency of the branch prediction unit and the cache units, the consistency +of the Memory Management Unit (MMU), the isolation of DMA-capable peripherals +(e.g., via IOMMU), state transitions in controllers, ranges of values read from +registers, the respect of documented hardware limitations, etc. + +When hardware fails to maintain its specified isolation (e.g., CPU bugs, +side-channels, hardware response to unexpected inputs), the kernel will usually +attempt to implement reasonable mitigations. These are best-effort measures +intended to reduce the attack surface or elevate the cost of an attack within +the limits of the hardware's facilities; they do not constitute a +kernel-provided safety guarantee. + +Users always perform their activities under the authority of an administrator +who is able to grant or deny various types of permissions that may affect how +users benefit from available resources, or the level of confidentiality of +their activities. Administrators may also delegate all or part of their own +permissions to some users, particularly via capabilities but not only. All this +is performed via configuration (sysctl, file-system permissions etc). + +The Linux Kernel applies a certain collection of default settings that match +its threat model. Distros have their own threat model and will come with their +own configuration presets, that the administrator may have to adjust to better +suit their expectations (relax or restrict). + +By default, the Linux Kernel guarantees the following protections when running +on common processors featuring privilege levels and memory management units: + +* **User-based isolation**: an unprivileged user may restrict access to their + own data from other unprivileged users running on the same system. This + includes: + + * stored data, via file system permissions + * in-memory data (pages are not accessible by default to other users) + * process activity (ptrace is not permitted to other users) + * inter-process communication (other users may not observe data exchanged via + UNIX domain sockets or other IPC mechanisms). + * network communications within the same or with other systems + +* **Capability-based protection**: + + * users not having elevated capabilities (including but not limited to + CAP_SYS_ADMIN) may not alter the + kernel's configuration, memory nor state, change other users' view of the + file system layout, grant any user capabilities they do not have, nor + affect the system's availability (shutdown, reboot, panic, hang, or making + the system unresponsive via unbounded resource exhaustion). + * users not having the ``CAP_NET_ADMIN`` capability may not alter the network + configuration, intercept nor spoof network communications from other users + nor systems. + * users not having ``CAP_SYS_PTRACE`` may not observe other users' processes + activities. + +When ``CONFIG_USER_NS`` is set, the kernel also permits unprivileged users to +create their own user namespace in which they have all capabilities, but with a +number of restrictions (they may not perform actions that have impacts on the +initial user namespace, such as changing time, loading modules or mounting +block devices). Please refer to ``user_namespaces(7)`` for more details, the +possibilities of user namespaces are not covered in this document. + +The kernel also offers a lot of troubleshooting and debugging facilities, which +can constitute attack vectors when placed in wrong hands. While some of them +are designed to be accessible to regular local users with a low risk (e.g. +kernel logs via ``/proc/kmsg``), some would expose enough information to +represent a risk in most places and the decision to expose them is under the +administrator's responsibility (perf events, traces), and others are not +designed to be accessed by non-privileged users (e.g. debugfs). Access to these +facilities by a user who has been explicitly granted permission by an +administrator does not constitute a security breach. + +Bugs that permit to violate the principles above constitute security breaches. +However, bugs that permit one violation only once another one was already +achieved are only weaknesses. The kernel applies a number of self-protection +measures whose purpose is to avoid crossing a security boundary when certain +classes of bugs are found, but a failure of these extra protections do not +constitute a vulnerability alone. + +What does not constitute a security bug +--------------------------------------- + +In the Linux kernel's threat model, the following classes of problems are +**NOT** considered as Linux Kernel security bugs. However, when it is believed +that the kernel could do better, they should be reported, so that they can be +reviewed and fixed where reasonably possible, but they will be handled as any +regular bug: + +* **Configuration**: + + * outdated kernels and particularly end-of-life branches are out of the scope + of the kernel's threat model: administrators are responsible for keeping + their system up to date. For a bug to qualify as a security bug, it must be + demonstrated that it affects actively maintained versions. + + * build-level: changes to the kernel configuration that are explicitly + documented as lowering the security level (e.g. ``CONFIG_NOMMU``), or + targeted at developers only. + + * OS-level: changes to command line parameters, sysctls, filesystem + permissions, user capabilities, exposure of privileged interfaces, that + explicitly increase exposure by either offering non-default access to + unprivileged users, or reduce the kernel's ability to enforce some + protections or mitigations. Example: write access to procfs or debugfs. + + * issues triggered only when using features intended for development or + debugging (e.g., LOCKDEP, KASAN, FAULT_INJECTION): these features are known + to introduce overhead and potential instability and are not intended for + production use. + + * issues affecting drivers exposed under CONFIG_STAGING, as well as features + marked EXPERIMENTAL in the configuration. + + * loading of explicitly insecure/broken/staging modules, and generally any + using any subsystem marked as experimental or not intended for production + use. + + * running out-of-tree modules or unofficial kernel forks; these should be + reported to the relevant vendor. + +* **Excess of initial privileges**: + + * actions performed by a user already possessing the privileges required to + perform that action or modify that state (e.g. ``CAP_SYS_ADMIN``, + ``CAP_NET_ADMIN``, ``CAP_SYS_RAWIO``, ``CAP_SYS_MODULE`` with no further + boundary being crossed). + + * actions performed in user namespace that do not bypass the restrictions + imposed to the initial user (e.g. ptrace usage, signal delivery, resource + usage, access to FS/device/sysctl/memory, network binding, system/network + configuration etc). + + * anything performed by the root user in the initial namespace (e.g. kernel + oops when writing to a privileged device). + +* **Out of production use**: + + This covers theoretical/probabilistic attacks that rely on laboratory + conditions with zero system noise, or those requiring an unrealistic number + of attempts (e.g., billions of trials) that would be detected by standard + system monitoring long before success, such as: + + * prediction of random numbers that only works in a totally silent + environment (such as IP ID, TCP ports or sequence numbers that can only be + guessed in a lab). + + * activity observation and information leaks based on probabilistic + approaches that are prone to measurement noise and not realistically + reproducible on a production system. + + * issues that can only be triggered by heavy attacks (e.g. brute force) whose + impact on the system makes it unlikely or impossible to remain undetected + before they succeed (e.g. consuming all memory before succeeding). + + * problems seen only under development simulators, emulators, or combinations + that do not exist on real systems at the time of reporting (issues + involving tens of millions of threads, tens of thousands of CPUs, + unrealistic CPU frequencies, RAM sizes or disk capacities, network speeds. + + * issues whose reproduction requires hardware modification or emulation, + including fake USB devices that pretend to be another one. + + * as well as issues that can be triggered at a cost that is orders of + magnitude higher than the expected benefits (e.g. fully functional keyboard + emulator only to retrieve 7 uninitialized bytes in a structure, or + brute-force method involving millions of connection attempts to guess a + port number). + +* **Hardening failures**: + + * ability to bypass some of the kernel's hardening measures with no + demonstrable exploit path (e.g. ASLR bypass, events timing or probing with + no demonstrable consequence). These are just weaknesses, not + vulnerabilities. + + * missing argument checks and failure to report certain errors with no + immediate consequence. + +* **Random information leaks**: + + This concerns information leaks of small data parts that happen to be there + and that cannot be chosen by the attacker, or face access restrictions: + + * structure padding reported by syscalls or other interfaces. + + * identifiers, partial data, non-terminated strings reported in error + messages. + + * Leaks of kernel memory addresses/pointers do not constitute an immediately + exploitable vector and are not security bugs, though they must be reported + and fixed. + +* **Crafted file system images**: + + * bugs triggered by mounting a corrupted or maliciously crafted file system + image are generally not security bugs, as the kernel assumes the underlying + storage media is under the administrator's control, unless the filesystem + driver is specifically documented as being hardened against untrusted media. + + * issues that are resolved, mitigated, or detected by running a filesystem + consistency check (fsck) on the image prior to mounting. + +* **Physical access**: + + Issues that require physical access to the machine, hardware modification, or + the use of specialized hardware (e.g., logic analyzers, DMA-attack tools over + PCI-E/Thunderbolt) are out of scope unless the system is explicitly + configured with technologies meant to defend against such attacks + (e.g. IOMMU). + +* **Functional and performance regressions**: + + Any issue that can be mitigated by setting proper permissions and limits + doesn't qualify as a security bug. |