Pull more documentation updates from Jonathan Corbet:
"A handful of late-arriving docs fixes, along with one document update
that fell through the cracks before"
* tag 'docs-7.2-2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux:
docs: tools: Fix typo 'ackward' to 'awkward' in unittest.rst
kdoc: xforms: ignore special static/inline macros
kdoc: xforms_lists: handle DECLARE_PER_CPU() in kernel-doc
MAINTAINERS: Fix regex for kdoc
docs: kgdb: Fix path of driver options
Documentation: tracing: fix typo in events documentation
Docs/driver-api/uio-howto: document mmap_prepare callback
docs/mm: clarify that we are not looking for LLM generated content
kernel-doc: xforms: support __SYSFS_FUNCTION_ALTERNATIVE()
Pull SPDX updates from Greg KH:
"Here is a "big" set of SPDX-like patches for 7.2-rc1. It is the
addition of the ability for the kernel build process to generate a
Software Bill of Materials (SBOM) in the SPDX format, that matches up
exactly with just the files that are actually built for the specific
kernel image generated.
To generate a sbom, after the kernel has been built, just do:
make sbom
and marvel at the JSON file that is generated...
This is needed by users for environments in which a SBOM is required
(medical, automotive, anything shipped in the EU, etc.) and cuts down
by a massive size the "naive" SBOM solution that many vendors have
done by just including _all_ of the kernel files in the resulting
document.
This result is still a giant JSON file, that I am told parses
properly, so we just have to trust that it is properly inclusive as
attempting to parse that thing by hand is impossible.
The scripts here are self-contained python scripts, no additional
libraries or tools to create the SBOM are needed, which is important
for many build systems. Overall it's just a bit over 4000 lines of
"simple" python code, the most complex part is the regex matching
lines, but those are nothing compared to what we maintain in
scripts/checkpatch.pl today...
The various parts where the tool touches the kbuild subsystem have
been acked by the kbuild maintainer, so all should be good here.
All of these patches have been in linux-next for weeks with no
reported problems"
* tag 'spdx-7.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/spdx:
scripts/sbom: add unit tests for SPDX-License-Identifier parsing
scripts/sbom: add unit tests for command parsers
scripts/sbom: add SPDX build graph
scripts/sbom: add SPDX source graph
scripts/sbom: add SPDX output graph
scripts/sbom: collect file metadata
scripts/sbom: add shared SPDX elements
scripts/sbom: add JSON-LD serialization
scripts/sbom: add SPDX classes
scripts/sbom: add additional dependency sources for cmd graph
scripts/sbom: add cmd graph generation
scripts/sbom: add command parsers
scripts/sbom: setup sbom logging
scripts/sbom: integrate script in make process
scripts/sbom: add documentation
Cover the newly added -A/--aligned option that aligns timerlat threads
using the corresponding feature of the timerlat tracer.
A note is added to clarify what alignment means, similar to the note in
the tracer implementation in commit 4245bf4dc5 ("tracing/osnoise: Add
option to align tlat threads").
Link: https://lore.kernel.org/r/20260527144928.2944472-3-tglozar@redhat.com
[ remove spurious newline ]
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
Instead of using getopt_long() directly to parse the command line
arguments given to an RTLA tool, use libsubcmd's parse_options().
Utilizing libsubcmd for parsing command line arguments has several
benefits:
- A help message is automatically generated by libsubcmd from the
specification, removing the need of writing it by hand.
- Options are sorted into groups based on which part of tracing (CPU,
thread, auto-analysis, tuning, histogram) they relate to.
- Common parsing patterns for numerical and boolean values now share
code, with the target variable being stored in the option array.
To avoid duplication of the option parsing logic, RTLA-specific
macros defining struct option values are created:
- RTLA_OPT_* for options common to all tools
- OSNOISE_OPT_* and TIMERLAT_OPT_* for options specific to
osnoise/timerlat tools
- HIST_OPT_* macros for options specific to histogram-based tools.
Individual *_parse_args() functions then construct an array out of
these macros that is then passed to libsubcmd's parse_options().
All code specific to command line options parsing is moved out of the
individual tool files into a new file, cli.c, which also contains the
contents of the rtla.c file. A private header, cli_p.h, is added
alongside the public header cli.h, so that unit tests are able to test
statically declared option callbacks.
Minor changes:
- The return value of tool-level help option changes to 129, as this is
the value set by libsubcmd; this is reflected in affected test cases.
The implementation of help for command-level and tracer-level help
is set to 129 as well for consistency, and the change is reflected in
exit value documentation.
- Related to the above, {rtla,osnoise,timerlat}_usage() are marked
__noreturn and exit() is removed from after they are called for
cleaner code.
- The error messages for invalid argument for options --dma-latency and
-E/--entries were corrected, fixing off-by-one in the limits.
Note that unsetting options (using --no-<opt> syntax) is currently not
implemented for options that use custom callbacks. For --irq and
--thread, it will never be implemented, as they conflict with already
existing --no-irq and --no-thread with a different meaning.
Assisted-by: Composer:composer-1.5
Link: https://lore.kernel.org/r/20260528103254.2990068-5-tglozar@redhat.com
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
Pull RTLA updates from Steven Rostedt:
- Simplify option parsing
Auto-generate getopt_long() optstring for short options from long
options array, avoiding the need to specify it manually and reducing
the surface for mistakes.
- Add unit tests
Implement unit tests (make unit-tests) using libcheck, next to
existing runtime tests (make check). Currently, three functions from
utils.c are tested.
- Add --stack-format option
In addition to stopping stack pointer decoding (with -s/--stack
option) on first unresolvable pointer, allow also skipping
unresolvable pointers and displaying everything, configurable with a
new option.
- Unify number of CPUs into one global variable
Use one global variable, nr_cpus, to store the number of CPUs instead
of retrieving it and passing it at multiple places.
- Fix behavior in various corner cases
Make RTLA behave correctly in several corner cases: memory allocation
failure, invalid value read from kernel side, thread creation
failure, malformed time value input, and read/write failure or
interruption by signal.
- Improve string handling
Simplify several places in the code that handle strings, including
parsing of action arguments. A few new helper functions and variables
are added for that purpose.
- Get rid of magic numbers
Few places handling paths use a magic number of 1024. Replace it with
MAX_PATH and ARRAY_SIZE() macro.
- Unify threshold handling
Code that handles response to latency threshold is duplicated between
tools, which has led to bugs in the past. Unify it into a new helper
as much as possible.
- Fix segfault on SIGINT during cleanup
The SIGINT handler touches dynamically allocated memory. Detach it
before freeing it during cleanup to prevent segmentation fault and
discarding of output buffers. Also, properly document SIGINT handling
while at it.
* tag 'trace-rtla-v7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/trace/linux-trace: (28 commits)
Documentation/rtla: Document SIGINT behavior
rtla: Fix segfault on multiple SIGINTs
rtla/utils: Fix loop condition in PID validation
rtla/utils: Fix resource leak in set_comm_sched_attr()
rtla/trace: Fix I/O handling in save_trace_to_file()
rtla/trace: Fix write loop in trace_event_save_hist()
rtla/timerlat: Simplify RTLA_NO_BPF environment variable check
rtla: Use str_has_prefix() for option prefix check
rtla: Enforce exact match for time unit suffixes
rtla: Use str_has_prefix() for prefix checks
rtla: Add str_has_prefix() helper function
rtla: Handle pthread_create() failure properly
rtla/timerlat: Add bounds check for softirq vector
rtla: Simplify code by caching string lengths
rtla: Replace magic number with MAX_PATH
rtla: Introduce common_threshold_handler() helper
rtla/actions: Simplify argument parsing
rtla: Use strdup() to simplify code
rtla: Exit on memory allocation failures during initialization
tools/rtla: Remove unneeded nr_cpus from for_each_monitored_cpu
...
Pull runtime verification updates from Steven Rostedt:
- Refactor da_monitor header to share handlers across monitor types
No functional changes, only less code duplication.
- Add Hybrid Automata model class
Add a new model class that extends deterministic automata by adding
constraints on transitions and states. Those constraints can take
into account wall-clock time and as such allow RV monitor to make
assertions on real time. Add documentation and code generation
scripts.
- Add stall monitor as hybrid automaton example
Add a monitor that triggers a violation when a task is stalling as an
example of automaton working with real time variables.
- Convert the opid monitor to a hybrid automaton
The opid monitor can be heavily simplified if written as a hybrid
automaton: instead of tracking preempt and interrupt enable/disable
events, it can just run constraints on the preemption/interrupt
states when events like wakeup and need_resched verify.
- Add support for per-object monitors in DA/HA
Allow writing deterministic and hybrid automata monitors for generic
objects (e.g. any struct), by exploiting a hash table where objects
are saved. This allows to track more than just tasks in RV. For
instance it will be used to track deadline entities in deadline
monitors.
- Add deadline tracepoints and move some deadline utilities
Prepare the ground for deadline monitors by defining events and
exporting helpers.
- Add nomiss deadline monitor
Add first example of deadline monitor asserting all entities complete
before their deadline.
- Improve rvgen error handling
Introduce AutomataError exception class and better handle expected
exceptions while showing a backtrace for unexpected ones.
- Improve python code quality in rvgen
Refactor the rvgen generation scripts to align with python best
practices: use f-strings instead of %, use len() instead of
__len__(), remove semicolons, use context managers for file
operations, fix whitespace violations, extract magic strings into
constants, remove unused imports and methods.
- Fix small bugs in rvgen
The generator scripts presented some corner case bugs: logical error
in validating what a correct dot file looks like, fix an isinstance()
check, enforce a dot file has an initial state, fix type annotations
and typos in comments.
- rvgen refactoring
Refactor automata.py to use iterator-based parsing and handle
required arguments directly in argparse.
- Allow epoll in rtapp-sleep monitor
The epoll_wait call is now rt-friendly so it should be allowed in the
sleep monitor as a valid sleep method.
* tag 'trace-rv-v7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/trace/linux-trace: (32 commits)
rv: Allow epoll in rtapp-sleep monitor
rv/rvgen: fix _fill_states() return type annotation
rv/rvgen: fix unbound loop variable warning
rv/rvgen: enforce presence of initial state
rv/rvgen: extract node marker string to class constant
rv/rvgen: fix isinstance check in Variable.expand()
rv/rvgen: make monitor arguments required in rvgen
rv/rvgen: remove unused __get_main_name method
rv/rvgen: remove unused sys import from dot2c
rv/rvgen: refactor automata.py to use iterator-based parsing
rv/rvgen: use class constant for init marker
rv/rvgen: fix DOT file validation logic error
rv/rvgen: fix PEP 8 whitespace violations
rv/rvgen: fix typos in automata and generator docstring and comments
rv/rvgen: use context managers for file operations
rv/rvgen: remove unnecessary semicolons
rv/rvgen: replace __len__() calls with len()
rv/rvgen: replace % string formatting with f-strings
rv/rvgen: remove bare except clauses in generator
rv/rvgen: introduce AutomataError exception class
...
Web links in the documentation are not properly displayed.
In the man pages web links look like:
Osnoise tracer documentation: < <https://www.kernel.org/doc/html/lat‐
est/trace/osnoise-tracer.html> >
On web pages the URL caption is the URL itself.
Convert tracer documentation links to RST anonymous hyperlink format
for better rendering. Use newer docs.kernel.org instead of
www.kernel.org/doc/html/latest for brevity.
After the change, the links in the man pages look like:
Osnoise tracer <https://docs.kernel.org/trace/osnoise-tracer.html>
On web pages the captions are the titles of the links.
Signed-off-by: Costa Shulyupin <costa.shul@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260405163847.3337981-1-costa.shul@redhat.com>
Over the time, most of the changes at kernel-doc are related
to maintaining a list of transforms to convert macros into pure
C code.
Place such transforms on a separate module, to cleanup the
parser module.
There is an advantage on that: QEMU also uses our own kernel-doc,
but the xforms list there is different. By placing it on a
separate module, we can minimize the differences and make it
easier to keep QEMU in sync with Kernel upstream.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <ccd74b7589e1fff340a74bf8ed16a974532cb54f.1772469446.git.mchehab+huawei@kernel.org>
Pull RTLA updates from Steven Rostedt:
- Remove unused function declarations
Some functions were removed in recent code consolidation 6.18, but
their prototypes were not removed from headers. Remove them.
- Set stop threshold after enabling instances
Prefer recording samples without stopping on them on the start of
tracing to stopping on samples that are never recorded. This fixes
flakiness of some RTLA tests and unifies behavior of sample
collection between tracefs mode and BPF mode.
- Consolidate usage help message implementation
RTLA tools (osnoise-top, osnoise-hist, timerlat-top, timerlat-hist)
each implement usage help individually. Move common logic between
them into a new function to reduce code duplication.
- Add BPF actions feature
Add option --bpf-action to attach a BPF program (passed as filename
of its ELF representation) to be executed via BPF tail call at
latency threshold.
- Consolidate command line option parsing
Each RTLA tool implements the parsing of command line options
individually. Now that we have a common structure for parameters,
unify the parsing of those options common among all four tools into
one function.
- De-duplicate cgroup common code
Two functions in utils.c, setting cgroup for comm and setting cgroup
for pid, duplicate code for constructing the cgroup path. Extract it
to a new helper function.
- String and error handling fixes and cleanups
There were several instances of unsafe string and error handling that
could cause invalid memory access; fix them. Also, remove a few
unused headers, update .gitignore, and deduplicate code.
* tag 'trace-rtla-v7.0' of git://git.kernel.org/pub/scm/linux/kernel/git/trace/linux-trace: (30 commits)
rtla: Fix parse_cpu_set() bug introduced by strtoi()
rtla: Fix parse_cpu_set() return value documentation
rtla: Ensure null termination after read operations in utils.c
rtla: Make stop_tracing variable volatile
rtla: Add generated output files to gitignore
rtla: Fix NULL pointer dereference in actions_parse
rtla: Remove unused headers
rtla: Remove redundant memset after calloc
rtla: Use standard exit codes for result enum
rtla: Replace atoi() with a robust strtoi()
rtla: Introduce for_each_action() helper
tools/rtla: Deduplicate cgroup path opening code
tools/rtla: Consolidate -H/--house-keeping option parsing
tools/rtla: Consolidate -P/--priority option parsing
tools/rtla: Consolidate -e/--event option parsing
tools/rtla: Consolidate -d/--duration option parsing
tools/rtla: Consolidate -D/--debug option parsing
tools/rtla: Consolidate -C/--cgroup option parsing
tools/rtla: Consolidate -c/--cpus option parsing
tools/rtla: Add common_parse_options()
...
The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.
For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.
This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.
Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.
For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>
