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

[Athira Rajeev <atrajeev@linux.ibm.com>]

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 <atrajeev@linux.ibm.com>
---
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