Re: [RFC v1 15/19] ptwrite uprobes: Add a tutorial and overview documentation

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 3 potential issue(s) to consider:
- [Low] Missing blank line before a bullet list in reStructuredText.
- [Low] Typos in the 'Options in this case' list.
- [Low] Formatting inconsistency with double backticks in indented block.
--

commit e96dac3fdefb27a2867c9e268822b99d3e4c7aa7
Author: Andi Kleen <ak@kernel.org>

ptwrite uprobes: Add a tutorial and overview documentation

This patch adds a new documentation file explaining how to use ptwrite
uprobes for hardware tracing. It covers performance benefits, requirements,
and provides examples for configuring probes via tracefs and perf probe.

> diff --git a/Documentation/trace/ptwrite-uprobes.rst b/Documentation/trace/ptwrite-uprobes.rst
> new file mode 100644
> index 0000000000000..79ab35824b93c
> --- /dev/null
> +++ b/Documentation/trace/ptwrite-uprobes.rst

[ ... ]

> +Punning is a probabilistic method that depends on the existing
> +instruction bytes and the placement of the executable in memory.
> +It has a high chance of success on PIE/PIC binaries, but tends
> +to work poorly on non PIE main executables.
> +
> +When punning is not possible the probe is rejected at install
> +time. Options in this case:
> +- Move the probe site to a different instruction which may work.

[Severity: Low]
Does this list render correctly in Sphinx without a blank line before it?
In reStructuredText, bullet lists generally must be preceded by a blank
line, otherwise the list items may get merged into the preceding paragraph
or trigger build warnings.

> +- Rebuild with -fPIE if it's a main problem not using PIE.
> +- Enable or disable /proc/sys/kernel/randomize_va_space. If the
> +  randomization is enabled it may also just work on a rerun of
> +  the program.
> +- Fall back to a classic uprobes

[Severity: Low]
There are a couple of minor typos in this section. Could "main problem" 
be corrected to "main program", and "a classic uprobes" be changed to 
"a classic uprobe" or "classic uprobes"?

[ ... ]

> +If the program itself also executes own ``PTWRITE``, those values mix with the
> +uprobe output in the stream. The decoder uses the header magic to identify
> +uprobe records. Other values are printed as ``manual ptwrite:`` lines (with
> +their IP when ``fup_on_ptw`` is set) and counted in the summary's ``stray``
> +field.
> +
> +To also print the decoded branch stream alongside the records, add
> +``b`` to the itrace options and drop the ``q``
> +
> +    # ``perf script --itrace=web -s uprobe-ptwrite-decode.py -i perf.data``

[Severity: Low]
Are the double backticks intended here? Because this line is already indented
as a literal block, the double backticks will likely be rendered verbatim in
the output instead of being parsed as inline literal formatting.

> +
> +Each decoded branch prints as a ``branch:`` line (from => to, with
> +symbols where resolvable), interleaved with the probe records and any

[ ... ]

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260831150651.1134594-1-ak@kernel.org?part=15