Jonathan Corbet [Tue, 18 Nov 2025 16:26:11 +0000 (09:26 -0700)]
Merge branch 'python-modules' into docs-mw
scripts/lib was always a bit of an awkward place for Python libraries; give
them a proper home under tools/lib/python. Put the modules from
tools/docs/lib there for good measure.
The second patch ties them into a single package namespace. It would be
more aesthetically pleasing to add a kernel layer, so we could say:
from kernel.kdoc import kdoc_parser
...and have the kernel-specific stuff clearly marked, but that means adding
an empty directory in the hierarchy, which isn't as pleasing.
There are some other "Python library" directories hidden in the kernel
tree; we may eventually want to encourage them to move as well.
Jonathan Corbet [Mon, 10 Nov 2025 22:04:30 +0000 (15:04 -0700)]
docs: bring some order to our Python module hierarchy
Now that we have tools/lib/python for our Python modules, turn them into
proper packages with a single namespace so that everything can just use
tools/lib/python in sys.path. No functional change.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251110220430.726665-3-corbet@lwn.net>
Jonathan Corbet [Mon, 10 Nov 2025 22:04:29 +0000 (15:04 -0700)]
docs: Move the python libraries to tools/lib/python
"scripts/lib" was always a bit of an awkward place for Python modules. We
already have tools/lib; create a tools/lib/python, move the libraries
there, and update the users accordingly.
While at it, move the contents of tools/docs/lib. Rather than make another
directory, just put these documentation-oriented modules under "kdoc".
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251110220430.726665-2-corbet@lwn.net>
Since the beginning, SPHINXDIRS was meant to be used by any
subdirectory inside Documentation/ that contains a file named
index.rst on it. The typical usecase for SPHINXDIRS is help
building subsystem-specific documentation, without needing to
wait for the entire building (with can take 3 minutes with
Sphinx 8.x and above, and a lot more with older versions).
Yet, the documentation for such feature was written back in
2016, where almost all index.rst files were at the first
level (Documentation/*/index.rst).
Update the documentation to reflect the way it works.
scripts: docs: kdoc_files.py: don't consider symlinks as directories
As reported by Randy, currently kdoc_files can go into endless
looks when symlinks are used:
$ ln -s . Documentation/peci/foo
$ ./scripts/kernel-doc Documentation/peci/
...
File "/new_devel/docs/scripts/lib/kdoc/kdoc_files.py", line 52, in _parse_dir
if entry.is_dir():
~~~~~~~~~~~~^^
OSError: [Errno 40] Too many levels of symbolic links: 'Documentation/peci/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo'
Prevent that by not considering symlinks as directories.
Reported-by: Randy Dunlap <rdunlap@infradead.org> Closes: https://lore.kernel.org/linux-doc/80701524-09fd-4d68-8715-331f47c969f2@infradead.org/ Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <73c3450f34e2a4b42ef2ef279d7487c47d22e3bd.1763027622.git.mchehab+huawei@kernel.org>
C macro references are erroneously written using :c:macro:: (note the
double colon). This causes the references to be outputted as combination
of verbatim roles and italicized names instead.
Correct the syntax.
Fixes: dce548889650c1 ("Documentation: Add TI TPS6594 PFSM") Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251104041812.31402-4-bagasdotme@gmail.com>
C macro references are erroneously written using :c:macro:: (note the
double colon). This causes the references to be outputted as combination
of verbatim roles and italicized names instead.
Correct the syntax.
Fixes: 5f67eef6dff394 ("misc: mrvl-cn10k-dpi: add Octeon CN10K DPI administrative driver") Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251104041812.31402-3-bagasdotme@gmail.com>
Bagas Sanjaya [Tue, 4 Nov 2025 13:07:50 +0000 (20:07 +0700)]
Documentation: taskstats: Reindent payload kinds list
Payload kinds list text is indented at the first text column, rather
than aligned to the list number. As an effect, the third item becomes
sublist of second item's third sublist item (TASKTYPE_TYPE_STATS).
Reindent the list text.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251104130751.22755-1-bagasdotme@gmail.com>
Gou Hao [Wed, 5 Nov 2025 01:35:06 +0000 (09:35 +0800)]
xfs-doc: Fix typo error
Online fsck may take longer than offline fsck...
Signed-off-by: Gou Hao <gouhao@uniontech.com> Reviewed-by: Christoph Hellwig <hch@lst.de> Reviewed-by: Darrick J. Wong <djwong@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251105013506.358-1-gouhao@uniontech.com>
Bagas Sanjaya [Wed, 5 Nov 2025 12:49:47 +0000 (19:49 +0700)]
Documentation: parport-lowlevel: Separate function listing code blocks
Commit be9d0411f1608a ("parport-lowlevel.txt: standardize document
format") reSTify parport interface documentation but forgets to properly
mark function listing code blocks up. As such, these are rendered as
long-running normal paragraph instead.
Fix them by adding missing separator between the code block marker and
the listing.
Fixes: be9d0411f1608a ("parport-lowlevel.txt: standardize document format") Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251105124947.45048-1-bagasdotme@gmail.com>
pierwill [Sun, 9 Nov 2025 02:34:21 +0000 (02:34 +0000)]
docs: Fix missing word in spectre.rst
Corrects a missing word in the hardware vulnerability docs.
Signed-off-by: Will Pierce <pierwill@protonmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <Ru-d3ltJIyY4Oc6tzHwpSiDeFwSLHEzd7Utcr6iobgIy1B8wLRI4f6JiCb0a9n-0-r19d0dyLL3yS8KWVcyHfpkyDErWXYTkI3AJfUPTNCc=@protonmail.com>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Petr Pavlu <petr.pavlu@suse.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251102060458.517911-1-rdunlap@infradead.org>
Randy Dunlap [Tue, 4 Nov 2025 05:09:30 +0000 (21:09 -0800)]
doc-guide: kernel-doc: add %CONST examples
Add examples of using '%' for formatting constant values to
facilitate more usage of "%CONST" in kernel-doc.
Suggested-by: Tony Luck <tony.luck@intel.com> Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251104050930.720711-1-rdunlap@infradead.org>
docs: Makefile: Sort Documentation targets case-insensitively in make help
Avoid case-sensitive sorting when listing Documentation targets in make help.
Previously, targets like PCI and RCU appeared ahead of others due to uppercase
names.
Normalize casing during _SPHINXDIRS generation to ensure consistent and
intuitive ordering.
Fixes: 965fc39f7393 ("Documentation: sort _SPHINXDIRS for 'make help'") Tested-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Bhanu Seshu Kumar Valluri <bhanuseshukumar@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251104061723.16629-1-bhanuseshukumar@gmail.com>
Tomas Glozar [Fri, 10 Oct 2025 08:33:38 +0000 (10:33 +0200)]
Documentation/rtla: Include defaults for tracer options
Commit 0122938a7ab4 ("rtla: Always set all tracer options") changed the
behavior of RTLA to always set all osnoise and timerlat tracer options
to default values taken from the tracers whenever an RTLA measurement
is started. The change was done to make RTLA results consistent on
subsequent runs of the same command.
Include the default values for tracer options also in documentation
where appropriate.
Signed-off-by: Tomas Glozar <tglozar@redhat.com> Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251010083338.478961-10-tglozar@redhat.com>
Tomas Glozar [Fri, 10 Oct 2025 08:33:37 +0000 (10:33 +0200)]
Documentation/trace: Specify exact priority for timerlat
The timerlat tracer documentation mentions that threads are created with
real-time priority, but does not mention which priority and scheduling
class is used.
Add the information so that users do not have to look it up in
trace_osnoise.c.
Signed-off-by: Tomas Glozar <tglozar@redhat.com> Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251010083338.478961-9-tglozar@redhat.com>
Tomas Glozar [Fri, 10 Oct 2025 08:33:36 +0000 (10:33 +0200)]
Documentation/rtla: Mention default cgroup state
The RTLA option -C/--cgroup is used to set a cgroup for workload
threads. This is either a specific cgroup, if passed an argument, or
rtla's cgroup, if no argument is given.
Expand the documentation of the -C option to also include the
information about the cgroup settings when the option is not specified.
Signed-off-by: Tomas Glozar <tglozar@redhat.com> Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251010083338.478961-8-tglozar@redhat.com>
Tomas Glozar [Fri, 10 Oct 2025 08:33:35 +0000 (10:33 +0200)]
Documentation/rtla: Mention default priority
RTLA allows the priority of workload threads to be set using the -P
option. This is covered in docs, but the default state for RTLA's own
user workload (implemented in timerlat_u.c) is not mentioned.
Add mention of the default user workload priority as well as a reference
to osnoise and timerlat tracers for kernel workload priority.
Signed-off-by: Tomas Glozar <tglozar@redhat.com> Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251010083338.478961-7-tglozar@redhat.com>
Andy Shevchenko [Tue, 4 Nov 2025 21:55:02 +0000 (22:55 +0100)]
kernel-doc: Issue warnings that were silently discarded
When kernel-doc parses the sections for the documentation some errors
may occur. In many cases the warning is simply stored to the current
"entry" object. However, in the most of such cases this object gets
discarded and there is no way for the output engine to even know about
that. To avoid that, check if the "entry" is going to be discarded and
if there warnings have been collected, issue them to the current logger
as is and then flush the "entry". This fixes the problem that original
Perl implementation doesn't have.
As of Linux kernel v6.18-rc4 the reproducer can be:
$ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
...
Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
...
while with the proposed change applied it gives one more line:
$ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h
...
Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr
Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
...
And with the original Perl script:
$ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h
...
include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr
include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead
...
Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin") Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251104215502.1049817-1-andriy.shevchenko@linux.intel.com>
Lukas Bulwahn [Mon, 3 Nov 2025 07:59:48 +0000 (08:59 +0100)]
MAINTAINERS: extend DOCUMENTATION SCRIPTS to the full directories
Due to commit abd61d1ff8f0 ("scripts: sphinx-pre-install: move it to
tools/docs"), checkpatch.pl --self-test=patterns reported a non-matching
file entry in DOCUMENTATION SCRIPTS. Clearly, there are now multiple
documentation scripts, all located in Documentation/sphinx/ and tools/docs/
and Mauro is the maintainer of those.
Update the DOCUMENTATION SCRIPTS section to cover these directories. While
at it, also make the DOCUMENTATION section cover the subdirectories of
tools/docs/.
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251103075948.26026-1-lukas.bulwahn@redhat.com>
Jonathan Corbet [Mon, 3 Nov 2025 23:25:22 +0000 (16:25 -0700)]
Merge branch 'tools-final2' into docs-mw
Our documentation-related tools are spread out over various directories;
several are buried in the scripts/ dumping ground. That makes them harder
to discover and harder to maintain.
Recent work has started accumulating our documentation-related tools in
/tools/docs. This series nearly completes that task, moving most of the
rest of our various utilities there, hopefully fixing up all of the
relevant references in the process.
The one exception is scripts/kernel-doc; that move turned up some other
problems, so I have dropped it until those are ironed out.
At the end, rather than move the old, Perl kernel-doc, I simply removed it.
Bagas Sanjaya [Fri, 31 Oct 2025 04:33:56 +0000 (11:33 +0700)]
Documentation: treewide: Replace marc.info links with lore
In the past, people would link to third-party mailing list archives
(like marc.info) for any kernel-related discussions. Now that there
is lore archive under kernel.org infrastructure, replace these marc
links
Note that the only remaining marc link is "Re: Memory mapping on Cirrus
EP9315" [1] since that thread is not available at lore [2].
Jonathan Corbet [Mon, 3 Nov 2025 23:12:37 +0000 (16:12 -0700)]
Merge tag 'Chinese-docs-6.18' of gitolite.kernel.org:pub/scm/linux/kernel/git/alexs/linux into alex
Chinese translation docs for 6.18
This is the Chinese translation subtree for 6.18. It includes
the following changes:
- docs/zh_CN: Add rust Chinese translations
- docs/zh_CN: Add scsi Chinese translations
- docs/zh_CN: Add gfs2 Chinese translations
- Add some other Chinese translations and fixes
Alex Shi [Sun, 26 Oct 2025 13:29:35 +0000 (21:29 +0800)]
Revert "Docs/zh_CN: Translate skbuff.rst to Simplified Chinese"
This reverts commit d3e7609c6e5ec92587ed1043a985749d22cc78d1.
The commit cause a warning:
Documentation/networking/skbuff.rst:34: WARNING: duplicate label crc, other instance in Documentation/translations/zh_CN/networking/skbuff.rst
And there's no simple way to keep the meaningful doc context and avoid the
warning, so, let's remove the doc.
Jacob Keller [Thu, 30 Oct 2025 19:58:32 +0000 (12:58 -0700)]
docs: kdoc: fix duplicate section warning message
The python version of the kernel-doc parser emits some strange warnings
with just a line number in certain cases:
$ ./scripts/kernel-doc -Wall -none 'include/linux/virtio_config.h'
Warning: 174
Warning: 184
Warning: 190
Warning: include/linux/virtio_config.h:226 No description found for return value of '__virtio_test_bit'
Warning: include/linux/virtio_config.h:259 No description found for return value of 'virtio_has_feature'
Warning: include/linux/virtio_config.h:283 No description found for return value of 'virtio_has_dma_quirk'
Warning: include/linux/virtio_config.h:392 No description found for return value of 'virtqueue_set_affinity'
I eventually tracked this down to the lone call of emit_msg() in the
KernelEntry class, which looks like:
self.emit_msg(self.new_start_line, f"duplicate section name '{name}'\n")
This looks like all the other emit_msg calls. Unfortunately, the definition
within the KernelEntry class takes only a message parameter and not a line
number. The intended message is passed as the warning!
Pass the filename to the KernelEntry class, and use this to build the log
message in the same way as the KernelDoc class does.
To avoid future errors, mark the warning parameter for both emit_msg
definitions as a keyword-only argument. This will prevent accidentally
passing a string as the warning parameter in the future.
Also fix the call in dump_section to avoid an unnecessary additional
newline.
Fixes: e3b42e94cf10 ("scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class") Signed-off-by: Jacob Keller <jacob.e.keller@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251030-jk-fix-kernel-doc-duplicate-return-warning-v2-1-ec4b5c662881@intel.com>
Bagas Sanjaya [Wed, 22 Oct 2025 03:43:35 +0000 (10:43 +0700)]
Documentation: process: Also mention Sasha Levin as stable tree maintainer
Sasha has also maintaining stable branch in conjunction with Greg
since cb5d21946d2a2f ("MAINTAINERS: Add Sasha as a stable branch
maintainer"). Mention him in 2.Process.rst.
Cc: stable@vger.kernel.org Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251022034336.22839-1-bagasdotme@gmail.com>
Nadav Tasher [Sat, 25 Oct 2025 17:16:25 +0000 (20:16 +0300)]
docs: replace broken links in ramfs-rootfs-initramfs docs
http://www.uwsg.iu.edu/ doesn't seem to exist anymore.
I managed to find backups on archive.org, which helped me find
the right links on https://lore.kernel.org/.
http://freecode.com/projects/afio was also down, so I figured
it could be replaced with https://linux.die.net/man/1/afio.
Replace broken links to mailing list and aifo tool.
Signed-off-by: Nadav Tasher <tashernadav@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251025171625.33197-1-tashernadav@gmail.com>
Akira Yokosawa [Sun, 19 Oct 2025 14:24:51 +0000 (23:24 +0900)]
tools/docs/sphinx-build-wrapper: Emit $SPHINXOPTS later in args list
The option list to sphinx-build via SPHINXOPTS should have higher
priority than those the wrapper comes up with.
sphinx-build will choose the latest one if there are duplicates.
To restore the behavior of Makefile era, when the documentation builds
at https://www.kernel.org/doc/html/next/ had been depending on it,
reorder the flag list.
Jonathan Corbet [Wed, 13 Aug 2025 17:03:02 +0000 (11:03 -0600)]
docs: move checktransupdate.py to tools/docs
The checktranslate.py tool currently languishes in scripts/; move it to
tools/docs and update references accordingly.
Cc: Alex Shi <alexs@kernel.org> Cc: Yanteng Si <si.yanteng@linux.dev> Cc: Dongliang Mu <dzm91@hust.edu.cn> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Brian Norris [Fri, 17 Oct 2025 20:37:12 +0000 (13:37 -0700)]
docs: checkpatch: Drop networking comment style
Networking no longer has their own comment style, and checkpatch no
longer checks for this.
Signed-off-by: Brian Norris <briannorris@chromium.org> Suggested-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251017203719.1554224-2-briannorris@chromium.org>
Brian Norris [Fri, 17 Oct 2025 20:37:11 +0000 (13:37 -0700)]
docs: checkpatch: Align block comment style
Ironically, the block style comments in the checkpatch documentation are
not aligned properly. Correct that.
Signed-off-by: Brian Norris <briannorris@chromium.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251017203719.1554224-1-briannorris@chromium.org>
Ally Heev [Mon, 20 Oct 2025 10:46:30 +0000 (16:16 +0530)]
Documentation: fix dev-tools broken links in translations
gdb and kgdb debugging documentation were moved to
Documentation/process/debugging/ as a part of
Commit d5af79c05e9382d38b8546dc5362381ce07ba3d1 ("Documentation: move
dev-tools debugging files to process/debugging/"), but translations/
were not updated. Fix them
Signed-off-by: Ally Heev <allyheev@gmail.com> Fixes: d5af79c05e938 ("Documentation: move dev-tools debugging files to process/debugging/") Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251020-aheev-fix-docs-dev-tools-broken-links-v2-1-7db64bf0405a@gmail.com>
common_*.rst files are snippets that are intended to be included by rtla
docs (rtla*.rst). common_options.rst in particular contains
substitutions which depend on other common_* includes, so building it
independently as reST source results in above errors.
Rename all common_*.rst files to common_*.txt to prevent Sphinx from
building these snippets as standalone reST source and update all include
references accordingly.
Link: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions Suggested-by: Tomas Glozar <tglozar@redhat.com> Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Gopi Krishna Menon <krishnagopi487@gmail.com> Reviewed-by: Tomas Glozar <tglozar@redhat.com> Fixes: 05b7e10687c6 ("tools/rtla: Add remaining support for osnoise actions") Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Link: https://lore.kernel.org/r/20251008184522.13201-1-krishnagopi487@gmail.com
[Bagas: massage commit message and apply trailers] Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251013092719.30780-2-bagasdotme@gmail.com>
Bagas Sanjaya [Mon, 13 Oct 2025 09:56:30 +0000 (16:56 +0700)]
Documentation: assoc_array: Indent function explanation text
Paragraphs of function explanation are currently not indented following
their appropriate numbered list item, which causes only the first
paragraph and function prototype code blocks to be indented in the
numbered list in htmldocs output.
Indent the explanation.
Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251013095630.34235-3-bagasdotme@gmail.com>
Jonathan Corbet [Fri, 17 Oct 2025 20:11:30 +0000 (14:11 -0600)]
Merge branch 'build-script' into docs-mw
Quoth Mauro:
This series should probably be called:
"Move the trick-or-treat build hacks accumulated over time
into a single place and document them."
as this reflects its main goal. As such:
- it places the jobserver logic on a library;
- it removes sphinx/parallel-wrapper.sh;
- the code now properly implements a jobserver-aware logic
to do the parallelism when called via GNU make, failing back to
"-j" when there's no jobserver;
- converts check-variable-fonts.sh to Python and uses it via
function call;
- drops an extra script to generate man pages, adding a makefile
target for it;
- ensures that return code is 0 when PDF successfully builds;
- about half of the script is comments and documentation.
I tried to do my best to document all tricks that are inside the
script. This way, the docs build steps is now documented.
It should be noticed that it is out of the scope of this series
to change the implementation. Surely the process can be improved,
but first let's consolidate and document everything on a single
place.
Such script was written in a way that it can be called either
directly or via a Makefile. Running outside Makefile is
interesting specially when debug is needed. The command line
interface replaces the need of having lots of env vars before
calling sphinx-build:
positional arguments:
{cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs}
Documentation target to build
options:
-h, --help show this help message and exit
--sphinxdirs SPHINXDIRS [SPHINXDIRS ...]
Specific directories to build
--conf CONF Sphinx configuration file
--builddir BUILDDIR Sphinx configuration file
--theme THEME Sphinx theme to use
--css CSS Custom CSS file for HTML/EPUB
--paper {,a4,letter} Paper size for LaTeX/PDF output
-v, --verbose place build in verbose mode
-j, --jobs JOBS Sets number of jobs to use with sphinx-build
-i, --interactive Change latex default to run in interactive mode
-V, --venv [VENV] If used, run Sphinx from a venv dir (default dir: sphinx_latest)
the only mandatory argument is the target, which is identical with
"make" targets.
The call inside Makefile doesn't use the last four arguments. They're
there to help identifying problems at the build:
-v makes the output verbose;
-j helps to test parallelism;
-i runs latexmk in interactive mode, allowing to debug PDF
build issues;
-V is useful when testing it with different venvs.
When used with GNU make (or some other make which implements jobserver),
a call like:
make -j <targets> htmldocs
will make the wrapper to automatically use POSIX jobserver to claim
the number of available job slots, calling sphinx-build with a
"-j" parameter reflecting it. ON such case, the default can be
overriden via SPHINXDIRS argument.
Visiable changes when compared with the old behavior:
When V=0, the only visible difference is that:
- pdfdocs target now returns 0 on success, 1 on failures.
This addresses an issue over the current process where we
it always return success even on failures;
- it will now print the name of PDF files that failed to build,
if any.
In verbose mode, sphinx-build-wrapper and sphinx-build command lines
are now displayed.
Jonathan Corbet [Fri, 17 Oct 2025 20:07:08 +0000 (14:07 -0600)]
Merge branch 'media-uapi' into docs-mw
Mauro says:
In the past, media used Docbook to generate documentation, together
with some logic to ensure that cross-references would match the
actual defined uAPI.
The rationale is that we wanted to automatically check for uAPI
documentation gaps.
The same logic was migrated to Sphinx. Back then, broken links
were reported. However, recent versions of it and/or changes at
conf.py disabled such checks.
The result is that several symbols are now not cross-referenced,
and we don't get warnings anymore when something breaks.
This series consist on 2 parts:
Part 1: extra patches to parse_data_structs.py and kernel_include.py;
Part 2: media documentation fixes.
docs: cec: show broken xrefs and show TOC instead of cec.h content
Enable xref broken warnings. While here, change the output to
only show cross-references, as there's no need to show the entire cec.h
header at the docs.
docs: media: add missing c namespace to V4L headers
Media references belong to V4L namespace. Fix a lot of broken
links when including videodev2.h and probably fixing several
other broken cross-references between different files inside
media docs.
docs: kernel_include.py: use get_close_matches() to propose alternatives
Improve the suggestions algorithm by using get_close_matches() if
no suggestions with the same name are found. As we're now building
a dict, when the name is identical, but on a different domain,
the search is O(1), making it a lot faster.
The get_close_matches is also fast, as there is just one loop,
instead of 3.
This can be useful to detect typos on references, with could
be the base of a futuere extension that will handle ref unmatches
for the entire build, allowing someone to find typos and fix them.
As difflib and get_close_matches are there since the early
Python 3.x days, we don't need to handle any extra dependencies
to use it.
We're keeping the default values for the search, e.g. n=3, cutoff=0.6.
With that, we now have things like:
At the first example, it was not a typo, but a symbol that doesn't
seem to be properly documented. The second example points to
v4l2-queryctrl, which is a close match for the symbol.
docs: media: mediactl: use TOC instead of file contents
All we wanted were to have a way to link the comprehensive
documentation with the actual symbols parsed from the header
file, as this helps to identify any broken references.
Use the new :toc: flag for media controller and enable warnings.
Here, we need to adjust the exceptions file to setup the C
namespace accordingly.
docs: media: rc: use TOC instead of file contents for LIRC header
All we wanted were to have a way to link the comprehensive
documentation with the actual symbols parsed from the header
file, as this helps to identify any broken references.
Use the new :toc: flag for LIRC and enable warnings.
docs: media: dvb: enable warnings for most headers
Except for two exception rules and dmx.h, the other files
are already handling properly cross references.
Fix the two exception rules for frontend.h, as those are
false-positives:
include/uapi/linux/dvb/frontend.h:959: WARNING: can't link to: c:type:: FE_GET_PROPERTY
include/uapi/linux/dvb/frontend.h:933: WARNING: can't link to: c:func:: FE_SET_FRONTEND_TUNE_MODE
The dmx.h are actual issues that will require an extra
patch to fill gaps.
docs: media: dvb: use TOC instead of file contents at headers
All we wanted were to have a way to link the comprehensive
documentation with the actual symbols parsed from the header
file, as this helps to identify any broken references.
tools: docs: parse_data_structs.py: add namespace support
C domain supports a ".. c:namespace::" tag that allows setting a
symbol namespace. This is used within the kernel to avoid warnings
about duplicated symbols. This is specially important for syscalls,
as each subsystem may have their own documentation for them.
This is specially true for ioctl.
When such tag is used, all C domain symbols have c++ style,
e.g. they'll become "{namespace}.{reference}".
Allow specifying C namespace at the exception files, avoiding
the need of override rules for every symbol.
Specially when using c::namespace, it is not hard to break
a reference by forgetting to add a domain. Also, different
cases and using "-"/"_" the wrong way are typical cases that
people often gets wrong.
We might use a more complex logic here to also check for typos,
but let's keep it plain, simple.
This is enough to get thos exeptions from media controller:
.../include/uapi/linux/media.h:26: WARNING: Invalid xref: c:type:`media_device_info`. Possible alternatives:
c:type:`MC.media_device_info` (from mediactl/media-ioc-device-info)
.../include/uapi/linux/media.h:149: WARNING: Invalid xref: c:type:`media_entity_desc`. Possible alternatives:
c:type:`MC.media_entity_desc` (from mediactl/media-ioc-enum-entities)
.../include/uapi/linux/media.h:228: WARNING: Invalid xref: c:type:`media_link_desc`. Possible alternatives:
c:type:`MC.media_link_desc` (from mediactl/media-ioc-enum-links)
.../include/uapi/linux/media.h:235: WARNING: Invalid xref: c:type:`media_links_enum`. Possible alternatives:
c:type:`MC.media_links_enum` (from mediactl/media-ioc-enum-links)
.../include/uapi/linux/media.h:212: WARNING: Invalid xref: c:type:`media_pad_desc`. Possible alternatives:
c:type:`MC.media_pad_desc` (from mediactl/media-ioc-enum-links)
.../include/uapi/linux/media.h:298: WARNING: Invalid xref: c:type:`media_v2_entity`. Possible alternatives:
c:type:`MC.media_v2_entity` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:312: WARNING: Invalid xref: c:type:`media_v2_interface`. Possible alternatives:
c:type:`MC.media_v2_interface` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:307: WARNING: Invalid xref: c:type:`media_v2_intf_devnode`. Possible alternatives:
c:type:`MC.media_v2_intf_devnode` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:341: WARNING: Invalid xref: c:type:`media_v2_link`. Possible alternatives:
c:type:`MC.media_v2_link` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:333: WARNING: Invalid xref: c:type:`media_v2_pad`. Possible alternatives:
c:type:`MC.media_v2_pad` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:349: WARNING: Invalid xref: c:type:`media_v2_topology`. Possible alternatives:
c:type:`MC.media_v2_topology` (from mediactl/media-ioc-g-topology)
Documentation: process: Arbitrarily bump kernel major version number
The big picture section of 2.Process.rst currently hardcodes major
version number to 5 since fb0e0ffe7fc8e0 ("Documentation: bring process
docs up to date"). As it can get outdated when it is actually
incremented (the recent is 6 and will be 7 in the near future),
arbitrarily bump it to 9, giving a headroom for a decade.
Note that the version number examples are kept to illustrate the
numbering scheme.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
[jc: tweaked the initial 9.x mention slightly] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250922074219.26241-1-bagasdotme@gmail.com>
docs: ja_JP: SubmittingPatches: describe the 'Fixes:' tag
Sync the ja_JP translation with the following upstream commits:
commit 8401aa1f5997 ("Documentation/SubmittingPatches: describe the Fixes: tag")
commit 19c3fe285cba ("docs: Explicitly state that the 'Fixes:' tag shouldn't split lines")
commit 5b5bbb8cc51b ("docs: process: Add an example for creating a fixes tag")
commit 6356f18f09dc ("Align git commit ID abbreviation guidelines and checks")
The mix of plain text and reST markup for ``git bisect`` is intentional to
align with the eventual reST conversion.
Since the Handover Protocol was deprecated, the recommended approach is
to provide an initrd using a UEFI boot service with the
LINUX_EFI_INITRD_MEDIA_GUID device path. Documentation for the new
approach has been no more than an admonition with a link to an existing
implementation.
Provide a short explanation of this functionality, to ease future
implementations without having to reverse engineer existing ones.
[Bagas: Don't use :ref: link to EFI stub documentation and refer to
OVMF/edk2 implementation]
Linus Torvalds [Sun, 12 Oct 2025 20:27:56 +0000 (13:27 -0700)]
Merge tag 'i2c-for-6.18-rc1-hotfix' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux
Pull i2c fix from Wolfram Sang:
"One revert because of a regression in the I2C core which has sadly not
showed up during its time in -next"
* tag 'i2c-for-6.18-rc1-hotfix' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux:
Revert "i2c: boardinfo: Annotate code used in init phase only"
Linus Torvalds [Sun, 12 Oct 2025 15:45:52 +0000 (08:45 -0700)]
Merge tag 'irq_urgent_for_v6.18_rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
Pull irq fixes from Borislav Petkov:
- Skip interrupt ID 0 in sifive-plic during suspend/resume because
ID 0 is reserved and accessing reserved register space could result
in undefined behavior
- Fix a function's retval check in aspeed-scu-ic
* tag 'irq_urgent_for_v6.18_rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
irqchip/sifive-plic: Avoid interrupt ID 0 handling during suspend/resume
irqchip/aspeed-scu-ic: Fix an IS_ERR() vs NULL check
Linus Torvalds [Sat, 11 Oct 2025 23:06:04 +0000 (16:06 -0700)]
Merge tag 'trace-v6.18-3' of git://git.kernel.org/pub/scm/linux/kernel/git/trace/linux-trace
Pull tracing fixes from Steven Rostedt:
"The previous fix to trace_marker required updating trace_marker_raw as
well. The difference between trace_marker_raw from trace_marker is
that the raw version is for applications to write binary structures
directly into the ring buffer instead of writing ASCII strings. This
is for applications that will read the raw data from the ring buffer
and get the data structures directly. It's a bit quicker than using
the ASCII version.
Unfortunately, it appears that our test suite has several tests that
test writes to the trace_marker file, but lacks any tests to the
trace_marker_raw file (this needs to be remedied). Two issues came
about the update to the trace_marker_raw file that syzbot found:
- Fix tracing_mark_raw_write() to use per CPU buffer
The fix to use the per CPU buffer to copy from user space was
needed for both the trace_maker and trace_maker_raw file.
The fix for reading from user space into per CPU buffers properly
fixed the trace_marker write function, but the trace_marker_raw
file wasn't fixed properly. The user space data was correctly
written into the per CPU buffer, but the code that wrote into the
ring buffer still used the user space pointer and not the per CPU
buffer that had the user space data already written.
- Stop the fortify string warning from writing into trace_marker_raw
After converting the copy_from_user_nofault() into a memcpy(),
another issue appeared. As writes to the trace_marker_raw expects
binary data, the first entry is a 4 byte identifier. The entry
structure is defined as:
struct {
struct trace_entry ent;
int id;
char buf[];
};
The size of this structure is reserved on the ring buffer with:
size = sizeof(*entry) + cnt;
Then it is copied from the buffer into the ring buffer with:
memcpy(&entry->id, buf, cnt);
This use to be a copy_from_user_nofault(), but now converting it to
a memcpy() triggers the fortify-string code, and causes a warning.
The allocated space is actually more than what is copied, as the
cnt used also includes the entry->id portion. Allocating
sizeof(*entry) plus cnt is actually allocating 4 bytes more than
what is needed.
* tag 'trace-v6.18-3' of git://git.kernel.org/pub/scm/linux/kernel/git/trace/linux-trace:
tracing: Stop fortify-string from warning in tracing_mark_raw_write()
tracing: Fix tracing_mark_raw_write() to use buf and not ubuf
Linus Torvalds [Sat, 11 Oct 2025 22:47:12 +0000 (15:47 -0700)]
Merge tag 'kbuild-fixes-6.18-1' of git://git.kernel.org/pub/scm/linux/kernel/git/kbuild/linux
Pull Kbuild fixes from Nathan Chancellor:
- Fix UAPI types check in headers_check.pl
- Only enable -Werror for hostprogs with CONFIG_WERROR / W=e
- Ignore fsync() error when output of gen_init_cpio is a pipe
- Several little build fixes for recent modules.builtin.modinfo series
* tag 'kbuild-fixes-6.18-1' of git://git.kernel.org/pub/scm/linux/kernel/git/kbuild/linux:
kbuild: Use '--strip-unneeded-symbol' for removing module device table symbols
s390/vmlinux.lds.S: Move .vmlinux.info to end of allocatable sections
kbuild: Add '.rel.*' strip pattern for vmlinux
kbuild: Restore pattern to avoid stripping .rela.dyn from vmlinux
gen_init_cpio: Ignore fsync() returning EINVAL on pipes
scripts/Makefile.extrawarn: Respect CONFIG_WERROR / W=e for hostprogs
kbuild: uapi: Strip comments before size type check
Reported-by: Konrad Dybcio <konrad.dybcio@oss.qualcomm.com> Closes: https://lore.kernel.org/r/29ec0082-4dd4-4120-acd2-44b35b4b9487@oss.qualcomm.com Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Linus Torvalds [Sat, 11 Oct 2025 18:56:47 +0000 (11:56 -0700)]
Merge tag 'rtc-6.18' of git://git.kernel.org/pub/scm/linux/kernel/git/abelloni/linux
Pull RTC updates from Alexandre Belloni:
"This cycle, we have a new RTC driver, for the SpacemiT P1. The optee
driver gets alarm support. We also get a fix for a race condition that
was fairly rare unless while stress testing the alarms.
Subsystem:
- Fix race when setting alarm
- Ensure alarm irq is enabled when UIE is enabled
- remove unneeded 'fast_io' parameter in regmap_config
New driver:
- SpacemiT P1 RTC
Drivers:
- efi: Remove wakeup functionality
- optee: add alarms support
- s3c: Drop support for S3C2410
- zynqmp: Restore alarm functionality after kexec transition"
* tag 'rtc-6.18' of git://git.kernel.org/pub/scm/linux/kernel/git/abelloni/linux: (29 commits)
rtc: interface: Ensure alarm irq is enabled when UIE is enabled
rtc: tps6586x: Fix initial enable_irq/disable_irq balance
rtc: cpcap: Fix initial enable_irq/disable_irq balance
rtc: isl12022: Fix initial enable_irq/disable_irq balance
rtc: interface: Fix long-standing race when setting alarm
rtc: pcf2127: fix watchdog interrupt mask on pcf2131
rtc: zynqmp: Restore alarm functionality after kexec transition
rtc: amlogic-a4: Optimize global variables
rtc: sd2405al: Add I2C address.
rtc: Kconfig: move symbols to proper section
rtc: optee: make optee_rtc_pm_ops static
rtc: optee: Fix error code in optee_rtc_read_alarm()
rtc: optee: fix error code in probe()
dt-bindings: rtc: Convert apm,xgene-rtc to DT schema
rtc: spacemit: support the SpacemiT P1 RTC
rtc: optee: add alarm related rtc ops to optee rtc driver
rtc: optee: remove unnecessary memory operations
rtc: optee: fix memory leak on driver removal
rtc: x1205: Fix Xicor X1205 vendor prefix
dt-bindings: rtc: Fix Xicor X1205 vendor prefix
...
Linus Torvalds [Sat, 11 Oct 2025 18:49:00 +0000 (11:49 -0700)]
Merge tag 'scsi-misc' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi
Pull SCSI fixes from James Bottomley:
"Fixes only in drivers (ufs, mvsas, qla2xxx, target) that came in just
before or during the merge window.
The most important one is the qla2xxx which reverts a conversion to
fix flexible array member warnings, that went up in this merge window
but which turned out on further testing to be causing data corruption"
* tag 'scsi-misc' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi:
scsi: ufs: core: Include UTP error in INT_FATAL_ERRORS
scsi: ufs: sysfs: Make HID attributes visible
scsi: mvsas: Fix use-after-free bugs in mvs_work_queue
scsi: ufs: core: Fix PM QoS mutex initialization
scsi: ufs: core: Fix runtime suspend error deadlock
Revert "scsi: qla2xxx: Fix memcpy() field-spanning write issue"
scsi: target: target_core_configfs: Add length check to avoid buffer overflow
Linus Torvalds [Sat, 11 Oct 2025 18:19:16 +0000 (11:19 -0700)]
Merge tag 'x86_core_for_v6.18_rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
Pull more x86 updates from Borislav Petkov:
- Remove a bunch of asm implementing condition flags testing in KVM's
emulator in favor of int3_emulate_jcc() which is written in C
- Replace KVM fastops with C-based stubs which avoids problems with the
fastop infra related to latter not adhering to the C ABI due to their
special calling convention and, more importantly, bypassing compiler
control-flow integrity checking because they're written in asm
- Remove wrongly used static branches and other ugliness accumulated
over time in hyperv's hypercall implementation with a proper static
function call to the correct hypervisor call variant
- Add some fixes and modifications to allow running FRED-enabled
kernels in KVM even on non-FRED hardware
- Add kCFI improvements like validating indirect calls and prepare for
enabling kCFI with GCC. Add cmdline params documentation and other
code cleanups
- Use the single-byte 0xd6 insn as the official #UD single-byte
undefined opcode instruction as agreed upon by both x86 vendors
- Other smaller cleanups and touchups all over the place
* tag 'x86_core_for_v6.18_rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip: (24 commits)
x86,retpoline: Optimize patch_retpoline()
x86,ibt: Use UDB instead of 0xEA
x86/cfi: Remove __noinitretpoline and __noretpoline
x86/cfi: Add "debug" option to "cfi=" bootparam
x86/cfi: Standardize on common "CFI:" prefix for CFI reports
x86/cfi: Document the "cfi=" bootparam options
x86/traps: Clarify KCFI instruction layout
compiler_types.h: Move __nocfi out of compiler-specific header
objtool: Validate kCFI calls
x86/fred: KVM: VMX: Always use FRED for IRQs when CONFIG_X86_FRED=y
x86/fred: Play nice with invoking asm_fred_entry_from_kvm() on non-FRED hardware
x86/fred: Install system vector handlers even if FRED isn't fully enabled
x86/hyperv: Use direct call to hypercall-page
x86/hyperv: Clean up hv_do_hypercall()
KVM: x86: Remove fastops
KVM: x86: Convert em_salc() to C
KVM: x86: Introduce EM_ASM_3WCL
KVM: x86: Introduce EM_ASM_1SRC2
KVM: x86: Introduce EM_ASM_2CL
KVM: x86: Introduce EM_ASM_2W
...
gentwo / linux / .git / log