Commit 0122938a7a ("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>
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>
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>
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>
Several options in common_options.rst say "osnoise tracer" for both
osnoise and timerlat.
Use |tool| variable so that the correct tool name is used.
Fixes: b1be48307d ("rtla: Add rtla osnoise top documentation")
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-6-tglozar@redhat.com>
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: 9cbc2d3b13 ("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>
Due to commit abd61d1ff8 ("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>
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.
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
Above patches are tested by 'make htmldocs'
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.
Signed-off-by: Alex Shi <alexs@kernel.org>
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: e3b42e94cf ("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>
For PR_SPEC_STORE_BYPASS and PR_SPEC_INDIRECT_BRANCH, PR_SPEC_DISABLE
means "disable the speculation bug" i.e. "enable the mitigation".
For PR_SPEC_L1D_FLUSH, PR_SPEC_DISABLE means "disable the mitigation".
This is not obvious, so document it.
Signed-off-by: Brendan Jackman <jackmanb@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251015-l1d-flush-doc-v1-1-f8cefea3f2f2@google.com>
We've been using the Python version and nobody has missed this one. All
credit goes to Mauro Carvalho Chehab for creating the replacement.
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>
Move this tool out of scripts/ to join the other documentation tools; fix
up a couple of erroneous references in the process.
It's worth noting that this script will fail badly unless one has a
PYTHONPATH referencing scripts/lib/abi.
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>
The scripts for managing the features docs are found in three different
directories; unite them all under tools/docs and update references as
needed.
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>
gdb and kgdb debugging documentation were moved to
Documentation/process/debugging/ as a part of
Commit d5af79c05e ("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: d5af79c05e ("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>
Complete the translation of rust/testing.rst and add the testing TOC entry
to rust/index.rst.
Add the translation based on commit a3b2347343
("Documentation: rust: testing: add docs on the new KUnit `#[test]` tests").
Signed-off-by: Ben Guo <benx.guo@gmail.com>
Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cm>
Signed-off-by: Alex Shi <alexs@kernel.org>
Sphinx reports htmldocs errors:
Documentation/tools/rtla/common_options.rst:58: ERROR: Undefined substitution referenced: "threshold".
Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tool".
Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "thresharg".
Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tracer".
Documentation/tools/rtla/common_options.rst:92: ERROR: Undefined substitution referenced: "tracer".
Documentation/tools/rtla/common_options.rst:98: ERROR: Undefined substitution referenced: "actionsperf".
Documentation/tools/rtla/common_options.rst:113: ERROR: Undefined substitution referenced: "tool".
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: 05b7e10687 ("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>
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>
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:
$ ./tools/docs/sphinx-build-wrapper --help
usage: sphinx-build-wrapper [-h]
[--sphinxdirs SPHINXDIRS [SPHINXDIRS ...]] [--conf CONF]
[--builddir BUILDDIR] [--theme THEME] [--css CSS] [--paper {,a4,letter}] [-v]
[-j JOBS] [-i] [-V [VENV]]
{cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs}
Kernel documentation builder
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.
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.
