[PATCH V3 6/6] powerpc/perf/htm: Add documentation for Hardware Trace Macro PMU
From: Athira Rajeev <hidden>
Date: 2026-07-25 07:00:37
Also in:
linux-perf-users
Subsystem:
documentation, linux for powerpc (32-bit and 64-bit), the rest · Maintainers:
Jonathan Corbet, Madhavan Srinivasan, Michael Ellerman, Linus Torvalds
Extend Documentation/arch/powerpc/htm.rst with a new section covering
the HTM perf PMU interface.
The added documentation covers:
- How to open HTM events using perf record, including the event
syntax (nodalchipindex, nodeindex, htm_type, cpu=N) and the
required AUX buffer size (-m,256).
- The two output files produced by perf report:
htm.bin.nX.pX.cX raw bus-trace AUX data
translation.nX.pX.cX memory-configuration records
- How to pass the output files to htmdecode for trace decoding.
- Notes on system-wide collection (-a) vs CPU-pinned collection
(cpu=N in event config) and the one-event-per-target PMU
restriction.
The existing debugfs interface documentation is retained unchanged.
A brief cross-reference is added at the top to point readers to the
new perf interface section.
Signed-off-by: Athira Rajeev <redacted>
---
Changes in V3:
- Fixed "After running perf record, the following files are generated":
htm.bin.* and translation.* are written by perf report (which runs
powerpc_htm_process_auxtrace_info), not by perf record. perf record
produces only perf.data. Corrected the Output Files section and the
Complete Workflow example accordingly. Note: powerpc_htm_process_-
auxtrace_info() is implemented in the companion tools/perf patch series
("tools/perf: Add perf tool support for processing powerpc HTM AUXTRACE
records"); the documentation is written against the complete two-series
feature, which is standard practice for kernel+tools PMU submissions.
- Fixed "perf report -D" in the workflow: perf report -D only prints
AUX buffer sizes; it does not produce htm.bin.* or translation.*.
The output files are produced by plain "perf report".
- Added the missing htmdecode usage section (referenced in commit
message and V2 changelog but absent from the doc body).
- Added the missing PMU restriction note: the HTM PMU uses
PERF_PMU_CAP_EXCLUSIVE so only one event per target (node/chip/core)
is allowed; a second event on the same target returns -EBUSY. Also
noted that cpu=N in the event config is the supported way to pin
collection to a CPU, and -a without cpu=N causes -EBUSY from the
kernel (HTM events require cpu=N since the PMU operates on physical
hardware addresses, not per-task context).
- Fixed typo "htmtype" -> "htm_type" in the config description list.
- Fixed grammar "To open the event on a specific cpu can be specified
using" -> "To specify a CPU, include the cpu= parameter".
- Fixed typo "Target code 6" -> "Target core 6".
Changes in V2:
- Added a new perf-interface section to Documentation/arch/powerpc/htm.rst
describing perf record usage, required AUX buffer size (-m,256), the
two output files (htm.bin.nX.pX.cX and translation.nX.pX.cX), and how
to pass them to htmdecode.
- Added notes on system-wide (-a) vs CPU-pinned collection and
the one-event-per-target PMU restriction introduced in patch 2.
- A cross-reference is added at the top of htm.rst pointing readers to
the new perf interface section.
- The existing debugfs interface documentation is retained unchanged.
- Patch is now 6/6 instead of 5/5.
Documentation/arch/powerpc/htm.rst | 158 ++++++++++++++++++++++++++++-
1 file changed, 155 insertions(+), 3 deletions(-)
diff --git a/Documentation/arch/powerpc/htm.rst b/Documentation/arch/powerpc/htm.rst
index fcb4eb6306b1..15e7484f2836 100644
--- a/Documentation/arch/powerpc/htm.rst
+++ b/Documentation/arch/powerpc/htm.rst@@ -18,9 +18,10 @@ H_HTM is used as an interface for executing Hardware Trace Macro (HTM) functions, including setup, configuration, control and dumping of the HTM data. For using HTM, it is required to setup HTM buffers and HTM operations can be controlled using the H_HTM hcall. The hcall can be invoked for any core/chip -of the system from within a partition itself. To use this feature, a debugfs -folder called "htmdump" is present under /sys/kernel/debug/powerpc. +of the system from within a partition itself. +To use this feature, a debugfs folder called "htmdump" is present under +/sys/kernel/debug/powerpc. Another interface is via perf. HTM debugfs example usage =========================
@@ -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 +======================== + +The HTM (Hardware Trace Macro) perf interface enables collection and analysis +of hardware trace data from PowerPC systems. This interface allows users to +capture detailed execution traces for performance analysis and debugging. + +Event Configuration +------------------- + +Use ``perf record`` with the htm PMU event. The event is configured using +named parameters that specify the target hardware location and trace type: + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Parameter + - Description + * - htm_type + - Type of HTM trace to collect (bits 0-3) + * - nodeindex + - Node index in the system topology (bits 4-11) + * - nodalchipindex + - Chip index within the specified node (bits 12-19) + * - coreindexonchip + - Core index on the specified chip (bits 20-27) + +- event: "config:0-27" +- htm_type: "config:0-3" +- nodeindex: "config:4-11" +- nodalchipindex: "config:12-19" +- coreindexonchip: "config:20-27" + +1) nodeindex, nodalchipindex, coreindexonchip: this specifies + which partition to configure the HTM for. +2) htm_type: specifies the type of HTM. + +Event Syntax +------------ + +The event configuration uses named parameters:: + + htm/nodeindex=N,nodalchipindex=C,coreindexonchip=R,htm_type=T/ + +Opening the event on a specific CPU can be specified:: + + htm/nodeindex=N,nodalchipindex=C,coreindexonchip=R,htm_type=T,cpu=x/ + +Where: + +- N = node index +- C = chip index within the node +- R = core index on the chip +- T = HTM type +- x = CPU number + +Basic Usage Example +------------------- + +To collect HTM trace data for a specific chip: + +.. code-block:: sh + + # perf record -C 1 -e htm/nodalchipindex=2,nodeindex=0,htm_type=1/ <workload> + +In this example: + +- ``-C 1``: Collect on CPU 1 +- ``nodeindex=0``: Target node 0 +- ``nodalchipindex=2``: Target chip 2 within node 0 +- ``htm_type=1``: HTM trace type 1 + +.. code-block:: sh + + # perf record -m,256 -e htm/coreindexonchip=6,nodalchipindex=0,nodeindex=0,htm_type=2,cpu=16/ -a sleep 1 + +In this example: + +- ``cpu=16``: Collect on CPU 16 +- ``nodeindex=0``: Target node 0 +- ``nodalchipindex=0``: Target chip 0 within node 0 +- ``coreindexonchip=6``: Target core 6 +- ``htm_type=2``: HTM trace type 2 +- ``-m,256``: specifies number of mmap pages + +Running trace collection for multiple targets: + +.. code-block:: sh + + # perf record -m,256 -e htm/nodalchipindex=2,nodeindex=0,htm_type=1,cpu=8/ -e htm/nodalchipindex=1,nodeindex=0,htm_type=1,cpu=9/ -a sleep 1 + + +In this example, trace is collected for two events on different target chips + +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** : raw bus-trace AUX data for node X, chip X, core X +- **translation.nX.pX.cX** : memory-configuration records for the same target + +.. code-block:: sh + + # perf report + # ls htm.bin.* translation.* + htm.bin.n0.p2.c0 translation.n0.p2.c0 + +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:: + + htmdecode htm.bin.n0.p2.c0 translation.n0.p2.c0 + +PMU Restrictions +---------------- + +The HTM PMU uses ``PERF_PMU_CAP_EXCLUSIVE``, which enforces a limit of one +active event per target (node/chip/core tuple) at a time. Attempting to open +a second event on the same target returns ``-EBUSY``. + +HTM events must be pinned to a CPU using the ``cpu=N`` parameter in the event +config. Using ``-a`` (system-wide) without ``cpu=N`` causes ``-EBUSY`` from +the kernel because the HTM PMU operates on physical hardware addresses and +requires an explicit CPU binding. + +Complete Workflow Example +------------------------- + +.. code-block:: sh + + # Step 1: Collect trace data + perf record -m,256 -e htm/nodalchipindex=2,nodeindex=0,htm_type=1,cpu=9/ -a sleep 5 + + # Step 2: Extract trace and memory-config files + perf report + + # Step 3: Verify output files + ls htm.bin.* # htm.bin.n0.p2.c0 + ls translation.* # translation.n0.p2.c0 + ls perf.data + + # Step 4: Decode the trace + htmdecode htm.bin.n0.p2.c0 translation.n0.p2.c0 + +Benefits of using HTM interface ======================================= It is now possible to collect traces for a particular core/chip
--
2.43.0