* [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
* [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 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 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 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 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 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 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 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 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 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
* 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] docs: kselftest: Document the FORCE_TARGETS build variable
From: Ricardo B. Marlière @ 2026-04-17 17:36 UTC (permalink / raw)
To: Shuah Khan, Jonathan Corbet
Cc: Shuah Khan, linux-kselftest, workflows, linux-doc, linux-kernel,
Ricardo B. Marlière
FORCE_TARGETS has been part of the kselftest build system for
some time but is absent from the developer documentation. Without
an entry here, users relying on kselftest in CI pipelines would
have to read the selftests Makefile directly to discover the
option.
A build that exits zero despite some targets failing can mask
real breakage and mislead automated systems into reporting
success. Add a dedicated section so that CI authors can easily
find and adopt FORCE_TARGETS=1 to turn such silent partial
failures into hard errors.
Signed-off-by: Ricardo B. Marlière <rbm@suse.com>
---
Documentation/dev-tools/kselftest.rst | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst
index 18c2da67fae4..d7bfe320338c 100644
--- a/Documentation/dev-tools/kselftest.rst
+++ b/Documentation/dev-tools/kselftest.rst
@@ -126,6 +126,18 @@ dedicated skiplist::
See the top-level tools/testing/selftests/Makefile for the list of all
possible targets.
+Requiring all targets to build successfully
+===========================================
+
+By default, the build succeeds as long as at least one target builds
+without error. Set ``FORCE_TARGETS=1`` to instead require every target to
+build successfully; make will abort as soon as any target fails::
+
+ $ make -C tools/testing/selftests FORCE_TARGETS=1
+
+This applies to both the ``all`` and ``install`` targets and is useful in
+CI environments where a silent partial build would be misleading.
+
Running the full range hotplug selftests
========================================
---
base-commit: 83ef26f911432d9c98b6d8b6ed0709a8b79cd834
change-id: 20260417-selftests-docs-fdf4e922ad20
Best regards,
--
Ricardo B. Marlière <rbm@suse.com>
^ permalink raw reply related
* Re: [PATCH v2 01/11] MAINTAINERS: add an entry for media maintainers profile
From: Randy Dunlap @ 2026-04-19 0:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List
Cc: linux-kernel, linux-riscv, workflows, Dan Williams,
Mauro Carvalho Chehab
In-Reply-To: <361c00348573e45b4e06b674b2b45e47dc65c938.1776405189.git.mchehab+huawei@kernel.org>
On 4/16/26 11:11 PM, Mauro Carvalho Chehab wrote:
> 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/
I now see 2 P: entries for MEDIA INPUT INFRASTRUCTURE
and 2 P: entries for X86 ARCHITECTURE.
(don't know how/why)
--
~Randy
^ permalink raw reply
* Re: [PATCH v2 00/11] Auto-generate maintainer profile entries
From: Randy Dunlap @ 2026-04-19 0:05 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Albert Ou, Jonathan Corbet,
Mauro Carvalho Chehab, Palmer Dabbelt, Paul Walmsley
Cc: linux-doc, linux-kernel, linux-riscv, workflows, Alexandre Ghiti,
Shuah Khan, Dan Williams
In-Reply-To: <cover.1776405189.git.mchehab+huawei@kernel.org>
On 4/16/26 11:11 PM, Mauro Carvalho Chehab wrote:
> 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(-)
>
Just a note, not asking for a change or fix:
AFAICT, all P: entries are now listed nicely except for:
P: rust/pin-init/CONTRIBUTING.md
so for the series:
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
thanks.
--
~Randy
^ permalink raw reply
* [PATCH] Documentation: adopt new coding style of type-aware kmalloc-family
From: Manuel Ebner @ 2026-04-19 6:58 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc
Cc: lrcu, linux-kernel, workflows, linux-sound, rcu, linux-media,
Manuel Ebner
Update the documentation to reflect new type-aware kmalloc-family as
suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj() and family")
ptr = kmalloc(sizeof(*ptr), gfp);
-> ptr = kmalloc_obj(*ptr, gfp);
ptr = kmalloc(sizeof(struct some_obj_name), gfp);
-> ptr = kmalloc_obj(*ptr, gfp);
ptr = kzalloc(sizeof(*ptr), gfp);
-> ptr = kzalloc_obj(*ptr, gfp);
ptr = kmalloc_array(count, sizeof(*ptr), gfp);
-> ptr = kmalloc_objs(*ptr, count, gfp);
ptr = kcalloc(count, sizeof(*ptr), gfp);
-> ptr = kzalloc_objs(*ptr, count, gfp);
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
---
.../RCU/Design/Requirements/Requirements.rst | 6 +++---
Documentation/RCU/listRCU.rst | 2 +-
Documentation/RCU/whatisRCU.rst | 4 ++--
Documentation/core-api/kref.rst | 4 ++--
Documentation/core-api/list.rst | 4 ++--
Documentation/core-api/memory-allocation.rst | 4 ++--
Documentation/driver-api/mailbox.rst | 4 ++--
Documentation/driver-api/media/v4l2-fh.rst | 2 +-
Documentation/kernel-hacking/locking.rst | 4 ++--
Documentation/locking/locktypes.rst | 4 ++--
Documentation/process/coding-style.rst | 8 ++++----
.../sound/kernel-api/writing-an-alsa-driver.rst | 12 ++++++------
Documentation/spi/spi-summary.rst | 4 ++--
.../translations/it_IT/kernel-hacking/locking.rst | 4 ++--
.../translations/it_IT/locking/locktypes.rst | 4 ++--
.../translations/it_IT/process/coding-style.rst | 2 +-
.../translations/sp_SP/process/coding-style.rst | 2 +-
Documentation/translations/zh_CN/core-api/kref.rst | 4 ++--
.../translations/zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/video4linux/v4l2-framework.txt | 2 +-
.../translations/zh_TW/process/coding-style.rst | 2 +-
21 files changed, 42 insertions(+), 42 deletions(-)
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
index b5cdbba3ec2e..faca5a9c8c12 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -206,7 +206,7 @@ non-\ ``NULL``, locklessly accessing the ``->a`` and ``->b`` fields.
1 bool add_gp_buggy(int a, int b)
2 {
- 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 3 p = kmalloc_obj(*p, GFP_KERNEL);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
@@ -228,7 +228,7 @@ their rights to reorder this code as follows:
1 bool add_gp_buggy_optimized(int a, int b)
2 {
- 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 3 p = kmalloc_obj(*p, GFP_KERNEL);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
@@ -264,7 +264,7 @@ shows an example of insertion:
1 bool add_gp(int a, int b)
2 {
- 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
+ 3 p = kmalloc_obj(*p, GFP_KERNEL);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
index d8bb98623c12..48c7272a4ccc 100644
--- a/Documentation/RCU/listRCU.rst
+++ b/Documentation/RCU/listRCU.rst
@@ -276,7 +276,7 @@ The RCU version of audit_upd_rule() is as follows::
list_for_each_entry(e, list, list) {
if (!audit_compare_rule(rule, &e->rule)) {
- ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
+ ne = kmalloc_obj(*entry, GFP_ATOMIC);
if (ne == NULL)
return -ENOMEM;
audit_copy_rule(&ne->rule, &e->rule);
diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst
index a1582bd653d1..770aab8ea36a 100644
--- a/Documentation/RCU/whatisRCU.rst
+++ b/Documentation/RCU/whatisRCU.rst
@@ -468,7 +468,7 @@ uses of RCU may be found in listRCU.rst and NMI-RCU.rst.
struct foo *new_fp;
struct foo *old_fp;
- new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
+ new_fp = kmalloc_obj(*new_fp, GFP_KERNEL);
spin_lock(&foo_mutex);
old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
*new_fp = *old_fp;
@@ -570,7 +570,7 @@ The foo_update_a() function might then be written as follows::
struct foo *new_fp;
struct foo *old_fp;
- new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
+ new_fp = kmalloc_obj(*new_fp, GFP_KERNEL);
spin_lock(&foo_mutex);
old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
*new_fp = *old_fp;
diff --git a/Documentation/core-api/kref.rst b/Documentation/core-api/kref.rst
index 8db9ff03d952..1c14c036699d 100644
--- a/Documentation/core-api/kref.rst
+++ b/Documentation/core-api/kref.rst
@@ -40,7 +40,7 @@ kref_init as so::
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -100,7 +100,7 @@ thread to process::
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/core-api/list.rst b/Documentation/core-api/list.rst
index 241464ca0549..86cd0a1b77ea 100644
--- a/Documentation/core-api/list.rst
+++ b/Documentation/core-api/list.rst
@@ -112,7 +112,7 @@ list:
/* State 1 */
- grock = kzalloc(sizeof(*grock), GFP_KERNEL);
+ grock = kzalloc_obj(*grock, GFP_KERNEL);
if (!grock)
return -ENOMEM;
grock->name = "Grock";
@@ -123,7 +123,7 @@ list:
/* State 2 */
- dimitri = kzalloc(sizeof(*dimitri), GFP_KERNEL);
+ dimitri = kzalloc_obj(*dimitri, GFP_KERNEL);
if (!dimitri)
return -ENOMEM;
dimitri->name = "Dimitri";
diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 0f19dd524323..8379775f17d3 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -135,7 +135,7 @@ Selecting memory allocator
The most straightforward way to allocate memory is to use a function
from the kmalloc() family. And, to be on the safe side it's best to use
routines that set memory to zero, like kzalloc(). If you need to
-allocate memory for an array, there are kmalloc_array() and kcalloc()
+allocate memory for an array, there are kmalloc_objs() and kzalloc_objs()
helpers. The helpers struct_size(), array_size() and array3_size() can
be used to safely calculate object sizes without overflowing.
@@ -151,7 +151,7 @@ sizes, the alignment is guaranteed to be at least the largest power-of-two
divisor of the size.
Chunks allocated with kmalloc() can be resized with krealloc(). Similarly
-to kmalloc_array(): a helper for resizing arrays is provided in the form of
+to kmalloc_objs(): a helper for resizing arrays is provided in the form of
krealloc_array().
For large allocations you can use vmalloc() and vzalloc(), or directly
diff --git a/Documentation/driver-api/mailbox.rst b/Documentation/driver-api/mailbox.rst
index 463dd032b96c..4bcd73a99115 100644
--- a/Documentation/driver-api/mailbox.rst
+++ b/Documentation/driver-api/mailbox.rst
@@ -87,8 +87,8 @@ a message and a callback function to the API and return immediately).
struct async_pkt ap;
struct sync_pkt sp;
- dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
- dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
+ dc_sync = kzalloc_obj(*dc_sync, GFP_KERNEL);
+ dc_async = kzalloc_obj(*dc_async, GFP_KERNEL);
/* Populate non-blocking mode client */
dc_async->cl.dev = &pdev->dev;
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index a934caa483a4..38319130ebf5 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -42,7 +42,7 @@ Example:
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh, GFP_KERNEL);
...
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index dff0646a717b..d02e62367c4f 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -442,7 +442,7 @@ to protect the cache and all the objects within it. Here's the code::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -517,7 +517,7 @@ which are taken away, and the ``+`` are lines which are added.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst
index 37b6a5670c2f..ac1ad722a9e7 100644
--- a/Documentation/locking/locktypes.rst
+++ b/Documentation/locking/locktypes.rst
@@ -498,7 +498,7 @@ allocating memory. Thus, on a non-PREEMPT_RT kernel the following code
works perfectly::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
But this code fails on PREEMPT_RT kernels because the memory allocator is
fully preemptible and therefore cannot be invoked from truly atomic
@@ -507,7 +507,7 @@ while holding normal non-raw spinlocks because they do not disable
preemption on PREEMPT_RT kernels::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 35b381230f6e..a3bf75dc7c88 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -936,7 +936,7 @@ used.
---------------------
The kernel provides the following general purpose memory allocators:
-kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
+kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and
vzalloc(). Please refer to the API documentation for further information
about them. :ref:`Documentation/core-api/memory-allocation.rst
<memory_allocation>`
@@ -945,7 +945,7 @@ The preferred form for passing a size of a struct is the following:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
The alternative form where struct name is spelled out hurts readability and
introduces an opportunity for a bug when the pointer variable type is changed
@@ -959,13 +959,13 @@ The preferred form for allocating an array is the following:
.. code-block:: c
- p = kmalloc_array(n, sizeof(...), ...);
+ p = kmalloc_objs(*ptr, n, ...);
The preferred form for allocating a zeroed array is the following:
.. code-block:: c
- p = kcalloc(n, sizeof(...), ...);
+ p = kzalloc_objs(*ptr, n, ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 895752cbcedd..12433612aa9c 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -266,7 +266,7 @@ to details explained in the following section.
....
/* allocate a chip-specific data with zero filled */
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
if (chip == NULL)
return -ENOMEM;
@@ -628,7 +628,7 @@ After allocating a card instance via :c:func:`snd_card_new()`
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
.....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
The chip record should have the field to hold the card pointer at least,
@@ -747,7 +747,7 @@ destructor and PCI entries. Example code is shown first, below::
return -ENXIO;
}
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
if (chip == NULL) {
pci_disable_device(pci);
return -ENOMEM;
@@ -1737,7 +1737,7 @@ callback::
{
struct my_pcm_data *data;
....
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
substream->runtime->private_data = data;
....
}
@@ -3301,7 +3301,7 @@ You can then pass any pointer value to the ``private_data``. If you
assign private data, you should define a destructor, too. The
destructor function is set in the ``private_free`` field::
- struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
+ struct mydata *p = kmalloc_obj(*p, GFP_KERNEL);
hw->private_data = p;
hw->private_free = mydata_free;
@@ -3833,7 +3833,7 @@ chip data individually::
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip, GFP_KERNEL);
....
card->private_data = chip;
....
diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst
index 6e21e6f86912..7ad6af76c247 100644
--- a/Documentation/spi/spi-summary.rst
+++ b/Documentation/spi/spi-summary.rst
@@ -249,7 +249,7 @@ And SOC-specific utility code might look something like::
{
struct mysoc_spi_data *pdata2;
- pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
+ pdata2 = kmalloc_obj(*pdata2, GFP_KERNEL);
*pdata2 = pdata;
...
if (n == 2) {
@@ -373,7 +373,7 @@ a bus (appearing under /sys/class/spi_master).
return -ENODEV;
/* get memory for driver's per-chip state */
- chip = kzalloc(sizeof *chip, GFP_KERNEL);
+ chip = kzalloc(*chip, GFP_KERNEL);
if (!chip)
return -ENOMEM;
spi_set_drvdata(spi, chip);
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 4c21cf60f775..acca89a3743a 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -462,7 +462,7 @@ e tutti gli oggetti che contiene. Ecco il codice::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -537,7 +537,7 @@ sono quelle rimosse, mentre quelle ``+`` sono quelle aggiunte.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj, GFP_KERNEL)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/translations/it_IT/locking/locktypes.rst b/Documentation/translations/it_IT/locking/locktypes.rst
index 1c7056283b9d..d5fa36aa05cc 100644
--- a/Documentation/translations/it_IT/locking/locktypes.rst
+++ b/Documentation/translations/it_IT/locking/locktypes.rst
@@ -488,7 +488,7 @@ o rwlock_t. Per esempio, la sezione critica non deve fare allocazioni di
memoria. Su un kernel non-PREEMPT_RT il seguente codice funziona perfettamente::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
Ma lo stesso codice non funziona su un kernel PREEMPT_RT perché l'allocatore di
memoria può essere oggetto di prelazione e quindi non può essere chiamato in un
@@ -497,7 +497,7 @@ trattiene un blocco *non-raw* perché non disabilitano la prelazione sui kernel
PREEMPT_RT::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index c0dc786b8474..2a499412a2e3 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -943,7 +943,7 @@ Il modo preferito per passare la dimensione di una struttura è il seguente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa, dove il nome della struttura viene scritto interamente,
peggiora la leggibilità e introduce possibili bachi quando il tipo di
diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
index 7d63aa8426e6..44c93d5f6beb 100644
--- a/Documentation/translations/sp_SP/process/coding-style.rst
+++ b/Documentation/translations/sp_SP/process/coding-style.rst
@@ -955,7 +955,7 @@ La forma preferida para pasar el tamaño de una estructura es la siguiente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa donde se deletrea el nombre de la estructura perjudica
la legibilidad, y presenta una oportunidad para un error cuando se cambia
diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst
index b9902af310c5..fcff01e99852 100644
--- a/Documentation/translations/zh_CN/core-api/kref.rst
+++ b/Documentation/translations/zh_CN/core-api/kref.rst
@@ -52,7 +52,7 @@ kref可以出现在数据结构体中的任何地方。
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -106,7 +106,7 @@ Kref规则
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data, GFP_KERNEL);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 5a342a024c01..55d5da974d89 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -813,7 +813,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能
会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof
diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
index f0be21a60a0f..ba43c5c4797c 100644
--- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
+++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
@@ -799,7 +799,7 @@ int my_open(struct file *file)
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh, GFP_KERNEL);
...
diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index e2ba97b3d8bb..63c78982a1af 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -827,7 +827,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一種傳遞方式中，sizeof 的操作數是結構體的名字，這樣會降低可讀性，並且可能
會引入 bug。有可能指針變量類型被改變時，而對應的傳遞給內存分配函數的 sizeof
--
2.53.0
^ permalink raw reply related
* Re: [PATCH] Documentation: adopt new coding style of type-aware kmalloc-family
From: Jonathan Corbet @ 2026-04-19 10:29 UTC (permalink / raw)
To: Manuel Ebner, Shuah Khan, linux-doc
Cc: lrcu, linux-kernel, workflows, linux-sound, rcu, linux-media,
Manuel Ebner, Kees Cook
In-Reply-To: <20260419065824.165921-4-manuelebner@mailbox.org>
Manuel Ebner <manuelebner@mailbox.org> writes:
> Update the documentation to reflect new type-aware kmalloc-family as
> suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj() and family")
>
> ptr = kmalloc(sizeof(*ptr), gfp);
> -> ptr = kmalloc_obj(*ptr, gfp);
> ptr = kmalloc(sizeof(struct some_obj_name), gfp);
> -> ptr = kmalloc_obj(*ptr, gfp);
> ptr = kzalloc(sizeof(*ptr), gfp);
> -> ptr = kzalloc_obj(*ptr, gfp);
> ptr = kmalloc_array(count, sizeof(*ptr), gfp);
> -> ptr = kmalloc_objs(*ptr, count, gfp);
> ptr = kcalloc(count, sizeof(*ptr), gfp);
> -> ptr = kzalloc_objs(*ptr, count, gfp);
>
> Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
Just to be sure, did you write this patch yourself, or did you use some
sort of coding assistant?
Adding Kees, who did this work and might have something to add here.
> ---
> .../RCU/Design/Requirements/Requirements.rst | 6 +++---
> Documentation/RCU/listRCU.rst | 2 +-
> Documentation/RCU/whatisRCU.rst | 4 ++--
This patch will surely need to be split up; the RCU folks, for example,
will want to evaluate the change separately.
> Documentation/core-api/kref.rst | 4 ++--
> Documentation/core-api/list.rst | 4 ++--
> Documentation/core-api/memory-allocation.rst | 4 ++--
> Documentation/driver-api/mailbox.rst | 4 ++--
> Documentation/driver-api/media/v4l2-fh.rst | 2 +-
> Documentation/kernel-hacking/locking.rst | 4 ++--
> Documentation/locking/locktypes.rst | 4 ++--
> Documentation/process/coding-style.rst | 8 ++++----
> .../sound/kernel-api/writing-an-alsa-driver.rst | 12 ++++++------
> Documentation/spi/spi-summary.rst | 4 ++--
> .../translations/it_IT/kernel-hacking/locking.rst | 4 ++--
> .../translations/it_IT/locking/locktypes.rst | 4 ++--
> .../translations/it_IT/process/coding-style.rst | 2 +-
> .../translations/sp_SP/process/coding-style.rst | 2 +-
> Documentation/translations/zh_CN/core-api/kref.rst | 4 ++--
> .../translations/zh_CN/process/coding-style.rst | 2 +-
> .../zh_CN/video4linux/v4l2-framework.txt | 2 +-
> .../translations/zh_TW/process/coding-style.rst | 2 +-
> 21 files changed, 42 insertions(+), 42 deletions(-)
>
> diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst
> index b5cdbba3ec2e..faca5a9c8c12 100644
> --- a/Documentation/RCU/Design/Requirements/Requirements.rst
> +++ b/Documentation/RCU/Design/Requirements/Requirements.rst
> @@ -206,7 +206,7 @@ non-\ ``NULL``, locklessly accessing the ``->a`` and ``->b`` fields.
>
> 1 bool add_gp_buggy(int a, int b)
> 2 {
> - 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
> + 3 p = kmalloc_obj(*p, GFP_KERNEL);
So you have not gone with the "implicit GFP_KERNEL" approach that Linus
added. Given that, I assume, he wanted that to be the normal style, we
should probably go with it.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH] Documentation: adopt new coding style of type-aware kmalloc-family
From: Manuel Ebner @ 2026-04-19 11:33 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc
Cc: lrcu, linux-kernel, workflows, linux-sound, rcu, linux-media,
Kees Cook
In-Reply-To: <87se8rw8df.fsf@trenco.lwn.net>
On Sun, 2026-04-19 at 04:29 -0600, Jonathan Corbet wrote:
> Manuel Ebner <manuelebner@mailbox.org> writes:
>
> > Update the documentation to reflect new type-aware kmalloc-family as
> > suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj() and
> > family")
> >
> > ptr = kmalloc(sizeof(*ptr), gfp);
> > -> ptr = kmalloc_obj(*ptr, gfp);
> > ptr = kmalloc(sizeof(struct some_obj_name), gfp);
> > -> ptr = kmalloc_obj(*ptr, gfp);
> > ptr = kzalloc(sizeof(*ptr), gfp);
> > -> ptr = kzalloc_obj(*ptr, gfp);
> > ptr = kmalloc_array(count, sizeof(*ptr), gfp);
> > -> ptr = kmalloc_objs(*ptr, count, gfp);
> > ptr = kcalloc(count, sizeof(*ptr), gfp);
> > -> ptr = kzalloc_objs(*ptr, count, gfp);
> >
> > Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
>
> Just to be sure, did you write this patch yourself, or did you use some
> sort of coding assistant?
I wrote the patch myself.
> Adding Kees, who did this work and might have something to add here.
Thanks.
> > ---
> > .../RCU/Design/Requirements/Requirements.rst | 6 +++---
> > Documentation/RCU/listRCU.rst | 2 +-
> > Documentation/RCU/whatisRCU.rst | 4 ++--
>
> This patch will surely need to be split up; the RCU folks, for example,
> will want to evaluate the change separately.
will do that in [v2]
>
> > Documentation/core-api/kref.rst | 4 ++--
> > Documentation/core-api/list.rst | 4 ++--
> > Documentation/core-api/memory-allocation.rst | 4 ++--
> > Documentation/driver-api/mailbox.rst | 4 ++--
> > Documentation/driver-api/media/v4l2-fh.rst | 2 +-
> > Documentation/kernel-hacking/locking.rst | 4 ++--
> > Documentation/locking/locktypes.rst | 4 ++--
> > Documentation/process/coding-style.rst | 8 ++++----
> > .../sound/kernel-api/writing-an-alsa-driver.rst | 12 ++++++------
> > Documentation/spi/spi-summary.rst | 4 ++--
> > .../translations/it_IT/kernel-hacking/locking.rst | 4 ++--
> > .../translations/it_IT/locking/locktypes.rst | 4 ++--
> > .../translations/it_IT/process/coding-style.rst | 2 +-
> > .../translations/sp_SP/process/coding-style.rst | 2 +-
> > Documentation/translations/zh_CN/core-api/kref.rst | 4 ++--
> > .../translations/zh_CN/process/coding-style.rst | 2 +-
> > .../zh_CN/video4linux/v4l2-framework.txt | 2 +-
> > .../translations/zh_TW/process/coding-style.rst | 2 +-
> > 21 files changed, 42 insertions(+), 42 deletions(-)
> >
> > diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst
> > b/Documentation/RCU/Design/Requirements/Requirements.rst
> > index b5cdbba3ec2e..faca5a9c8c12 100644
> > --- a/Documentation/RCU/Design/Requirements/Requirements.rst
> > +++ b/Documentation/RCU/Design/Requirements/Requirements.rst
> > @@ -206,7 +206,7 @@ non-\ ``NULL``, locklessly accessing the ``->a`` and ``-
> > >b`` fields.
> >
> > 1 bool add_gp_buggy(int a, int b)
> > 2 {
> > - 3 p = kmalloc(sizeof(*p), GFP_KERNEL);
> > + 3 p = kmalloc_obj(*p, GFP_KERNEL);
>
> So you have not gone with the "implicit GFP_KERNEL" approach that Linus
> added. Given that, I assume, he wanted that to be the normal style, we
> should probably go with it.
I scanned those 8 replies by Linus, but i can't figure out what you mean with
implicit GFP_Kernel approach, can you give me a hint?
https://lore.kernel.org/all/?q=slab%3A+Introduce+kmalloc_obj%28%29+and+family+f%3Atorvalds
> Thanks,
>
> jon
Thanks,
manuel
^ permalink raw reply
* Re: [PATCH] Documentation: adopt new coding style of type-aware kmalloc-family
From: Jonathan Corbet @ 2026-04-19 11:43 UTC (permalink / raw)
To: Manuel Ebner, Shuah Khan, linux-doc
Cc: lrcu, linux-kernel, workflows, linux-sound, rcu, linux-media,
Kees Cook
In-Reply-To: <295490d9bd8b9d519dda5c4551e7dbaf36492a8a.camel@mailbox.org>
Manuel Ebner <manuelebner@mailbox.org> writes:
>> So you have not gone with the "implicit GFP_KERNEL" approach that Linus
>> added. Given that, I assume, he wanted that to be the normal style, we
>> should probably go with it.
>
> I scanned those 8 replies by Linus, but i can't figure out what you mean with
> implicit GFP_Kernel approach, can you give me a hint?
>
> https://lore.kernel.org/all/?q=slab%3A+Introduce+kmalloc_obj%28%29+and+family+f%3Atorvalds
See https://lwn.net/Articles/1062856/
jon
^ permalink raw reply
* Re: [PATCH v2 00/11] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-19 19:04 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, Benno Lossin
In-Reply-To: <9bcb8053-2eb6-4327-ae3f-2a23321c4c3e@infradead.org>
On Sat, 18 Apr 2026 17:05:56 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:
> On 4/16/26 11:11 PM, Mauro Carvalho Chehab wrote:
> > 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(-)
> >
>
> Just a note, not asking for a change or fix:
>
> AFAICT, all P: entries are now listed nicely except for:
>
> P: rust/pin-init/CONTRIBUTING.md
That's because it doesn't follow what's expected for "P":
either a file that Sphinx can read (rst files), placed inside
Documentation/ and added to Sphinx toctree or an external html URL.
The way it is, the subsystem profile regex won't get it.
While it is not hard to add an exception, IMO the best would be
to do:
$ pandoc -fgfm -trst rust/pin-init/CONTRIBUTING.md > Documentation/process/pin-init.rst
$ sed -i s,rust/pin-init/CONTRIBUTING.md,Documentation/process/pin-init.rst, MAINTAINERS
$ git rm rust/pin-init/CONTRIBUTING.md
$ git add Documentation/process/pin-init.rst
$ git commit -as
>
> so for the series:
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
Thanks!
Mauro
^ permalink raw reply
* Re: [PATCH v2 01/11] MAINTAINERS: add an entry for media maintainers profile
From: Mauro Carvalho Chehab @ 2026-04-19 19:07 UTC (permalink / raw)
To: Randy Dunlap
Cc: Jonathan Corbet, Linux Doc Mailing List, linux-kernel,
linux-riscv, workflows, Dan Williams, Mauro Carvalho Chehab
In-Reply-To: <63c25cd9-2145-40c7-b1bc-463214d5df6c@infradead.org>
On Sat, 18 Apr 2026 17:02:55 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:
> On 4/16/26 11:11 PM, Mauro Carvalho Chehab wrote:
> > 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/
>
> I now see 2 P: entries for MEDIA INPUT INFRASTRUCTURE
> and 2 P: entries for X86 ARCHITECTURE.
> (don't know how/why)
>
My patches (and my tests) are based on docs-next. Perhaps some other
patch is adding them as well.
I'll rebase them on the top of -rc1 after it gets released.
Thanks,
Mauro
^ permalink raw reply
* [PATCH] docs: maintainer-netdev: fix typo in "targeting"
From: Ariful Islam Shoikot @ 2026-04-20 11:45 UTC (permalink / raw)
To: netdev; +Cc: linux-doc, workflows, linux-kernel, Ariful Islam Shoikot
Fix spelling mistake "targgeting" -> "targeting" in
maintainer-netdev.rst
No functional change.
Signed-off-by: Ariful Islam Shoikot <islamarifulshoikat@gmail.com>
---
Documentation/process/maintainer-netdev.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index bda93b459a05..ec7b9aa2877f 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -528,7 +528,7 @@ The exact rules a driver must follow to acquire the ``Supported`` status:
status will be withdrawn.
5. Test failures due to bugs either in the driver or the test itself,
- or lack of support for the feature the test is targgeting are
+ or lack of support for the feature the test is targeting are
*not* a basis for losing the ``Supported`` status.
netdev CI will maintain an official page of supported devices, listing their
--
2.43.0
^ permalink raw reply related
* [PATCH v7 0/5] kunit: Add support for suppressing warning backtraces
From: Albert Esteve @ 2026-04-20 12:28 UTC (permalink / raw)
To: Arnd Bergmann, Brendan Higgins, David Gow, Rae Moar,
Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann, David Airlie,
Simona Vetter, Jonathan Corbet, Shuah Khan, Andrew Morton
Cc: linux-kernel, linux-arch, linux-kselftest, kunit-dev, dri-devel,
workflows, linux-doc, peterz, Alessandro Carminati, Guenter Roeck,
Kees Cook, Albert Esteve, Linux Kernel Functional Testing,
Dan Carpenter, Maíra Canal, Kees Cook, Simona Vetter,
David Gow
Some unit tests intentionally trigger warning backtraces by passing bad
parameters to kernel API functions. Such unit tests typically check the
return value from such calls, not the existence of the warning backtrace.
Such intentionally generated warning backtraces are neither desirable
nor useful for a number of reasons:
- They can result in overlooked real problems.
- A warning that suddenly starts to show up in unit tests needs to be
investigated and has to be marked to be ignored, for example by
adjusting filter scripts. Such filters are ad hoc because there is
no real standard format for warnings. On top of that, such filter
scripts would require constant maintenance.
One option to address the problem would be to add messages such as
"expected warning backtraces start/end here" to the kernel log.
However, that would again require filter scripts, might result in
missing real problematic warning backtraces triggered while the test
is running, and the irrelevant backtrace(s) would still clog the
kernel log.
Solve the problem by providing a means to identify and suppress specific
warning backtraces while executing test code. Support suppressing multiple
backtraces while at the same time limiting changes to generic code to the
absolute minimum.
Overview:
Patch#1 Introduces the suppression infrastructure.
Patch#2 Mitigates the impact of suppression.
Patch#3 Adds selftests to validate the functionality.
Patch#4 Demonstrates real-world usage in the DRM subsystem.
Patch#5 Documents the new API and usage guidelines.
Design Notes:
The objective is to suppress unwanted WARN*() generated messages.
Although most major architectures share common bug handling via `lib/bug.c`
and `report_bug()`, some minor or legacy architectures still rely on their
own platform-specific handling. This divergence must be considered in any
such feature. Additionally, a key challenge in implementing this feature is
the fragmentation of `WARN*()` message emission: part of the output is
produced in the macro itself (via __warn_printk()), and part in the exception
handler.
Lessons from the Previous Attempt:
In earlier iterations, suppression logic was added inside the
`__report_bug()` function to intercept WARN*() output. To implement the
check in the bug handler code, two strategies were considered:
* Strategy #1: Use `kallsyms` to infer the originating function. This
approach proved unreliable due to compiler-induced transformations
such as inlining, cloning, and code fragmentation.
* Strategy #2: Store function name `__func__` in `struct bug_entry` in
the `__bug_table`. However, `__func__` is a compiler-generated symbol,
which complicates relocation and linking in position-independent code.
Additionally, architectures not using the unified `BUG()` path would
still require ad-hoc handling.
A per-macro solution was also attempted (v5-v6), injecting checks
directly into the `WARN*()` macros in `include/asm-generic/bug.h`.
While this offered full control, it required modifying the generic
bug header and was considered too invasive and damaging the critical
path, and thus incorrect [1].
Current Proposal: Check in `warn_slowpath_fmt()` and `__report_bug()`.
Suppression is checked at two points in the warning path:
- In `warn_slowpath_fmt()` (kernel/panic.c), for architectures without
__WARN_FLAGS. The check runs before any output, fully suppressing
both message and backtrace.
- In `__report_bug()` (lib/bug.c), for architectures that define
__WARN_FLAGS. The check runs before `__warn()` is called, suppressing
the backtrace and stack dump. On this path, the `WARN()` format message
may still appear in the kernel log since `__warn_printk()` executes
before the trap.
This approach avoids modifying include/asm-generic/bug.h entirely,
requires no architecture-specific code, and limits changes to generic
code to the absolute minimum.
A helper function, `__kunit_is_suppressed_warning()`, walks an RCU-
protected list of active suppressions, matching by current task. The
suppression state is dynamically allocated via kunit_kzalloc() and
tied to the KUnit test lifecycle via kunit_add_action(), ensuring
automatic cleanup at test exit.
To minimize runtime impact when no suppressions are active, an atomic
counter tracks the number of active suppressions.
`__kunit_is_suppressed_warning()` checks this counter first and returns
immediately when it is zero, avoiding the RCU-protected list traversal
in the common case.
This series is based on the RFC patch and subsequent discussion at
https://patchwork.kernel.org/project/linux-kselftest/patch/02546e59-1afe-4b08-ba81-d94f3b691c9a@moroto.mountain/
and offers a more comprehensive solution of the problem discussed there.
[1] https://lore.kernel.org/all/CAGegRW76X8Fk_5qqOBw_aqBwAkQTsc8kXKHEuu9ECeXzdJwMSw@mail.gmail.com/
Changes since RFC:
- Introduced CONFIG_KUNIT_SUPPRESS_BACKTRACE
- Minor cleanups and bug fixes
- Added support for all affected architectures
- Added support for counting suppressed warnings
- Added unit tests using those counters
- Added patch to suppress warning backtraces in dev_addr_lists tests
Changes since v1:
- Rebased to v6.9-rc1
- Added Tested-by:, Acked-by:, and Reviewed-by: tags
[I retained those tags since there have been no functional changes]
- Introduced KUNIT_SUPPRESS_BACKTRACE configuration option, enabled by
default.
Changes since v2:
- Rebased to v6.9-rc2
- Added comments to drm warning suppression explaining why it is needed.
- Added patch to move conditional code in arch/sh/include/asm/bug.h
to avoid kerneldoc warning
- Added architecture maintainers to Cc: for architecture specific patches
- No functional changes
Changes since v3:
- Rebased to v6.14-rc6
- Dropped net: "kunit: Suppress lock warning noise at end of dev_addr_lists tests"
since 3db3b62955cd6d73afde05a17d7e8e106695c3b9
- Added __kunit_ and KUNIT_ prefixes.
- Tested on interessed architectures.
Changes since v4:
- Rebased to v6.15-rc7
- Dropped all code in __report_bug()
- Moved all checks in WARN*() macros.
- Dropped all architecture specific code.
- Made __kunit_is_suppressed_warning nice to noinstr functions.
Changes since v5:
- Rebased to v7.0-rc3
- Added RCU protection for the suppressed warnings list.
- Added static key and branching optimization.
- Removed custom `strcmp` implementation and reworked
__kunit_is_suppressed_warning() entrypoint function.
Changes since v6:
- Moved suppression checks from WARN*() macros to warn_slowpath_fmt()
and __report_bug().
- Replaced stack-allocated suppression struct with kunit_kzalloc() heap
allocation tied to the KUnit test lifecycle.
- Changed suppression strategy from function-name matching to task-scoped:
all warnings on the current task are suppressed between START and END,
rather than only warnings originating from a specific named function.
- Simplified macro API: removed KUNIT_DECLARE_SUPPRESSED_WARNING(),
the START macro now takes (test) and handles allocation internally.
- Removed static key and branching optiomization, as by the time it
was executed, callers are already in warn slowpaths.
- Link to v6: https://lore.kernel.org/r/20260317-kunit_add_support-v6-0-dd22aeb3fe5d@redhat.com
Alessandro Carminati (2):
bug/kunit: Core support for suppressing warning backtraces
bug/kunit: Suppressing warning backtraces reduced impact on WARN*()
sites
Guenter Roeck (3):
Add unit tests to verify that warning backtrace suppression works.
drm: Suppress intentional warning backtraces in scaling unit tests
kunit: Add documentation for warning backtrace suppression API
Documentation/dev-tools/kunit/usage.rst | 30 ++++++-
drivers/gpu/drm/tests/drm_rect_test.c | 16 ++++
include/asm-generic/bug.h | 48 +++++++----
include/kunit/bug.h | 62 ++++++++++++++
include/kunit/test.h | 1 +
lib/kunit/Kconfig | 9 ++
lib/kunit/Makefile | 9 +-
lib/kunit/backtrace-suppression-test.c | 105 ++++++++++++++++++++++++
lib/kunit/bug.c | 54 ++++++++++++
9 files changed, 316 insertions(+), 18 deletions(-)
create mode 100644 include/kunit/bug.h
create mode 100644 lib/kunit/backtrace-suppression-test.c
create mode 100644 lib/kunit/bug.c
--
2.34.1
---
Alessandro Carminati (2):
bug/kunit: Core support for suppressing warning backtraces
bug/kunit: Reduce runtime impact of warning backtrace suppression
Guenter Roeck (3):
kunit: Add backtrace suppression self-tests
drm: Suppress intentional warning backtraces in scaling unit tests
kunit: Add documentation for warning backtrace suppression API
Documentation/dev-tools/kunit/usage.rst | 30 ++++++++++-
drivers/gpu/drm/tests/drm_rect_test.c | 14 +++++
include/kunit/bug.h | 56 ++++++++++++++++++++
include/kunit/test.h | 1 +
kernel/panic.c | 8 ++-
lib/bug.c | 8 +++
lib/kunit/Kconfig | 9 ++++
lib/kunit/Makefile | 9 +++-
lib/kunit/backtrace-suppression-test.c | 90 ++++++++++++++++++++++++++++++++
lib/kunit/bug.c | 91 +++++++++++++++++++++++++++++++++
10 files changed, 312 insertions(+), 4 deletions(-)
---
base-commit: 80234b5ab240f52fa45d201e899e207b9265ef91
change-id: 20260312-kunit_add_support-2f35806b19dd
Best regards,
--
Albert Esteve <aesteve@redhat.com>
^ permalink raw reply
* [PATCH v7 1/5] bug/kunit: Core support for suppressing warning backtraces
From: Albert Esteve @ 2026-04-20 12:28 UTC (permalink / raw)
To: Arnd Bergmann, Brendan Higgins, David Gow, Rae Moar,
Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann, David Airlie,
Simona Vetter, Jonathan Corbet, Shuah Khan, Andrew Morton
Cc: linux-kernel, linux-arch, linux-kselftest, kunit-dev, dri-devel,
workflows, linux-doc, peterz, Alessandro Carminati, Guenter Roeck,
Kees Cook, Albert Esteve
In-Reply-To: <20260420-kunit_add_support-v7-0-e8bc6e0f70de@redhat.com>
From: Alessandro Carminati <acarmina@redhat.com>
Some unit tests intentionally trigger warning backtraces by passing bad
parameters to kernel API functions. Such unit tests typically check the
return value from such calls, not the existence of the warning backtrace.
Such intentionally generated warning backtraces are neither desirable
nor useful for a number of reasons:
- They can result in overlooked real problems.
- A warning that suddenly starts to show up in unit tests needs to be
investigated and has to be marked to be ignored, for example by
adjusting filter scripts. Such filters are ad hoc because there is
no real standard format for warnings. On top of that, such filter
scripts would require constant maintenance.
Solve the problem by providing a means to identify and suppress specific
warning backtraces while executing test code. Support suppressing multiple
backtraces while at the same time limiting changes to generic code to the
absolute minimum.
Implementation details:
Suppression is checked at two points in the warning path:
- In warn_slowpath_fmt(), the check runs before any output, fully
suppressing both message and backtrace.
- In __report_bug(), the check runs before __warn() is called,
suppressing the backtrace and stack dump. Note that on this path,
the WARN() format message may still appear in the kernel log since
__warn_printk() runs before the trap that enters __report_bug().
A helper function, `__kunit_is_suppressed_warning()`, walks an
RCU-protected list of active suppressions, matching by current task.
The suppression state is tied to the KUnit test lifecycle via
kunit_add_action(), ensuring automatic cleanup at test exit.
The list of suppressed warnings is protected with RCU to allow
concurrent read access without locks.
The implementation is deliberately simple and avoids architecture-specific
optimizations to preserve portability.
Signed-off-by: Guenter Roeck <linux@roeck-us.net>
Signed-off-by: Alessandro Carminati <acarmina@redhat.com>
Reviewed-by: Kees Cook <kees@kernel.org>
Signed-off-by: Albert Esteve <aesteve@redhat.com>
---
include/kunit/bug.h | 56 +++++++++++++++++++++++++++++++++++
include/kunit/test.h | 1 +
kernel/panic.c | 8 ++++-
lib/bug.c | 8 +++++
lib/kunit/Kconfig | 9 ++++++
lib/kunit/Makefile | 6 ++--
lib/kunit/bug.c | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++
7 files changed, 169 insertions(+), 3 deletions(-)
diff --git a/include/kunit/bug.h b/include/kunit/bug.h
new file mode 100644
index 0000000000000..e52c9d21d9fe6
--- /dev/null
+++ b/include/kunit/bug.h
@@ -0,0 +1,56 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * KUnit helpers for backtrace suppression
+ *
+ * Copyright (C) 2025 Alessandro Carminati <acarmina@redhat.com>
+ * Copyright (C) 2024 Guenter Roeck <linux@roeck-us.net>
+ */
+
+#ifndef _KUNIT_BUG_H
+#define _KUNIT_BUG_H
+
+#ifndef __ASSEMBLY__
+
+#include <linux/kconfig.h>
+
+struct kunit;
+
+#ifdef CONFIG_KUNIT_SUPPRESS_BACKTRACE
+
+#include <linux/types.h>
+
+struct task_struct;
+
+struct __suppressed_warning {
+ struct list_head node;
+ struct task_struct *task;
+ int counter;
+};
+
+struct __suppressed_warning *
+__kunit_start_suppress_warning(struct kunit *test);
+void __kunit_end_suppress_warning(struct kunit *test,
+ struct __suppressed_warning *warning);
+int __kunit_suppressed_warning_count(struct __suppressed_warning *warning);
+bool __kunit_is_suppressed_warning(void);
+
+#define KUNIT_START_SUPPRESSED_WARNING(test) \
+ struct __suppressed_warning *__kunit_suppress = \
+ __kunit_start_suppress_warning(test)
+
+#define KUNIT_END_SUPPRESSED_WARNING(test) \
+ __kunit_end_suppress_warning(test, __kunit_suppress)
+
+#define KUNIT_SUPPRESSED_WARNING_COUNT() \
+ __kunit_suppressed_warning_count(__kunit_suppress)
+
+#else /* CONFIG_KUNIT_SUPPRESS_BACKTRACE */
+
+#define KUNIT_START_SUPPRESSED_WARNING(test)
+#define KUNIT_END_SUPPRESSED_WARNING(test)
+#define KUNIT_SUPPRESSED_WARNING_COUNT() 0
+static inline bool __kunit_is_suppressed_warning(void) { return false; }
+
+#endif /* CONFIG_KUNIT_SUPPRESS_BACKTRACE */
+#endif /* __ASSEMBLY__ */
+#endif /* _KUNIT_BUG_H */
diff --git a/include/kunit/test.h b/include/kunit/test.h
index 9cd1594ab697d..4ec07b3fa0204 100644
--- a/include/kunit/test.h
+++ b/include/kunit/test.h
@@ -10,6 +10,7 @@
#define _KUNIT_TEST_H
#include <kunit/assert.h>
+#include <kunit/bug.h>
#include <kunit/try-catch.h>
#include <linux/args.h>
diff --git a/kernel/panic.c b/kernel/panic.c
index c78600212b6c1..d7a7a679f56c4 100644
--- a/kernel/panic.c
+++ b/kernel/panic.c
@@ -39,6 +39,7 @@
#include <linux/sys_info.h>
#include <trace/events/error_report.h>
#include <asm/sections.h>
+#include <kunit/bug.h>
#define PANIC_TIMER_STEP 100
#define PANIC_BLINK_SPD 18
@@ -1080,9 +1081,14 @@ void __warn(const char *file, int line, void *caller, unsigned taint,
void warn_slowpath_fmt(const char *file, int line, unsigned taint,
const char *fmt, ...)
{
- bool rcu = warn_rcu_enter();
+ bool rcu;
struct warn_args args;
+ if (__kunit_is_suppressed_warning())
+ return;
+
+ rcu = warn_rcu_enter();
+
pr_warn(CUT_HERE);
if (!fmt) {
diff --git a/lib/bug.c b/lib/bug.c
index 623c467a8b76c..606205c8c302f 100644
--- a/lib/bug.c
+++ b/lib/bug.c
@@ -48,6 +48,7 @@
#include <linux/rculist.h>
#include <linux/ftrace.h>
#include <linux/context_tracking.h>
+#include <kunit/bug.h>
extern struct bug_entry __start___bug_table[], __stop___bug_table[];
@@ -223,6 +224,13 @@ static enum bug_trap_type __report_bug(struct bug_entry *bug, unsigned long buga
no_cut = bug->flags & BUGFLAG_NO_CUT_HERE;
has_args = bug->flags & BUGFLAG_ARGS;
+ /*
+ * Before the once logic so suppressed warnings do not consume
+ * the single-fire budget of WARN_ON_ONCE().
+ */
+ if (warning && __kunit_is_suppressed_warning())
+ return BUG_TRAP_TYPE_WARN;
+
if (warning && once) {
if (done)
return BUG_TRAP_TYPE_WARN;
diff --git a/lib/kunit/Kconfig b/lib/kunit/Kconfig
index 498cc51e493dc..57527418fcf09 100644
--- a/lib/kunit/Kconfig
+++ b/lib/kunit/Kconfig
@@ -15,6 +15,15 @@ menuconfig KUNIT
if KUNIT
+config KUNIT_SUPPRESS_BACKTRACE
+ bool "KUnit - Enable backtrace suppression"
+ default y
+ help
+ Enable backtrace suppression for KUnit. If enabled, backtraces
+ generated intentionally by KUnit tests are suppressed. Disable
+ to reduce kernel image size if image size is more important than
+ suppression of backtraces generated by KUnit tests.
+
config KUNIT_DEBUGFS
bool "KUnit - Enable /sys/kernel/debug/kunit debugfs representation" if !KUNIT_ALL_TESTS
default KUNIT_ALL_TESTS
diff --git a/lib/kunit/Makefile b/lib/kunit/Makefile
index 656f1fa35abcc..fe177ff3ebdef 100644
--- a/lib/kunit/Makefile
+++ b/lib/kunit/Makefile
@@ -16,8 +16,10 @@ ifeq ($(CONFIG_KUNIT_DEBUGFS),y)
kunit-objs += debugfs.o
endif
-# KUnit 'hooks' are built-in even when KUnit is built as a module.
-obj-$(if $(CONFIG_KUNIT),y) += hooks.o
+# KUnit 'hooks' and bug handling are built-in even when KUnit is built
+# as a module.
+obj-$(if $(CONFIG_KUNIT),y) += hooks.o \
+ bug.o
obj-$(CONFIG_KUNIT_TEST) += kunit-test.o
obj-$(CONFIG_KUNIT_TEST) += platform-test.o
diff --git a/lib/kunit/bug.c b/lib/kunit/bug.c
new file mode 100644
index 0000000000000..356c8a5928828
--- /dev/null
+++ b/lib/kunit/bug.c
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * KUnit helpers for backtrace suppression
+ *
+ * Copyright (C) 2025 Alessandro Carminati <acarmina@redhat.com>
+ * Copyright (C) 2024 Guenter Roeck <linux@roeck-us.net>
+ */
+
+#include <kunit/bug.h>
+#include <kunit/resource.h>
+#include <linux/export.h>
+#include <linux/rculist.h>
+#include <linux/sched.h>
+
+#ifdef CONFIG_KUNIT_SUPPRESS_BACKTRACE
+
+static LIST_HEAD(suppressed_warnings);
+
+static void __kunit_suppress_warning_remove(struct __suppressed_warning *warning)
+{
+ list_del_rcu(&warning->node);
+ synchronize_rcu(); /* Wait for readers to finish */
+}
+
+KUNIT_DEFINE_ACTION_WRAPPER(__kunit_suppress_warning_cleanup,
+ __kunit_suppress_warning_remove,
+ struct __suppressed_warning *);
+
+struct __suppressed_warning *
+__kunit_start_suppress_warning(struct kunit *test)
+{
+ struct __suppressed_warning *warning;
+ int ret;
+
+ warning = kunit_kzalloc(test, sizeof(*warning), GFP_KERNEL);
+ if (!warning)
+ return NULL;
+
+ warning->task = current;
+ list_add_rcu(&warning->node, &suppressed_warnings);
+
+ ret = kunit_add_action_or_reset(test,
+ __kunit_suppress_warning_cleanup,
+ warning);
+ if (ret)
+ return NULL;
+
+ return warning;
+}
+EXPORT_SYMBOL_GPL(__kunit_start_suppress_warning);
+
+void __kunit_end_suppress_warning(struct kunit *test,
+ struct __suppressed_warning *warning)
+{
+ if (!warning)
+ return;
+ kunit_release_action(test, __kunit_suppress_warning_cleanup, warning);
+}
+EXPORT_SYMBOL_GPL(__kunit_end_suppress_warning);
+
+int __kunit_suppressed_warning_count(struct __suppressed_warning *warning)
+{
+ return warning ? warning->counter : 0;
+}
+EXPORT_SYMBOL_GPL(__kunit_suppressed_warning_count);
+
+bool __kunit_is_suppressed_warning(void)
+{
+ struct __suppressed_warning *warning;
+
+ rcu_read_lock();
+ list_for_each_entry_rcu(warning, &suppressed_warnings, node) {
+ if (warning->task == current) {
+ warning->counter++;
+ rcu_read_unlock();
+ return true;
+ }
+ }
+ rcu_read_unlock();
+
+ return false;
+}
+
+#endif /* CONFIG_KUNIT_SUPPRESS_BACKTRACE */
--
2.52.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