Re: [PATCH V5 6/6] powerpc/perf/htm: Add documentation for Hardware Trace Macro PMU

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Low] Malformed ReST inline markup for output filenames will cause Sphinx warnings.
- [Low] Inconsistent naming of the trace decoding tool ('htmdecode' vs 'htmdecoder').
--

--- Patch [6]: [PATCH V5 6/6] powerpc/perf/htm: Add documentation for Hardware Trace Macro PMU ---
commit f01dd0b2a68c8e69f2fcef07fa210282e973c5a5
Author: Athira Rajeev <atrajeev@linux.ibm.com>

powerpc/perf/htm: Add documentation for Hardware Trace Macro PMU

This commit extends Documentation/arch/powerpc/htm.rst with a new
section detailing the HTM perf PMU interface. It covers how to open
HTM events, explains the required AUX buffer size, details the output
files produced by perf report, and describes how to decode the traces.

> diff --git a/Documentation/arch/powerpc/htm.rst b/Documentation/arch/powerpc/htm.rst
> index fcb4eb6306b16..42ad9924a7f6a 100644
> --- a/Documentation/arch/powerpc/htm.rst
> +++ b/Documentation/arch/powerpc/htm.rst
[ ... ]
> @@ -94,7 +95,158 @@ This trace file will contain the relevant instruction traces
>  collected during the workload execution. And can be used as
>  input file for trace decoders to understand data.
>  
> -Benefits of using HTM debugfs interface
> +HTM perf interface usage
> +========================
[ ... ]
> +Output Files
> +------------
> +
> +``perf record`` produces ``perf.data``.  Running ``perf report`` on that
> +file invokes the HTM auxtrace handler, which writes the output files:
> +
> +- **htm.bin.nX.pX.cX**.tX** : raw bus-trace AUX data for node X, chip X, core X
> +- **translation.nX.pX.cX**.tX** : memory-configuration records for the same target

[Severity: Low]
Can this formatting cause Sphinx to emit warnings? It looks like there is an
extra set of bold markup asterisks trailing the first part of the filenames
that leaves the inline markup unbalanced.

> +
> +.. code-block:: sh
> +
> +   # perf report
> +   # ls htm.bin.* translation.*
> +   htm.bin.n0.p2.c0.t1  translation.n0.p2.c0.t1
> +
> +Note: ``perf report -D`` prints AUX buffer sizes but does not produce
> +the output files.  Use plain ``perf report`` to extract trace data.
> +
> +Decoding Output Files
> +---------------------
> +
> +Pass the generated files to htmdecode for trace decoding::
> +
> +   htmdecoder <decode_options> htm.bin.n0.p2.c0.t1

[Severity: Low]
Is the decoding tool named htmdecode or htmdecoder? The descriptive text
refers to htmdecode, but the code block uses htmdecoder.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260807143734.1224-1-atrajeev@linux.ibm.com?part=6