* [PATCH 3/9] docs: kdoc: ensure that comments are using our coding style
From: Mauro Carvalho Chehab @ 2026-01-19 12:04 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, dri-devel, intel-gfx, linux-kbuild,
linux-kernel, workflows, Mauro Carvalho Chehab
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
Along kernel-doc libs, we opted to have all comments starting/ending
with a blank comment line. Use the same style here.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc.py | 24 ++++++++++++++++++------
1 file changed, 18 insertions(+), 6 deletions(-)
diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 1ebb16b9bb08..f1f3f56edeb5 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -3,7 +3,7 @@
# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
#
# pylint: disable=C0103,R0912,R0914,R0915
-
+#
# NOTE: While kernel-doc requires at least version 3.6 to run, the
# command line should work with Python 3.2+ (tested with 3.4).
# The rationale is that it shall fail gracefully during Kernel
@@ -12,7 +12,7 @@
# - no f-strings can be used on this file.
# - the libraries that require newer versions can only be included
# after Python version is checked.
-
+#
# Converted from the kernel-doc script originally written in Perl
# under GPLv2, copyrighted since 1998 by the following authors:
#
@@ -197,8 +197,9 @@ def main():
parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
description=DESC)
+ #
# Normal arguments
-
+ #
parser.add_argument("-v", "-verbose", "--verbose", action="store_true",
help="Verbose output, more warnings and other information.")
@@ -213,8 +214,9 @@ def main():
action="store_true",
help="Enable line number output (only in ReST mode)")
+ #
# Arguments to control the warning behavior
-
+ #
parser.add_argument("-Wreturn", "--wreturn", action="store_true",
help="Warns about the lack of a return markup on functions.")
@@ -235,8 +237,9 @@ def main():
parser.add_argument("-export-file", "--export-file", action='append',
help=EXPORT_FILE_DESC)
+ #
# Output format mutually-exclusive group
-
+ #
out_group = parser.add_argument_group("Output format selection (mutually exclusive)")
out_fmt = out_group.add_mutually_exclusive_group()
@@ -248,8 +251,9 @@ def main():
out_fmt.add_argument("-N", "-none", "--none", action="store_true",
help="Do not output documentation, only warnings.")
+ #
# Output selection mutually-exclusive group
-
+ #
sel_group = parser.add_argument_group("Output selection (mutually exclusive)")
sel_mut = sel_group.add_mutually_exclusive_group()
@@ -262,7 +266,9 @@ def main():
sel_mut.add_argument("-s", "-function", "--symbol", action='append',
help=FUNCTION_DESC)
+ #
# Those are valid for all 3 types of filter
+ #
parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append',
help=NOSYMBOL_DESC)
@@ -295,9 +301,11 @@ def main():
python_ver = sys.version_info[:2]
if python_ver < (3,6):
+ #
# Depending on Kernel configuration, kernel-doc --none is called at
# build time. As we don't want to break compilation due to the
# usage of an old Python version, return 0 here.
+ #
if args.none:
logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
sys.exit(0)
@@ -307,7 +315,9 @@ def main():
if python_ver < (3,7):
logger.warning("Python 3.7 or later is required for correct results")
+ #
# Import kernel-doc libraries only after checking Python version
+ #
from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415
from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415
@@ -346,6 +356,8 @@ def main():
sys.exit(0)
+#
# Call main method
+#
if __name__ == "__main__":
main()
--
2.52.0
^ permalink raw reply related
* [PATCH 0/9] docs: Fix kernel-doc -Werror and moves it to tools/docs
From: Mauro Carvalho Chehab @ 2026-01-19 12:04 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Alex Shi, Carlos Bilbao, David Airlie,
Federico Vaga, Hu Haowen, Jani Nikula, Joonas Lahtinen,
Mauro Carvalho Chehab, Nathan Chancellor, Nicolas Schier,
Rodrigo Vivi, Simona Vetter, Tvrtko Ursulin, Yanteng Si,
dri-devel, intel-gfx, linux-doc, linux-kbuild, linux-kernel,
workflows, Thomas Weißschuh, Andy Shevchenko, Avadhut Naik,
Chenguang Zhao, David Disseldorp, Dongliang Mu, Gang Yan,
Kees Cook, Masahiro Yamada, Miguel Ojeda, Randy Dunlap,
Shuah Khan, Steven Rostedt, Tamir Duberstein, Vincent Mailhol,
WangYuli
Hi Jon,
After a restful weekend and revisiting both yours and my series,
I'm opting to send a patch series merging both into one:
- The first 4 patches are from my series (no changes since v5):
https://lore.kernel.org/linux-doc/cover.1768642102.git.mchehab+huawei@kernel.org/T/#m81211c0ff38bbaa82b8b0b6606f242ccc0c2a9ac
- It follows by the 2 patches from your renaming series:
https://lore.kernel.org/linux-doc/20260119111745.4694546b@foz.lan/T/#m51099c31a99dccccdb4d17cbaadc818e9e4df8c4
with the fix I proposed for kernel-doc to find its libraries
I added 3 patches afterwards:
- patch 5: move possible return values from docstring to helper message;
- patch 6: improve MsgFormatter description;
- patch 7: moves kerneldoc_bin from conf.py to the sphinx/kerneldoc.py
(this is now just a debugging message - no need to pick it from env)
IMO, this series is ready to be merged.
NOTE:
I didn't rename kernel-doc to kernel_doc.py nor added any symlinks.
If we want some day to use sphinx autoparse extension, we can do it
later. I guess we can also revisit it during -rc period, if needed.
Regards,
Mauro
Jonathan Corbet (2):
docs: kdoc: remove support for an external kernel-doc from sphinx
docs: kdoc: move kernel-doc to tools/docs
Mauro Carvalho Chehab (7):
docs: kdoc: fix logic to handle unissued warnings
docs: kdoc: avoid error_count overflows
docs: kdoc: ensure that comments are using our coding style
docs: kdoc: some fixes to kernel-doc comments
docs: kdoc: move the return values to the helper message
docs: kdoc: improve description of MsgFormatter
docs: conf.py: get rid of the now unused kerneldoc_bin env var
Documentation/conf.py | 4 -
Documentation/doc-guide/kernel-doc.rst | 8 +-
Documentation/kbuild/kbuild.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
Documentation/sphinx/kerneldoc.py | 60 +++----------
.../it_IT/doc-guide/kernel-doc.rst | 8 +-
.../sp_SP/process/coding-style.rst | 2 +-
.../zh_CN/doc-guide/kernel-doc.rst | 10 +--
.../translations/zh_CN/kbuild/kbuild.rst | 2 +-
.../zh_CN/process/coding-style.rst | 2 +-
.../zh_TW/process/coding-style.rst | 2 +-
MAINTAINERS | 2 -
Makefile | 2 +-
drivers/gpu/drm/i915/Makefile | 2 +-
scripts/kernel-doc | 1 -
tools/docs/find-unused-docs.sh | 2 +-
.../kernel-doc.py => tools/docs/kernel-doc | 89 ++++++++++++-------
tools/docs/sphinx-build-wrapper | 2 +-
tools/lib/python/kdoc/kdoc_parser.py | 35 ++++++--
19 files changed, 120 insertions(+), 117 deletions(-)
delete mode 120000 scripts/kernel-doc
rename scripts/kernel-doc.py => tools/docs/kernel-doc (88%)
--
2.52.0
^ permalink raw reply
* [PATCH 5/9] docs: kdoc: remove support for an external kernel-doc from sphinx
From: Mauro Carvalho Chehab @ 2026-01-19 12:05 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, dri-devel, intel-gfx, linux-kbuild,
linux-kernel, workflows, Shuah Khan, Mauro Carvalho Chehab
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
From: Jonathan Corbet <corbet@lwn.net>
The ability to build the docs with an external kernel-doc program involves
some truly confusing logic and complicates the task of moving kernel-doc
out of scripts/. But this feature is not useful for normal documentation
builds, and the external kernel-doc can always be run by hand when it needs
debugging. So just remove that feature and make life easier.
There is still a bunch of logic to build a command line that we never use;
the idea is to be able to output it, but I'm not sure if that is worth
keeping.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/kerneldoc.py | 53 ++++---------------------------
1 file changed, 6 insertions(+), 47 deletions(-)
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index d8cdf068ef35..afbab458550a 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -190,35 +190,7 @@ class KernelDocDirective(Directive):
return cmd
- def run_cmd(self, cmd):
- """
- Execute an external kernel-doc command.
- """
-
- env = self.state.document.settings.env
- node = nodes.section()
-
- p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
- out, err = p.communicate()
-
- out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
-
- if p.returncode != 0:
- sys.stderr.write(err)
-
- logger.warning("kernel-doc '%s' failed with return code %d"
- % (" ".join(cmd), p.returncode))
- return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
- elif env.config.kerneldoc_verbosity > 0:
- sys.stderr.write(err)
-
- filenames = self.parse_args["file_list"]
- for filename in filenames:
- self.parse_msg(filename, node, out, cmd)
-
- return node.children
-
- def parse_msg(self, filename, node, out, cmd):
+ def parse_msg(self, filename, node, out):
"""
Handles a kernel-doc output for a given file
"""
@@ -244,7 +216,7 @@ class KernelDocDirective(Directive):
self.do_parse(result, node)
- def run_kdoc(self, cmd, kfiles):
+ def run_kdoc(self, kfiles):
"""
Execute kernel-doc classes directly instead of running as a separate
command.
@@ -258,23 +230,17 @@ class KernelDocDirective(Directive):
filenames = self.parse_args["file_list"]
for filename, out in kfiles.msg(**self.msg_args, filenames=filenames):
- self.parse_msg(filename, node, out, cmd)
+ self.parse_msg(filename, node, out)
return node.children
def run(self):
- global kfiles
-
cmd = self.handle_args()
if self.verbose >= 1:
logger.info(cmd_str(cmd))
try:
- if kfiles:
- return self.run_kdoc(cmd, kfiles)
- else:
- return self.run_cmd(cmd)
-
+ return self.run_kdoc(kfiles)
except Exception as e: # pylint: disable=W0703
logger.warning("kernel-doc '%s' processing failed with: %s" %
(cmd_str(cmd), pformat(e)))
@@ -286,15 +252,8 @@ class KernelDocDirective(Directive):
def setup_kfiles(app):
global kfiles
-
- kerneldoc_bin = app.env.config.kerneldoc_bin
-
- if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
- print("Using Python kernel-doc")
- out_style = RestFormat()
- kfiles = KernelFiles(out_style=out_style, logger=logger)
- else:
- print(f"Using {kerneldoc_bin}")
+ out_style = RestFormat()
+ kfiles = KernelFiles(out_style=out_style, logger=logger)
def setup(app):
--
2.52.0
^ permalink raw reply related
* [PATCH 1/9] docs: kdoc: fix logic to handle unissued warnings
From: Mauro Carvalho Chehab @ 2026-01-19 12:04 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, dri-devel, intel-gfx, linux-kbuild,
linux-kernel, workflows, Andy Shevchenko, Mauro Carvalho Chehab,
Randy Dunlap, stable
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
Changeset 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently discarded")
didn't properly addressed the missing messages behavior, as
it was calling directly python logger low-level function,
instead of using the expected method to emit warnings.
Basically, there are two methods to log messages:
- self.config.log.warning() - This is the raw level to emit a
warning. It just writes the a message at stderr, via python
logging, as it is initialized as:
self.config.log = logging.getLogger("kernel-doc")
- self.config.warning() - This is where we actually consider a
message as a warning, properly incrementing error count.
Due to that, several parsing error messages are internally considered
as success, causing -Werror to not work on such messages.
While here, ensure that the last ignored entry will also be handled
by adding an extra check at the end of the parse handler.
Fixes: 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently discarded")
Closes: https://lore.kernel.org/linux-doc/20260112091053.00cee29a@foz.lan/
Cc: stable@vger.kernel.org
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
tools/lib/python/kdoc/kdoc_parser.py | 35 ++++++++++++++++++++++------
1 file changed, 28 insertions(+), 7 deletions(-)
diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index a9a37519145d..c03505889dc2 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -295,7 +295,7 @@ class KernelEntry:
# TODO: rename to emit_message after removal of kernel-doc.pl
def emit_msg(self, ln, msg, *, warning=True):
- """Emit a message"""
+ """Emit a message."""
log_msg = f"{self.fname}:{ln} {msg}"
@@ -448,18 +448,37 @@ class KernelDoc:
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
+ def emit_unused_warnings(self):
+ """
+ When the parser fails to produce a valid entry, it places some
+ warnings under `entry.warnings` that will be discarded when resetting
+ the state.
+
+ Ensure that those warnings are not lost.
+
+ .. note::
+
+ Because we are calling `config.warning()` here, those
+ warnings are not filtered by the `-W` parameters: they will all
+ be produced even when `-Wreturn`, `-Wshort-desc`, and/or
+ `-Wcontents-before-sections` are used.
+
+ Allowing those warnings to be filtered is complex, because it
+ would require storing them in a buffer and then filtering them
+ during the output step of the code, depending on the
+ selected symbols.
+ """
+ if self.entry and self.entry not in self.entries:
+ for log_msg in self.entry.warnings:
+ self.config.warning(log_msg)
+
def reset_state(self, ln):
"""
Ancillary routine to create a new entry. It initializes all
variables used by the state machine.
"""
- #
- # Flush the warnings out before we proceed further
- #
- if self.entry and self.entry not in self.entries:
- for log_msg in self.entry.warnings:
- self.config.log.warning(log_msg)
+ self.emit_unused_warnings()
self.entry = KernelEntry(self.config, self.fname, ln)
@@ -1741,6 +1760,8 @@ class KernelDoc:
# Hand this line to the appropriate state handler
self.state_actions[self.state](self, ln, line)
+ self.emit_unused_warnings()
+
except OSError:
self.config.log.error(f"Error: Cannot open file {self.fname}")
--
2.52.0
^ permalink raw reply related
* [PATCH 4/9] docs: kdoc: some fixes to kernel-doc comments
From: Mauro Carvalho Chehab @ 2026-01-19 12:04 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, dri-devel, intel-gfx, linux-kbuild,
linux-kernel, workflows, Mauro Carvalho Chehab
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
There are some typos and English errors in the comments of kernel‑doc.py.
Locate them with the help of an LLM (gpt‑oss 14B), executed locally
with this prompt:
review English grammar and syntax at the comments on the code below:
<cat scripts/kernel-doc.py>
While LLM worked fine for the task of doing an English grammar review
for strings, being able to distinguish them from the actual code, it
was not is perfect: some things required manual work to fix.
-
While here, replace:
"/**" with: ``/**``
As, if we ever rename this script to kernel_doc.py and add it to
Sphinx ext autodoc, we want to avoid this warning:
scripts/kernel_doc.py:docstring of kernel_doc:10: WARNING: Inline strong start-string without end-string. [docutils]
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/kernel-doc.py | 29 +++++++++++++----------------
1 file changed, 13 insertions(+), 16 deletions(-)
diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index f1f3f56edeb5..4e3b9cfe3fd7 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -9,9 +9,9 @@
# The rationale is that it shall fail gracefully during Kernel
# compilation with older Kernel versions. Due to that:
# - encoding line is needed here;
-# - no f-strings can be used on this file.
-# - the libraries that require newer versions can only be included
-# after Python version is checked.
+# - f-strings cannot be used in this file.
+# - libraries that require newer versions can only be included
+# after the Python version has been checked.
#
# Converted from the kernel-doc script originally written in Perl
# under GPLv2, copyrighted since 1998 by the following authors:
@@ -88,16 +88,13 @@
# Yujie Liu <yujie.liu@intel.com>
"""
-kernel_doc
-==========
-
-Print formatted kernel documentation to stdout
+Print formatted kernel documentation to stdout.
Read C language source or header FILEs, extract embedded
documentation comments, and print formatted documentation
to standard output.
-The documentation comments are identified by the "/**"
+The documentation comments are identified by the ``/**``
opening comment mark.
See Documentation/doc-guide/kernel-doc.rst for the
@@ -134,13 +131,13 @@ May be used multiple times.
"""
EXPORT_DESC = """
-Only output documentation for the symbols that have been
+Only output documentation for symbols that have been
exported using EXPORT_SYMBOL() and related macros in any input
FILE or -export-file FILE.
"""
INTERNAL_DESC = """
-Only output documentation for the symbols that have NOT been
+Only output documentation for symbols that have NOT been
exported using EXPORT_SYMBOL() and related macros in any input
FILE or -export-file FILE.
"""
@@ -163,7 +160,7 @@ Header and C source files to be parsed.
"""
WARN_CONTENTS_BEFORE_SECTIONS_DESC = """
-Warns if there are contents before sections (deprecated).
+Warn if there are contents before sections (deprecated).
This option is kept just for backward-compatibility, but it does nothing,
neither here nor at the original Perl script.
@@ -171,7 +168,7 @@ neither here nor at the original Perl script.
class MsgFormatter(logging.Formatter):
- """Helper class to format warnings on a similar way to kernel-doc.pl"""
+ """Helper class to format warnings in a similar way to kernel-doc.pl."""
def format(self, record):
record.levelname = record.levelname.capitalize()
@@ -273,7 +270,7 @@ def main():
help=NOSYMBOL_DESC)
parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections",
- action='store_true', help="Don't outputt DOC sections")
+ action='store_true', help="Don't output DOC sections")
parser.add_argument("files", metavar="FILE",
nargs="+", help=FILES_DESC)
@@ -302,12 +299,12 @@ def main():
python_ver = sys.version_info[:2]
if python_ver < (3,6):
#
- # Depending on Kernel configuration, kernel-doc --none is called at
+ # Depending on the Kernel configuration, kernel-doc --none is called at
# build time. As we don't want to break compilation due to the
# usage of an old Python version, return 0 here.
#
if args.none:
- logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
+ logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks")
sys.exit(0)
sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
@@ -316,7 +313,7 @@ def main():
logger.warning("Python 3.7 or later is required for correct results")
#
- # Import kernel-doc libraries only after checking Python version
+ # Import kernel-doc libraries only after checking the Python version
#
from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415
from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415
--
2.52.0
^ permalink raw reply related
* [PATCH 8/9] docs: kdoc: improve description of MsgFormatter
From: Mauro Carvalho Chehab @ 2026-01-19 12:05 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, dri-devel,
intel-gfx, linux-kbuild, linux-kernel, workflows, Shuah Khan
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
The description there is quite vague. Make it clearer.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
tools/docs/kernel-doc | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc
index 902397804e80..aed09f9a54dd 100755
--- a/tools/docs/kernel-doc
+++ b/tools/docs/kernel-doc
@@ -182,7 +182,10 @@ return 0 if there are issues at kernel-doc markups;
"""
class MsgFormatter(logging.Formatter):
- """Helper class to format warnings in a similar way to kernel-doc.pl."""
+ """
+ Helper class to capitalize errors and warnings, the same way
+ the venerable (now retired) kernel-doc.pl used to do.
+ """
def format(self, record):
record.levelname = record.levelname.capitalize()
--
2.52.0
^ permalink raw reply related
* [PATCH 9/9] docs: conf.py: get rid of the now unused kerneldoc_bin env var
From: Mauro Carvalho Chehab @ 2026-01-19 12:05 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, dri-devel, intel-gfx, linux-kbuild,
linux-kernel, workflows, Mauro Carvalho Chehab, Shuah Khan
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
In the past, this contained the location of the binary file to parse
kernel-doc. Nowadays, it is used only for debugging purposes, inside
kerneldoc.py extension.
Move it to sphinx/kerneldoc.py, to avoid needing to handle with it
on several places.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 4 ----
Documentation/sphinx/kerneldoc.py | 7 +++++--
2 files changed, 5 insertions(+), 6 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 383d5e5b9d0a..65df81a9e414 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -579,10 +579,6 @@ pdf_documents = [
("kernel-documentation", "Kernel", "Kernel", "J. Random Bozo"),
]
-# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
-# the Docs). In a normal build, these are supplied from the Makefile via command
-# line arguments.
-kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now
kerneldoc_srctree = ".."
def setup(app):
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index afbab458550a..c1cadb4eb099 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -47,6 +47,10 @@ sys.path.insert(0, os.path.join(srctree, "tools/lib/python"))
from kdoc.kdoc_files import KernelFiles
from kdoc.kdoc_output import RestFormat
+# Used when verbose is active to show how to reproduce kernel-doc
+# issues via command line
+kerneldoc_bin = "tools/docs/kernel-doc"
+
__version__ = '1.0'
kfiles = None
logger = logging.getLogger(__name__)
@@ -95,7 +99,7 @@ class KernelDocDirective(Directive):
def handle_args(self):
env = self.state.document.settings.env
- cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
+ cmd = [kerneldoc_bin, '-rst', '-enable-lineno']
filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
@@ -257,7 +261,6 @@ def setup_kfiles(app):
def setup(app):
- app.add_config_value('kerneldoc_bin', None, 'env')
app.add_config_value('kerneldoc_srctree', None, 'env')
app.add_config_value('kerneldoc_verbosity', 1, 'env')
--
2.52.0
^ permalink raw reply related
* [PATCH 7/9] docs: kdoc: move the return values to the helper message
From: Mauro Carvalho Chehab @ 2026-01-19 12:05 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, dri-devel, intel-gfx, linux-kbuild,
linux-kernel, workflows, Mauro Carvalho Chehab, Shuah Khan
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
It makes sense to describe what kernel-doc is expected to return
on its help message. Move such messages to argparse epilog.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
tools/docs/kernel-doc | 27 +++++++++++++++------------
1 file changed, 15 insertions(+), 12 deletions(-)
diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc
index a19a92566780..902397804e80 100755
--- a/tools/docs/kernel-doc
+++ b/tools/docs/kernel-doc
@@ -166,6 +166,20 @@ This option is kept just for backward-compatibility, but it does nothing,
neither here nor at the original Perl script.
"""
+EPILOG = """
+The return value is:
+
+- 0: success or Python version is not compatible with
+kernel-doc. If -Werror is not used, it will also
+return 0 if there are issues at kernel-doc markups;
+
+- 1: an abnormal condition happened;
+
+- 2: argparse issued an error;
+
+- 3: When -Werror is used, it means that one or more unfiltered parse
+ warnings happened.
+"""
class MsgFormatter(logging.Formatter):
"""Helper class to format warnings in a similar way to kernel-doc.pl."""
@@ -178,21 +192,10 @@ def main():
"""
Main program.
- By default, the return value is:
-
- - 0: success or Python version is not compatible with
- kernel-doc. If -Werror is not used, it will also
- return 0 if there are issues at kernel-doc markups;
-
- - 1: an abnormal condition happened;
-
- - 2: argparse issued an error;
-
- - 3: -Werror is used, and one or more unfiltered parse warnings happened.
"""
parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
- description=DESC)
+ description=DESC, epilog=EPILOG)
#
# Normal arguments
--
2.52.0
^ permalink raw reply related
* [PATCH 2/9] docs: kdoc: avoid error_count overflows
From: Mauro Carvalho Chehab @ 2026-01-19 12:04 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, dri-devel, intel-gfx, linux-kbuild,
linux-kernel, workflows, Mauro Carvalho Chehab, stable
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
The glibc library limits the return code to 8 bits. We need to
stick to this limit when using sys.exit(error_count).
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: stable@vger.kernel.org
---
scripts/kernel-doc.py | 26 +++++++++++++++++++-------
1 file changed, 19 insertions(+), 7 deletions(-)
diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 7a1eaf986bcd..1ebb16b9bb08 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -116,6 +116,8 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
+WERROR_RETURN_CODE = 3
+
DESC = """
Read C language source or header FILEs, extract embedded documentation comments,
and print formatted documentation to standard output.
@@ -176,7 +178,21 @@ class MsgFormatter(logging.Formatter):
return logging.Formatter.format(self, record)
def main():
- """Main program"""
+ """
+ Main program.
+
+ By default, the return value is:
+
+ - 0: success or Python version is not compatible with
+ kernel-doc. If -Werror is not used, it will also
+ return 0 if there are issues at kernel-doc markups;
+
+ - 1: an abnormal condition happened;
+
+ - 2: argparse issued an error;
+
+ - 3: -Werror is used, and one or more unfiltered parse warnings happened.
+ """
parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
description=DESC)
@@ -323,16 +339,12 @@ def main():
if args.werror:
print("%s warnings as errors" % error_count) # pylint: disable=C0209
- sys.exit(error_count)
+ sys.exit(WERROR_RETURN_CODE)
if args.verbose:
print("%s errors" % error_count) # pylint: disable=C0209
- if args.none:
- sys.exit(0)
-
- sys.exit(error_count)
-
+ sys.exit(0)
# Call main method
if __name__ == "__main__":
--
2.52.0
^ permalink raw reply related
* [PATCH 6/9] docs: kdoc: move kernel-doc to tools/docs
From: Mauro Carvalho Chehab @ 2026-01-19 12:05 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: dri-devel, intel-gfx, linux-kbuild, linux-kernel, workflows,
Thomas Weißschuh, Alex Shi, Avadhut Naik, Carlos Bilbao,
Chenguang Zhao, David Airlie, David Disseldorp, Dongliang Mu,
Federico Vaga, Gang Yan, Hu Haowen, Jani Nikula, Joonas Lahtinen,
Kees Cook, Masahiro Yamada, Mauro Carvalho Chehab, Miguel Ojeda,
Nathan Chancellor, Nicolas Schier, Randy Dunlap, Rodrigo Vivi,
Shuah Khan, Simona Vetter, Steven Rostedt, Tamir Duberstein,
Tvrtko Ursulin, Vincent Mailhol, WangYuli, Yanteng Si,
Mauro Carvalho Chehab
In-Reply-To: <cover.1768823489.git.mchehab+huawei@kernel.org>
From: Jonathan Corbet <corbet@lwn.net>
kernel-doc is the last documentation-related tool still living outside of
the tools/docs directory; the time has come to move it over.
[mchehab: fixed kdoc lib location]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/conf.py | 2 +-
Documentation/doc-guide/kernel-doc.rst | 8 ++++----
Documentation/kbuild/kbuild.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
.../translations/it_IT/doc-guide/kernel-doc.rst | 8 ++++----
.../translations/sp_SP/process/coding-style.rst | 2 +-
.../translations/zh_CN/doc-guide/kernel-doc.rst | 10 +++++-----
Documentation/translations/zh_CN/kbuild/kbuild.rst | 2 +-
.../translations/zh_CN/process/coding-style.rst | 2 +-
.../translations/zh_TW/process/coding-style.rst | 2 +-
MAINTAINERS | 2 --
Makefile | 2 +-
drivers/gpu/drm/i915/Makefile | 2 +-
scripts/kernel-doc | 1 -
tools/docs/find-unused-docs.sh | 2 +-
scripts/kernel-doc.py => tools/docs/kernel-doc | 2 +-
tools/docs/sphinx-build-wrapper | 2 +-
17 files changed, 25 insertions(+), 28 deletions(-)
delete mode 120000 scripts/kernel-doc
rename scripts/kernel-doc.py => tools/docs/kernel-doc (99%)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1ea2ae5c6276..383d5e5b9d0a 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -582,7 +582,7 @@ pdf_documents = [
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
# the Docs). In a normal build, these are supplied from the Makefile via command
# line arguments.
-kerneldoc_bin = "../scripts/kernel-doc.py"
+kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now
kerneldoc_srctree = ".."
def setup(app):
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index b56128d7f5c3..8d2c09fb36e4 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -54,7 +54,7 @@ Running the ``kernel-doc`` tool with increased verbosity and without actual
output generation may be used to verify proper formatting of the
documentation comments. For example::
- scripts/kernel-doc -v -none drivers/foo/bar.c
+ tools/docs/kernel-doc -v -none drivers/foo/bar.c
The documentation format of ``.c`` files is also verified by the kernel build
when it is requested to perform extra gcc checks::
@@ -365,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a
left parenthesis ('(') for function-like macros or not followed by one
for object-like macros.
-Function-like macros are handled like functions by ``scripts/kernel-doc``.
+Function-like macros are handled like functions by ``tools/docs/kernel-doc``.
They may have a parameter list. Object-like macros have do not have a
parameter list.
@@ -596,8 +596,8 @@ from the source file.
The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
-``scripts/kernel-doc`` script to extract the documentation comments from the
-source.
+``tools/docs/kernel-doc`` script to extract the documentation comments from
+the source.
.. _kernel_doc:
diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index 82826b0332df..5a9013bacfb7 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -180,7 +180,7 @@ architecture.
KDOCFLAGS
---------
Specify extra (warning/error) flags for kernel-doc checks during the build,
-see scripts/kernel-doc for which flags are supported. Note that this doesn't
+see tools/docs/kernel-doc for which flags are supported. Note that this doesn't
(currently) apply to documentation builds.
ARCH
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 258158637f65..35b381230f6e 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -614,7 +614,7 @@ it.
When commenting the kernel API functions, please use the kernel-doc format.
See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
-``scripts/kernel-doc`` for details. Note that the danger of over-commenting
+``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting
applies to kernel-doc comments all the same. Do not add boilerplate
kernel-doc which simply reiterates what's obvious from the signature
of the function.
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
index aa0e31d353d6..bac959b8b7b9 100644
--- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
@@ -80,7 +80,7 @@ Al fine di verificare che i commenti siano formattati correttamente, potete
eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
che questo produca alcuna documentazione. Per esempio::
- scripts/kernel-doc -v -none drivers/foo/bar.c
+ tools/docs/kernel-doc -v -none drivers/foo/bar.c
Il formato della documentazione è verificato della procedura di generazione
del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
@@ -378,7 +378,7 @@ distinguono in base al fatto che il nome della macro simile a funzione sia
immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
oggetti no.
-Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
+Le macro simili a funzioni sono gestite come funzioni da ``tools/docs/kernel-doc``.
Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
elenco di parametri.
@@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*).
L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
-lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
+lo script ``tools/docs/kernel-doc`` per estrarre i commenti di documentazione
dai file sorgenti.
Come utilizzare kernel-doc per generare pagine man
@@ -604,4 +604,4 @@ Come utilizzare kernel-doc per generare pagine man
Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
farlo direttamente dai sorgenti del kernel::
- $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
+ $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
index 025223be9706..7d63aa8426e6 100644
--- a/Documentation/translations/sp_SP/process/coding-style.rst
+++ b/Documentation/translations/sp_SP/process/coding-style.rst
@@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
Al comentar las funciones de la API del kernel, utilice el formato
kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
-y ``scripts/kernel-doc`` para más detalles.
+y ``tools/docs/kernel-doc`` para más detalles.
El estilo preferido para comentarios largos (de varias líneas) es:
diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
index ccfb9b8329c2..fb2bbaaa85c1 100644
--- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
@@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取
用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
是否正确。例如::
- scripts/kernel-doc -v -none drivers/foo/bar.c
+ tools/docs/kernel-doc -v -none drivers/foo/bar.c
当请求执行额外的gcc检查时，内核构建将验证文档格式::
@@ -473,7 +473,7 @@ doc: *title*
如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
-在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
+在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
.. _kernel_doc_zh:
@@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
- $ scripts/kernel-doc -man \
+ $ tools/docs/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
| scripts/split-man.pl /tmp/man
一些旧版本的git不支持路径排除语法的某些变体。
以下命令之一可能适用于这些版本::
- $ scripts/kernel-doc -man \
+ $ tools/docs/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
| scripts/split-man.pl /tmp/man
- $ scripts/kernel-doc -man \
+ $ tools/docs/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
| scripts/split-man.pl /tmp/man
diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst
index 57f5cf5b2cdd..a477b4b08958 100644
--- a/Documentation/translations/zh_CN/kbuild/kbuild.rst
+++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst
@@ -174,7 +174,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确
KDOCFLAGS
---------
指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
-scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
+tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
ARCH
----
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 0484d0c65c25..5a342a024c01 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
也可以加上它做这些事情的原因。
当注释内核 API 函数时，请使用 kernel-doc 格式。详见
-Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
+Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
长 (多行) 注释的首选风格是：
diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index 311c6f6bad0b..e2ba97b3d8bb 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供
也可以加上它做這些事情的原因。
當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見
-Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
+Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
長 (多行) 註釋的首選風格是：
diff --git a/MAINTAINERS b/MAINTAINERS
index 02ec226dd571..d009e2da2215 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7523,7 +7523,6 @@ S: Maintained
P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next
F: Documentation/
-F: scripts/kernel-doc*
F: tools/lib/python/*
F: tools/docs/
F: tools/net/ynl/pyynl/lib/doc_generator.py
@@ -7561,7 +7560,6 @@ M: Mauro Carvalho Chehab <mchehab@kernel.org>
L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/sphinx/
-F: scripts/kernel-doc*
F: tools/lib/python/*
F: tools/docs/
diff --git a/Makefile b/Makefile
index 3cd00b62cde9..81a4ab11256c 100644
--- a/Makefile
+++ b/Makefile
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG = pkg-config
# the KERNELDOC macro needs to be exported, as scripts/Makefile.build
# has a logic to call it
-KERNELDOC = $(srctree)/scripts/kernel-doc.py
+KERNELDOC = $(srctree)/tools/docs/kernel-doc
export KERNELDOC
KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
index 4db24050edb0..c979c579de66 100644
--- a/drivers/gpu/drm/i915/Makefile
+++ b/drivers/gpu/drm/i915/Makefile
@@ -443,7 +443,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \
- $(srctree)/scripts/kernel-doc -none -Werror $<; touch $@
+ $(KERNELDOC) -none -Werror $<; touch $@
$(obj)/%.hdrtest: $(src)/%.h FORCE
$(call if_changed_dep,hdrtest)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
deleted file mode 120000
index 3b6ef807791a..000000000000
--- a/scripts/kernel-doc
+++ /dev/null
@@ -1 +0,0 @@
-kernel-doc.py
\ No newline at end of file
diff --git a/tools/docs/find-unused-docs.sh b/tools/docs/find-unused-docs.sh
index ca4e607ec3f7..53514c759dc1 100755
--- a/tools/docs/find-unused-docs.sh
+++ b/tools/docs/find-unused-docs.sh
@@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do
if [[ ${FILES_INCLUDED[$file]+_} ]]; then
continue;
fi
- str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null)
+ str=$(PYTHONDONTWRITEBYTECODE=1 tools/docs/kernel-doc -export "$file" 2>/dev/null)
if [[ -n "$str" ]]; then
echo "$file"
fi
diff --git a/scripts/kernel-doc.py b/tools/docs/kernel-doc
similarity index 99%
rename from scripts/kernel-doc.py
rename to tools/docs/kernel-doc
index 4e3b9cfe3fd7..a19a92566780 100755
--- a/scripts/kernel-doc.py
+++ b/tools/docs/kernel-doc
@@ -108,7 +108,7 @@ import sys
# Import Python modules
-LIB_DIR = "../tools/lib/python"
+LIB_DIR = "../lib/python"
SRC_DIR = os.path.dirname(os.path.realpath(__file__))
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 7a5fcef25429..cb2a5005e633 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -246,7 +246,7 @@ class SphinxBuilder:
#
self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build")
self.kerneldoc = self.get_path(os.environ.get("KERNELDOC",
- "scripts/kernel-doc.py"))
+ "tools/docs/kernel-doc"))
self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True)
#
--
2.52.0
^ permalink raw reply related
* Re: [PATCH v2] docs: netdev: refine 15-patch limit
From: patchwork-bot+netdevbpf @ 2026-01-19 14:18 UTC (permalink / raw)
To: Simon Horman
Cc: davem, edumazet, kuba, pabeni, corbet, netdev, workflows,
linux-doc
In-Reply-To: <20260115-15-minutes-of-fame-v2-1-70cbf0883aff@kernel.org>
Hello:
This patch was applied to netdev/net.git (main)
by Jakub Kicinski <kuba@kernel.org>:
On Thu, 15 Jan 2026 13:54:00 +0000 you wrote:
> The 15 patch limit is intended by the maintainers to cover
> all outstanding patches on the mailing list on a per-tree basis.
> Not just those in a single patchset. Document this practice accordingly.
>
> Signed-off-by: Simon Horman <horms@kernel.org>
> ---
> Changes in v2:
> - Clarify that the limit is per-tree. (Jakub)
> - Link to v1: https://lore.kernel.org/r/20260113-15-minutes-of-fame-v1-1-0806b418c6fd@kernel.org
>
> [...]
Here is the summary with links:
- [v2] docs: netdev: refine 15-patch limit
https://git.kernel.org/netdev/net/c/ff7737946812
You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
^ permalink raw reply
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Guillaume Tucker @ 2026-01-19 14:22 UTC (permalink / raw)
To: Nathan Chancellor
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm
In-Reply-To: <20260116211246.GA1826279@ax162>
Hi Nathan,
On 16/01/2026 10:12 pm, Nathan Chancellor wrote:
> Hi Guillaume,
>
> On Fri, Jan 16, 2026 at 11:28:24AM +0100, Guillaume Tucker wrote:
>> Hello,
>>
>> On 31/12/2025 17:51, Guillaume Tucker wrote:
>>> Changes in v3:
>>> - Refactor common code for Docker and Podman
>>> - Add docs.kernel.org URL in help message
>>> - Use pathlib Python package
>>> - Handle signals in parent process by default
>>> - Add --shell option to use an interactive shell
>>> - Tweak debug messages in verbose mode
>>> - Specify Python 3.10 as minimum version in the docs
>>> - Provide an example env file in the docs
>>> - Update docs regarding interactive shell usage
>>
>> I'm sure you're all busy landing commits ahead of the next merge
>> window. Could you please take a look at this v3 when you have a
>> moment? I believe I've addressed everything from previous reviews.
>
> So sorry for the radio silence. I was going to try and look at this
> today to give feedback before the weekend but I will not be able to look
> at it until Monday. Given that this is self-contained (no pun intended)
> with no regression risks, I would have no qualms with applying this late
> in the development cycle.
Thanks for getting back to me, that's great. I'll keep working on
some follow-up improvements in the meantime, regardless of the pace
of the review process.
Cheers,
Guillaume
^ permalink raw reply
* Re: [PATCH] doc: kgdb: Add description about rodata=off kernel parameter
From: Daniel Thompson @ 2026-01-19 14:49 UTC (permalink / raw)
To: junan
Cc: jason.wessel, dianders, corbet, workflows, linux-doc,
linux-kernel, Will Deacon
In-Reply-To: <20260116050410.772340-2-junan76@163.com>
On Fri, Jan 16, 2026 at 01:03:13PM +0800, junan wrote:
> STRICT_KERNEL_RWX can not be turned off throught menuconfig on some
> architectures, pass "rodata=off" to the kernel in this case.
>
> Tested with qemu on arm64.
>
> Signed-off-by: junan <junan76@163.com>
> Suggested-by: Will Deacon <will@kernel.org>
Reviewed-by: Daniel Thompson (RISCstar) <danielt@kernel.org>
Jonathan: do you want to take this or should I take it via the kgdb
tree?
Daniel.
^ permalink raw reply
* Re: [PATCH] doc: kgdb: Add description about rodata=off kernel parameter
From: Jonathan Corbet @ 2026-01-19 14:54 UTC (permalink / raw)
To: Daniel Thompson, junan
Cc: jason.wessel, dianders, workflows, linux-doc, linux-kernel,
Will Deacon
In-Reply-To: <aW5EhId-E6TzvR89@aspen.lan>
Daniel Thompson <danielt@kernel.org> writes:
> On Fri, Jan 16, 2026 at 01:03:13PM +0800, junan wrote:
>> STRICT_KERNEL_RWX can not be turned off throught menuconfig on some
>> architectures, pass "rodata=off" to the kernel in this case.
>>
>> Tested with qemu on arm64.
>>
>> Signed-off-by: junan <junan76@163.com>
>> Suggested-by: Will Deacon <will@kernel.org>
>
> Reviewed-by: Daniel Thompson (RISCstar) <danielt@kernel.org>
>
> Jonathan: do you want to take this or should I take it via the kgdb
> tree?
I'm fine either way; I'll pick it up shortly unless you say you've
already done so.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH] [v5] Documentation: Provide guidelines for tool-generated content
From: Dave Hansen @ 2026-01-19 19:57 UTC (permalink / raw)
To: Jonathan Corbet, Dave Hansen, linux-kernel
Cc: Shuah Khan, Kees Cook, Greg Kroah-Hartman, Miguel Ojeda,
Luis Chamberlain, SeongJae Park, Dan Williams, Steven Rostedt,
Paul E . McKenney, Simon Glass, NeilBrown, Lorenzo Stoakes,
Theodore Ts'o, Sasha Levin, Vlastimil Babka, workflows,
ksummit
In-Reply-To: <875x95xqqs.fsf@trenco.lwn.net>
On 1/13/26 11:22, Jonathan Corbet wrote:
>> --- a/Documentation/process/index.rst
>> +++ b/Documentation/process/index.rst
>> @@ -68,6 +68,7 @@ beyond).
>> stable-kernel-rules
>> management-style
>> researcher-guidelines
>> + generated-content
> At some point, $SOMEBODY should probably add a brief reference to
> submitting-patches.rst as well.
I can definitely send a follow-up for that.
It has a "Tooling" section. But it also seems like a sentence at the
top, like:
...
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -15,6 +15,8 @@ Documentation/process/submit-checklist.rst
for a list of items to check before submitting code.
For device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.rst.
+If you used tools to generate part of your contribution, read
+Documentation/process/generated-content.rst.
This documentation assumes that you're using ``git`` to prepare your patches.
If you're unfamiliar with ``git``, you would be well-advised to learn how to
might also be appropriate.
Any preferences?
^ permalink raw reply
* [PATCH] [v6] Documentation: Provide guidelines for tool-generated content
From: Dave Hansen @ 2026-01-19 20:04 UTC (permalink / raw)
To: linux-kernel
Cc: Dave Hansen, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, Luis Chamberlain, SeongJae Park, Dan Williams,
Steven Rostedt, Paul E . McKenney, Simon Glass, Lee Jones,
Lorenzo Stoakes, NeilBrown, Theodore Ts'o, Sasha Levin,
Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In the last few years, the capabilities of coding tools have exploded.
As those capabilities have expanded, contributors and maintainers have
more and more questions about how and when to apply those
capabilities.
Add new Documentation to guide contributors on how to best use kernel
development tools, new and old.
Note, though, there are fundamentally no new or unique rules in this
new document. It clarifies expectations that the kernel community has
had for many years. For example, researchers are already asked to
disclose the tools they use to find issues by
Documentation/process/researcher-guidelines.rst. This new document
just reiterates existing best practices for development tooling.
In short: Please show your work and make sure your contribution is
easy to review.
Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
Reviewed-by: Shuah Khan <shuah@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
Reviewed-by: Luis Chamberlain <mcgrof@kernel.org>
Reviewed-by: SeongJae Park <sj@kernel.org>
Reviewed-by: Dan Williams <dan.j.williams@intel.com>
Reviewed-by: Steven Rostedt <rostedt@goodmis.org>
Reviewed-by: Paul E. McKenney <paulmck@kernel.org>
Reviewed-by: Simon Glass <simon.glass@canonical.com>
Reviewed-by: Lee Jones <lee@kernel.org>
Reviewed-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: NeilBrown <neilb@ownmail.net>
Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Theodore Ts'o <tytso@mit.edu>
Cc: Sasha Levin <sashal@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: workflows@vger.kernel.org
Cc: ksummit@lists.linux.dev
Link: https://lore.kernel.org/all/cfb8bb96-e798-474d-bc6f-9cf610fe720f@lucifer.local/
--
Changes from v5:
* Add more review tags
* Add a blurb to the "special" asks bullet to mention that extra
testing may be requested.
* Reword the closing paragraph of "Out of Scope" section for clarity
* Remove an "AI" and make small wording tweak (Jon)
Changes from v4:
* Modest tweaking and rewording to strengthen language
* Add a section to help alleviate concerns that the document would
not enable maintainers to act forcefully enough in the face of
high-volume low-quality contributions (aka. AI slop).
This is very close to some text that Lorenzo posted. I just
made some very minor wording tweaks and spelling fixes.
* Note: v4 mistakenly had "v3" in the subject
Changes from v3:
* Wording/formatting tweaks (Randy)
Changes from v2:
* Mention testing (Shuah)
* Remove "very", rename LLM => coding assistant (Dan)
* More formatting sprucing up and minor typos (Miguel)
* Make changelog and text less flashy (Christian)
* Tone down critical=>helpful (Neil)
Changes from v1:
* Rename to generated-content.rst and add to documentation index.
(Jon)
* Rework subject to align with the new filename
* Replace commercial names with generic ones. (Jon)
* Be consistent about punctuation at the end of bullets for whole
sentences. (Miguel)
* Formatting sprucing up and minor typos (Miguel)
This document was a collaborative effort from all the members of
the TAB. I just reformatted it into .rst and wrote the changelog.
---
Documentation/process/generated-content.rst | 109 ++++++++++++++++++++
Documentation/process/index.rst | 1 +
2 files changed, 110 insertions(+)
create mode 100644 Documentation/process/generated-content.rst
diff --git a/Documentation/process/generated-content.rst b/Documentation/process/generated-content.rst
new file mode 100644
index 000000000000..08621e50a462
--- /dev/null
+++ b/Documentation/process/generated-content.rst
@@ -0,0 +1,109 @@
+============================================
+Kernel Guidelines for Tool-Generated Content
+============================================
+
+Purpose
+=======
+
+Kernel contributors have been using tooling to generate contributions
+for a long time. These tools can increase the volume of contributions.
+At the same time, reviewer and maintainer bandwidth is a scarce
+resource. Understanding which portions of a contribution come from
+humans versus tools is helpful to maintain those resources and keep
+kernel development healthy.
+
+The goal here is to clarify community expectations around tools. This
+lets everyone become more productive while also maintaining high
+degrees of trust between submitters and reviewers.
+
+Out of Scope
+============
+
+These guidelines do not apply to tools that make trivial tweaks to
+preexisting content. Nor do they pertain to tooling that helps with
+menial tasks. Some examples:
+
+ - Spelling and grammar fix ups, like rephrasing to imperative voice
+ - Typing aids like identifier completion, common boilerplate or
+ trivial pattern completion
+ - Purely mechanical transformations like variable renaming
+ - Reformatting, like running Lindent, ``clang-format`` or
+ ``rust-fmt``
+
+Even whenever your tool use is out of scope, you should still always
+consider if it would help reviewing your contribution if the reviewer
+knows about the tool that you used.
+
+In Scope
+========
+
+These guidelines apply when a meaningful amount of content in a kernel
+contribution was not written by a person in the Signed-off-by chain,
+but was instead created by a tool.
+
+Detection of a problem and testing the fix for it is also part of the
+development process; if a tool was used to find a problem addressed by
+a change, that should be noted in the changelog. This not only gives
+credit where it is due, it also helps fellow developers find out about
+these tools.
+
+Some examples:
+ - Any tool-suggested fix such as ``checkpatch.pl --fix``
+ - Coccinelle scripts
+ - A chatbot generated a new function in your patch to sort list entries.
+ - A .c file in the patch was originally generated by a coding
+ assistant but cleaned up by hand.
+ - The changelog was generated by handing the patch to a generative AI
+ tool and asking it to write the changelog.
+ - The changelog was translated from another language.
+
+If in doubt, choose transparency and assume these guidelines apply to
+your contribution.
+
+Guidelines
+==========
+
+First, read the Developer's Certificate of Origin:
+Documentation/process/submitting-patches.rst. Its rules are simple
+and have been in place for a long time. They have covered many
+tool-generated contributions. Ensure that you understand your entire
+submission and are prepared to respond to review comments.
+
+Second, when making a contribution, be transparent about the origin of
+content in cover letters and changelogs. You can be more transparent
+by adding information like this:
+
+ - What tools were used?
+ - The input to the tools you used, like the Coccinelle source script.
+ - If code was largely generated from a single or short set of
+ prompts, include those prompts. For longer sessions, include a
+ summary of the prompts and the nature of resulting assistance.
+ - Which portions of the content were affected by that tool?
+ - How is the submission tested and what tools were used to test the
+ fix?
+
+As with all contributions, individual maintainers have discretion to
+choose how they handle the contribution. For example, they might:
+
+ - Treat it just like any other contribution.
+ - Reject it outright.
+ - Treat the contribution specially, for example, asking for extra
+ testing, reviewing with extra scrutiny, or reviewing at a lower
+ priority than human-generated content.
+ - Ask for some other special steps, like asking the contributor to
+ elaborate on how the tool or model was trained.
+ - Ask the submitter to explain in more detail about the contribution
+ so that the maintainer can be assured that the submitter fully
+ understands how the code works.
+ - Suggest a better prompt instead of suggesting specific code changes.
+
+If tools permit you to generate a contribution automatically, expect
+additional scrutiny in proportion to how much of it was generated.
+
+As with the output of any tooling, the result may be incorrect or
+inappropriate. You are expected to understand and to be able to defend
+everything you submit. If you are unable to do so, then do not submit
+the resulting changes.
+
+If you do so anyway, maintainers are entitled to reject your series
+without detailed review.
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index aa12f2660194..e1a8a31389f5 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -68,6 +68,7 @@ beyond).
stable-kernel-rules
management-style
researcher-guidelines
+ generated-content
Dealing with bugs
-----------------
--
2.34.1
^ permalink raw reply related
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Nathan Chancellor @ 2026-01-19 21:35 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm
In-Reply-To: <cover.1767199119.git.gtucker@gtucker.io>
Hi Guillaume,
On Wed, Dec 31, 2025 at 05:51:48PM +0100, Guillaume Tucker wrote:
> This proposal emerged from discussions over email and after a talk at
> Plumbers 2024:
>
> https://lore.kernel.org/all/affb7aff-dc9b-4263-bbd4-a7965c19ac4e@gtucker.io/
>
> The aim is to facilitate reproducing builds for CI bots as well as
> developers using containers. Here's an illustrative example with a
> kernel.org toolchain in a Docker image from tuxmake:
>
> $ scripts/container -i tuxmake/korg-clang-21 make LLVM=1 defconfig
> HOSTCC scripts/basic/fixdep
> HOSTCC scripts/kconfig/conf.o
> [...]
> HOSTCC scripts/kconfig/util.o
> HOSTLD scripts/kconfig/conf
> *** Default configuration is based on 'x86_64_defconfig'
> #
> # configuration written to .config
> #
>
> This patch series also includes a documentation page with all the
> relevant details and further examples about how to use the tool.
>
> To go one step further, I'm in the process of preparing reference
> container images with kernel.org toolchains and no third-party
> dependencies other than the base Debian distro. See this thread for
> more details and options to host them in an upstream way:
>
> https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/
>
> Say, to run KUnit using the latest kernel.org GCC toolchain:
>
> scripts/container --shell \
> -i registry.gitlab.com/gtucker/korg-containers/gcc:kunit -- \
> tools/testing/kunit/kunit.py \
> run \
> --arch=x86_64 \
> --cross_compile=x86_64-linux-
I went over the script and the documentation and it looks pretty good to
me at this point. My only comment would be potentially referencing the
TuxMake container images in the example section to give folks a
"prebuilt" container option while getting the kernel.org container
images sorted out but that can always be done in a follow-up change.
I will apply this to kbuild-next-unstable shortly to give folks a week
or so to voice any objections or give critical review comments.
Cheers,
Nathan
^ permalink raw reply
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Nathan Chancellor @ 2026-01-19 21:49 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm, Nicolas Schier
In-Reply-To: <20260119213516.GA1051134@ax162>
On Mon, Jan 19, 2026 at 02:35:16PM -0700, Nathan Chancellor wrote:
> I will apply this to kbuild-next-unstable shortly to give folks a week
> or so to voice any objections or give critical review comments.
During application, checkpatch.pl pointed out that this should have a
MAINTAINERS entry. Would you be opposed to the following?
CONTAINER BUILD SCRIPT
M: Guillaume Tucker <gtucker@gtucker.io>
S: Maintained
F: Documentation/dev-tools/container.rst
F: scripts/container
I will also add scripts/container to the kbuild entry. Now that I am
looking, it looks like Nicolas has been left out of this whole thread,
cc'ing him now (even though I assume he should have seen this through
linux-kbuild but just in case not, the top of the thread is
https://lore.kernel.org/cover.1767199119.git.gtucker@gtucker.io/).
Cheers,
Nathan
^ permalink raw reply
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Guillaume Tucker @ 2026-01-20 9:46 UTC (permalink / raw)
To: Nathan Chancellor
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm
In-Reply-To: <20260119213516.GA1051134@ax162>
Hi Nathan,
On 19/01/2026 22:35, Nathan Chancellor wrote:
> I went over the script and the documentation and it looks pretty good to
> me at this point. My only comment would be potentially referencing the
> TuxMake container images in the example section to give folks a
> "prebuilt" container option while getting the kernel.org container
> images sorted out but that can always be done in a follow-up change.
Well the tuxmake LLVM image is mentioned in the first example:
scripts/container -i tuxmake/korg-clang -- make LLVM=1 defconfig
scripts/container -i tuxmake/korg-clang -- make LLVM=1 -j$(nproc)
So that should just work out of the box. Or did you mean to add
something else to the docs?
But yes, the topic of available container images will be something to
expand upon once the tool starts getting used. If things go well
with this initial version then we can try and move forward with
hosting first-party images as per the other discussion thread:
https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/
> I will apply this to kbuild-next-unstable shortly to give folks a week
> or so to voice any objections or give critical review comments.
Sounds great, thanks! I'll spread the word too once it's available
in linux-next.
Cheers,
Guillaume
^ permalink raw reply
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Guillaume Tucker @ 2026-01-20 9:56 UTC (permalink / raw)
To: Nathan Chancellor
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm, Nicolas Schier
In-Reply-To: <20260119214931.GA1058062@ax162>
On 19/01/2026 22:49, Nathan Chancellor wrote:
> On Mon, Jan 19, 2026 at 02:35:16PM -0700, Nathan Chancellor wrote:
>> I will apply this to kbuild-next-unstable shortly to give folks a week
>> or so to voice any objections or give critical review comments.
>
> During application, checkpatch.pl pointed out that this should have a
> MAINTAINERS entry. Would you be opposed to the following?
Not at all, on the contrary I have some dedicated time and long-term
interest to keep maintaining this. Please feel free to add me or I
can send an extra patch if you'd rather I did it.
> CONTAINER BUILD SCRIPT
> M: Guillaume Tucker <gtucker@gtucker.io>
> S: Maintained
> F: Documentation/dev-tools/container.rst
> F: scripts/container
>
> I will also add scripts/container to the kbuild entry. Now that I am
> looking, it looks like Nicolas has been left out of this whole thread,
> cc'ing him now (even though I assume he should have seen this through
> linux-kbuild but just in case not, the top of the thread is
> https://lore.kernel.org/cover.1767199119.git.gtucker@gtucker.io/).
OK sounds good. And sorry, get_maintainer.pl didn't mention Nicolas.
I should have checked the KERNEL BUILD entry by hand in the file...
Cheers,
Guillaume
^ permalink raw reply
* Re: [cocci] [PATCH RESEND 0/3] scripts: coccicheck: document debug log handling
From: Julia Lawall @ 2026-01-20 12:32 UTC (permalink / raw)
To: Benjamin Philip
Cc: Julia Lawall, Nicolas Palix, Jonathan Corbet, cocci, workflows,
linux-doc, linux-kernel
In-Reply-To: <20260106190836.36630-1-benjamin.philip495@gmail.com>
On Wed, 7 Jan 2026, Benjamin Philip wrote:
> Currently coccicheck prints debug logs to stdout unless a debug file has been
> set. This makes it hard to read coccinelle's suggested changes, especially for
> someone new to coccicheck.
>
> This patchset documents this behaviour in both the coccicheck script as well as
> in the dev-tools documentation. Additionally, it simplifies some of the logic
> for handling debug files.
>
> Benjamin Philip (3):
> scripts: coccicheck: simplify debug file handling
> scripts: coccicheck: warn on unset debug file
> Documentation: Coccinelle: document debug log handling
>
> Documentation/dev-tools/coccinelle.rst | 21 ++++++++++++++++-----
> scripts/coccicheck | 21 +++++++++++++--------
> 2 files changed, 29 insertions(+), 13 deletions(-)
Thanks for the update. I will try to get this in for the next release.
julia
^ permalink raw reply
* Re: [PATCH v3 2/2] Documentation: dev-tools: add container.rst page
From: Nicolas Schier @ 2026-01-20 13:53 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Nathan Chancellor, Miguel Ojeda, David Gow, Onur Özkan,
Arnd Bergmann, linux-kernel, rust-for-linux, linux-kbuild,
automated-testing, workflows, llvm
In-Reply-To: <c859f9b6dd5313136f7a445497d6209405eafa7e.1767199119.git.gtucker@gtucker.io>
On Wed, Dec 31, 2025 at 05:51:50PM +0100, Guillaume Tucker wrote:
> Add a dev-tools/container.rst documentation page for the
> scripts/container tool. This covers the basic usage with additional
> information about environment variables and user IDs. It also
> includes a number of practical examples with a reference to the
> experimental kernel.org toolchain images.
>
> Cc: Nathan Chancellor <nathan@kernel.org>
> Cc: Miguel Ojeda <ojeda@kernel.org>
> Cc: David Gow <davidgow@google.com>
> Cc: "Onur Özkan" <work@onurozkan.dev>
> Signed-off-by: Guillaume Tucker <gtucker@gtucker.io>
> ---
> Documentation/dev-tools/container.rst | 201 ++++++++++++++++++++++++++
> Documentation/dev-tools/index.rst | 1 +
> 2 files changed, 202 insertions(+)
> create mode 100644 Documentation/dev-tools/container.rst
>
> diff --git a/Documentation/dev-tools/container.rst b/Documentation/dev-tools/container.rst
> new file mode 100644
> index 000000000000..f6f134ec09f5
> --- /dev/null
> +++ b/Documentation/dev-tools/container.rst
> @@ -0,0 +1,201 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +.. Copyright (C) 2025 Guillaume Tucker
> +
> +====================
> +Containerized Builds
> +====================
> +
> +The ``container`` tool can be used to run any command in the kernel source tree
> +from within a container. Doing so facilitates reproducing builds across
> +various platforms, for example when a test bot has reported an issue which
> +requires a specific version of a compiler or an external test suite. While
> +this can already be done by users who are familiar with containers, having a
> +dedicated tool in the kernel tree lowers the barrier to entry by solving common
> +problems once and for all (e.g. user id management). It also makes it easier
> +to share an exact command line leading to a particular result. The main use
> +case is likely to be kernel builds but virtually anything can be run: KUnit,
> +checkpatch etc. provided a suitable image is available.
> +
> +
> +Options
> +=======
> +
> +Command line syntax::
> +
> + scripts/container -i IMAGE [OPTION]... CMD...
> +
> +Available options:
> +
> +``-e, --env-file ENV_FILE``
> +
> + Path to an environment file to load in the container.
> +
> +``-g, --gid GID``
> +
> + Group id to use inside the container.
> +
> +``-i, --image IMAGE``
> +
> + Container image name (required).
> +
> +``-r, --runtime RUNTIME``
> +
> + Container runtime name. Supported runtimes: ``docker``, ``podman``.
> +
> + If not specified, the first one found on the system will be used
> + i.e. Docker if present, otherwise Podman.
> +
> +``-s, --shell``
> +
> + Run the container in an interactive shell.
> +
> +``-u, --uid UID``
> +
> + User id to use inside the container.
> +
> + If the ``-g`` option is not specified, the user id will also be used for
> + the group id.
> +
> +``-v, --verbose``
> +
> + Enable verbose output.
> +
> +``-h, --help``
> +
> + Show the help message and exit.
> +
> +
> +Usage
> +=====
> +
> +It's entirely up to the user to choose which image to use and the ``CMD``
> +arguments are passed directly as an arbitrary command line to run in the
> +container. The tool will take care of mounting the source tree as the current
> +working directory and adjust the user and group id as needed.
> +
> +The container image which would typically include a compiler toolchain is
> +provided by the user and selected via the ``-i`` option. The container runtime
> +can be selected with the ``-r`` option, which can be either ``docker`` or
> +``podman``. If none is specified, the first one found on the system will be
> +used. Support for other runtimes may be added later depending on their
> +popularity among users.
> +
> +By default, commands are run non-interactively. The user can abort a running
> +container with SIGINT (Ctrl-C). To run commands interactively with a TTY, the
> +``--shell`` or ``-s`` option can be used. Signals will then be received by the
> +shell directly rather than the parent ``container`` process. To exit an
> +interactive shell, use Ctrl-D or ``exit``.
> +
> +.. note::
> +
> + The only host requirement aside from a container runtime is Python 3.10 or
> + later.
> +
> +
> +Environment Variables
> +=====================
> +
> +Environment variables are not propagated to the container so they have to be
> +either defined in the image itself or via the ``-e`` option using an
> +environment file. In some cases it makes more sense to have them defined in
> +the Containerfile used to create the image. For example, a Clang-only compiler
> +toolchain image may have ``LLVM=1`` defined.
> +
> +The local environment file is more useful for user-specific variables added
> +during development. It is passed as-is to the container runtime so its format
> +may vary. Typically, it will look like the output of ``env``. For example::
> +
> + INSTALL_MOD_STRIP=1
> + SOME_RANDOM_TEXT=One upon a time
> +
> +Please also note that ``make`` options can still be passed on the command line,
> +so while this can't be done since the first argument needs to be the
> +executable::
> +
> + scripts/container -i tuxmake/korg-clang LLVM=1 make
> +
> +this will work::
> +
> + scripts/container -i tuxmake/korg-clang make LLVM=1
First of all: Thanks for all that work!
I probably have just read it over: I have to prefix the
'tuxmake/korg-clang' by 'docker.io/'. Is that a problem of my system
configuration (Debian forky, no special podman config)?
> +
> +
> +User IDs
> +========
> +
> +This is an area where the behaviour will vary slightly depending on the
> +container runtime. The goal is to run commands as the user invoking the tool.
> +With Podman, a namespace is created to map the current user id to a different
> +one in the container (1000 by default). With Docker, while this is also
> +possible with recent versions it requires a special feature to be enabled in
> +the daemon so it's not used here for simplicity. Instead, the container is run
> +with the current user id directly. In both cases, this will provide the same
> +file permissions for the kernel source tree mounted as a volume. The only
> +difference is that when using Docker without a namespace, the user id may not
> +be the same as the default one set in the image.
> +
> +Say, we're using an image which sets up a default user with id 1000 and the
> +current user calling the ``container`` tool has id 1234. The kernel source
> +tree was checked out by this same user so the files belong to user 1234. With
> +Podman, the container will be running as user id 1000 with a mapping to id 1234
> +so that the files from the mounted volume appear to belong to id 1000 inside
> +the container. With Docker and no namespace, the container will be running
> +with user id 1234 which can access the files in the volume but not in the user
> +1000 home directory. This shouldn't be an issue when running commands only in
> +the kernel tree but it is worth highlighting here as it might matter for
> +special corner cases.
I tested a tiny bit with podman as runtime backend. If I leave out the
'-r podman' podman's docker emulation is in effect and fails with:
$ scripts/container -i docker.io/tuxmake/korg-clang -- make LLVM=1 -j8 olddefconfig
Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg.
mkdir: cannot create directory '.tmp_15': Permission denied
mkdir: cannot create directory '.tmp_19': Permission denied
mkdir: cannot create directory '.tmp_22': Permission denied
mkdir: cannot create directory '.tmp_25': Permission denied
mkdir: cannot create directory '.tmp_28': Permission denied
mkdir: cannot create directory '.tmp_31': Permission denied
HOSTCC scripts/basic/fixdep
error: error opening 'scripts/basic/.fixdep.d': Permission denied
1 error generated.
make[2]: *** [scripts/Makefile.host:114: scripts/basic/fixdep] Error 1
make[1]: *** [/src/Makefile:655: scripts_basic] Error 2
make: *** [Makefile:248: __sub-make] Error 2
[exit code 2]
But with '-r podman' it works like a charm.
Would it make sense to switch the default runtime to podman to
prevent non-functional podman-docker emulation? (Or is this just a
problem on my machine?)
--
Nicolas
^ permalink raw reply
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Nicolas Schier @ 2026-01-20 13:54 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Nathan Chancellor, Miguel Ojeda, David Gow, Onur Özkan,
Arnd Bergmann, linux-kernel, rust-for-linux, linux-kbuild,
automated-testing, workflows, llvm
In-Reply-To: <cover.1767199119.git.gtucker@gtucker.io>
On Wed, Dec 31, 2025 at 05:51:48PM +0100, Guillaume Tucker wrote:
> This proposal emerged from discussions over email and after a talk at
> Plumbers 2024:
>
> https://lore.kernel.org/all/affb7aff-dc9b-4263-bbd4-a7965c19ac4e@gtucker.io/
>
> The aim is to facilitate reproducing builds for CI bots as well as
> developers using containers. Here's an illustrative example with a
> kernel.org toolchain in a Docker image from tuxmake:
>
> $ scripts/container -i tuxmake/korg-clang-21 make LLVM=1 defconfig
> HOSTCC scripts/basic/fixdep
> HOSTCC scripts/kconfig/conf.o
> [...]
> HOSTCC scripts/kconfig/util.o
> HOSTLD scripts/kconfig/conf
> *** Default configuration is based on 'x86_64_defconfig'
> #
> # configuration written to .config
> #
>
> This patch series also includes a documentation page with all the
> relevant details and further examples about how to use the tool.
>
> To go one step further, I'm in the process of preparing reference
> container images with kernel.org toolchains and no third-party
> dependencies other than the base Debian distro. See this thread for
> more details and options to host them in an upstream way:
>
> https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/
>
> Say, to run KUnit using the latest kernel.org GCC toolchain:
>
> scripts/container --shell \
> -i registry.gitlab.com/gtucker/korg-containers/gcc:kunit -- \
> tools/testing/kunit/kunit.py \
> run \
> --arch=x86_64 \
> --cross_compile=x86_64-linux-
>
> ---
> Changes in v3:
> - Refactor common code for Docker and Podman
> - Add docs.kernel.org URL in help message
> - Use pathlib Python package
> - Handle signals in parent process by default
> - Add --shell option to use an interactive shell
> - Tweak debug messages in verbose mode
> - Specify Python 3.10 as minimum version in the docs
> - Provide an example env file in the docs
> - Update docs regarding interactive shell usage
>
> Changes in v2:
> - Drop default image but make -i option required
> - Look for Docker and Podman if no runtime specified
> - Catch SIGINT from user to abort container with Docker
> - Explicitly name each container with a UUID
> - Update documentation accordingly
>
> ---
>
> Guillaume Tucker (2):
> scripts: add tool to run containerized builds
> Documentation: dev-tools: add container.rst page
>
> Documentation/dev-tools/container.rst | 201 ++++++++++++++++++++++++++
> Documentation/dev-tools/index.rst | 1 +
> scripts/container | 199 +++++++++++++++++++++++++
> 3 files changed, 401 insertions(+)
> create mode 100644 Documentation/dev-tools/container.rst
> create mode 100755 scripts/container
>
> --
> 2.47.3
>
>
Out-of-source builds do not work on my system with podman. If this is
expected, I think it would be great to mention that somewhere in the
documentation.
Nevertheless, thanks a lot! I expect me to use that a lot in the
future!
For the whole patch set:
Tested-by: Nicolas Schier <nsc@kernel.org>
Acked-by: Nicolas Schier <nsc@kernel.org>
Kind regards,
Nicolas
--
Nicolas
^ permalink raw reply
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Nathan Chancellor @ 2026-01-20 17:55 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm
In-Reply-To: <4d4ec41f-1203-4cef-8f49-402440f3e983@gtucker.io>
On Tue, Jan 20, 2026 at 10:46:15AM +0100, Guillaume Tucker wrote:
> Well the tuxmake LLVM image is mentioned in the first example:
>
> scripts/container -i tuxmake/korg-clang -- make LLVM=1 defconfig
> scripts/container -i tuxmake/korg-clang -- make LLVM=1 -j$(nproc)
>
> So that should just work out of the box. Or did you mean to add
> something else to the docs?
I was just envisioning a blurb like "Additionally, TuxMake has prebuilt
containers for various architectures: https://hub.docker.com/u/tuxmake"
or something like that at the end of the paragraph before "To build just
``bzImage`` using Clang::" in the documentation.
> But yes, the topic of available container images will be something to
> expand upon once the tool starts getting used. If things go well
> with this initial version then we can try and move forward with
> hosting first-party images as per the other discussion thread:
>
> https://lore.kernel.org/all/cc737636-2a43-4a97-975e-4725733f7ee4@gtucker.io/
Yeah hopefully usage of this tool will spur some movement on that
discussion thread.
Cheers,
Nathan
^ permalink raw reply
* Re: [PATCH v3 0/2] scripts: introduce containerized builds
From: Nathan Chancellor @ 2026-01-20 17:58 UTC (permalink / raw)
To: Guillaume Tucker
Cc: Miguel Ojeda, David Gow, Onur Özkan, Arnd Bergmann,
linux-kernel, rust-for-linux, linux-kbuild, automated-testing,
workflows, llvm, Nicolas Schier
In-Reply-To: <1766d2ae-1224-4d3e-bc9f-786702989a79@gtucker.io>
On Tue, Jan 20, 2026 at 10:56:46AM +0100, Guillaume Tucker wrote:
> Not at all, on the contrary I have some dedicated time and long-term
> interest to keep maintaining this. Please feel free to add me or I
> can send an extra patch if you'd rather I did it.
I can fold that into the two changes in a natural way.
> OK sounds good. And sorry, get_maintainer.pl didn't mention Nicolas.
> I should have checked the KERNEL BUILD entry by hand in the file...
No worries, I am sure there are quite a few scripts that we technically
own but do not have an entry for it in MAINTAINERS. This won't be a
problem going forward at least :)
^ 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