* Re: [PATCH 0/2] Improve the crypto library documentation
From: Jonathan Corbet @ 2026-04-17 7:22 UTC (permalink / raw)
To: Eric Biggers, linux-crypto
Cc: linux-kernel, Ard Biesheuvel, Jason A . Donenfeld, Herbert Xu,
linux-doc, Mauro Carvalho Chehab, Randy Dunlap, Eric Biggers
In-Reply-To: <20260417065529.64925-1-ebiggers@kernel.org>
Eric Biggers <ebiggers@kernel.org> writes:
> While the crypto library already has a lot of kerneldoc, it's not being
> included in the HTML or PDF documentation. Update Documentation/crypto/
> to include it, and also add a high-level overview of the library.
>
> I'd like to take this series via the libcrypto tree for 7.1.
>
> Eric Biggers (2):
> docs: kdoc: Expand 'at_least' when creating parameter list
> lib/crypto: docs: Add rst documentation to Documentation/crypto/
>
> Documentation/crypto/index.rst | 2 +-
> .../crypto/libcrypto-blockcipher.rst | 19 ++
> Documentation/crypto/libcrypto-hash.rst | 86 +++++++++
> Documentation/crypto/libcrypto-signature.rst | 11 ++
> Documentation/crypto/libcrypto-utils.rst | 6 +
> Documentation/crypto/libcrypto.rst | 167 ++++++++++++++++++
> Documentation/crypto/sha3.rst | 2 +
> tools/lib/python/kdoc/kdoc_parser.py | 5 +
> 8 files changed, 297 insertions(+), 1 deletion(-)
I think this is great - sorry about the snide comment on LWN, but this
will make this documentation much more accessible.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 1/2] docs: kdoc: Expand 'at_least' when creating parameter list
From: Jonathan Corbet @ 2026-04-17 7:18 UTC (permalink / raw)
To: Eric Biggers, linux-crypto
Cc: linux-kernel, Ard Biesheuvel, Jason A . Donenfeld, Herbert Xu,
linux-doc, Mauro Carvalho Chehab, Randy Dunlap, Eric Biggers
In-Reply-To: <20260417065529.64925-2-ebiggers@kernel.org>
Eric Biggers <ebiggers@kernel.org> writes:
> sphinx doesn't know that the kernel headers do:
>
> #define at_least static
>
> Do this replacement before declarations are passed to it.
>
> This prevents errors like the following from appearing once the
> lib/crypto/ kerneldoc is wired up to the sphinx build:
>
> linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
> Error in declarator or parameters
> Invalid C declaration: Expected ']' in end of array operator. [error at 59]
> void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE])
>
> Signed-off-by: Eric Biggers <ebiggers@kernel.org>
> ---
> tools/lib/python/kdoc/kdoc_parser.py | 5 +++++
> 1 file changed, 5 insertions(+)
>
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index 74af7ae47aa47..f982db7fddac2 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -437,10 +437,15 @@ class KernelDoc:
>
> for arg in args.split(splitter):
> # Ignore argument attributes
> arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
>
> + # Replace '[at_least ' with '[static '. This allows sphinx to parse
> + # array parameter declarations like 'char A[at_least 4]', where
> + # 'at_least' is #defined to 'static' by the kernel headers.
> + arg = KernRe(r'\[at_least ').sub('[static ', arg)
> +
This could be a regular string replacement rather than a regex. Not
something I'm willing to dig in my heels on, though... so if you want to
push this, either way:
Acked-by: Jonathan Corbet <corbet@lwn.net>
Thanks,
jon
^ permalink raw reply
* [PATCH 2/2] lib/crypto: docs: Add rst documentation to Documentation/crypto/
From: Eric Biggers @ 2026-04-17 6:55 UTC (permalink / raw)
To: linux-crypto
Cc: linux-kernel, Ard Biesheuvel, Jason A . Donenfeld, Herbert Xu,
linux-doc, Jonathan Corbet, Mauro Carvalho Chehab, Randy Dunlap,
Eric Biggers
In-Reply-To: <20260417065529.64925-1-ebiggers@kernel.org>
Add a documentation file Documentation/crypto/libcrypto.rst which
provides a high-level overview of lib/crypto/.
Also add several sub-pages which include the kerneldoc for the
algorithms that have it. This makes the existing, quite extensive
kerneldoc start being included in the HTML documentation.
Note that the intent is very much *not* that everyone has to read these
Documentation/ files. The library is intended to be straightforward and
use familiar conventions; generally it should be possible to dive right
into the kerneldoc. You shouldn't need to read a lot of documentation
to just call `sha256()`, for example, or to run the unit tests if you're
already familiar with KUnit. (This differs from the traditional crypto
API which has a larger barrier to entry.)
Nevertheless, this seems worth adding. Hopefully it is useful and makes
LWN no longer consider the library to be "meticulously undocumented".
Signed-off-by: Eric Biggers <ebiggers@kernel.org>
---
Documentation/crypto/index.rst | 2 +-
.../crypto/libcrypto-blockcipher.rst | 19 ++
Documentation/crypto/libcrypto-hash.rst | 86 +++++++++
Documentation/crypto/libcrypto-signature.rst | 11 ++
Documentation/crypto/libcrypto-utils.rst | 6 +
Documentation/crypto/libcrypto.rst | 167 ++++++++++++++++++
Documentation/crypto/sha3.rst | 2 +
7 files changed, 292 insertions(+), 1 deletion(-)
create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst
create mode 100644 Documentation/crypto/libcrypto-hash.rst
create mode 100644 Documentation/crypto/libcrypto-signature.rst
create mode 100644 Documentation/crypto/libcrypto-utils.rst
create mode 100644 Documentation/crypto/libcrypto.rst
diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst
index 4ee667c446f99..705f186d662ba 100644
--- a/Documentation/crypto/index.rst
+++ b/Documentation/crypto/index.rst
@@ -11,10 +11,11 @@ for cryptographic use cases, as well as programming examples.
.. toctree::
:caption: Table of contents
:maxdepth: 2
+ libcrypto
intro
api-intro
architecture
async-tx-api
@@ -25,6 +26,5 @@ for cryptographic use cases, as well as programming examples.
api
api-samples
descore-readme
device_drivers/index
krb5
- sha3
diff --git a/Documentation/crypto/libcrypto-blockcipher.rst b/Documentation/crypto/libcrypto-blockcipher.rst
new file mode 100644
index 0000000000000..dd5ce2f8b5151
--- /dev/null
+++ b/Documentation/crypto/libcrypto-blockcipher.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Block ciphers
+=============
+
+AES
+---
+
+Support for the AES block cipher.
+
+.. kernel-doc:: include/crypto/aes.h
+
+DES
+---
+
+Support for the DES block cipher. This algorithm is obsolete and is supported
+only for backwards compatibility.
+
+.. kernel-doc:: include/crypto/des.h
diff --git a/Documentation/crypto/libcrypto-hash.rst b/Documentation/crypto/libcrypto-hash.rst
new file mode 100644
index 0000000000000..ccffe8c3398eb
--- /dev/null
+++ b/Documentation/crypto/libcrypto-hash.rst
@@ -0,0 +1,86 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Hash functions, MACs, and XOFs
+==============================
+
+BLAKE2s
+-------
+
+Support for the BLAKE2s cryptographic hash function.
+
+.. kernel-doc:: include/crypto/blake2s.h
+
+BLAKE2b
+-------
+
+Support for the BLAKE2b cryptographic hash function.
+
+.. kernel-doc:: include/crypto/blake2b.h
+
+AES-CMAC and AES-XCBC
+---------------------
+
+Support for the AES-CMAC and AES-XCBC message authentication codes.
+
+.. kernel-doc:: include/crypto/aes-cbc-macs.h
+
+GHASH and POLYVAL
+-----------------
+
+Support for the GHASH and POLYVAL universal hash functions. These algorithms
+are used only as internal components of other algorithms.
+
+.. kernel-doc:: include/crypto/gf128hash.h
+
+MD5
+---
+
+Support for the MD5 cryptographic hash function and HMAC-MD5. This algorithm is
+obsolete and is supported only for backwards compatibility.
+
+.. kernel-doc:: include/crypto/md5.h
+
+NH
+--
+
+Support for the NH universal hash function. This algorithm is used only as an
+internal component of other algorithms.
+
+.. kernel-doc:: include/crypto/nh.h
+
+Poly1305
+--------
+
+Support for the Poly1305 universal hash function. This algorithm is used only
+as an internal component of other algorithms.
+
+.. kernel-doc:: include/crypto/poly1305.h
+
+SHA-1
+-----
+
+Support for the SHA-1 cryptographic hash function and HMAC-SHA1. This algorithm
+is obsolete and is supported only for backwards compatibility.
+
+.. kernel-doc:: include/crypto/sha1.h
+
+SHA-2
+-----
+
+Support for the SHA-2 family of cryptographic hash functions, including SHA-224,
+SHA-256, SHA-384, and SHA-512. Also support for their corresponding HMACs:
+HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512.
+
+.. kernel-doc:: include/crypto/sha2.h
+
+SHA-3
+-----
+
+The SHA-3 functions are documented in :ref:`sha3`.
+
+SM3
+---
+
+Support for the SM3 cryptographic hash function.
+
+.. kernel-doc:: include/crypto/sm3.h
diff --git a/Documentation/crypto/libcrypto-signature.rst b/Documentation/crypto/libcrypto-signature.rst
new file mode 100644
index 0000000000000..e80d59fa51b6a
--- /dev/null
+++ b/Documentation/crypto/libcrypto-signature.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Digital signature algorithms
+============================
+
+ML-DSA
+------
+
+Support for the ML-DSA digital signature algorithm.
+
+.. kernel-doc:: include/crypto/mldsa.h
diff --git a/Documentation/crypto/libcrypto-utils.rst b/Documentation/crypto/libcrypto-utils.rst
new file mode 100644
index 0000000000000..9d833f47ed390
--- /dev/null
+++ b/Documentation/crypto/libcrypto-utils.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Utility functions
+=================
+
+.. kernel-doc:: include/crypto/utils.h
diff --git a/Documentation/crypto/libcrypto.rst b/Documentation/crypto/libcrypto.rst
new file mode 100644
index 0000000000000..32bb61df9e4c3
--- /dev/null
+++ b/Documentation/crypto/libcrypto.rst
@@ -0,0 +1,167 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+==============
+Crypto library
+==============
+
+``lib/crypto/`` provides faster and easier access to cryptographic algorithms
+than the traditional crypto API.
+
+Each cryptographic algorithm is supported via a set of dedicated functions.
+"Crypto agility", where needed, is left to calling code.
+
+The crypto library functions are intended to be boring and straightforward, and
+to follow familiar conventions. Their primary documentation is their (fairly
+extensive) kerneldoc. This page just provides some extra high-level context.
+
+Note that the crypto library is not entirely new. ``lib/`` has contained some
+crypto functions since 2005. Rather, it's just an approach that's been expanded
+over time as it's been found to work well. It also largely just matches how the
+kernel already does things elsewhere.
+
+Scope and intended audience
+===========================
+
+The crypto library documentation is primarily meant for kernel developers who
+need to use a particular cryptographic algorithm(s) in kernel code. For
+example, "I just need to compute a SHA-256 hash." A secondary audience is
+developers working on the crypto algorithm implementations themselves.
+
+If you're looking for more general information about cryptography, like the
+differences between the different crypto algorithms or how to select an
+appropriate algorithm, you should refer to external sources which cover that
+type of information much more comprehensively. If you need help selecting
+algorithms for a new kernel feature that doesn't already have its algorithms
+predefined, please reach out to ``linux-crypto@vger.kernel.org`` for advice.
+
+Code organization
+=================
+
+- ``lib/crypto/*.c``: the crypto algorithm implementations
+
+- ``lib/crypto/$(SRCARCH)/``: architecture-specific code for crypto algorithms.
+ It is here rather than somewhere in ``arch/`` partly because this allows
+ generic and architecture-optimized code to be easily built into a single
+ loadable module (when the algorithm is set to 'm' in the kconfig).
+
+- ``lib/crypto/tests/``: KUnit tests for the crypto algorithms
+
+- ``include/crypto/``: crypto headers, both for the crypto library and the
+ traditional crypto API
+
+Generally, there is one kernel module per algorithm. Sometimes related
+algorithms are grouped into one module. There is intentionally no common
+framework, though there are some utility functions that multiple algorithms use.
+
+Each algorithm module is controlled by a tristate kconfig symbol
+``CRYPTO_LIB_$(ALGORITHM)``. As is the norm for library functions in the
+kernel, these are hidden symbols which don't show up in the kconfig menu.
+Instead, they are just selected by all the kconfig symbols that need them.
+
+Many of the algorithms have multiple implementations: a generic implementation
+and architecture-optimized implementation(s). Each module initialization
+function, or initcall in the built-in case, automatically enables the best
+implementation based on the available CPU features.
+
+Note that the crypto library doesn't use the ``crypto/``,
+``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories. These
+directories are used by the traditional crypto API. When possible, algorithms
+in the traditional crypto API are implemented by calls into the library.
+
+Advantages
+==========
+
+Some of the advantages of the library over the traditional crypto API are:
+
+- The library functions tend to be much easier to use. For example, a hash
+ value can be computed using only a single function call.
+
+- The library functions are usually faster, especially for short inputs. They
+ call the crypto algorithms directly without inefficient indirect calls, memory
+ allocations, string parsing, lookups in an algorithm registry, and other
+ unnecessary API overhead. Architecture-optimized code is enabled by default.
+
+- Most of the library functions return void and never fail. Thus, in most cases
+ callers don't need to handle errors.
+
+- Most of the library functions operate on standard virtual addresses, rather
+ than scatterlists which are difficult and less efficient to work with.
+
+- The library functions use standard link-time dependencies instead of
+ error-prone dynamic loading by name.
+
+- The library focuses on the approach that works the best on the vast majority
+ of systems: CPU-based implementations of the crypto algorithms, utilizing
+ on-CPU acceleration (such as AES instructions) when available.
+
+- The library uses standard KUnit tests, rather than custom ad-hoc tests.
+
+- The library tends to have higher assurance implementations of the crypto
+ algorithms. This is both due to its simpler design and because more of its
+ code is being regularly tested.
+
+- The library supports features that don't fit into the rigid framework of the
+ traditional crypto API, for example interleaved hashing and XOFs.
+
+When to use it
+==============
+
+In-kernel users should use the library (rather than the traditional crypto API)
+whenever possible. Many subsystems have already been converted. It usually
+simplifies their code significantly and improves performance.
+
+Some kernel features allow userspace to provide an arbitrary string that selects
+an arbitrary algorithm from the traditional crypto API by name. These features
+generally will have to keep using the traditional crypto API for backwards
+compatibility.
+
+Note: new kernel features should not support every algorithm, but rather make a
+deliberate choice about what algorithm(s) to support. History has shown that
+making a deliberate, thoughtful choice greatly simplifies code maintenance,
+reduces the chance for mistakes (such as using an obsolete, insecure, or
+inappropriate algorithm), and makes your feature easier to use.
+
+Testing
+=======
+
+The crypto library uses standard KUnit tests. Like many of the kernel's other
+KUnit tests, they are included in the set of tests that are run by
+``tools/testing/kunit/kunit.py run --alltests``.
+
+A ``.kunitconfig`` file is also provided to run just the crypto library tests.
+For example, here's how to run them in user-mode Linux:
+
+.. code-block::
+
+ tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/
+
+Many of the crypto algorithms have architecture-optimized implementations.
+Testing those requires building an appropriate kernel and running the tests
+either in QEMU or on appropriate hardware. Here's one example with QEMU:
+
+.. code-block::
+
+ tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ --arch=arm64 --make_options LLVM=1
+
+Depending on the code being tested, flags may need to be provided to QEMU to
+emulate the correct type of hardware for the code to be reached.
+
+Since correctness is essential in cryptographic code, new architecture-optimized
+code is accepted only if it can be tested in QEMU.
+
+Note: the crypto library also includes FIPS 140 self-tests. These are
+lightweight, are designed specifically to meet FIPS 140 requirements, and exist
+*only* to meet those requirements. Normal testing done by kernel developers and
+integrators should use the much more comprehensive KUnit tests instead.
+
+API documentation
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ libcrypto-blockcipher
+ libcrypto-hash
+ libcrypto-signature
+ libcrypto-utils
+ sha3
diff --git a/Documentation/crypto/sha3.rst b/Documentation/crypto/sha3.rst
index 37640f295118b..250669c98f6ba 100644
--- a/Documentation/crypto/sha3.rst
+++ b/Documentation/crypto/sha3.rst
@@ -1,7 +1,9 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
+.. _sha3:
+
==========================
SHA-3 Algorithm Collection
==========================
.. contents::
--
2.53.0
^ permalink raw reply related
* [PATCH 1/2] docs: kdoc: Expand 'at_least' when creating parameter list
From: Eric Biggers @ 2026-04-17 6:55 UTC (permalink / raw)
To: linux-crypto
Cc: linux-kernel, Ard Biesheuvel, Jason A . Donenfeld, Herbert Xu,
linux-doc, Jonathan Corbet, Mauro Carvalho Chehab, Randy Dunlap,
Eric Biggers
In-Reply-To: <20260417065529.64925-1-ebiggers@kernel.org>
sphinx doesn't know that the kernel headers do:
#define at_least static
Do this replacement before declarations are passed to it.
This prevents errors like the following from appearing once the
lib/crypto/ kerneldoc is wired up to the sphinx build:
linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected ']' in end of array operator. [error at 59]
void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE])
Signed-off-by: Eric Biggers <ebiggers@kernel.org>
---
tools/lib/python/kdoc/kdoc_parser.py | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 74af7ae47aa47..f982db7fddac2 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -437,10 +437,15 @@ class KernelDoc:
for arg in args.split(splitter):
# Ignore argument attributes
arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
+ # Replace '[at_least ' with '[static '. This allows sphinx to parse
+ # array parameter declarations like 'char A[at_least 4]', where
+ # 'at_least' is #defined to 'static' by the kernel headers.
+ arg = KernRe(r'\[at_least ').sub('[static ', arg)
+
# Strip leading/trailing spaces
arg = arg.strip()
arg = KernRe(r'\s+').sub(' ', arg, count=1)
if arg.startswith('#'):
--
2.53.0
^ permalink raw reply related
* [PATCH 0/2] Improve the crypto library documentation
From: Eric Biggers @ 2026-04-17 6:55 UTC (permalink / raw)
To: linux-crypto
Cc: linux-kernel, Ard Biesheuvel, Jason A . Donenfeld, Herbert Xu,
linux-doc, Jonathan Corbet, Mauro Carvalho Chehab, Randy Dunlap,
Eric Biggers
While the crypto library already has a lot of kerneldoc, it's not being
included in the HTML or PDF documentation. Update Documentation/crypto/
to include it, and also add a high-level overview of the library.
I'd like to take this series via the libcrypto tree for 7.1.
Eric Biggers (2):
docs: kdoc: Expand 'at_least' when creating parameter list
lib/crypto: docs: Add rst documentation to Documentation/crypto/
Documentation/crypto/index.rst | 2 +-
.../crypto/libcrypto-blockcipher.rst | 19 ++
Documentation/crypto/libcrypto-hash.rst | 86 +++++++++
Documentation/crypto/libcrypto-signature.rst | 11 ++
Documentation/crypto/libcrypto-utils.rst | 6 +
Documentation/crypto/libcrypto.rst | 167 ++++++++++++++++++
Documentation/crypto/sha3.rst | 2 +
tools/lib/python/kdoc/kdoc_parser.py | 5 +
8 files changed, 297 insertions(+), 1 deletion(-)
create mode 100644 Documentation/crypto/libcrypto-blockcipher.rst
create mode 100644 Documentation/crypto/libcrypto-hash.rst
create mode 100644 Documentation/crypto/libcrypto-signature.rst
create mode 100644 Documentation/crypto/libcrypto-utils.rst
create mode 100644 Documentation/crypto/libcrypto.rst
base-commit: 3cd8b194bf3428dfa53120fee47e827a7c495815
--
2.53.0
^ permalink raw reply
* Re: [PATCH V10 00/10] famfs: port into fuse
From: Gregory Price @ 2026-04-17 6:46 UTC (permalink / raw)
To: Joanne Koong
Cc: John Groves, Darrick J. Wong, Miklos Szeredi, Bernd Schubert,
John Groves, Dan Williams, Bernd Schubert, Alison Schofield,
John Groves, Jonathan Corbet, Shuah Khan, Vishal Verma,
Dave Jiang, Matthew Wilcox, Jan Kara, Alexander Viro,
David Hildenbrand, Christian Brauner, Randy Dunlap, Jeff Layton,
Amir Goldstein, Jonathan Cameron, Stefan Hajnoczi, Josef Bacik,
Bagas Sanjaya, Chen Linxuan, James Morse, Fuad Tabba,
Sean Christopherson, Shivank Garg, Ackerley Tng, Aravind Ramesh,
Ajay Joshi, venkataravis@micron.com, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, nvdimm@lists.linux.dev,
linux-cxl@vger.kernel.org, linux-fsdevel@vger.kernel.org, djbw
In-Reply-To: <CAJnrk1ad6t6CJV+xnXwhoNHrHYA3htuaVdDq47FeT60cPBzj7g@mail.gmail.com>
On Thu, Apr 16, 2026 at 06:24:02PM -0700, Joanne Koong wrote:
> On Thu, Apr 16, 2026 at 1:14 PM Gregory Price <gourry@gourry.net> wrote:
> >
> > I worry that this discussion is going to turn towards implementing a
> > solution grounded in parsing arbitrary formats and how to store them,
> > and that is completely detached from why FAMFS went this route in the
> > first place.
> >
> > I question whether the actual issue here lies in the interface APPEARING
> > more general purpose than it actually is - and therefore inviting
> > attempts to over-genericize it.
>
> Would you mind clarifying this part? Are you saying that the interface
> and logic is *already* generic and usable for other dax-backed
> servers, just that everything is *named* famfs but it's not really
> famfs specific?
Yes.
If you just find/replace "famfs" with "dax_iomap", the structures
here don't really seem all *that* crazy specific - they're just
optimized for memory speeds instead of I/O.
There is a circular nature to this - FAMFS figured it out first, in
what we think is a reasonably generic way, but we can't know for sure.
John, Dan, and Darrick have all proposed reasonable ways to hedge
against the obvious fact the interface will not be perfect - which
incorporates your BPF proposal along with a reasonably straight forward
deprecation path that's not always possible in other arenas.
All that while solving a real (and novel) problem.
That's actually pretty damn cool.
I would urge you to consider these proposals earnestly.
~Gregory
^ permalink raw reply
* Re: [PATCH 0/8] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-17 6:18 UTC (permalink / raw)
To: Randy Dunlap
Cc: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley, linux-doc, linux-kernel, linux-riscv, workflows,
Alexandre Ghiti, Shuah Khan, Dan Williams
In-Reply-To: <c325d85e-98d2-4e35-b7e7-7bb4d6ee77aa@infradead.org>
On Thu, 16 Apr 2026 14:32:04 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
> On 4/16/26 1:00 AM, Mauro Carvalho Chehab wrote:
> > On Wed, 15 Apr 2026 13:41:16 -0700
> > Randy Dunlap <rdunlap@infradead.org> wrote:
> >
> >> Hi Mauro,
> >>
> >> Thanks for tackling this issue.
> >>
> >> On 4/15/26 1:52 AM, Mauro Carvalho Chehab wrote:
> >>> Date: Tue, 14 Apr 2026 16:29:03 +0200
> >>> From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >>> To: Albert Ou <aou@eecs.berkeley.edu>, Jonathan Corbet <corbet@lwn.net>, Dan Williams <djbw@kernel.org>, Mauro Carvalho Chehab <mchehab@kernel.org>, Palmer Dabbelt <palmer@dabbelt.com>, Paul Walmsley <pjw@kernel.org>
> >>> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Randy Dunlap <rdunlap@infradead.org>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-riscv@lists.infradead.org, workflows@vger.kernel.org, Alexandre Ghiti <alex@ghiti.fr>, Shuah Khan <skhan@linuxfoundation.org>
> >>> Message-ID: <cover.1776176108.git.mchehab+huawei@kernel.org>
> >>>
> >>> Hi Dan/Jon,
> >>>
> >>> This patch series change the way maintainer entry profile links
> >>> are added to the documentation. Instead of having an entry for
> >>> each of them at an ReST file, get them from MAINTAINERS content.
> >>>
> >>> That should likely make easier to maintain, as there will be a single
> >>> point to place all such profiles.
> >>>
> >>> On this version, I added Dan's text to patch 4.
> >>>
> >>> I also added a couple of other patches to improve its output. While
> >>> I could have them merged at the first patch, I opted to make them
> >>> separate, as, in case of problems or needed changes, it would be
> >>> easier to revert or modify the corresponding logic. Also, it should
> >>> be better to review, in case one wants some changes there.
> >>>
> >>> The main changes against RFC are:
> >>>
> >>> - now, the TOC will be presented with 1 depth identation level,
> >>> meaning that it would look like a list;
> >>> - for files outside Documentation/process, it will use the name of
> >>> the subsystem with title capitalization for the name of the
> >>> profile entry;
> >>> - the logic also parses and produces a list of profiles that are
> >>> maintained elsewhere, picking its http/https link;
> >>> - entries are now better sorted: first by subsystem name, then
> >>> by its name.
> >>>
> >>> Suggested-by: Dan Williams <djbw@kernel.org>
> >>> Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
> >>>
> >>> Mauro Carvalho Chehab (8):
> >>> docs: maintainers_include: auto-generate maintainer profile TOC
> >>> MAINTAINERS: add an entry for media maintainers profile
> >>> MAINTAINERS: add maintainer-tip.rst to X86
> >>> docs: auto-generate maintainer entry profile links
> >>> docs: maintainers_include: use a better title for profiles
> >>> docs: maintainers_include: add external profile URLs
> >>> docs: maintainers_include: preserve names for files under process/
> >>> docs: maintainers_include: Only show main entry for profiles
> >>>
> >>> .../maintainer/maintainer-entry-profile.rst | 24 +---
> >>> .../process/maintainer-handbooks.rst | 17 ++-
> >>> Documentation/sphinx/maintainers_include.py | 131 +++++++++++++++---
> >>> MAINTAINERS | 2 +
> >>> 4 files changed, 128 insertions(+), 46 deletions(-)
> >>
> >> When building htmldocs with O=DOCS, I get a bunch of warnings.
> >> I tested against today's linux-next tree.
> >>
> >> The 'make O=DOCS htmldocs' warnings are (subset of all warnings):
> >>
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-kvm-x86' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/filesystems/xfs/xfs-maintainer-entry-profile' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-soc-clean-dts' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-netdev' [toc.not_readable]
> >> linux-next/MAINTAINERS:38: WARNING: toctree contains reference to nonexisting document 'DOCS/Documentation/process/maintainer-tip' [toc.not_readable]
> >>
> >> linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >> linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
> >>
> >> linux-next/MAINTAINERS:1: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc' [ref.doc]
> >> linux-next/MAINTAINERS:2: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> >> linux-next/MAINTAINERS:3: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-soc-clean-dts' [ref.doc]
> >> linux-next/MAINTAINERS:5: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
> >> linux-next/MAINTAINERS:6: WARNING: unknown document: '../../DOCS/Documentation/process/maintainer-tip' [ref.doc]
> >
> > Heh, os.path.relpath() does the wrong thing here.
> >
> > The enclosed patch should handle it better.
> >
> > Thanks,
> > Mauro
> >
> > [PATCH] docs: maintainers_include: fix support for O=dir
> >
> > os.path.relpath() will do the wrong thing with O=dir, as the build
> > system uses "cd <dir>" internally.
> >
> > Solve it by using app.srcdir, which, on normal cases, point to
> > Documentation/, or, when SPHINXDIRS=process, it will be set with
> > Documentation/process.
> >
> > While here, remove a dead code while writing maintainer profiles,
> > as now all entries should have both profile and entry.
> >
> > Reported-by: Randy Dunlap <rdunlap@infradead.org>
> > Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >
> > diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
> > index 5413c1350bba..fff9bdd55a56 100755
> > --- a/Documentation/sphinx/maintainers_include.py
> > +++ b/Documentation/sphinx/maintainers_include.py
> > @@ -27,15 +27,24 @@ from docutils import statemachine
> > from docutils.parsers.rst import Directive
> > from docutils.parsers.rst.directives.misc import Include
> >
> > +#
> > +# Base URL for intersphinx-like links to maintainer profiles
> > +#
> > +KERNELDOC_URL = "https://docs.kernel.org/"
> > +
> > def ErrorString(exc): # Shamelessly stolen from docutils
> > return f'{exc.__class__.__name}: {exc}'
> >
> > __version__ = '1.0'
> >
> > +base_dir = "."
> > +
> > class MaintainersParser:
> > """Parse MAINTAINERS file(s) content"""
> >
> > - def __init__(self, base_path, path):
> > + def __init__(self, path):
> > + global base_dir
> > +
> > self.profile_toc = set()
> > self.profile_entries = {}
> >
> > @@ -76,9 +85,18 @@ class MaintainersParser:
> > #
> > # Handle profile entries - either as files or as https refs
> > #
> > - match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
> > + match = re.match(r"P:\s*Documentation(/\S+)\.rst", line)
> > if match:
> > - entry = os.path.relpath(match.group(1), base_path)
> > + entry = os.path.relpath(match.group(1), base_dir)
> > +
> > + #
> > + # When SPHINXDIRS is used, it will try to reference files
> > + # outside srctree, causing warnings. To avoid that, point
> > + # to the latest official documentation
> > + #
> > + if entry.startswith("../"):
> > + entry = KERNELDOC_URL + match.group(1) + ".html"
> > +
> > if "*" in entry:
> > for e in glob(entry):
> > self.profile_toc.add(e)
> > @@ -189,10 +207,10 @@ class MaintainersInclude(Include):
> > """MaintainersInclude (``maintainers-include``) directive"""
> > required_arguments = 0
> >
> > - def emit(self, base_path, path):
> > + def emit(self, path):
> > """Parse all the MAINTAINERS lines into ReST for human-readability"""
> >
> > - output = MaintainersParser(base_path, path).output
> > + output = MaintainersParser(path).output
> >
> > # For debugging the pre-rendered results...
> > #print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
> > @@ -213,11 +231,10 @@ class MaintainersInclude(Include):
> >
> > # Append "MAINTAINERS"
> > path = os.path.join(path, "MAINTAINERS")
> > - base_path = os.path.dirname(self.state.document.document.current_source)
> >
> > try:
> > self.state.document.settings.record_dependencies.add(path)
> > - lines = self.emit(base_path, path)
> > + lines = self.emit(path)
> > except IOError as error:
> > raise self.severe('Problems with "%s" directive path:\n%s.' %
> > (self.name, ErrorString(error)))
> > @@ -227,27 +244,20 @@ class MaintainersInclude(Include):
> > class MaintainersProfile(Include):
> > required_arguments = 0
> >
> > - def emit(self, base_path, path):
> > + def emit(self, path):
> > """Parse all the MAINTAINERS lines looking for profile entries"""
> >
> > - maint = MaintainersParser(base_path, path)
> > + maint = MaintainersParser(path)
> >
> > #
> > # Produce a list with all maintainer profiles, sorted by subsystem name
> > #
> > output = ""
> > -
> > - for profile, entry in maint.profile_entries.items():
> > + for profile, entry in sorted(maint.profile_entries.items()):
> > if entry.startswith("http"):
> > - if profile:
> > - output += f"- `{profile} <{entry}>`_\n"
> > - else:
> > - output += f"- `<{entry}>_`\n"
> > + output += f"- `{profile} <{entry}>`_\n"
> > else:
> > - if profile:
> > - output += f"- :doc:`{profile} <{entry}>`\n"
> > - else:
> > - output += f"- :doc:`<{entry}>`\n"
> > + output += f"- :doc:`{profile} <{entry}>`\n"
> >
> > #
> > # Create a hidden TOC table with all profiles. That allows adding
> > @@ -277,11 +287,10 @@ class MaintainersProfile(Include):
> >
> > # Append "MAINTAINERS"
> > path = os.path.join(path, "MAINTAINERS")
> > - base_path = os.path.dirname(self.state.document.document.current_source)
> >
> > try:
> > self.state.document.settings.record_dependencies.add(path)
> > - lines = self.emit(base_path, path)
> > + lines = self.emit(path)
> > except IOError as error:
> > raise self.severe('Problems with "%s" directive path:\n%s.' %
> > (self.name, ErrorString(error)))
> > @@ -289,6 +298,15 @@ class MaintainersProfile(Include):
> > return []
> >
> > def setup(app):
> > + global base_dir
> > +
> > + #
> > + # partition will pick the path after Documentation.
> > + # NOTE: we're using os.fspath() here because of a Sphinx warning:
> > + # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
> > + #
> > + _, _, base_dir = os.fspath(app.srcdir).partition("Documentation")
> > +
> > app.add_directive("maintainers-include", MaintainersInclude)
> > app.add_directive("maintainers-profile-toc", MaintainersProfile)
> > return dict(
>
> With that patch I still see 6 warnings:
>
> linux-next/Documentation/filesystems/nfs/nfsd-maintainer-entry-profile.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-kvm-x86.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-netdev.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-soc-clean-dts.rst: WARNING: document isn't included in any toctree [toc.not_included]
> linux-next/Documentation/process/maintainer-tip.rst: WARNING: document isn't included in any toctree [toc.not_included]
Heh, dealing with patches is tricky. At least on my tests, things seem
to be working fine at v2 of this series:
https://lore.kernel.org/linux-doc/cover.1776405189.git.mchehab+huawei@kernel.org/T/#t
here, I tested building docs with and without SPHINXDIRS=process and
O=DOCS, but it is nice if you can re-test it.
Basically, when SPHINXDIRS=process is used, instead of generating
wakings for docs outside process/ directory, it converts them to
hyperlinks to their corresponding name inside
https://docs.kernel.org/ (*).
(*) The logic assumes that the file would exist there, but doesn't
check.
Thanks,
Mauro
^ permalink raw reply
* [PATCH v2 10/11] docs: maintainers_include: fix support for O=dir
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
os.path.relpath() will do the wrong thing with O=dir, as the build
system uses "cd <dir>" internally.
Solve it by using app.srcdir, which, on normal cases, point to
Documentation/, or, when SPHINXDIRS=process, it will be set with
Documentation/process.
While here, remove a dead code while writing maintainer profiles,
as now all entries should have both profile and entry.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 71 +++++++++++++++------
1 file changed, 50 insertions(+), 21 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 5413c1350bba..ae52e8198750 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -27,15 +27,24 @@ from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
+#
+# Base URL for intersphinx-like links to maintainer profiles
+#
+KERNELDOC_URL = "https://docs.kernel.org/"
+
def ErrorString(exc): # Shamelessly stolen from docutils
return f'{exc.__class__.__name}: {exc}'
__version__ = '1.0'
+app_dir = "."
+
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, base_path, path):
+ def __init__(self, path):
+ global app_dir
+
self.profile_toc = set()
self.profile_entries = {}
@@ -57,6 +66,9 @@ class MaintainersParser:
field_content = ""
subsystem_name = None
+ base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
+ print("BASE DIR", base_dir)
+
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
if descriptions and line.startswith('Maintainers'):
@@ -76,9 +88,25 @@ class MaintainersParser:
#
# Handle profile entries - either as files or as https refs
#
- match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ match = re.match(rf"P:\s*({doc_dir})(/\S+)\.rst", line)
if match:
- entry = os.path.relpath(match.group(1), base_path)
+ name = "".join(match.groups())
+ entry = os.path.relpath(base_dir + name, app_dir)
+
+ full_name = os.path.join(base_dir, name)
+ path = os.path.relpath(full_name, app_dir)
+ #
+ # When SPHINXDIRS is used, it will try to reference files
+ # outside srctree, causing warnings. To avoid that, point
+ # to the latest official documentation
+ #
+ if path.startswith("../"):
+ entry = KERNELDOC_URL + match.group(2) + ".html"
+ else:
+ entry = "/" + entry
+
+ print(f"{name}: entry: {entry} FULL: {full_name} path: {path}")
+
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -189,10 +217,10 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
- output = MaintainersParser(base_path, path).output
+ output = MaintainersParser(path).output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -213,11 +241,10 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -227,27 +254,20 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, base_path, path):
+ def emit(self, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- maint = MaintainersParser(base_path, path)
+ maint = MaintainersParser(path)
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
-
- for profile, entry in maint.profile_entries.items():
+ for profile, entry in sorted(maint.profile_entries.items()):
if entry.startswith("http"):
- if profile:
- output += f"- `{profile} <{entry}>`_\n"
- else:
- output += f"- `<{entry}>_`\n"
+ output += f"- `{profile} <{entry}>`_\n"
else:
- if profile:
- output += f"- :doc:`{profile} <{entry}>`\n"
- else:
- output += f"- :doc:`<{entry}>`\n"
+ output += f"- :doc:`{profile} <{entry}>`\n"
#
# Create a hidden TOC table with all profiles. That allows adding
@@ -261,6 +281,8 @@ class MaintainersProfile(Include):
output += "\n"
+ print(output)
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -277,11 +299,10 @@ class MaintainersProfile(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
- base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(base_path, path)
+ lines = self.emit(path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -289,6 +310,14 @@ class MaintainersProfile(Include):
return []
def setup(app):
+ global app_dir
+
+ #
+ # NOTE: we're using os.fspath() here because of a Sphinx warning:
+ # RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
+ #
+ app_dir = os.fspath(app.srcdir)
+
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
return dict(
--
2.53.0
^ permalink raw reply related
* [PATCH v2 07/11] docs: maintainers_include: preserve names for files under process/
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
When a maintainer's profile is stored outside process, they're
already included on some other book and the name of the filesystem
may not be there. That's why the logic picks the name from the
subsystem's name.
However, files directly placed together with maintainers-handbooks.rst
(e.g. under Documentation/process/) is a different history: those
aren't placed anywhere, so we can keep using their own names,
letting Sphinx do his thing.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index f1b8d4b00c2a..948746b998a3 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -76,11 +76,13 @@ class MaintainersParser:
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
fname = os.path.relpath(match.group(1), base_path)
- if fname not in self.profiles:
+ if fname.startswith("../"):
if self.profiles.get(fname) is None:
self.profiles[fname] = subsystem_name
else:
self.profiles[fname] += f", {subsystem_name}"
+ else:
+ self.profiles[fname] = None
match = re.match(r"P:\s*(https?://.*)", line)
if match:
--
2.53.0
^ permalink raw reply related
* [PATCH v2 08/11] docs: maintainers_include: Only show main entry for profiles
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Instead of showing as a "Contents:" with 2 identation levels,
drop its title and show profiles as a list of entries.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainer-handbooks.rst | 2 --
Documentation/sphinx/maintainers_include.py | 2 +-
2 files changed, 1 insertion(+), 3 deletions(-)
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 531985a0fae8..3821e78aefc0 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -16,6 +16,4 @@ For maintainers, consider documenting additional requirements and
expectations if submissions routinely overlook specific submission
criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
-Contents:
-
.. maintainers-profile-toc::
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 948746b998a3..7ab921820612 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -235,7 +235,7 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
- output += " :maxdepth: 2\n\n"
+ output += " :maxdepth: 1\n\n"
items = sorted(maint.profiles.items(),
key=lambda kv: (kv[1] or "", kv[0]))
--
2.53.0
^ permalink raw reply related
* [PATCH v2 11/11] docs: maintainers_include: parse MAINTAINERS just once
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Change the logic to parse MAINTAINERS file content just once,
while still allowing using it multiple times.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 61 +++++++--------------
1 file changed, 21 insertions(+), 40 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index ae52e8198750..436e7ac42ffc 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,14 +37,13 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-app_dir = "."
+maint_parser = None
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
- def __init__(self, path):
- global app_dir
-
+ def __init__(self, app_dir, path):
+ self.path = path
self.profile_toc = set()
self.profile_entries = {}
@@ -67,7 +66,6 @@ class MaintainersParser:
subsystem_name = None
base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
- print("BASE DIR", base_dir)
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -105,8 +103,6 @@ class MaintainersParser:
else:
entry = "/" + entry
- print(f"{name}: entry: {entry} FULL: {full_name} path: {path}")
-
if "*" in entry:
for e in glob(entry):
self.profile_toc.add(e)
@@ -217,14 +213,17 @@ class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
+ global maint_parser
- output = MaintainersParser(path).output
+ path = maint_parser.path
+ output = maint_parser.output
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -232,19 +231,8 @@ class MaintainersInclude(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -254,16 +242,17 @@ class MaintainersInclude(Include):
class MaintainersProfile(Include):
required_arguments = 0
- def emit(self, path):
+ def emit(self):
"""Parse all the MAINTAINERS lines looking for profile entries"""
+ global maint_parser
- maint = MaintainersParser(path)
+ path = maint_parser.path
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
- for profile, entry in sorted(maint.profile_entries.items()):
+ for profile, entry in sorted(maint_parser.profile_entries.items()):
if entry.startswith("http"):
output += f"- `{profile} <{entry}>`_\n"
else:
@@ -276,13 +265,12 @@ class MaintainersProfile(Include):
output += "\n.. toctree::\n"
output += " :hidden:\n\n"
- for fname in maint.profile_toc:
+ for fname in maint_parser.profile_toc:
output += f" {fname}\n"
output += "\n"
- print(output)
-
+ self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
@@ -290,19 +278,8 @@ class MaintainersProfile(Include):
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
- # Walk up source path directories to find Documentation/../
- path = self.state_machine.document.attributes['source']
- path = os.path.realpath(path)
- tail = path
- while tail != "Documentation" and tail != "":
- (path, tail) = os.path.split(path)
-
- # Append "MAINTAINERS"
- path = os.path.join(path, "MAINTAINERS")
-
try:
- self.state.document.settings.record_dependencies.add(path)
- lines = self.emit(path)
+ lines = self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
@@ -310,13 +287,17 @@ class MaintainersProfile(Include):
return []
def setup(app):
- global app_dir
+ global maint_parser
#
# NOTE: we're using os.fspath() here because of a Sphinx warning:
# RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead.
#
app_dir = os.fspath(app.srcdir)
+ srctree = os.path.abspath(os.environ["srctree"])
+ path = os.path.join(srctree, "MAINTAINERS")
+
+ maint_parser = MaintainersParser(app_dir, path)
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
--
2.53.0
^ permalink raw reply related
* [PATCH v2 06/11] docs: maintainers_include: add external profile URLs
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Some subsystem profiles are maintained elsewhere. Add them to
the output.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 28 +++++++++++++++++++--
1 file changed, 26 insertions(+), 2 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index cf428db7599c..f1b8d4b00c2a 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -37,6 +37,7 @@ class MaintainersParser:
def __init__(self, base_path, path):
self.profiles = {}
+ self.profile_urls = {}
result = list()
result.append(".. _maintainers:")
@@ -81,6 +82,16 @@ class MaintainersParser:
else:
self.profiles[fname] += f", {subsystem_name}"
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ url = match.group(1).strip()
+ if url not in self.profile_urls:
+ if self.profile_urls.get(url) is None:
+ self.profile_urls[url] = subsystem_name
+ else:
+ self.profile_urls[url] += f", {subsystem_name}"
+
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -219,18 +230,31 @@ class MaintainersProfile(Include):
def emit(self, base_path, path):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- profiles = MaintainersParser(base_path, path).profiles
+ maint = MaintainersParser(base_path, path)
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ items = sorted(maint.profiles.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
for fname, profile in items:
if profile:
output += f" {profile} <{fname}>\n"
else:
output += f" {fname}\n"
+ output += "\n**External profiles**\n\n"
+
+ items = sorted(maint.profile_urls.items(),
+ key=lambda kv: (kv[1] or "", kv[0]))
+ for url, profile in items:
+ if profile:
+ output += f"- {profile} <{url}>\n"
+ else:
+ output += f"- {url}\n"
+
+ output += "\n"
+
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
--
2.53.0
^ permalink raw reply related
* [PATCH v2 04/11] docs: auto-generate maintainer entry profile links
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Albert Ou, Alexandre Ghiti, Dan Williams, Mauro Carvalho Chehab,
Palmer Dabbelt, Paul Walmsley, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Instead of manually creating a TOC tree for them, use the new
tag to auto-generate its TOC.
Co-developed-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <9228f77b0339b8e5dea4a201ab6d4feb30cef5c2.1776176108.git.mchehab+huawei@kernel.org>
---
.../maintainer/maintainer-entry-profile.rst | 24 ++++---------------
.../process/maintainer-handbooks.rst | 19 ++++++++-------
2 files changed, 14 insertions(+), 29 deletions(-)
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 6020d188e13d..58e2af333692 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -92,24 +92,8 @@ full series, or privately send a reminder email. This section might also
list how review works for this code area and methods to get feedback
that are not directly from the maintainer.
-Existing profiles
------------------
+Maintainer Handbooks
+--------------------
-For now, existing maintainer profiles are listed here; we will likely want
-to do something different in the near future.
-
-.. toctree::
- :maxdepth: 1
-
- ../doc-guide/maintainer-profile
- ../nvdimm/maintainer-entry-profile
- ../arch/riscv/patch-acceptance
- ../process/maintainer-soc
- ../process/maintainer-soc-clean-dts
- ../driver-api/media/maintainer-entry-profile
- ../process/maintainer-netdev
- ../driver-api/vfio-pci-device-specific-driver-acceptance
- ../nvme/feature-and-quirk-policy
- ../filesystems/nfs/nfsd-maintainer-entry-profile
- ../filesystems/xfs/xfs-maintainer-entry-profile
- ../mm/damon/maintainer-profile
+For examples of other subsystem handbooks see
+Documentation/process/maintainer-handbooks.rst.
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 3d72ad25fc6a..531985a0fae8 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -7,14 +7,15 @@ The purpose of this document is to provide subsystem specific information
which is supplementary to the general development process handbook
:ref:`Documentation/process <development_process_main>`.
+For developers, see below for all the known subsystem specific guides.
+If the subsystem you are contributing to does not have a guide listed
+here, it is fair to seek clarification of questions raised in
+Documentation/maintainer/maintainer-entry-profile.rst.
+
+For maintainers, consider documenting additional requirements and
+expectations if submissions routinely overlook specific submission
+criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
+
Contents:
-.. toctree::
- :numbered:
- :maxdepth: 2
-
- maintainer-netdev
- maintainer-soc
- maintainer-soc-clean-dts
- maintainer-tip
- maintainer-kvm-x86
+.. maintainers-profile-toc::
--
2.53.0
^ permalink raw reply related
* [PATCH v2 09/11] docs: maintainers_include: improve its output
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
There are three "types" of profiles:
1. Profiles already included inside subsystem-specific documentation.
This is the most common case;
2. Profiles that are hosted externally;
3. Profiles that are at the same location as maintainer-handbooks.rst.
For (3), we need to create a TOC, as they don't exist elsewhere.
Change the logic to create TOC just for (3), prepending the
content of maintainer-handbooks with a sorted entry of all types,
before the TOC.
With such change, we can have an unique sorted list of profiles,
having the subsystem names used there listed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 76 +++++++++++----------
1 file changed, 40 insertions(+), 36 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 7ab921820612..5413c1350bba 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,7 +21,7 @@ import sys
import re
import os.path
-from textwrap import indent
+from glob import glob
from docutils import statemachine
from docutils.parsers.rst import Directive
@@ -36,8 +36,8 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = {}
- self.profile_urls = {}
+ self.profile_toc = set()
+ self.profile_entries = {}
result = list()
result.append(".. _maintainers:")
@@ -73,26 +73,24 @@ class MaintainersParser:
# Drop needless input whitespace.
line = line.rstrip()
+ #
+ # Handle profile entries - either as files or as https refs
+ #
match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
if match:
- fname = os.path.relpath(match.group(1), base_path)
- if fname.startswith("../"):
- if self.profiles.get(fname) is None:
- self.profiles[fname] = subsystem_name
- else:
- self.profiles[fname] += f", {subsystem_name}"
+ entry = os.path.relpath(match.group(1), base_path)
+ if "*" in entry:
+ for e in glob(entry):
+ self.profile_toc.add(e)
+ self.profile_entries[subsystem_name] = e
else:
- self.profiles[fname] = None
-
- match = re.match(r"P:\s*(https?://.*)", line)
- if match:
- url = match.group(1).strip()
- if url not in self.profile_urls:
- if self.profile_urls.get(url) is None:
- self.profile_urls[url] = subsystem_name
- else:
- self.profile_urls[url] += f", {subsystem_name}"
-
+ self.profile_toc.add(entry)
+ self.profile_entries[subsystem_name] = entry
+ else:
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ entry = match.group(1).strip()
+ self.profile_entries[subsystem_name] = entry
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -234,26 +232,32 @@ class MaintainersProfile(Include):
maint = MaintainersParser(base_path, path)
- output = ".. toctree::\n"
- output += " :maxdepth: 1\n\n"
+ #
+ # Produce a list with all maintainer profiles, sorted by subsystem name
+ #
+ output = ""
- items = sorted(maint.profiles.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for fname, profile in items:
- if profile:
- output += f" {profile} <{fname}>\n"
+ for profile, entry in maint.profile_entries.items():
+ if entry.startswith("http"):
+ if profile:
+ output += f"- `{profile} <{entry}>`_\n"
+ else:
+ output += f"- `<{entry}>_`\n"
else:
- output += f" {fname}\n"
+ if profile:
+ output += f"- :doc:`{profile} <{entry}>`\n"
+ else:
+ output += f"- :doc:`<{entry}>`\n"
- output += "\n**External profiles**\n\n"
+ #
+ # Create a hidden TOC table with all profiles. That allows adding
+ # profiles without needing to add them on any index.rst file.
+ #
+ output += "\n.. toctree::\n"
+ output += " :hidden:\n\n"
- items = sorted(maint.profile_urls.items(),
- key=lambda kv: (kv[1] or "", kv[0]))
- for url, profile in items:
- if profile:
- output += f"- {profile} <{url}>\n"
- else:
- output += f"- {url}\n"
+ for fname in maint.profile_toc:
+ output += f" {fname}\n"
output += "\n"
--
2.53.0
^ permalink raw reply related
* [PATCH v2 00/11] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-riscv,
workflows, Alexandre Ghiti, Shuah Khan, Randy Dunlap,
Dan Williams
Hi Jon,
This patch series change the way maintainer entry profile links
are added to the documentation. Instead of having an entry for
each of them at an ReST file, get them from MAINTAINERS content.
That should likely make easier to maintain, as there will be a single
point to place all such profiles.
The output is a per-subsystem sorted (*) series of links shown as a
list like this:
- Arm And Arm64 Soc Sub-Architectures (Common Parts)
- Arm/Samsung S3C, S5P And Exynos Arm Architectures
- Arm/Tesla Fsd Soc Support
...
- Xfs Filesystem
Please notice that the series is doing one logical change per patch.
I could have merged some changes altogether, but I opted doing it
in small steps to help reviews. If you prefer, feel free to merge
maintainers_include changes on merge.
There is one interesting side effect of this series: there is no
need to add rst files containing profiles inside a TOC tree: Just
creating the file anywhere inside Documentation and adding a P entry
is enough. Adding them to a TOC won't hurt.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
(*) At the end, I opted to use sorted(), just to ensure it, even
knowing that MAINTAINER entries are supposed to be sorted, as
the cost of sorting ~20 already-sorted entries is negligible.
---
v2:
- I placed the to MAINTAINERS changes at the beginning.
- fix a bug when O=DOCS is used;
- proper handle glob "P" entries (just in case, no profiles use it ATM);
- when SPHINXDIRS=process, instead of producing warnings, point to
entries at https://docs.kernel.org;
- MAINTAINERS parsing now happens just once;
- The output won't be numered for entries inside numered TOC trees;
- TOC tree is now hidden;
- instead of display a TOC tree, it shows a list of profiles,
ordered and named after file system name taken from MAINTAINERS file;
- At the output list, both https and file profiles are shown the same
way.
Mauro Carvalho Chehab (11):
MAINTAINERS: add an entry for media maintainers profile
MAINTAINERS: add maintainer-tip.rst to X86
docs: maintainers_include: auto-generate maintainer profile TOC
docs: auto-generate maintainer entry profile links
docs: maintainers_include: use a better title for profiles
docs: maintainers_include: add external profile URLs
docs: maintainers_include: preserve names for files under process/
docs: maintainers_include: Only show main entry for profiles
docs: maintainers_include: improve its output
docs: maintainers_include: fix support for O=dir
docs: maintainers_include: parse MAINTAINERS just once
.../maintainer/maintainer-entry-profile.rst | 24 +--
.../process/maintainer-handbooks.rst | 17 +-
Documentation/sphinx/maintainers_include.py | 161 +++++++++++++++---
MAINTAINERS | 2 +
4 files changed, 150 insertions(+), 54 deletions(-)
--
2.53.0
^ permalink raw reply
* [PATCH v2 05/11] docs: maintainers_include: use a better title for profiles
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
As we're picking the name of the subsystem from MAINTAINERS,
also use its subsystem name for the titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 1dac83bf1a65..cf428db7599c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -36,7 +36,7 @@ class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_path, path):
- self.profiles = list()
+ self.profiles = {}
result = list()
result.append(".. _maintainers:")
@@ -54,6 +54,7 @@ class MaintainersParser:
prev = None
field_prev = ""
field_content = ""
+ subsystem_name = None
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
@@ -75,7 +76,10 @@ class MaintainersParser:
if match:
fname = os.path.relpath(match.group(1), base_path)
if fname not in self.profiles:
- self.profiles.append(fname)
+ if self.profiles.get(fname) is None:
+ self.profiles[fname] = subsystem_name
+ else:
+ self.profiles[fname] += f", {subsystem_name}"
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
@@ -112,6 +116,8 @@ class MaintainersParser:
output = field_content + "\n\n"
field_content = ""
+ subsystem_name = line.title()
+
# Collapse whitespace in subsystem name.
heading = re.sub(r"\s+", " ", line)
output = output + "%s\n%s" % (heading, "~" * len(heading))
@@ -217,7 +223,13 @@ class MaintainersProfile(Include):
output = ".. toctree::\n"
output += " :maxdepth: 2\n\n"
- output += indent("\n".join(profiles), " ")
+
+ items = sorted(profiles.items(), key=lambda kv: (kv[1] or "", kv[0]))
+ for fname, profile in items:
+ if profile:
+ output += f" {profile} <{fname}>\n"
+ else:
+ output += f" {fname}\n"
self.state_machine.insert_input(statemachine.string2lines(output), path)
--
2.53.0
^ permalink raw reply related
* [PATCH v2 02/11] MAINTAINERS: add maintainer-tip.rst to X86
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
The X86 subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <970434c647aa1e1e9a81c87b4d5fed934d4018a7.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 620219e48f98..a85fcae5f56e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -28560,6 +28560,7 @@ M: Ingo Molnar <mingo@redhat.com>
M: Borislav Petkov <bp@alien8.de>
M: Dave Hansen <dave.hansen@linux.intel.com>
M: x86@kernel.org
+P: Documentation/process/maintainer-tip.rst
R: "H. Peter Anvin" <hpa@zytor.com>
L: linux-kernel@vger.kernel.org
S: Maintained
--
2.53.0
^ permalink raw reply related
* [PATCH v2 03/11] docs: maintainers_include: auto-generate maintainer profile TOC
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Randy Dunlap, Shuah Khan
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
Add a feature to allow auto-generating media entry profiles from the
corresponding field inside MAINTAINERS file(s).
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 93 +++++++++++++++++----
1 file changed, 76 insertions(+), 17 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 519ad18685b2..1dac83bf1a65 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,6 +21,8 @@ import sys
import re
import os.path
+from textwrap import indent
+
from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
@@ -30,20 +32,11 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-def setup(app):
- app.add_directive("maintainers-include", MaintainersInclude)
- return dict(
- version = __version__,
- parallel_read_safe = True,
- parallel_write_safe = True
- )
+class MaintainersParser:
+ """Parse MAINTAINERS file(s) content"""
-class MaintainersInclude(Include):
- """MaintainersInclude (``maintainers-include``) directive"""
- required_arguments = 0
-
- def parse_maintainers(self, path):
- """Parse all the MAINTAINERS lines into ReST for human-readability"""
+ def __init__(self, base_path, path):
+ self.profiles = list()
result = list()
result.append(".. _maintainers:")
@@ -78,6 +71,12 @@ class MaintainersInclude(Include):
# Drop needless input whitespace.
line = line.rstrip()
+ match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ if match:
+ fname = os.path.relpath(match.group(1), base_path)
+ if fname not in self.profiles:
+ self.profiles.append(fname)
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -165,12 +164,23 @@ class MaintainersInclude(Include):
for separated in field_content.split('\n'):
result.append(separated)
- output = "\n".join(result)
+ self.output = "\n".join(result)
+
+ # Create a TOC class
+
+class MaintainersInclude(Include):
+ """MaintainersInclude (``maintainers-include``) directive"""
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines into ReST for human-readability"""
+
+ output = MaintainersParser(base_path, path).output
+
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
- self.state_machine.insert_input(
- statemachine.string2lines(output), path)
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
@@ -186,12 +196,61 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.parse_maintainers(path)
+ lines = self.emit(base_path, path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
+class MaintainersProfile(Include):
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines looking for profile entries"""
+
+ profiles = MaintainersParser(base_path, path).profiles
+
+ output = ".. toctree::\n"
+ output += " :maxdepth: 2\n\n"
+ output += indent("\n".join(profiles), " ")
+
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
+
+ def run(self):
+ """Include the MAINTAINERS file as part of this reST file."""
+ if not self.state.document.settings.file_insertion_enabled:
+ raise self.warning('"%s" directive disabled.' % self.name)
+
+ # Walk up source path directories to find Documentation/../
+ path = self.state_machine.document.attributes['source']
+ path = os.path.realpath(path)
+ tail = path
+ while tail != "Documentation" and tail != "":
+ (path, tail) = os.path.split(path)
+
+ # Append "MAINTAINERS"
+ path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
+
+ try:
+ self.state.document.settings.record_dependencies.add(path)
+ lines = self.emit(base_path, path)
+ except IOError as error:
+ raise self.severe('Problems with "%s" directive path:\n%s.' %
+ (self.name, ErrorString(error)))
+
+ return []
+
+def setup(app):
+ app.add_directive("maintainers-include", MaintainersInclude)
+ app.add_directive("maintainers-profile-toc", MaintainersProfile)
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
--
2.53.0
^ permalink raw reply related
* [PATCH v2 01/11] MAINTAINERS: add an entry for media maintainers profile
From: Mauro Carvalho Chehab @ 2026-04-17 6:11 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Dan Williams, Mauro Carvalho Chehab, Randy Dunlap
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
The media subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <5af4aa6a716228eea4d59dc26b97d642e1e7d419.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index f0b106a4dd96..620219e48f98 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16115,6 +16115,7 @@ S: Maintained
W: https://linuxtv.org
Q: http://patchwork.kernel.org/project/linux-media/list/
T: git git://linuxtv.org/media.git
+P: Documentation/driver-api/media/maintainer-entry-profile.rst
F: Documentation/admin-guide/media/
F: Documentation/devicetree/bindings/media/
F: Documentation/driver-api/media/
--
2.53.0
^ permalink raw reply related
* Re: [PATCH V10 00/10] famfs: port into fuse
From: Darrick J. Wong @ 2026-04-17 5:40 UTC (permalink / raw)
To: Joanne Koong
Cc: Dan Williams, Gregory Price, John Groves, Miklos Szeredi,
Bernd Schubert, John Groves, Dan J Williams, Bernd Schubert,
Alison Schofield, John Groves, Jonathan Corbet, Shuah Khan,
Vishal Verma, Dave Jiang, Matthew Wilcox, Jan Kara,
Alexander Viro, David Hildenbrand, Christian Brauner,
Randy Dunlap, Jeff Layton, Amir Goldstein, Jonathan Cameron,
Stefan Hajnoczi, Josef Bacik, Bagas Sanjaya, Chen Linxuan,
James Morse, Fuad Tabba, Sean Christopherson, Shivank Garg,
Ackerley Tng, Aravind Ramesh, Ajay Joshi, venkataravis@micron.com,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
nvdimm@lists.linux.dev, linux-cxl@vger.kernel.org,
linux-fsdevel@vger.kernel.org
In-Reply-To: <CAJnrk1Y78UGLyAGVjiQ10PERTz1d2qcimok6bqCquy7jQYaXag@mail.gmail.com>
On Thu, Apr 16, 2026 at 05:44:28PM -0700, Joanne Koong wrote:
> On Thu, Apr 16, 2026 at 3:43 PM Darrick J. Wong <djwong@kernel.org> wrote:
> >
> > On Thu, Apr 16, 2026 at 01:53:27PM -0700, Dan Williams wrote:
> > >
> > >
> > > On Thu, Apr 16, 2026, at 1:14 PM, Gregory Price wrote:
> > > > On Thu, Apr 16, 2026 at 08:56:46AM -0700, Joanne Koong wrote:
> > > >> On Tue, Apr 14, 2026 at 5:10 PM John Groves <John@groves.net> wrote:
> > > >> >
> > > >> > There is a FUSE_DAX_FMAP capability that the kernel may advertise or not
> > > >> > at init time; this capability "is" the famfs GET_FMAP AND GET_DAXDEV
> > > >> > commands. In the future, if we find a way to use BPF (or some other
> > > >> > mechanism) to avoid needing those fuse messages, the kernel could be updated
> > > >> > to NEVER advertise the FUSE_DAX_FMAP capability. All of the famfs-specific
> > > >> > code could be taken out of kernels that never advertise that capability.
> > > >>
> > > >> I’m not sure the capability bit can be used like that (though I am
> > > >> hoping it can!). As I understand it, once the kernel advertises a
> > > >> capability, it must continue supporting it in future kernels else
> > > >> userspace programs that rely on it will break.
> >
> > So don't break fuse servers. If you wanted to (say) get rid of
> > GET_FMAP in favor of IOMAP_BEGIN, you could alter libfuse to translate a
> > fuse server's ->get_fmap implementation into the equivalent
> > ->iomap_begin, and eventually the kernel can stop making GET_FMAP calls
> > to userspace.
>
> I don't think it's this simple. We can't assume libfuse is the only
> way servers talk to the kernel. Some servers use the /dev/fuse
> interface directly. And, as I understand it, this would still break
> users who are on older versions of libfuse if they upgrade to a newer
> kernel.
>
> My reason for pushing back isn't because I don't want this to work; I
> just want to make sure that if we're going to rely on this as a safety
> hatch, then we can actually do it.
>
> Going back to what Dan said about using the capability bits for
> deprecation, "In some future kernel the famfs native option disappears
> after a deprecation period" - what does the deprecation period/process
> look like? Do you have to wait a certain amount of time before it can
> be fully removed or is it pretty immediate?
That depends on how much gluecode you can stand up to redirect older
programs.
> > The trouble here is that I've also seen half a dozen projects vendoring
> > libfuse so that's a nightmare that will have to be dealt with. But
> > maybe that doesn't even matter, because...
> >
> > > > FUSE_DAX_FMAP is already conditional on CONFIG_FUSE_DAX, the kernel is
> > > > not required to continue advertising FUSE_DAX_FMAP in perpetuity.
> > > >
> > > > Setting CONFIG_FUSE_DAX=n does not mean userland "is broken", this would
> > > > only be the case if FUSE_DAX_FMAP was advertised but not actually
> > > > supported.
> >
> > ...the memory interleaving is a rather interesting quality of famfs.
> > There's no good way to express a formulaic meta-mapping in traditional
> > iomap parlance, and famfs needs that to interleave across memory
> > controllers/dimm boxen/whatever. Throwing individual iomaps at the
> > kernel is a very inefficient way to do that. So I don't think there's a
> > good reason to get rid of GET_FMAP at this time...
>
> So could we make the interleaving part generic then? Striped /
> interleaved layouts are used elsewhere (eg RAID-0, md-stripe, etc.) -
> could we add a generic interleave descriptor to the uapi and use that
> for what famfs needs?
I doubt it. md-raid presents a unified LBA address space, which means
that the filesystem doesn't have to know anything about whatever
translations might happen underneath it. Even memory controllers
quietly take care of striping across DIMMs and whatnot.
Most filesystems that implement striping themselves don't restrict
themselves to monotonically increasing LBA ranges rotored across each
device like md-raid0 does.
But for whatever reason, pmem/dax don't have remapping layers like
md/dm so filesystems have to do that on their own if the hardware
doesn't do it for them.
> > > > If DAX were removed from the kernel (unlikely, but stick with me) this
> > > > would be equivalent to permanently changing CONFIG_FUSE_DAX to always
> > > > off, and there would be no squabbles over whether that particular
> > > > change broke userland (there would be much strife over removing dax).
> >
> > ...however the strongest case (IMO) would be if (having merged famfs) we
> > then merge fuse-iomap after famfs. Then we extend the existing
> > fuse-iomap-bpf prototype to allow per-mount and per-inode iomap bpf ops.
> > That enables us to analyze thoroughly the performance characteristics of:
> >
> > a) Using GET_FMAP as-is
> >
> > b) Uploading raw iomaps (HA)
> >
> > c) Uploading a single bpf program to make iomaps, exchanging fmap-style
> > mapping data into a bpf map, and having the single bpf program walk
> > through the map
> >
> > d) Uploading a custom bpf program per famfs file to make iomaps. No
> > bpfmap required, but the setup and compilation are now much more complex
> >
> > Then we'll finally know which approach is the best, having broken the
> > Gordian Knot of how to merge famfs and fuse-iomap.
> >
> > If we decide that (c) or (d) are actually better, then guess what? To
> > get any of the iomap functionality, you have to set an inode flag, and
> > that (FUSE_CAP_FAMFS && FUSE_CAP_IOMAP && FUSE_ATTR_IOMAP) is the signal
> > for "don't call GET_FMAP". FUSE_CAP_FAMFS && (!FUSE_CAP_IOMAP ||
> > !FUSE_ATTR_IOMAP) means "call GET_FMAP".
> >
> > Yes, we burn a couple of fuse command values to find out, but that's all.
> >
> > (TBH I still dislike GET_DAXDEV, that really should just be another
> > application of backing files, and the backing file id gets passed to
> > GET_FMAP.)
> >
> > What do you all think of doing that?
>
> To be completely honest, this is orthogonal to what I was hoping we
> could discuss on this thread. My main concern is the GET_FMAP part.
> Can we make it more generic to other interleaved/striped layouts?
"Generic"... do we even /have/ a second user? I don't feel like we do.
--D
> Thanks,
> Joanne
>
> >
> > > > While not a deprecation method, this is what capability bits are
> > > > designed for. Same as cpuid capability bits - just because the bit is
> > > > there doesn't mean a processor is required to support it in perpetuity.
> > > >
> > > > They're only required to support it if the bit is turned on.
> > > >
> > >
> > > Right, if the protocol on day one is "user space must ask which method
> > > is available", then userspace can not be surprised when one option
> > > disappears. So to give time for the bpf approach to mature the kernel
> > > can do something like "famfs and bpf mapping support are available".
> > > In some future kernel the famfs native option disappears after a
> > > deprecation period.
> > >
> > > When folks ask 10 years from now why this ever supported optionality
> > > the explanation is "oh because famfs enjoyed first mover advantage to
> > > prove out fs semantics layered on dax devices", or "turns out there
> > > are some cases where bpf is not fast enough but it still stops the
> > > proliferation of more in kernel mapping implementations".
> >
> > Yes. We're not *capable* of determining the best mechanism unless we
> > can start shipping these things to users to get their feedback. Only
> > then can we iterate and make real improvements.
> >
> > > Something like FUSE_DAX_FMAP is always available but the backend to
> > > that is optionally native vs bpf. ...or some other arrangement to make
> > > it clear that native might be gone someday.
> >
> > --D
>
^ permalink raw reply
* RE: [PATCH v2 1/2] dt-bindings: hwmon: pmbus: add max20830
From: Torreno, Alexis Czezar @ 2026-04-17 3:32 UTC (permalink / raw)
To: Guenter Roeck, Conor Dooley
Cc: Rob Herring, Krzysztof Kozlowski, Conor Dooley, Jonathan Corbet,
Shuah Khan, linux-hwmon@vger.kernel.org,
devicetree@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-doc@vger.kernel.org
In-Reply-To: <a142d5ce-e4a3-4f50-8009-f796609fb13c@roeck-us.net>
> >>
> >> It's an output on this device seemingly. I don't care if the driver
> >> ignores it, but for completeness (and we like completeness with
> >> bindings) I think it should be documented as an interrupt or gpio.
> >
> > Alright, I'll add it as an interrupt: optional power-good signal
> >
>
> Uuh, that really doesn't make any sense. Please at least make it a gpio pin,
> matching pwr-good-gpios of ti,tps65185.yaml.
>
I see, will do.
^ permalink raw reply
* Re: [PATCH v2 1/2] dt-bindings: hwmon: pmbus: add max20830
From: Guenter Roeck @ 2026-04-17 3:22 UTC (permalink / raw)
To: Torreno, Alexis Czezar, Conor Dooley
Cc: Rob Herring, Krzysztof Kozlowski, Conor Dooley, Jonathan Corbet,
Shuah Khan, linux-hwmon@vger.kernel.org,
devicetree@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-doc@vger.kernel.org
In-Reply-To: <PH0PR03MB635166088B7C473CF59F17D1F1202@PH0PR03MB6351.namprd03.prod.outlook.com>
On 4/16/26 18:04, Torreno, Alexis Czezar wrote:
>
>>>>
>>>> On the previous version, you got an LLM comment about not having the
>>>> interrupts property amongst other things.
>>>> I think the other things got implemented, but I didn't see any reply
>>>> to the bot about that?
>
> I wasn't sure if it was that type of bot. I'll try replying on the other patch review.
> I just added a note in the cover letter change log about the lacking smbalert.
>
>>>> I think the answer is that it shouldn't because the pin it
>>>> referenced doesn't exist, but when looking at the schematic I have
>>>> to wonder if
>>>
>>> I had to look this up in the datasheet. A SMBus chip with no alert pin
>>> is a bit odd, but you are correct.
>>>
>>>> there should be an interrupts property for dealing with "pgood"?
>>>>
>>> FWIW, I have never seen that. Normally such pins are used to take
>>> devices out of reset.
>>
>> It's an output on this device seemingly. I don't care if the driver ignores it, but
>> for completeness (and we like completeness with
>> bindings) I think it should be documented as an interrupt or gpio.
>
> Alright, I'll add it as an interrupt: optional power-good signal
>
Uuh, that really doesn't make any sense. Please at least make it a gpio pin,
matching pwr-good-gpios of ti,tps65185.yaml.
Guenter
^ permalink raw reply
* [PATCH] docs: Update nosmt support for arm64
From: Jinjie Ruan @ 2026-04-17 3:25 UTC (permalink / raw)
To: corbet, skhan, akpm, bp, rdunlap, pmladek, pawan.kumar.gupta,
feng.tang, dapeng1.mi, kees, elver, paulmck, lirongqing,
safinaskar, bhelgaas, linux-doc, linux-kernel, skelley
Cc: ruanjinjie
commit eed4583bcf9a6 ("arm64: Kconfig: Enable HOTPLUG_SMT") enable
HOTPLUG_SMT for SMT control for arm64, but the documentation was
not updated accordingly to reflect that ARM64 now supports control SMT
via boot parameter and sysfs knobs:
1. Boot parameters:
nosmt: Disable SMT, can be enabled via sysfs knobs.
nosmt=force: Disable SMT, cannot be enabled via sysfs knobs.
2. Runtime sysfs controls:
Write "on", "off", "forceoff" or the number of SMT threads (1, 2, ...)
to /sys/devices/system/cpu/smt/control.
Signed-off-by: Jinjie Ruan <ruanjinjie@huawei.com>
---
Documentation/admin-guide/kernel-parameters.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index cb850e5290c2..6a73eb5abae9 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4661,7 +4661,7 @@ Kernel parameters
nosmt [KNL,MIPS,PPC,EARLY] Disable symmetric multithreading (SMT).
Equivalent to smt=1.
- [KNL,LOONGARCH,X86,PPC,S390] Disable symmetric multithreading (SMT).
+ [KNL,LOONGARCH,X86,ARM64,PPC,S390] Disable symmetric multithreading (SMT).
nosmt=force: Force disable SMT, cannot be undone
via the sysfs control file.
--
2.34.1
^ permalink raw reply related
* [PATCH 3/3] Documentation: rust: testing: add Kconfig guidance
From: Yury Norov @ 2026-04-17 3:15 UTC (permalink / raw)
To: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Alice Ryhl, Trevor Gross,
Danilo Krummrich, Jonathan Corbet, Shuah Khan, Lorenzo Stoakes,
Vlastimil Babka, Liam R. Howlett, Uladzislau Rezki, Burak Emir,
Yury Norov, Brendan Higgins, David Gow, Rae Moar, Will Deacon,
Peter Zijlstra, Mark Rutland, Nathan Chancellor, Kees Cook,
Nicolas Schier, Thomas Weißschuh, Thomas Gleixner,
Douglas Anderson, Shakeel Butt, Christian Brauner, Randy Dunlap,
Tamir Duberstein, rust-for-linux, linux-doc, linux-kernel,
linux-kselftest, kunit-dev
Cc: Yury Norov
In-Reply-To: <20260417031531.315281-1-ynorov@nvidia.com>
Now that rust KUnit tests are protected with Kconfig, update the
documentation to mention it.
Signed-off-by: Yury Norov <ynorov@nvidia.com>
---
Documentation/rust/testing.rst | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/Documentation/rust/testing.rst b/Documentation/rust/testing.rst
index f43cb77bcc69..24de173471b2 100644
--- a/Documentation/rust/testing.rst
+++ b/Documentation/rust/testing.rst
@@ -141,10 +141,13 @@ These tests are introduced by the ``kunit_tests`` procedural macro, which takes
the name of the test suite as an argument.
For instance, assume we want to test the function ``f`` from the documentation
-tests section. We could write, in the same file where we have our function:
+tests section. We could write, in the same file where we have our function.
+Each test is protected with the corresponding Kconfig option, see
+rust/kernel/Kconfig.test.
.. code-block:: rust
+ #[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)]
#[kunit_tests(rust_kernel_mymod)]
mod tests {
use super::*;
--
2.51.0
^ permalink raw reply related
* [PATCH 2/3] rust: testing: add Kconfig for KUnit test
From: Yury Norov @ 2026-04-17 3:15 UTC (permalink / raw)
To: Miguel Ojeda, Boqun Feng, Gary Guo, Björn Roy Baron,
Benno Lossin, Andreas Hindborg, Alice Ryhl, Trevor Gross,
Danilo Krummrich, Jonathan Corbet, Shuah Khan, Lorenzo Stoakes,
Vlastimil Babka, Liam R. Howlett, Uladzislau Rezki, Burak Emir,
Yury Norov, Brendan Higgins, David Gow, Rae Moar, Will Deacon,
Peter Zijlstra, Mark Rutland, Nathan Chancellor, Kees Cook,
Nicolas Schier, Thomas Weißschuh, Thomas Gleixner,
Douglas Anderson, Shakeel Butt, Christian Brauner, Randy Dunlap,
Tamir Duberstein, rust-for-linux, linux-doc, linux-kernel,
linux-kselftest, kunit-dev
Cc: Yury Norov
In-Reply-To: <20260417031531.315281-1-ynorov@nvidia.com>
There are 6 individual Rust KUnit tests. All the tests are compiled
unconditionally now, which adds ~200 kB to the kernel image for me
on x86_64. As Rust matures, this bloating will inevitably grow.
Add Kconfig.test which includes a RUST_KUNIT_TESTS menu, and all
individual tests under it.
As usual, new tests are all enabled if KUNIT_ALL_TESTS=y.
Suggested-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Yury Norov <ynorov@nvidia.com>
---
This doesn't create a new entry in MAINTAINERS for the Kconfig.test,
so the new file just follows the implicit rule for the rust/ directory.
Please let me know if the explicit entry is needed.
init/Kconfig | 2 +
rust/kernel/Kconfig.test | 76 ++++++++++++++++++++++++++++
rust/kernel/alloc/allocator.rs | 1 +
rust/kernel/alloc/kvec.rs | 1 +
rust/kernel/bitmap.rs | 1 +
rust/kernel/kunit.rs | 1 +
rust/kernel/str.rs | 1 +
rust/kernel/sync/atomic/predefine.rs | 1 +
8 files changed, 84 insertions(+)
create mode 100644 rust/kernel/Kconfig.test
diff --git a/init/Kconfig b/init/Kconfig
index 43875ef36752..4af544514e6c 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -2208,6 +2208,8 @@ config RUST
If unsure, say N.
+source "rust/kernel/Kconfig.test"
+
config RUSTC_VERSION_TEXT
string
depends on RUST
diff --git a/rust/kernel/Kconfig.test b/rust/kernel/Kconfig.test
new file mode 100644
index 000000000000..a05243696a01
--- /dev/null
+++ b/rust/kernel/Kconfig.test
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: GPL-2.0-only
+menuconfig RUST_KUNIT_TESTS
+ bool "Rust KUnit tests"
+ depends on KUNIT && RUST
+ default KUNIT_ALL_TESTS
+ help
+ This menu collects all options for Rust Kunit tests.
+ See Documentation/rust/testing.rst for how to protect
+ unit tests with these options.
+
+ Say Y here to enable Rust KUnit tests.
+
+ If unsure, say N.
+
+if RUST_KUNIT_TESTS
+config RUST_ALLOCATOR_KUNIT_TEST
+ bool "KUnit tests for Rust allocator API" if !KUNIT_ALL_TESTS
+ default KUNIT_ALL_TESTS
+ help
+ This option enables KUnit tests for the Rust allocator API.
+ These are only for development and testing, not for regular
+ kernel use cases.
+
+ If unsure, say N.
+
+config RUST_KVEC_KUNIT_TEST
+ bool "KUnit tests for Rust KVEC API" if !KUNIT_ALL_TESTS
+ default KUNIT_ALL_TESTS
+ help
+ This option enables KUnit tests for the Rust KVEC API.
+ These are only for development and testing, not for
+ regular kernel use cases.
+
+ If unsure, say N.
+
+config RUST_BITMAP_KUNIT_TEST
+ bool "KUnit tests for Rust bitmap API" if !KUNIT_ALL_TESTS
+ default KUNIT_ALL_TESTS
+ help
+ This option enables KUnit tests for the Rust bitmap API.
+ These are only for development and testing, not for regular
+ kernel use cases.
+
+ If unsure, say N.
+
+config RUST_KUNIT_SELFTEST
+ bool "KUnit selftests for Rust" if !KUNIT_ALL_TESTS
+ default KUNIT_ALL_TESTS
+ help
+ This option enables KUnit selftests. These are only
+ for development and testing, not for regular kernel
+ use cases.
+
+ If unsure, say N.
+
+config RUST_STR_KUNIT_TEST
+ bool "KUnit tests for Rust strings APIs" if !KUNIT_ALL_TESTS
+ default KUNIT_ALL_TESTS
+ help
+ This option enables KUnit tests for the Rust strings API.
+ These are only for development and testing, not for regular
+ kernel use cases.
+
+ If unsure, say N.
+
+config RUST_ATOMICS_KUNIT_TEST
+ bool "KUnit tests for Rust atomics APIs" if !KUNIT_ALL_TESTS
+ default KUNIT_ALL_TESTS
+ help
+ This option enables KUnit tests for the Rust atomics API.
+ These are only for development and testing, not for regular
+ kernel use cases.
+
+ If unsure, say N.
+
+endif
diff --git a/rust/kernel/alloc/allocator.rs b/rust/kernel/alloc/allocator.rs
index 63bfb91b3671..0d3434bca867 100644
--- a/rust/kernel/alloc/allocator.rs
+++ b/rust/kernel/alloc/allocator.rs
@@ -251,6 +251,7 @@ unsafe fn realloc(
}
}
+#[cfg(CONFIG_RUST_ALLOCATOR_KUNIT_TEST)]
#[macros::kunit_tests(rust_allocator)]
mod tests {
use super::*;
diff --git a/rust/kernel/alloc/kvec.rs b/rust/kernel/alloc/kvec.rs
index ac8d6f763ae8..563c760c8105 100644
--- a/rust/kernel/alloc/kvec.rs
+++ b/rust/kernel/alloc/kvec.rs
@@ -1351,6 +1351,7 @@ fn drop(&mut self) {
}
}
+#[cfg(CONFIG_RUST_KVEC_KUNIT_TEST)]
#[macros::kunit_tests(rust_kvec)]
mod tests {
use super::*;
diff --git a/rust/kernel/bitmap.rs b/rust/kernel/bitmap.rs
index 894043c9e460..b27e0ec80d64 100644
--- a/rust/kernel/bitmap.rs
+++ b/rust/kernel/bitmap.rs
@@ -499,6 +499,7 @@ pub fn next_zero_bit(&self, start: usize) -> Option<usize> {
}
}
+#[cfg(CONFIG_RUST_BITMAP_KUNIT_TEST)]
#[macros::kunit_tests(rust_kernel_bitmap)]
mod tests {
use super::*;
diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
index a1edf7491579..cdee5f27bd7f 100644
--- a/rust/kernel/kunit.rs
+++ b/rust/kernel/kunit.rs
@@ -329,6 +329,7 @@ pub fn in_kunit_test() -> bool {
!unsafe { bindings::kunit_get_current_test() }.is_null()
}
+#[cfg(CONFIG_RUST_KUNIT_SELFTEST)]
#[kunit_tests(rust_kernel_kunit)]
mod tests {
use super::*;
diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
index 8311d91549e1..a435674f05ea 100644
--- a/rust/kernel/str.rs
+++ b/rust/kernel/str.rs
@@ -415,6 +415,7 @@ macro_rules! c_str {
}};
}
+#[cfg(CONFIG_RUST_STR_KUNIT_TEST)]
#[kunit_tests(rust_kernel_str)]
mod tests {
use super::*;
diff --git a/rust/kernel/sync/atomic/predefine.rs b/rust/kernel/sync/atomic/predefine.rs
index 84fcd7cfcb73..7468153429e1 100644
--- a/rust/kernel/sync/atomic/predefine.rs
+++ b/rust/kernel/sync/atomic/predefine.rs
@@ -154,6 +154,7 @@ fn rhs_into_delta(rhs: usize) -> isize_atomic_repr {
}
}
+#[cfg(CONFIG_RUST_ATOMICS_KUNIT_TEST)]
#[macros::kunit_tests(rust_atomics)]
mod tests {
use super::super::*;
--
2.51.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox