* [PATCH v3 00/13] Improve process/maintainers output
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Mauro Carvalho Chehab, Miguel Ojeda
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, rust-for-linux,
Björn Roy Baron, Alice Ryhl, Andreas Hindborg, Andrew Morton,
Benno Lossin, Boqun Feng, Danilo Krummrich, Gary Guo, Joe Perches,
Matteo Croce, Shuah Khan, Trevor Gross
Hi Jon,
This series improve the output at process/maintainers: instead of a
pure enriched text, the maintainer's file content is now converted
to a table, and has gained a javascript to allow filtering entries.
The initial patches change the logic to split parsing from
output generation. Then, everything is stored into a dict at
the parsing phase, and ona header description variable.
This way, it is easier to adjust the output handler to produce
a more structured document. Right now, the entries are sorted
alphabetically, per subsystem's name(*).
(*) Currently, MAINTAINERS file has several entries not sorted.
One has to run:
scripts/parse-maintainers.pl --input MAINTAINERS --output MAINTAINERS.new
to sort it.
-
v3:
- don't remove rust/pin-init/CONTRIBUTING.md;
- added two extra patches due to sashiko-bot feedback, to better
handle wildcards and paths;
- fixed some issues related with O=DIRS;
v2:
- now, entries are sorted internally, instead of trusting that
MAINTAINERS is already sorted;
- file fields inside the description are now showing as literals;
- Added a change in MAINTAINERS for rust-init profile;
- Make it clearer at MAINTAINERS description that "P" expects
a rst file;
- fixed several bugs related to using or not O=DOCS.
Mauro Carvalho Chehab (13):
docs: maintainers_include: keep hidden TOC sorted
docs: maintainers_include: split state machine on multiple funcs
docs: maintainers_include: cleanup the code
docs: maintainers_include: clean most SPHINXDIRS=process warnings
docs: maintainers_include: do some coding style cleanups
docs: maintainers_include: store maintainers entries on a dict
docs: maintainers_include: properly handle file patterns
docs: maintainers_include: add a filtering javascript
docs: maintainers_include: don't ignore invalid profile entries
docs: maintainers_include: better handle directories
docs: maintainers_include: better handle doc wildcards
MAINTAINERS: make clearer about what's expected for "P" field
MAINTAINERS: use a URL for pin-init maintainer's profile entry
Documentation/sphinx/maintainers_include.py | 478 ++++++++++++--------
MAINTAINERS | 8 +-
2 files changed, 294 insertions(+), 192 deletions(-)
--
2.54.0
^ permalink raw reply
* [PATCH v3 08/13] docs: maintainers_include: add a filtering javascript
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux, Shuah Khan
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
The maintainers table is big. Add a javascript to allow filtering
it. Such script is only added at the page which contains the
maintainers-include tag.
I opted to keep the search case-sensitive, as, this way,
upper case searches at subsystem.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <c435ef150f5d6ed16570969f43d92ba6fb857842.1777987027.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 78 +++++++++++++++++++--
1 file changed, 72 insertions(+), 6 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 5361774b61bc..7035754a1c66 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -31,6 +31,49 @@ __version__ = "1.0"
maint_parser = None # pylint: disable=C0103
+JS_FILTER = """
+(function() {
+ function filterTable(table) {
+ const filter = document.getElementById("filter-table").value.trim();
+ const rows = table.querySelectorAll("tbody tr");
+ for (let i = 0; i < rows.length; i++) {
+ const tds = rows[i].getElementsByTagName("td");
+ let match = false;
+ for (let j = 0; j < tds.length; j++) {
+ const cellText = (tds[j].textContent || tds[j].innerText);
+ if (cellText.includes(filter)) {
+ match = true;
+ break;
+ }
+ }
+ rows[i].style.display = match ? "table-row" : "none";
+ }
+ }
+ function addInput() {
+ const table = document.getElementById("maintainers-table");
+ if (!table) return;
+ let input = document.getElementById("filter-table");
+ if (!input) {
+ const filt_div = document.createElement('div');
+ filt_div.innerHTML = `
+ <p>Filter:
+ <input type="search" id="filter-table" placeholder="search string"/>
+ subsystem or property (case-sensitive)
+ </p>
+ `;
+ table.parentNode.insertBefore(filt_div, table);
+ const input = document.getElementById("filter-table")
+ input.addEventListener('input', () => filterTable(table));
+ }
+ }
+ if (document.readyState === 'loading') {
+ document.addEventListener('DOMContentLoaded', addInput);
+ } else {
+ addInput();
+ }
+})();
+"""
+
# Shamelessly stolen from docutils
def ErrorString(exc): # pylint: disable=C0103, C0116
@@ -59,7 +102,7 @@ class MaintainersParser:
#
self.profile_toc = set()
self.profile_entries = {}
- self.header = ".. _maintainers:\n\n"
+ self.header = ""
self.maint_entries = {}
self.fields = {}
@@ -228,15 +271,28 @@ class MaintainersInclude(Include):
def emit(self):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
path = maint_parser.path
- output = maint_parser.header
+ output = ".. _maintainers:\n\n"
+ output += maint_parser.header
+
+ output += ".. _maintainers_table:\n\n"
+ output += ".. flat-table::\n"
+ output += " :header-rows: 1\n\n"
+ output += " * - Subsystem\n"
+ output += " - Properties\n\n"
+
+ self.state.document['maintainers_included'] = True
for name, fields in sorted(maint_parser.maint_entries.items()):
- output += "\n" + name + "\n"
- output += "~" * len(name) + "\n"
-
+ output += f" * - {name}\n"
+ tag = "-"
for field, lines in fields.items():
field_name = maint_parser.fields.get(field, field)
- output += f":{field_name}:\n\t" + ",\n\t".join(lines) + "\n\n"
+
+ output += f" {tag} :{field_name}:\n "
+ output += ",\n ".join(lines) + "\n"
+ tag = " "
+
+ output += "\n"
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
@@ -308,6 +364,14 @@ class MaintainersProfile(Include):
return []
+# pylint: disable=W0613
+def add_filter_script(app, pagename, templatename, context, doctree):
+ """Add Filter javascript only to maintainers page"""
+
+ if doctree and doctree.get('maintainers_included'):
+ app.add_js_file(None, body=JS_FILTER)
+
+
def setup(app):
"""Setup Sphinx extension"""
global maint_parser # pylint: disable=W0603
@@ -325,6 +389,8 @@ def setup(app):
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
+ app.connect("html-page-context", add_filter_script)
+
return {
"version": __version__,
"parallel_read_safe": True,
--
2.54.0
^ permalink raw reply related
* [PATCH v3 09/13] docs: maintainers_include: don't ignore invalid profile entries
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux,
Björn Roy Baron, Alice Ryhl, Andreas Hindborg, Benno Lossin,
Boqun Feng, Danilo Krummrich, Gary Guo, Miguel Ojeda, Shuah Khan,
Trevor Gross
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
Currently, there is a "P" entry for Rust pin-init that is
neither a valid ReST file inside Documentation nor an URL.
A proper fix is to either convert/move the file or point to
a URL. Yet, the parser should be able to pick what's there and
show on its output.
Add a logic to produce a warning when this happens.
Message-ID: <63228e005fcf3dc4583cee06905341e8bce84181.1777987027.git.mchehab+huawei@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 7035754a1c66..073a10575872 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -240,6 +240,8 @@ class MaintainersParser:
if match:
entry = match.group(1).strip()
self.profile_entries[self.subsystem_name] = entry
+ else:
+ self.profile_entries[self.subsystem_name] = f"``{details}``"
details = self.linkify(details)
@@ -328,12 +330,15 @@ class MaintainersProfile(Include):
#
output = ""
for profile, entry in sorted(maint_parser.profile_entries.items()):
- profile = profile.title()
+ name = profile.title()
if entry.startswith("http"):
- output += f"- `{profile} <{entry}>`_\n"
+ output += f"- `{name} <{entry}>`_\n"
+ elif entry.startswith("`"):
+ output += f"- {name}: {entry}\n"
+ self.warning(f"{profile}: Invalid 'P' tag: {entry}\n")
else:
- output += f"- :doc:`{profile} <{entry}>`\n"
+ output += f"- :doc:`{name} <{entry}>`\n"
#
# Create a hidden TOC table with all profiles. That allows adding
--
2.54.0
^ permalink raw reply related
* [PATCH v3 12/13] MAINTAINERS: make clearer about what's expected for "P" field
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux,
Mauro Carvalho Chehab
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
The "P" field is meant to point to a subsystem maintainer's
profile, stored either at the Kernel documentation or on an
external site. Make it clearer.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <921e5e6a074f9d8cf77483d73e6801f49254bbb8.1777987027.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/MAINTAINERS b/MAINTAINERS
index 2fb1c75afd16..77244b7f9545 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -25,9 +25,9 @@ Descriptions of section entries and preferred order
C: URI for *chat* protocol, server and channel where developers
usually hang out, for example irc://server/channel.
P: *Subsystem Profile* document for more details submitting
- patches to the given subsystem. This is either an in-tree file,
- or a URI. See Documentation/maintainer/maintainer-entry-profile.rst
- for details.
+ patches to the given subsystem. This is either an in-tree .rst file
+ inside Documentation/, or a URI.
+ See Documentation/maintainer/maintainer-entry-profile.rst for details.
T: *SCM* tree type and location.
Type is one of: git, hg, quilt, stgit, topgit
F: *Files* and directories wildcard patterns.
--
2.54.0
^ permalink raw reply related
* [PATCH v3 07/13] docs: maintainers_include: properly handle file patterns
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux,
Andrew Morton, Joe Perches, Matteo Croce, Shuah Khan,
Matteo Croce
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
handling asterisks inside file patterns atdescription part is
problematic, as ReST has special meaning for them. Due to
that, convert such patterns to literal strings.
Reported-by: Matteo Croce <teknoraver@meta.com>
Fixes: 420849332f9f ("get_maintainer: add ** glob pattern support")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <89127706fb3493d00ecb21e528c8a27081e5ed40.1777987027.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 26 ++++++++++-----------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index ed9cd7b3dc66..5361774b61bc 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -47,9 +47,6 @@ class MaintainersParser:
self.maintainers = False
self.subsystems = False
- # Field letter to field name mapping.
- self.field_letter = None
-
self.subsystem_name = None
self.app_dir = os.path.abspath(app_dir)
@@ -125,19 +122,22 @@ class MaintainersParser:
self.header += "\n" + line
return
- # Escape the escapes in preformatted text.
- self.header += "| " + self.linkify(line).replace("\\", "\\\\")
-
# Look for and record field letter to field name mappings:
# R: Designated *reviewer*: FullName <address@domain>
- m = re.search(r"\s(\S):\s", line)
+ m = re.match(r"\s+(\S):\s+(\S+)", line)
if m:
- self.field_letter = m.group(1)
+ field = m.group(1)
+ details = m.group(2)
+
+ if field not in self.fields:
+ m = re.search(r"\*([^\*]+)\*", line)
+ if m:
+ self.fields[field] = m.group(1)
+ elif field in ['F', 'N', 'X', 'K']:
+ line = line.replace(details, f'``{details}``')
+
+ self.header += "| " + self.linkify(line)
- if self.field_letter and self.field_letter not in self.fields:
- m = re.search(r"\*([^\*]+)\*", line)
- if m:
- self.fields[self.field_letter] = m.group(1)
def parse_subsystems(self, line):
"""Handle contents of the per-subsystem sections."""
@@ -206,7 +206,7 @@ class MaintainersParser:
#
if field in ['F', 'N', 'X', 'K']:
# But only if not already marked :)
- if not ':doc:' in details:
+ if ':doc:' not in details and "http" not in details:
details = '``%s``' % (details)
if self.subsystem_name not in self.maint_entries:
--
2.54.0
^ permalink raw reply related
* [PATCH v3 13/13] MAINTAINERS: use a URL for pin-init maintainer's profile entry
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Miguel Ojeda
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux,
Björn Roy Baron, Alice Ryhl, Andreas Hindborg, Benno Lossin,
Boqun Feng, Danilo Krummrich, Gary Guo, Mauro Carvalho Chehab,
Trevor Gross
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
This maintainer's entry is not inside documentation nor is
ReST, preventing Sphinx to create a hyperlink to it.
Change it to point to the already-formatted URL.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <1bceee886b9027d66bbb48d9d6c8d1250ce8dbcb.1777987028.git.mchehab+huawei@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
MAINTAINERS | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/MAINTAINERS b/MAINTAINERS
index 77244b7f9545..dd424a4f9f3b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -23402,7 +23402,7 @@ S: Maintained
W: https://rust-for-linux.com/pin-init
B: https://github.com/Rust-for-Linux/pin-init/issues
C: zulip://rust-for-linux.zulipchat.com
-P: rust/pin-init/CONTRIBUTING.md
+P: https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md
T: git https://github.com/Rust-for-Linux/linux.git pin-init-next
F: rust/kernel/init.rs
F: rust/pin-init/
--
2.54.0
^ permalink raw reply related
* [PATCH v3 03/13] docs: maintainers_include: cleanup the code
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux, Shuah Khan
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
Simplify the logic without affecting the output result.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <24a83995778de8710cac40a3089c2f2fe5c38dbd.1777987027.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 184 ++++++++++----------
1 file changed, 91 insertions(+), 93 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 6d47d55f5b73..615af227a8f8 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -44,10 +44,6 @@ class MaintainersParser:
def __init__(self, app_dir, path):
self.path = path
- self.profile_toc = set()
- self.profile_entries = {}
-
- self.output = ".. _maintainers:\n\n"
# Poor man's state machine.
self.descriptions = False
@@ -67,6 +63,13 @@ class MaintainersParser:
self.re_doc = re.compile(r'(Documentation/([^\s\?\*]*)\.rst)')
+ #
+ # Output variables with maintainers content to be stored
+ #
+ self.profile_toc = set()
+ self.profile_entries = {}
+ self.output = ".. _maintainers:\n\n"
+
prev = None
for line in open(path):
if self.descriptions:
@@ -98,6 +101,16 @@ class MaintainersParser:
self.output = self.output.rstrip()
+
+ def linkify(self, text):
+ """Linkify all non-wildcard refs to ReST files in Documentation/"""
+ m = self.re_doc.search(text)
+ if m:
+ # maintainers.rst is in a subdirectory, so include "../".
+ text = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), text)
+
+ return text
+
def parse_descriptions(self, line):
"""Handle contents of the descriptions section."""
@@ -107,14 +120,8 @@ class MaintainersParser:
self.output += "\n" + line
return
- # Linkify all non-wildcard refs to ReST files in Documentation/.
- m = self.re_doc.search(line)
- if m:
- # maintainers.rst is in a subdirectory, so include "../".
- line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
-
# Escape the escapes in preformatted text.
- output = "| %s" % (line.replace("\\", "\\\\"))
+ self.output += "| " + self.linkify(line).replace("\\", "\\\\")
# Look for and record field letter to field name mappings:
# R: Designated *reviewer*: FullName <address@domain>
@@ -127,105 +134,96 @@ class MaintainersParser:
if m:
self.fields[self.field_letter] = m.group(1)
- # Append parsed content to self.output
- self.output += output
-
def parse_subsystems(self, line):
"""Handle contents of the per-subsystem sections."""
# Drop needless input whitespace.
line = line.rstrip()
+ # Skip empty lines: subsystem parser adds them as needed.
+ if not line:
+ return
+
+ # Subsystem fields are batched into "field_content"
+ if line[1] != ':':
+ line = self.linkify(line)
+
+ # Render a subsystem entry as:
+ # SUBSYSTEM NAME
+ # ~~~~~~~~~~~~~~
+ # Flush pending field content.
+ self.output += self.field_content + "\n\n"
+ self.field_content = ""
+
+ self.subsystem_name = line.title()
+
+ # Collapse whitespace in subsystem name.
+ heading = re.sub(r"\s+", " ", line)
+ self.output += "%s\n%s" % (heading, "~" * len(heading)) + "\n"
+ self.field_prev = ""
+
+ return
+
+ # Render a subsystem field as:
+ # :Field: entry
+ # entry...
+ field, details = line.split(':', 1)
+ details = details.strip()
+
#
# Handle profile entries - either as files or as https refs
#
- match = re.match(rf"P:\s*({self.doc_dir})(/\S+)\.rst", line)
- if match:
- name = "".join(match.groups())
- entry = os.path.relpath(self.base_dir + name, self.app_dir)
-
- full_name = os.path.join(self.base_dir, name)
- path = os.path.relpath(full_name, self.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
-
- if "*" in entry:
- for e in glob(entry):
- self.profile_toc.add(e)
- self.profile_entries[self.subsystem_name] = e
- else:
- self.profile_toc.add(entry)
- self.profile_entries[self.subsystem_name] = entry
- else:
- match = re.match(r"P:\s*(https?://.*)", line)
+ if field == "P":
+ match = self.re_doc.match(details)
if match:
- entry = match.group(1).strip()
- self.profile_entries[self.subsystem_name] = entry
+ name = "".join(match.groups())
+ entry = os.path.relpath(self.base_dir + name, self.app_dir)
- # Linkify all non-wildcard refs to ReST files in Documentation/.
- m = self.re_doc.search(line)
- if m:
- # maintainers.rst is in a subdirectory, so include "../".
- line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
+ full_name = os.path.join(self.base_dir, name)
+ path = os.path.relpath(full_name, self.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
- # Check state machine for output rendering behavior.
- output = None
- if self.subsystems:
- # Skip empty lines: subsystem parser adds them as needed.
- if len(line) == 0:
- return
- # Subsystem fields are batched into "field_content"
- if line[1] != ':':
- # Render a subsystem entry as:
- # SUBSYSTEM NAME
- # ~~~~~~~~~~~~~~
- # Flush pending field content.
- output = self.field_content + "\n\n"
- self.field_content = ""
-
- self.subsystem_name = line.title()
-
- # Collapse whitespace in subsystem name.
- heading = re.sub(r"\s+", " ", line)
- output = output + "%s\n%s" % (heading, "~" * len(heading))
- self.field_prev = ""
+ if "*" in entry:
+ for e in glob(entry):
+ self.profile_toc.add(e)
+ self.profile_entries[self.subsystem_name] = e
+ else:
+ self.profile_toc.add(entry)
+ self.profile_entries[self.subsystem_name] = entry
else:
- # Render a subsystem field as:
- # :Field: entry
- # entry...
- field, details = line.split(':', 1)
- details = details.strip()
+ match = re.match(r"(https?://.*)", details)
+ if match:
+ entry = match.group(1).strip()
+ self.profile_entries[self.subsystem_name] = entry
- # Mark paths (and regexes) as literal text for improved
- # readability and to escape any escapes.
- if field in ['F', 'N', 'X', 'K']:
- # But only if not already marked :)
- if not ':doc:' in details:
- details = '``%s``' % (details)
+ details = self.linkify(details)
- # Comma separate email field continuations.
- if field == self.field_prev and self.field_prev in ['M', 'R', 'L']:
- self.field_content = self.field_content + ","
+ # Mark paths (and regexes) as literal text for improved
+ # readability and to escape any escapes.
+ if field in ['F', 'N', 'X', 'K']:
+ # But only if not already marked :)
+ if not ':doc:' in details:
+ details = '``%s``' % (details)
- # Do not repeat field names, so that field entries
- # will be collapsed together.
- if field != self.field_prev:
- output = self.field_content + "\n"
- self.field_content = ":%s:" % (self.fields.get(field, field))
- self.field_content = self.field_content + "\n\t%s" % (details)
- self.field_prev = field
- elif not self.descriptions:
- output = line
+ # Comma separate email field continuations.
+ if field == self.field_prev and self.field_prev in ['M', 'R', 'L']:
+ self.field_content = self.field_content + ","
- if output is not None:
- self.output += output + "\n"
+ # Do not repeat field names, so that field entries
+ # will be collapsed together.
+ if field != self.field_prev:
+ self.output += self.field_content + "\n\n"
+ self.field_content = ":%s:" % (self.fields.get(field, field))
+ self.field_content = self.field_content + "\n\t%s" % (details)
+ self.field_prev = field
class MaintainersInclude(Include):
--
2.54.0
^ permalink raw reply related
* [PATCH v3 05/13] docs: maintainers_include: do some coding style cleanups
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux, Shuah Khan
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
Minor coding style adjustments to use the style most python
doc scripts are following.
No functional changes.
Assisted-by: pylint, black
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <460aabd0518f080b34e12fdc0beb7ec7685d5866.1777987027.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 101 ++++++++++----------
1 file changed, 51 insertions(+), 50 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index d3ad01e5309e..345eb28804ff 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -1,30 +1,25 @@
#!/usr/bin/env python
# SPDX-License-Identifier: GPL-2.0
# -*- coding: utf-8; mode: python -*-
-# pylint: disable=R0903, C0330, R0914, R0912, E0401
+# pylint: disable=C0209, C0301, E0401, R0022, R0902, R0903, R0912, R0914
"""
- maintainers-include
- ~~~~~~~~~~~~~~~~~~~
+Implementation of the ``maintainers-include`` reST-directive.
- Implementation of the ``maintainers-include`` reST-directive.
+:copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org>
+:license: GPL Version 2, June 1991 see linux/COPYING for details.
- :copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org>
- :license: GPL Version 2, June 1991 see linux/COPYING for details.
-
- The ``maintainers-include`` reST-directive performs extensive parsing
- specific to the Linux kernel's standard "MAINTAINERS" file, in an
- effort to avoid needing to heavily mark up the original plain text.
+The ``maintainers-include`` reST-directive performs extensive parsing
+specific to the Linux kernel's standard "MAINTAINERS" file, in an
+effort to avoid needing to heavily mark up the original plain text.
"""
-import sys
-import re
import os.path
+import re
from glob import glob
from docutils import statemachine
-from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
#
@@ -32,12 +27,14 @@ from docutils.parsers.rst.directives.misc import Include
#
KERNELDOC_URL = "https://docs.kernel.org/"
-def ErrorString(exc): # Shamelessly stolen from docutils
- return f'{exc.__class__.__name}: {exc}'
+__version__ = "1.0"
-__version__ = '1.0'
+maint_parser = None # pylint: disable=C0103
-maint_parser = None
+
+# Shamelessly stolen from docutils
+def ErrorString(exc): # pylint: disable=C0103, C0116
+ return f"{exc.__class__.__name}: {exc}" # pylint: disable=W0212
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
@@ -52,7 +49,7 @@ class MaintainersParser:
# Field letter to field name mapping.
self.field_letter = None
- self.fields = dict()
+ self.fields = {}
self.field_prev = ""
self.field_content = ""
@@ -71,29 +68,30 @@ class MaintainersParser:
self.output = ".. _maintainers:\n\n"
prev = None
- for line in open(path):
- if self.descriptions:
- self.parse_descriptions(line)
- elif self.maintainers and not self.subsystems:
- if re.search('^[A-Z0-9]', line):
- self.subsystems = True
+ with open(path, "r", encoding="utf-8") as fp:
+ for line in fp:
+ if self.descriptions:
+ self.parse_descriptions(line)
+ elif self.maintainers and not self.subsystems:
+ if re.search('^[A-Z0-9]', line):
+ self.subsystems = True
+ self.parse_subsystems(line)
+ else:
+ self.output += line
+ elif self.subsystems:
self.parse_subsystems(line)
else:
self.output += line
- elif self.subsystems:
- self.parse_subsystems(line)
- else:
- self.output += line
- # Update the state machine when we find heading separators.
- if line.startswith('----------'):
- if prev.startswith('Descriptions'):
- self.descriptions = True
- if prev.startswith('Maintainers'):
- self.maintainers = True
+ # Update the state machine when we find heading separators.
+ if line.startswith("----------"):
+ if prev.startswith("Descriptions"):
+ self.descriptions = True
+ if prev.startswith("Maintainers"):
+ self.maintainers = True
- # Retain previous line for state machine transitions.
- prev = line
+ # Retain previous line for state machine transitions.
+ prev = line
# Flush pending field contents.
if self.field_content:
@@ -130,7 +128,7 @@ class MaintainersParser:
"""Handle contents of the descriptions section."""
# Have we reached the end of the preformatted Descriptions text?
- if line.startswith('Maintainers'):
+ if line.startswith("Maintainers"):
self.descriptions = False
self.output += "\n" + line
return
@@ -182,7 +180,7 @@ class MaintainersParser:
# Render a subsystem field as:
# :Field: entry
# entry...
- field, details = line.split(':', 1)
+ field, details = line.split(":", 1)
details = details.strip()
#
@@ -248,12 +246,11 @@ class MaintainersParser:
class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
+
required_arguments = 0
def emit(self):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
- global maint_parser
-
path = maint_parser.path
output = maint_parser.output
@@ -269,20 +266,21 @@ class MaintainersInclude(Include):
raise self.warning('"%s" directive disabled.' % self.name)
try:
- lines = self.emit()
+ self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
class MaintainersProfile(Include):
+ """Generate a list with all maintainer's profiles"""
+
required_arguments = 0
def emit(self):
"""Parse all the MAINTAINERS lines looking for profile entries"""
- global maint_parser
-
path = maint_parser.path
#
@@ -316,15 +314,17 @@ class MaintainersProfile(Include):
raise self.warning('"%s" directive disabled.' % self.name)
try:
- lines = self.emit()
+ self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
def setup(app):
- global maint_parser
+ """Setup Sphinx extension"""
+ global maint_parser # pylint: disable=W0603
#
# NOTE: we're using os.fspath() here because of a Sphinx warning:
@@ -338,8 +338,9 @@ 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
- )
+
+ return {
+ "version": __version__,
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ }
--
2.54.0
^ permalink raw reply related
* [PATCH v3 02/13] docs: maintainers_include: split state machine on multiple funcs
From: Mauro Carvalho Chehab @ 2026-05-09 6:56 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, rust-for-linux, Shuah Khan
In-Reply-To: <cover.1778309595.git.mchehab+huawei@kernel.org>
Instead of one big __init__ code, split the MaintainersParser
code in a way that the state machine remains on __init__, but
the actual parser for descriptions and subsystems are moved
to separate functions.
To make parser easier, instead storing parsed results on a list,
place them directly on a string.
That granted 15% of performance increase(*) with Python 3.14 and
made the logic simpler.
(*) measured by creating a new directory under Documentation/,
and placing justmaintainers.rst and an index file there,
building it via sphinx-build-wrapper.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <0b72530cf496ce5e2987ca784058a50f4dc814d2.1777987027.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 297 +++++++++++---------
1 file changed, 158 insertions(+), 139 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 694cdbdc4caf..6d47d55f5b73 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -47,167 +47,186 @@ class MaintainersParser:
self.profile_toc = set()
self.profile_entries = {}
- result = list()
- result.append(".. _maintainers:")
- result.append("")
+ self.output = ".. _maintainers:\n\n"
# Poor man's state machine.
- descriptions = False
- maintainers = False
- subsystems = False
+ self.descriptions = False
+ self.maintainers = False
+ self.subsystems = False
# Field letter to field name mapping.
- field_letter = None
- fields = dict()
+ self.field_letter = None
+ self.fields = dict()
+
+ self.field_prev = ""
+ self.field_content = ""
+ self.subsystem_name = None
+
+ self.app_dir = app_dir
+ self.base_dir, self.doc_dir, self.sphinx_dir = app_dir.partition("Documentation")
+
+ self.re_doc = re.compile(r'(Documentation/([^\s\?\*]*)\.rst)')
prev = None
- field_prev = ""
- field_content = ""
- subsystem_name = None
-
- base_dir, doc_dir, sphinx_dir = app_dir.partition("Documentation")
-
for line in open(path):
- # Have we reached the end of the preformatted Descriptions text?
- if descriptions and line.startswith('Maintainers'):
- descriptions = False
- # Ensure a blank line following the last "|"-prefixed line.
- result.append("")
-
- # Start subsystem processing? This is to skip processing the text
- # between the Maintainers heading and the first subsystem name.
- if maintainers and not subsystems:
+ if self.descriptions:
+ self.parse_descriptions(line)
+ elif self.maintainers and not self.subsystems:
if re.search('^[A-Z0-9]', line):
- subsystems = True
-
- # Drop needless input whitespace.
- line = line.rstrip()
-
- #
- # Handle profile entries - either as files or as https refs
- #
- match = re.match(rf"P:\s*({doc_dir})(/\S+)\.rst", line)
- if match:
- 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"
+ self.subsystems = True
+ self.parse_subsystems(line)
else:
- entry = "/" + entry
-
- if "*" in entry:
- for e in glob(entry):
- self.profile_toc.add(e)
- self.profile_entries[subsystem_name] = e
- else:
- 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)'
- m = re.search(pat, line)
- if m:
- # maintainers.rst is in a subdirectory, so include "../".
- line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
-
- # Check state machine for output rendering behavior.
- output = None
- if descriptions:
- # Escape the escapes in preformatted text.
- output = "| %s" % (line.replace("\\", "\\\\"))
- # Look for and record field letter to field name mappings:
- # R: Designated *reviewer*: FullName <address@domain>
- m = re.search(r"\s(\S):\s", line)
- if m:
- field_letter = m.group(1)
- if field_letter and not field_letter in fields:
- m = re.search(r"\*([^\*]+)\*", line)
- if m:
- fields[field_letter] = m.group(1)
- elif subsystems:
- # Skip empty lines: subsystem parser adds them as needed.
- if len(line) == 0:
- continue
- # Subsystem fields are batched into "field_content"
- if line[1] != ':':
- # Render a subsystem entry as:
- # SUBSYSTEM NAME
- # ~~~~~~~~~~~~~~
-
- # Flush pending field content.
- 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))
- field_prev = ""
- else:
- # Render a subsystem field as:
- # :Field: entry
- # entry...
- field, details = line.split(':', 1)
- details = details.strip()
-
- # Mark paths (and regexes) as literal text for improved
- # readability and to escape any escapes.
- if field in ['F', 'N', 'X', 'K']:
- # But only if not already marked :)
- if not ':doc:' in details:
- details = '``%s``' % (details)
-
- # Comma separate email field continuations.
- if field == field_prev and field_prev in ['M', 'R', 'L']:
- field_content = field_content + ","
-
- # Do not repeat field names, so that field entries
- # will be collapsed together.
- if field != field_prev:
- output = field_content + "\n"
- field_content = ":%s:" % (fields.get(field, field))
- field_content = field_content + "\n\t%s" % (details)
- field_prev = field
+ self.output += line
+ elif self.subsystems:
+ self.parse_subsystems(line)
else:
- output = line
-
- # Re-split on any added newlines in any above parsing.
- if output != None:
- for separated in output.split('\n'):
- result.append(separated)
+ self.output += line
# Update the state machine when we find heading separators.
if line.startswith('----------'):
if prev.startswith('Descriptions'):
- descriptions = True
+ self.descriptions = True
if prev.startswith('Maintainers'):
- maintainers = True
+ self.maintainers = True
# Retain previous line for state machine transitions.
prev = line
# Flush pending field contents.
- if field_content != "":
- for separated in field_content.split('\n'):
- result.append(separated)
+ if self.field_content:
+ self.output += self.field_content + "\n\n"
- self.output = "\n".join(result)
+ self.output = self.output.rstrip()
+
+ def parse_descriptions(self, line):
+ """Handle contents of the descriptions section."""
+
+ # Have we reached the end of the preformatted Descriptions text?
+ if line.startswith('Maintainers'):
+ self.descriptions = False
+ self.output += "\n" + line
+ return
+
+ # Linkify all non-wildcard refs to ReST files in Documentation/.
+ m = self.re_doc.search(line)
+ if m:
+ # maintainers.rst is in a subdirectory, so include "../".
+ line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
+
+ # Escape the escapes in preformatted text.
+ output = "| %s" % (line.replace("\\", "\\\\"))
+
+ # Look for and record field letter to field name mappings:
+ # R: Designated *reviewer*: FullName <address@domain>
+ m = re.search(r"\s(\S):\s", line)
+ if m:
+ self.field_letter = m.group(1)
+
+ if self.field_letter and self.field_letter not in self.fields:
+ m = re.search(r"\*([^\*]+)\*", line)
+ if m:
+ self.fields[self.field_letter] = m.group(1)
+
+ # Append parsed content to self.output
+ self.output += output
+
+ def parse_subsystems(self, line):
+ """Handle contents of the per-subsystem sections."""
+
+ # Drop needless input whitespace.
+ line = line.rstrip()
+
+ #
+ # Handle profile entries - either as files or as https refs
+ #
+ match = re.match(rf"P:\s*({self.doc_dir})(/\S+)\.rst", line)
+ if match:
+ name = "".join(match.groups())
+ entry = os.path.relpath(self.base_dir + name, self.app_dir)
+
+ full_name = os.path.join(self.base_dir, name)
+ path = os.path.relpath(full_name, self.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
+
+ if "*" in entry:
+ for e in glob(entry):
+ self.profile_toc.add(e)
+ self.profile_entries[self.subsystem_name] = e
+ else:
+ self.profile_toc.add(entry)
+ self.profile_entries[self.subsystem_name] = entry
+ else:
+ match = re.match(r"P:\s*(https?://.*)", line)
+ if match:
+ entry = match.group(1).strip()
+ self.profile_entries[self.subsystem_name] = entry
+
+ # Linkify all non-wildcard refs to ReST files in Documentation/.
+ m = self.re_doc.search(line)
+ if m:
+ # maintainers.rst is in a subdirectory, so include "../".
+ line = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
+
+ # Check state machine for output rendering behavior.
+ output = None
+ if self.subsystems:
+ # Skip empty lines: subsystem parser adds them as needed.
+ if len(line) == 0:
+ return
+ # Subsystem fields are batched into "field_content"
+ if line[1] != ':':
+ # Render a subsystem entry as:
+ # SUBSYSTEM NAME
+ # ~~~~~~~~~~~~~~
+ # Flush pending field content.
+ output = self.field_content + "\n\n"
+ self.field_content = ""
+
+ self.subsystem_name = line.title()
+
+ # Collapse whitespace in subsystem name.
+ heading = re.sub(r"\s+", " ", line)
+ output = output + "%s\n%s" % (heading, "~" * len(heading))
+ self.field_prev = ""
+ else:
+ # Render a subsystem field as:
+ # :Field: entry
+ # entry...
+ field, details = line.split(':', 1)
+ details = details.strip()
+
+ # Mark paths (and regexes) as literal text for improved
+ # readability and to escape any escapes.
+ if field in ['F', 'N', 'X', 'K']:
+ # But only if not already marked :)
+ if not ':doc:' in details:
+ details = '``%s``' % (details)
+
+ # Comma separate email field continuations.
+ if field == self.field_prev and self.field_prev in ['M', 'R', 'L']:
+ self.field_content = self.field_content + ","
+
+ # Do not repeat field names, so that field entries
+ # will be collapsed together.
+ if field != self.field_prev:
+ output = self.field_content + "\n"
+ self.field_content = ":%s:" % (self.fields.get(field, field))
+ self.field_content = self.field_content + "\n\t%s" % (details)
+ self.field_prev = field
+ elif not self.descriptions:
+ output = line
+
+ if output is not None:
+ self.output += output + "\n"
- # Create a TOC class
class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
--
2.54.0
^ permalink raw reply related
* Re: [RFC net-next 0/4] devlink: Add boot-time defaults
From: Jiri Pirko @ 2026-05-09 7:01 UTC (permalink / raw)
To: Jakub Kicinski
Cc: Mark Bloch, Eric Dumazet, Paolo Abeni, Andrew Lunn,
David S. Miller, Jonathan Corbet, Shuah Khan, Simon Horman,
Saeed Mahameed, Leon Romanovsky, Tariq Toukan, Andrew Morton,
Borislav Petkov (AMD), Randy Dunlap, Dave Hansen,
Christian Brauner, Petr Mladek, Peter Zijlstra (Intel),
Thomas Gleixner, Pawan Gupta, Dapeng Mi, Kees Cook, Marco Elver,
Eric Biggers, Li RongQing, Paul E. McKenney, linux-doc,
linux-kernel, netdev, linux-rdma
In-Reply-To: <20260508175213.1952097f@kernel.org>
Sat, May 09, 2026 at 02:52:13AM +0200, kuba@kernel.org wrote:
>On Fri, 8 May 2026 20:07:44 +0200 Jiri Pirko wrote:
>> >I don't think switchdev by default should mean CX4+ in general. If we get
>> >there, I would expect it to be limited to the DPU/BlueField/ECPF case, where
>> >the host PF probe path can depend on the ECPF reaching switchdev. Changing the
>> >default for regular host NIC deployments feels like a much larger compatibility
>> >change.
>>
>> We can't travel throught time, but if from CX5 onwards the default would
>> be switchdev, nobody would feel broken in terms of compatibility. That
>> is my point. Having "legacy" as default is simply wrong for never NIC
>> generations. That is why it is called "legacy" and it should have been
>> rotten through and out since CX4 times.
>
>legacy vs switchdev only describes the eswitch configuration.
>As a non-SR-IOV user I really don't want to see the extra representors
>hanging around my systems, confusing all daemons. IIRC mlx5 had some
>limitations around the uplink representor. Maybe that's the disconnect.
>But for a real, fully featured switchdev eswitches having the
>PHY and PF representors on boot, always, will not make sense.
As "a non-SR-IOV user", what extra representors you talk about? When you
have pfs only, you don't have anything extra. Just 1 netdev per-pf, one
devlink port per-pf. What's extra about it? When you don't have VFs/SFs.
Everyhing is the same:
c-220-136-220-218:~$ sudo devlink dev eswitch show pci/0000:08:00.0
pci/0000:08:00.0: mode switchdev inline-mode none encap-mode basic
c-220-136-220-218:~$ sudo devlink dev eswitch show pci/0000:08:00.1
pci/0000:08:00.1: mode legacy inline-mode none encap-mode basic
c-220-136-220-218:~$ devlink dev
pci/0000:08:00.0: index 0
nested_devlink:
auxiliary/mlx5_core.eth.0
devlink_index/1: index 1
nested_devlink:
pci/0000:08:00.0
pci/0000:08:00.1
auxiliary/mlx5_core.eth.0: index 2
pci/0000:08:00.1: index 3
nested_devlink:
auxiliary/mlx5_core.eth.1
auxiliary/mlx5_core.eth.1: index 4
c-220-136-220-218:~$ devlink port
auxiliary/mlx5_core.eth.0/65535: type eth netdev eth2 flavour physical port 0 splittable false
auxiliary/mlx5_core.eth.1/131071: type eth netdev eth3 flavour physical port 1 splittable false
c-220-136-220-218:~$ ip link
...
4: eth2: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
link/ether b8:e9:24:f2:b7:6c brd ff:ff:ff:ff:ff:ff
altname enp8s0f0np0
5: eth3: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
link/ether b8:e9:24:f2:b7:6d brd ff:ff:ff:ff:ff:ff
altname enp8s0f1np1
>
>IOW it's not a question of the generation of the card but of
>the deployment type / use case.
I don't think so, not in the case of mlx5. The difference is only when
you work with sr-iov, you either use legacy way (ip vf) or the new one.
Same usecase.
>
>> >For the ASIC/NV bit: maybe technically possible, but it feels like the wrong
>> >layer. This is boot/deployment policy, not a persistent hardware property, and
>> >storing it in NV memory would make the state persist across kernels/hosts in a
>> >surprising way.
>>
>> Well, as any other nv config, it persists across kernels/hosts. Think
>> about it as "unbreak-my-not-legacy-device" bit.
>
>For most devices the switchdev mode does not change anything
>substantial about the device. It's purely a kernel / driver config.
>It changes what objects and default rules kernel / driver installs.
>So I don't get why it would make sense to flash into the device
>nvmem a Linux SW stack specific config.
I look at it from the perspective that from some CX generation,
switchdev mode should be default. So that is a device-based decision.
I believe as such it can optionally be permanenty configured (nv config)
on older device. Why not?
[...]
^ permalink raw reply
* Re: [PATCH v2 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Willy Tarreau @ 2026-05-09 7:43 UTC (permalink / raw)
To: Greg KH
Cc: Linus Torvalds, leon, security, Jonathan Corbet, skhan, workflows,
linux-doc, linux-kernel
In-Reply-To: <2026050929-hatred-underfoot-a32a@gregkh>
On Sat, May 09, 2026 at 08:39:37AM +0200, Greg KH wrote:
> On Fri, May 08, 2026 at 06:39:07PM +0200, Willy Tarreau wrote:
> > Greg,
> >
> > does this addition on top of the current patch address your concerns ?
> >
> > --- a/Documentation/process/security-bugs.rst
> > +++ b/Documentation/process/security-bugs.rst
> > @@ -88,6 +88,14 @@ can be easily exploited, representing an imminent threat to many users. Before
> > reporting, consider whether the issue actually crosses a trust boundary on such
> > a system.
> >
> > +**If you resorted to AI assistance to identify a bug, you must treat it as
> > +public**. While you may have valid reasons to believe it is not, the security
> > +team's experience shows that bugs discovered this way systematically surface
> > +simultaneously across multiple researchers, often on the same day. In this
> > +case, do not publicly share a reproducer, as this could cause unintended harm;
> > +just mention that one is available and maintainers might ask for it privately
> > +if they need it.
> > +
> > If you are unsure whether an issue qualifies, err on the side of reporting
> > privately: the security team would rather triage a borderline report than miss
> > a real vulnerability. Reporting ordinary bugs to the security list, however,
> > @@ -102,7 +110,7 @@ affected subsystem's maintainers and Cc: the Linux kernel security team. Do
> > not send it to a public list at this stage, unless you have good reasons to
> > consider the issue as being public or trivial to discover (e.g. result of a
> > widely available automated vulnerability scanning tool that can be repeated by
> > -anyone).
> > +anyone, or use of AI-based tools).
> >
> > If you're sending a report for issues affecting multiple parts in the kernel,
> > even if they're fairly similar issues, please send individual messages (think
> >
> > If so I can resend with it.
>
> Looks good to me, thanks!
Thank you. I'll integrate Shuah's comments and will send a v3. After
that I'll see if we can better split the public vs private part, because
I'm starting to find it complicated, but I don't want to postpone for
too long if having all of this can already help us.
Willy
^ permalink raw reply
* [PATCH] docs: Document panic_on_rcu_stall default behavior
From: Kunwu Chan @ 2026-05-09 9:12 UTC (permalink / raw)
To: corbet, skhan; +Cc: linux-doc, linux-kernel, paulmck, gustavold, Kunwu Chan
From: Kunwu Chan <kunwu.chan@gmail.com>
Commit ab875b3e179f ("rcu: Add BOOTPARAM_RCU_STALL_PANIC
Kconfig option") made the default value of
kernel.panic_on_rcu_stall depend on
CONFIG_BOOTPARAM_RCU_STALL_PANIC.
Document this in kernel.rst
Signed-off-by: Kunwu Chan <kunwu.chan@gmail.com>
---
Documentation/admin-guide/sysctl/kernel.rst | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
index c6994e55d141..99598a83f830 100644
--- a/Documentation/admin-guide/sysctl/kernel.rst
+++ b/Documentation/admin-guide/sysctl/kernel.rst
@@ -948,6 +948,10 @@ panic_on_rcu_stall
When set to 1, calls panic() after RCU stall detection messages. This
is useful to define the root cause of RCU stalls using a vmcore.
+The default value can be configured at build time via
+``CONFIG_BOOTPARAM_RCU_STALL_PANIC``. Runtime updates to this sysctl
+always override the built-in default.
+
= ============================================================
0 Do not panic() when RCU stall takes place, default behavior.
1 panic() after printing RCU stall messages.
--
2.43.0
^ permalink raw reply related
* [PATCH v3 3/3] Documentation: security-bugs: clarify requirements for AI-assisted reports
From: Willy Tarreau @ 2026-05-09 9:47 UTC (permalink / raw)
To: greg
Cc: Leon Romanovsky, Jonathan Corbet, skhan, security, workflows,
linux-doc, linux-kernel, Willy Tarreau, Greg KH
In-Reply-To: <20260509094755.2838-1-w@1wt.eu>
AI tools are increasingly used to assist in bug discovery. While these
tools can identify valid issues, reports that are submitted without
manual verification often lack context, contain speculative impact
assessments, or include unnecessary formatting. Such reports increase
triage effort, waste maintainers' time and may be ignored.
Reports where the reporter has verified the issue and the proposed fix
typically meet quality standards. This documentation outlines specific
requirements for length, formatting, and impact evaluation to reduce
the effort needed to deal with these reports.
Cc: Greg KH <gregkh@linuxfoundation.org>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Leon Romanovsky <leon@kernel.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
Documentation/process/security-bugs.rst | 57 +++++++++++++++++++++++++
1 file changed, 57 insertions(+)
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 54260dbfc64d5..f85c65f31f12f 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -167,6 +167,63 @@ the Linux kernel security team only. Your message will be triaged, and you
will receive instructions about whom to contact, if needed. Your message may
equally be forwarded as-is to the relevant maintainers.
+Responsible use of AI to find bugs
+----------------------------------
+
+A significant fraction of bug reports submitted to the security team are
+actually the result of code reviews assisted by AI tools. While this can be an
+efficient means to find bugs in rarely explored areas, it causes an overload on
+maintainers, who are sometimes forced to ignore such reports due to their poor
+quality or accuracy. As such, reporters must be particularly cautious about a
+number of points which tend to make these reports needlessly difficult to
+handle:
+
+ * **Length**: AI-generated reports tend to be excessively long, containing
+ multiple sections and excessive detail. This makes it difficult to spot
+ important information such as affected files, versions, and impact. Please
+ ensure that a clear summary of the problem and all critical details are
+ presented first. Do not require triage engineers to scan multiple pages of
+ text. Configure your tools to produce concise, human-style reports.
+
+ * **Formatting**: Most AI-generated reports are littered with Markdown tags.
+ These decorations complicate the search for important information and do
+ not survive the quoting processes involved in forwarding or replying.
+ Please **always convert your report to plain text** without any formatting
+ decorations before sending it.
+
+ * **Impact Evaluation**: Many AI-generated reports lack an understanding of
+ the kernel's threat model and go to great lengths inventing theoretical
+ consequences. This adds noise and complicates triage. Please stick to
+ verifiable facts (e.g., "this bug permits any user to gain CAP_NET_ADMIN")
+ without enumerating speculative implications. Have your tool read this
+ documentation as part of the evaluation process.
+
+ * **Reproducer**: AI-based tools are often capable of generating reproducers.
+ Please always ensure your tool provides one and **test it thoroughly**. If
+ the reproducer does not work, or if the tool cannot produce one, the
+ validity of the report should be seriously questioned. Note that since the
+ report will be posted to a public list, the reproducer should only be
+ shared upon maintainers' request.
+
+ * **Propose a Fix**: Many AI tools are actually better at writing code than
+ evaluating it. Please ask your tool to propose a fix and **test it** before
+ reporting the problem. If the fix cannot be tested because it relies on
+ rare hardware or almost extinct network protocols, the issue is likely not
+ a security bug. In any case, if a fix is proposed, it must adhere to
+ Documentation/process/submitting-patches.rst and include a 'Fixes:' tag
+ designating the commit that introduced the bug.
+
+Failure to consider these points exposes your report to the risk of being
+ignored.
+
+Use common sense when evaluating the report. If the affected file has not been
+touched for more than one year and is maintained by a single individual, it is
+likely that usage has declined and exposed users are virtually non-existent
+(e.g., drivers for very old hardware, obsolete filesystems). In such cases,
+there is no need to consume a maintainer's time with an unimportant report. If
+the issue is clearly trivial and publicly discoverable, you should report it
+directly to the public mailing lists.
+
Sending the report
------------------
--
2.52.0
^ permalink raw reply related
* [PATCH v3 0/3] Documentation: security-bugs: new updates covering triage and AI
From: Willy Tarreau @ 2026-05-09 9:47 UTC (permalink / raw)
To: greg
Cc: Leon Romanovsky, Jonathan Corbet, skhan, security, workflows,
linux-doc, linux-kernel, Willy Tarreau
This series tries to translate recent discussions on the security list
on how to better handle reports. It details:
- when not to Cc: the security list
- what classes of bugs do not need to be handled privately
- minimum requirements for AI-assisted reports
As usual, this is probably perfectible but can already help in the short
term as we can point it to reporters, so barring any strong disagreement,
better continue to proceed in small incremental improvements and observe
the effects.
Thanks!
Willy
---
v3:
- comments about choice of words and option enumeration from Shuah
- AI is public, from Linus and Greg
- added extra reviewed-by (Greg, Shuah).
- Leon, I kept your reviewed-by since changes are very minimal and
didn't change the initial spirit.
v2:
- fixes for issues reported by Randy
- Greg's ack on the AI part
- reworded the "when to Cc" part based on Greg's feedback
(Greg I didn't take your original ack since the wording changed)
- split the threat model into its own document as per Greg's suggestion
---
Willy Tarreau (3):
Documentation: security-bugs: do not systematically Cc the security
team
Documentation: security-bugs: explain what is and is not a security
bug
Documentation: security-bugs: clarify requirements for AI-assisted
reports
Documentation/process/index.rst | 1 +
Documentation/process/security-bugs.rst | 105 ++++++++++-
Documentation/process/threat-model.rst | 236 ++++++++++++++++++++++++
3 files changed, 340 insertions(+), 2 deletions(-)
create mode 100644 Documentation/process/threat-model.rst
--
2.52.0
^ permalink raw reply
* [PATCH v3 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Willy Tarreau @ 2026-05-09 9:47 UTC (permalink / raw)
To: greg
Cc: Leon Romanovsky, Jonathan Corbet, skhan, security, workflows,
linux-doc, linux-kernel, Willy Tarreau, Greg KH
In-Reply-To: <20260509094755.2838-1-w@1wt.eu>
The use of automated tools to find bugs in random locations of the kernel
induces a raise of security reports even if most of them should just be
reported as regular bugs. This patch is an attempt at drawing a line
between what qualifies as a security bug and what does not, hoping to
improve the situation and ease decision on the reporter's side.
It defers the enumeration to a new file, threat-model.rst, that tries
to enumerate various classes of issues that are and are not security
bugs. This should permit to more easily update this file for various
subsystem-specific rules without having to revisit the security bug
reporting guide.
Cc: Greg KH <gregkh@linuxfoundation.org>
Cc: Leon Romanovsky <leon@kernel.org>
Suggested-by: Leon Romanovsky <leon@kernel.org>
Suggested-by: Greg KH <gregkh@linuxfoundation.org>
Reviewed-by: Leon Romanovsky <leon@kernel.org>
Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
Documentation/process/index.rst | 1 +
Documentation/process/security-bugs.rst | 38 +++-
Documentation/process/threat-model.rst | 236 ++++++++++++++++++++++++
3 files changed, 274 insertions(+), 1 deletion(-)
create mode 100644 Documentation/process/threat-model.rst
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index dbd6ea16aca70..aa7c959a52b87 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -86,6 +86,7 @@ regressions and security problems.
debugging/index
handling-regressions
security-bugs
+ threat-model
cve
embargoed-hardware-issues
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 6dc525858125e..54260dbfc64d5 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -66,6 +66,42 @@ In addition, the following information are highly desirable:
the issue appear. It is useful to share them, as they can be helpful to
keep end users protected during the time it takes them to apply the fix.
+What qualifies as a security bug
+--------------------------------
+
+It is important that most bugs are handled publicly so as to involve the widest
+possible audience and find the best solution. By nature, bugs that are handled
+in closed discussions between a small set of participants are less likely to
+produce the best possible fix (e.g., risk of missing valid use cases, limited
+testing abilities).
+
+It turns out that the majority of the bugs reported via the security team are
+just regular bugs that have been improperly qualified as security bugs due to
+a lack of awareness of the Linux kernel's threat model, as described in
+Documentation/process/threat-model.rst, and ought to have been sent through
+the normal channels described in Documentation/admin-guide/reporting-issues.rst
+instead.
+
+The security list exists for urgent bugs that grant an attacker a capability
+they are not supposed to have on a correctly configured production system, and
+can be easily exploited, representing an imminent threat to many users. Before
+reporting, consider whether the issue actually crosses a trust boundary on such
+a system.
+
+**If you resorted to AI assistance to identify a bug, you must treat it as
+public**. While you may have valid reasons to believe it is not, the security
+team's experience shows that bugs discovered this way systematically surface
+simultaneously across multiple researchers, often on the same day. In this
+case, do not publicly share a reproducer, as this could cause unintended harm;
+just mention that one is available and maintainers might ask for it privately
+if they need it.
+
+If you are unsure whether an issue qualifies, err on the side of reporting
+privately: the security team would rather triage a borderline report than miss
+a real vulnerability. Reporting ordinary bugs to the security list, however,
+does not make them move faster and consumes triage capacity that other reports
+need.
+
Identifying contacts
--------------------
@@ -74,7 +110,7 @@ affected subsystem's maintainers and Cc: the Linux kernel security team. Do
not send it to a public list at this stage, unless you have good reasons to
consider the issue as being public or trivial to discover (e.g. result of a
widely available automated vulnerability scanning tool that can be repeated by
-anyone).
+anyone, or use of AI-based tools).
If you're sending a report for issues affecting multiple parts in the kernel,
even if they're fairly similar issues, please send individual messages (think
diff --git a/Documentation/process/threat-model.rst b/Documentation/process/threat-model.rst
new file mode 100644
index 0000000000000..ecb432390e792
--- /dev/null
+++ b/Documentation/process/threat-model.rst
@@ -0,0 +1,236 @@
+.. _threatmodel:
+
+The Linux Kernel threat model
+=============================
+
+There are a lot of assumptions regarding what the kernel does and does not
+protect against. These assumptions tend to cause confusion for bug reports
+(:doc:`security-related ones <security-bugs>` vs :doc:`non-security ones
+<../admin-guide/reporting-issues>`), and can complicate security enforcement
+when the responsibilities for some boundaries is not clear between the kernel,
+distros, administrators and users.
+
+This document tries to clarify the responsibilities of the kernel in this
+domain.
+
+The kernel's responsibilities
+-----------------------------
+
+The kernel abstracts access to local hardware resources and to remote systems
+in a way that allows multiple local users to get a fair share of the available
+resources granted to them, and, when the underlying hardware permits, to assign
+a level of confidentiality to their communications and to the data they are
+processing or storing.
+
+The kernel assumes that the underlying hardware behaves according to its
+specifications. This includes the integrity of the CPU's instruction set, the
+transparency of the branch prediction unit and the cache units, the consistency
+of the Memory Management Unit (MMU), the isolation of DMA-capable peripherals
+(e.g., via IOMMU), state transitions in controllers, ranges of values read from
+registers, the respect of documented hardware limitations, etc.
+
+When hardware fails to maintain its specified isolation (e.g., CPU bugs,
+side-channels, hardware response to unexpected inputs), the kernel will usually
+attempt to implement reasonable mitigations. These are best-effort measures
+intended to reduce the attack surface or elevate the cost of an attack within
+the limits of the hardware's facilities; they do not constitute a
+kernel-provided safety guarantee.
+
+Users always perform their activities under the authority of an administrator
+who is able to grant or deny various types of permissions that may affect how
+users benefit from available resources, or the level of confidentiality of
+their activities. Administrators may also delegate all or part of their own
+permissions to some users, particularly via capabilities but not only. All this
+is performed via configuration (sysctl, file-system permissions etc).
+
+The Linux Kernel applies a certain collection of default settings that match
+its threat model. Distros have their own threat model and will come with their
+own configuration presets, that the administrator may have to adjust to better
+suit their expectations (relax or restrict).
+
+By default, the Linux Kernel guarantees the following protections when running
+on common processors featuring privilege levels and memory management units:
+
+* **User-based isolation**: an unprivileged user may restrict access to their
+ own data from other unprivileged users running on the same system. This
+ includes:
+
+ * stored data, via file system permissions
+ * in-memory data (pages are not accessible by default to other users)
+ * process activity (ptrace is not permitted to other users)
+ * inter-process communication (other users may not observe data exchanged via
+ UNIX domain sockets or other IPC mechanisms).
+ * network communications within the same or with other systems
+
+* **Capability-based protection**:
+
+ * users not having the ``CAP_SYS_ADMIN`` capability may not alter the
+ kernel's configuration, memory nor state, change other users' view of the
+ file system layout, grant any user capabilities they do not have, nor
+ affect the system's availability (shutdown, reboot, panic, hang, or making
+ the system unresponsive via unbounded resource exhaustion).
+ * users not having the ``CAP_NET_ADMIN`` capability may not alter the network
+ configuration, intercept nor spoof network communications from other users
+ nor systems.
+ * users not having ``CAP_SYS_PTRACE`` may not observe other users' processes
+ activities.
+
+When ``CONFIG_USER_NS`` is set, the kernel also permits unprivileged users to
+create their own user namespace in which they have all capabilities, but with a
+number of restrictions (they may not perform actions that have impacts on the
+initial user namespace, such as changing time, loading modules or mounting
+block devices). Please refer to ``user_namespaces(7)`` for more details, the
+possibilities of user namespaces are not covered in this document.
+
+The kernel also offers a lot of troubleshooting and debugging facilities, which
+can constitute attack vectors when placed in wrong hands. While some of them
+are designed to be accessible to regular local users with a low risk (e.g.
+kernel logs via ``/proc/kmsg``), some would expose enough information to
+represent a risk in most places and the decision to expose them is under the
+administrator's responsibility (perf events, traces), and others are not
+designed to be accessed by non-privileged users (e.g. debugfs). Access to these
+facilities by a user who has been explicitly granted permission by an
+administrator does not constitute a security breach.
+
+Bugs that permit to violate the principles above constitute security breaches.
+However, bugs that permit one violation only once another one was already
+achieved are only weaknesses. The kernel applies a number of self-protection
+measures whose purpose is to avoid crossing a security boundary when certain
+classes of bugs are found, but a failure of these extra protections do not
+constitute a vulnerability alone.
+
+What does not constitute a security bug
+---------------------------------------
+
+In the Linux kernel's threat model, the following classes of problems are
+**NOT** considered as Linux Kernel security bugs. However, when it is believed
+that the kernel could do better, they should be reported, so that they can be
+reviewed and fixed where reasonably possible, but they will be handled as any
+regular bug:
+
+* **Configuration**:
+
+ * outdated kernels and particularly end-of-life branches are out of the scope
+ of the kernel's threat model: administrators are responsible for keeping
+ their system up to date. For a bug to qualify as a security bug, it must be
+ demonstrated that it affects actively maintained versions.
+
+ * build-level: changes to the kernel configuration that are explicitly
+ documented as lowering the security level (e.g. ``CONFIG_NOMMU``), or
+ targeted at developers only.
+
+ * OS-level: changes to command line parameters, sysctls, filesystem
+ permissions, user capabilities, exposure of privileged interfaces, that
+ explicitly increase exposure by either offering non-default access to
+ unprivileged users, or reduce the kernel's ability to enforce some
+ protections or mitigations. Example: write access to procfs or debugfs.
+
+ * issues triggered only when using features intended for development or
+ debugging (e.g., LOCKDEP, KASAN, FAULT_INJECTION): these features are known
+ to introduce overhead and potential instability and are not intended for
+ production use.
+
+ * issues affecting drivers exposed under CONFIG_STAGING, as well as features
+ marked EXPERIMENTAL in the configuration.
+
+ * loading of explicitly insecure/broken/staging modules, and generally any
+ using any subsystem marked as experimental or not intended for production
+ use.
+
+ * running out-of-tree modules or unofficial kernel forks; these should be
+ reported to the relevant vendor.
+
+* **Excess of initial privileges**:
+
+ * actions performed by a user already possessing the privileges required to
+ perform that action or modify that state (e.g. ``CAP_SYS_ADMIN``,
+ ``CAP_NET_ADMIN``, ``CAP_SYS_RAWIO``, ``CAP_SYS_MODULE`` with no further
+ boundary being crossed).
+
+ * actions performed in user namespace that do not bypass the restrictions
+ imposed to the initial user (e.g. ptrace usage, signal delivery, resource
+ usage, access to FS/device/sysctl/memory, network binding, system/network
+ configuration etc).
+
+ * anything performed by the root user in the initial namespace (e.g. kernel
+ oops when writing to a privileged device).
+
+* **Out of production use**:
+
+ This covers theoretical/probabilistic attacks that rely on laboratory
+ conditions with zero system noise, or those requiring an unrealistic number
+ of attempts (e.g., billions of trials) that would be detected by standard
+ system monitoring long before success, such as:
+
+ * prediction of random numbers that only works in a totally silent
+ environment (such as IP ID, TCP ports or sequence numbers that can only be
+ guessed in a lab).
+
+ * activity observation and information leaks based on probabilistic
+ approaches that are prone to measurement noise and not realistically
+ reproducible on a production system.
+
+ * issues that can only be triggered by heavy attacks (e.g. brute force) whose
+ impact on the system makes it unlikely or impossible to remain undetected
+ before they succeed (e.g. consuming all memory before succeeding).
+
+ * problems seen only under development simulators, emulators, or combinations
+ that do not exist on real systems at the time of reporting (issues
+ involving tens of millions of threads, tens of thousands of CPUs,
+ unrealistic CPU frequencies, RAM sizes or disk capacities, network speeds.
+
+ * issues whose reproduction requires hardware modification or emulation,
+ including fake USB devices that pretend to be another one.
+
+ * as well as issues that can be triggered at a cost that is orders of
+ magnitude higher than the expected benefits (e.g. fully functional keyboard
+ emulator only to retrieve 7 uninitialized bytes in a structure, or
+ brute-force method involving millions of connection attempts to guess a
+ port number).
+
+* **Hardening failures**:
+
+ * ability to bypass some of the kernel's hardening measures with no
+ demonstrable exploit path (e.g. ASLR bypass, events timing or probing with
+ no demonstrable consequence). These are just weaknesses, not
+ vulnerabilities.
+
+ * missing argument checks and failure to report certain errors with no
+ immediate consequence.
+
+* **Random information leaks**:
+
+ This concerns information leaks of small data parts that happen to be there
+ and that cannot be chosen by the attacker, or face access restrictions:
+
+ * structure padding reported by syscalls or other interfaces.
+
+ * identifiers, partial data, non-terminated strings reported in error
+ messages.
+
+ * Leaks of kernel memory addresses/pointers do not constitute an immediately
+ exploitable vector and are not security bugs, though they must be reported
+ and fixed.
+
+* **Crafted file system images**:
+
+ * bugs triggered by mounting a corrupted or maliciously crafted file system
+ image are generally not security bugs, as the kernel assumes the underlying
+ storage media is under the administrator's control, unless the filesystem
+ driver is specifically documented as being hardened against untrusted media.
+
+ * issues that are resolved, mitigated, or detected by running a filesystem
+ consistency check (fsck) on the image prior to mounting.
+
+* **Physical access**:
+
+ Issues that require physical access to the machine, hardware modification, or
+ the use of specialized hardware (e.g., logic analyzers, DMA-attack tools over
+ PCI-E/Thunderbolt) are out of scope unless the system is explicitly
+ configured with technologies meant to defend against such attacks
+ (e.g. IOMMU).
+
+* **Functional and performance regressions**:
+
+ Any issue that can be mitigated by setting proper permissions and limits
+ doesn't qualify as a security bug.
--
2.52.0
^ permalink raw reply related
* [PATCH v3 1/3] Documentation: security-bugs: do not systematically Cc the security team
From: Willy Tarreau @ 2026-05-09 9:47 UTC (permalink / raw)
To: greg
Cc: Leon Romanovsky, Jonathan Corbet, skhan, security, workflows,
linux-doc, linux-kernel, Willy Tarreau, Greg KH
In-Reply-To: <20260509094755.2838-1-w@1wt.eu>
With the increase of automated reports, the security team is dealing
with way more messages than really needed. The reporting process works
well with most teams so there is no need to systematically involve the
security team in reports.
Let's suggest to keep it for small lists of recipients and new reporters
only. This should continue to cover the risk of lost messages while
reducing the volume from prolific reporters.
Cc: Greg KH <gregkh@linuxfoundation.org>
Cc: Leon Romanovsky <leon@kernel.org>
Reviewed-by: Leon Romanovsky <leon@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
Documentation/process/security-bugs.rst | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 27b028e858610..6dc525858125e 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -148,7 +148,15 @@ run additional tests. Reports where the reporter does not respond promptly
or cannot effectively discuss their findings may be abandoned if the
communication does not quickly improve.
-The report must be sent to maintainers, with the security team in ``Cc:``.
+The report must be sent to maintainers. If there are two or fewer
+recipients in your message, you must also always Cc: the Linux kernel
+security team who will ensure the message is delivered to the proper
+people, and will be able to assist small maintainer teams with processes
+they may not be familiar with. For larger teams, Cc: the Linux kernel
+security team for your first few reports or when seeking specific help,
+such as when resending a message which got no response within a week.
+Once you have become comfortable with the process for a few reports, it is
+no longer necessary to Cc: the security list when sending to large teams.
The Linux kernel security team can be contacted by email at
<security@kernel.org>. This is a private list of security officers
who will help verify the bug report and assist developers working on a fix.
--
2.52.0
^ permalink raw reply related
* Re: [PATCH v3 0/3] Documentation: security-bugs: new updates covering triage and AI
From: Leon Romanovsky @ 2026-05-09 10:52 UTC (permalink / raw)
To: Willy Tarreau
Cc: greg, Jonathan Corbet, skhan, security, workflows, linux-doc,
linux-kernel
In-Reply-To: <20260509094755.2838-1-w@1wt.eu>
On Sat, May 09, 2026 at 11:47:52AM +0200, Willy Tarreau wrote:
> This series tries to translate recent discussions on the security list
> on how to better handle reports. It details:
> - when not to Cc: the security list
> - what classes of bugs do not need to be handled privately
> - minimum requirements for AI-assisted reports
>
> As usual, this is probably perfectible but can already help in the short
> term as we can point it to reporters, so barring any strong disagreement,
> better continue to proceed in small incremental improvements and observe
> the effects.
>
> Thanks!
> Willy
<...>
> - Leon, I kept your reviewed-by since changes are very minimal and
> didn't change the initial spirit.
Thanks. The intent is the same, and I'm not the right person to argue over
the precise wording anyway.
^ permalink raw reply
* Re: [PATCH v3 0/3] Documentation: security-bugs: new updates covering triage and AI
From: Willy Tarreau @ 2026-05-09 10:56 UTC (permalink / raw)
To: Leon Romanovsky
Cc: greg, Jonathan Corbet, skhan, security, workflows, linux-doc,
linux-kernel
In-Reply-To: <20260509105222.GA15586@unreal>
On Sat, May 09, 2026 at 01:52:22PM +0300, Leon Romanovsky wrote:
> On Sat, May 09, 2026 at 11:47:52AM +0200, Willy Tarreau wrote:
> > This series tries to translate recent discussions on the security list
> > on how to better handle reports. It details:
> > - when not to Cc: the security list
> > - what classes of bugs do not need to be handled privately
> > - minimum requirements for AI-assisted reports
> >
> > As usual, this is probably perfectible but can already help in the short
> > term as we can point it to reporters, so barring any strong disagreement,
> > better continue to proceed in small incremental improvements and observe
> > the effects.
> >
> > Thanks!
> > Willy
>
> <...>
>
> > - Leon, I kept your reviewed-by since changes are very minimal and
> > didn't change the initial spirit.
>
> Thanks. The intent is the same, and I'm not the right person to argue over
> the precise wording anyway.
That was also my understanding, but thanks for confirming!
willy
^ permalink raw reply
* Re: [PATCH v3 13/13] MAINTAINERS: use a URL for pin-init maintainer's profile entry
From: Gary Guo @ 2026-05-09 12:11 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Jonathan Corbet, Linux Doc Mailing List,
Miguel Ojeda
Cc: linux-kernel, rust-for-linux, Björn Roy Baron, Alice Ryhl,
Andreas Hindborg, Benno Lossin, Boqun Feng, Danilo Krummrich,
Gary Guo, Mauro Carvalho Chehab, Trevor Gross
In-Reply-To: <59144e7323b95166e61a7c7f84096a0b9bb5d26e.1778309595.git.mchehab+huawei@kernel.org>
On Sat May 9, 2026 at 7:56 AM BST, Mauro Carvalho Chehab wrote:
> This maintainer's entry is not inside documentation nor is
> ReST, preventing Sphinx to create a hyperlink to it.
>
> Change it to point to the already-formatted URL.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Message-ID: <1bceee886b9027d66bbb48d9d6c8d1250ce8dbcb.1777987028.git.mchehab+huawei@kernel.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Gary Guo <gary@garyguo.net>
> ---
> MAINTAINERS | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
^ permalink raw reply
* Re: [PATCH v2] killswitch: add per-function short-circuit mitigation primitive
From: Sasha Levin @ 2026-05-09 12:34 UTC (permalink / raw)
To: Florian Weimer
Cc: corbet, akpm, skhan, linux-doc, linux-kernel, linux-kselftest,
gregkh
In-Reply-To: <87ecjku6y7.fsf@mid.deneb.enyo.de>
On Sat, May 09, 2026 at 02:02:24PM +0200, Florian Weimer wrote:
>* Sasha Levin:
>
>> When a kernel (security) issue goes public, fleets stay exposed until a patched
>> kernel is built, distributed, and rebooted into.
>>
>> For many such issues the simplest mitigation is to stop calling the buggy
>> function. Killswitch provides that. An admin writes:
>>
>> echo "engage af_alg_sendmsg -1" \
>> > /sys/kernel/security/killswitch/control
>>
>> After this, af_alg_sendmsg() returns -EPERM on every call without
>> running its body. The mitigation takes effect immediately, and is dropped on
>> the next reboot -- by which point a patched kernel is hopefully in place.
>
>Do you expect this to be safe to enable in kernel lockdown mode (i.e.,
>with typical Secure Boot configurations in distributions)?
Yes: under lockdown, killswitch has to be configured on the cmdline. Runtime
engage is gated on the new LOCKDOWN_KILLSWITCH reason.
I do need to resend a v3 that also gates disengage and the retval write so a
cmdline-installed mitigation is fixed for the boot - I didn't think about that
scenario.
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH v2] killswitch: add per-function short-circuit mitigation primitive
From: Florian Weimer @ 2026-05-09 12:02 UTC (permalink / raw)
To: Sasha Levin
Cc: corbet, akpm, skhan, linux-doc, linux-kernel, linux-kselftest,
gregkh
In-Reply-To: <20260508195749.1885522-1-sashal@kernel.org>
* Sasha Levin:
> When a kernel (security) issue goes public, fleets stay exposed until a patched
> kernel is built, distributed, and rebooted into.
>
> For many such issues the simplest mitigation is to stop calling the buggy
> function. Killswitch provides that. An admin writes:
>
> echo "engage af_alg_sendmsg -1" \
> > /sys/kernel/security/killswitch/control
>
> After this, af_alg_sendmsg() returns -EPERM on every call without
> running its body. The mitigation takes effect immediately, and is dropped on
> the next reboot -- by which point a patched kernel is hopefully in place.
Do you expect this to be safe to enable in kernel lockdown mode (i.e.,
with typical Secure Boot configurations in distributions)?
^ permalink raw reply
* [PATCH v2 2/4] docs: fix repeated word 'that' across documentation
From: Adrien Reynard @ 2026-05-09 14:30 UTC (permalink / raw)
To: paulmck, corbet, gregkh, dhowells, mhiramat
Cc: frederic, neeraj.upadhyay, joelagnelf, josh, boqun, urezki,
rostedt, skhan, rafael, dakr, pc, rcu, linux-doc, driver-core,
netfs, linux-fsdevel, linux-trace-kernel, linux-kernel,
Adrien Reynard
In-Reply-To: <20260508163759.16231-1-reynard.adrien.08@gmail.com>
Remove duplicated word 'that' found in RCU/rcu.rst,
driver-api/driver-model/overview.rst,
filesystems/netfs_library.rst, trace/histogram-design.rst
and trace/histogram.rst.
Signed-off-by: Adrien Reynard <reynard.adrien.08@gmail.com>
---
Documentation/RCU/rcu.rst | 2 +-
Documentation/driver-api/driver-model/overview.rst | 2 +-
Documentation/filesystems/netfs_library.rst | 2 +-
Documentation/trace/histogram-design.rst | 2 +-
Documentation/trace/histogram.rst | 2 +-
5 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index bf6617b330a7..110f3d42cace 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -32,7 +32,7 @@ Frequently Asked Questions
Just as with spinlocks, RCU readers are not permitted to
block, switch to user-mode execution, or enter the idle loop.
Therefore, as soon as a CPU is seen passing through any of these
- three states, we know that that CPU has exited any previous RCU
+ three states, we know that the CPU has exited any previous RCU
read-side critical sections. So, if we remove an item from a
linked list, and then wait until all CPUs have switched context,
executed in user mode, or executed in the idle loop, we can
diff --git a/Documentation/driver-api/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst
index b3f447bf9f07..4360cd5200be 100644
--- a/Documentation/driver-api/driver-model/overview.rst
+++ b/Documentation/driver-api/driver-model/overview.rst
@@ -55,7 +55,7 @@ struct pci_dev now looks like this::
Note first that the struct device dev within the struct pci_dev is
statically allocated. This means only one allocation on device discovery.
-Note also that that struct device dev is not necessarily defined at the
+Note also that the struct device dev is not necessarily defined at the
front of the pci_dev structure. This is to make people think about what
they're doing when switching between the bus driver and the global driver,
and to discourage meaningless and incorrect casts between the two.
diff --git a/Documentation/filesystems/netfs_library.rst b/Documentation/filesystems/netfs_library.rst
index ddd799df6ce3..715218e1b233 100644
--- a/Documentation/filesystems/netfs_library.rst
+++ b/Documentation/filesystems/netfs_library.rst
@@ -626,7 +626,7 @@ A number of members are available for access/use by the filesystem:
These are set by the filesystem or the cache in ->prepare_read() or
->prepare_write() for each subrequest to indicate the maximum number of
- bytes and, optionally, the maximum number of segments (if not 0) that that
+ bytes and, optionally, the maximum number of segments (if not 0) that the
subrequest can support.
* ``submit_extendable_to``
diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst
index e92f56ebd0b5..c25587f411f2 100644
--- a/Documentation/trace/histogram-design.rst
+++ b/Documentation/trace/histogram-design.rst
@@ -738,7 +738,7 @@ creates its own variable, wakeup_lat, but nothing yet uses it::
Looking at the sched_waking 'hist_debug' output, in addition to the
normal key and value hist_fields, in the val fields section we see a
-field with the HIST_FIELD_FL_VAR flag, which indicates that that field
+field with the HIST_FIELD_FL_VAR flag, which indicates that the field
represents a variable. Note that in addition to the variable name,
contained in the var.name field, it includes the var.idx, which is the
index into the tracing_map_elt.vars[] array of the actual variable
diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst
index 340bcb5099e7..ca619499ce28 100644
--- a/Documentation/trace/histogram.rst
+++ b/Documentation/trace/histogram.rst
@@ -1700,7 +1700,7 @@ to that rule is that any variable used in an expression is essentially
'read-once' - once it's used by an expression in a subsequent event,
it's reset to its 'unset' state, which means it can't be used again
unless it's set again. This ensures not only that an event doesn't
-use an uninitialized variable in a calculation, but that that variable
+use an uninitialized variable in a calculation, but that the variable
is used only once and not for any unrelated subsequent match.
The basic syntax for saving a variable is to simply prefix a unique
--
2.54.0
^ permalink raw reply related
* [PATCH v2 3/4] docs: fix repeated word 'as' in dax-hv-api documentation
From: Adrien Reynard @ 2026-05-09 14:30 UTC (permalink / raw)
To: corbet; +Cc: skhan, linux-doc, linux-kernel, Adrien Reynard
In-Reply-To: <20260508163802.16249-1-reynard.adrien.08@gmail.com>
Remove duplicated word 'as' found in three places in
arch/sparc/oradax/dax-hv-api.txt.
Signed-off-by: Adrien Reynard <reynard.adrien.08@gmail.com>
---
Documentation/arch/sparc/oradax/dax-hv-api.txt | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/arch/sparc/oradax/dax-hv-api.txt b/Documentation/arch/sparc/oradax/dax-hv-api.txt
index ef1a4c2bf08b..6dac2a778ccd 100644
--- a/Documentation/arch/sparc/oradax/dax-hv-api.txt
+++ b/Documentation/arch/sparc/oradax/dax-hv-api.txt
@@ -485,7 +485,7 @@ Offset Size Field Description
the virtual machine to use when accessing this data stream
(checking is only guaranteed to be performed when using API
version 1.1 and later). If using a virtual address, this field will
- be used as as primary input address bits [59:56].
+ be used as the primary input address bits [59:56].
[55:0] Primary input address bits [55:0]. Address type is determined
by CCB header.
24 8 Data Access Control
@@ -576,7 +576,7 @@ Offset Size Field Description
the virtual machine to use when accessing this data stream
(checking is only guaranteed to be performed when using API
version 1.1 and later). If using a virtual address, this field will
- be used as as symbol table address bits [59:56].
+ be used as symbol table address bits [59:56].
[55:4] Symbol table address bits [55:4]. Address type is determined
by CCB header.
[3:0] Symbol table version
@@ -815,7 +815,7 @@ Offset Size Field Description
the virtual machine to use when accessing this data stream
(checking is only guaranteed to be performed when using API
version 1.1 and later). If using a virtual address, this field will
- be used as as bit table address bits [59:56]
+ be used as bit table address bits [59:56]
[55:4] Bit table address bits [55:4]. Address type is determined by
CCB header. Address must be 64-byte aligned (CCB version
0) or 16-byte aligned (CCB version 1).
--
2.54.0
^ permalink raw reply related
* Re: [PATCH v5 1/3] dt-bindings: trivial-devices: Add Delta E50SN12051
From: Guenter Roeck @ 2026-05-09 15:38 UTC (permalink / raw)
To: Colin Huang
Cc: Rob Herring, Krzysztof Kozlowski, Conor Dooley, Kevin Chang,
Jonathan Corbet, Shuah Khan, linux-hwmon, devicetree,
linux-kernel, linux-doc, Colin Huang
In-Reply-To: <20260508-add-e50sn12051-v5-1-abebdcc29665@gmail.com>
On Fri, May 08, 2026 at 05:44:28PM +0800, Colin Huang wrote:
> From: Colin Huang <u8813345@gmail.com>
>
> Add 600W Non-isolated 1/8th Brick DC/DC Power Modules, E50SN12051.
>
> Signed-off-by: Colin Huang <u8813345@gmail.com>
> Acked-by: Conor Dooley <conor.dooley@microchip.com>
Applied, after swapping the inserted lines below.
Thanks,
Guenter
> ---
> Documentation/devicetree/bindings/trivial-devices.yaml | 2 ++
> 1 file changed, 2 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml
> index 23fd4513933a..0f10368a1386 100644
> --- a/Documentation/devicetree/bindings/trivial-devices.yaml
> +++ b/Documentation/devicetree/bindings/trivial-devices.yaml
> @@ -100,6 +100,8 @@ properties:
> # Delta Electronics DPS920AB 920W 54V Power Supply
> - delta,dps920ab
> # 1/4 Brick DC/DC Regulated Power Module
> + - delta,e50sn12051
> + # 600W Non-isolated 1/8th Brick DC/DC Power Modules
> - delta,q54sj108a2
> # 1300W 1/4 Brick DC/DC Regulated Power Module
> - delta,q54sn120a1
^ permalink raw reply
* Re: [PATCH v5 2/3] Documentation/hwmon: add Delta E50SN12051 documentation
From: Guenter Roeck @ 2026-05-09 15:40 UTC (permalink / raw)
To: Colin Huang
Cc: Rob Herring, Krzysztof Kozlowski, Conor Dooley, Kevin Chang,
Jonathan Corbet, Shuah Khan, linux-hwmon, devicetree,
linux-kernel, linux-doc, Colin Huang
In-Reply-To: <20260508-add-e50sn12051-v5-2-abebdcc29665@gmail.com>
On Fri, May 08, 2026 at 05:44:29PM +0800, Colin Huang wrote:
> From: Colin Huang <u8813345@gmail.com>
>
> Document the hardware monitoring support for the Delta E50SN12051
> device.
>
> The documentation describes the supported sensors exposed via the
> hwmon subsystem, including voltage, current, and temperature measurements.
>
> Signed-off-by: Colin Huang <u8813345@gmail.com>
> Reviewed-by: Guenter Roeck <linux@roeck-us.net>
Applied.
Thanks,
Guenter
^ permalink raw reply
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