Skip to contentSkip to conversation

powerpc/perf: Add HTM PMU driver and perf AUX support

PATCH New Athira Rajeev 2 participants 11 messages Aug 7

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

v5 cover powerpc/perf: Add HTM PMU driver and perf AUX support

Overview:
The Hardware Trace Macro (HTM) on POWER systems provides hardware-level bus-trace data for a specific node/chip/core target within a logical partition. It is accessed via the H_HTM hypervisor call and traces continuously at node, chip, or core scope independent of task scheduling.

This series adds a new "htm" PMU driver under arch/powerpc/perf/ that exposes HTM trace collection via the standard perf interface using the perf AUX buffer infrastructure, together with ABI and RST documentation.

Patch overview:
Patch 1 introduces the core HTM PMU driver (htm-perf.c). The event configuration encodes the trace target as a 28-bit value in perf_event_attr.config:

bits 0-3: htm_type (HTM_CORE=2, HTM_NEST=1, HTM_LLAT=3)
bits 4-11: nodeindex
bits 12-19: nodalchipindex
bits 20-27: coreindexonchip

The PMU lifecycle maps to H_HTM_OP_CONFIGURE/DECONFIGURE at add/del time and H_HTM_OP_START/STOP at start/stop time. Context-switch callbacks (PERF_EF_RELOAD / PERF_EF_UPDATE) are intentionally ignored because HTM traces the hardware scope, not individual tasks. Tracing state is kept in event->pmu_private (HTM_TRACING_ACTIVE / HTM_TRACING_INACTIVE) as the authoritative source, with event->hw.state kept in sync as a hint for the perf core.

Patch 2 adds duplicate-reservation protection. When 'perf record -a' is used, perf opens system-wide events on all CPUs in parallel. Without driver-side tracking, concurrent opens for the same HTM target (node, chip, core, type) can race and issue duplicate H_HTM_OP_CONFIGURE flows. A global reserved-targets list is added; htm_event_init() rejects any open that matches an already-reserved tuple, while different targets can still be opened simultaneously on different CPUs.

Patch 3 adds AUX ring-buffer support so that high-volume trace data can be streamed into a perf AUX buffer. The driver opts into PERF_PMU_CAP_AUX_NO_SG | PERF_PMU_CAP_AUX_PREFER_LARGE to request physically contiguous allocations, which H_HTM_OP_DUMP_DATA requires. A page-by-page physical-continuity scan is performed before each dump to detect and bound any fragmentation gaps, preventing silent memory corruption. event->count is set to the number of 128-byte HTM trace records written on a successful dump, 1 when the AUX buffer is temporarily full but the hypervisor stream is intact, and 0 when the stream is exhausted or a hard error occurs; the perf tool uses this as a drain signal to decide whether another read pass is needed before closing the event.

Patch 4 adds system memory configuration capture. After writing trace data to the AUX buffer, htm_event_read() calls H_HTM_OP_DUMP_SYSMEM_CONF and emits the returned physical-to-logical address mapping records as PERF_SAMPLE_RAW data. Keeping trace data in the AUX stream and memory configuration in raw samples allows each to be decoded independently in userspace.

Patch 5 adds ABI documentation for the sysfs entries under /sys/bus/event_source/devices/htm/, covering the format attribute (config bit layout) and the events attribute group.

Patch 6 extends Documentation/arch/powerpc/htm.rst with a new section on the perf interface: event syntax, required options, the two output files (htm.bin.nX.pX.cX.tX and translation.nX.pX.cX.tX), and how to pass them to htmdecode for trace decoding.

Usage example:
Collect HTM trace data from two simultaneous chip targets:

  # 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 10
  # perf report

Output files written by perf report:

  htm.bin.n0.p2.c0.t1       raw HTM bus-trace, chip 2
  htm.bin.n0.p1.c0.t1       raw HTM bus-trace, chip 1
  translation.n0.p2.c0.t1   memory config records, chip 2
  translation.n0.p1.c0.t1   memory config records, chip 1

The htm.bin.* files can then be decoded with htmdecoder to produce trace output.

Testing:
Tested on POWER11 with two simultaneous HTM targets. Both htm.bin.* and translation.* files are produced correctly.

  # perf record -C 9 -m,256 \
      -e htm/nodalchipindex=2,nodeindex=0,htm_type=1/ -a sleep 3
  [ perf record: Woken up 1 times to write data ]
  [ perf record: Captured and wrote 256.277 MB perf.data ]
  # perf record -m,512 \
  -e htm/htm_type=3,nodalchipindex=1,nodeindex=0,coreindexonchip=6,cpu=8/ \
  -e htm/htm_nest,nodalchipindex=1,nodeindex=0,cpu=16/ -a sleep 1
  [ perf record: Woken up 1 times to write data ]
  [ perf record: Captured and wrote 514.095 MB perf.data ]

Athira Rajeev (6):
powerpc/perf: Add HTM PMU driver to expose Hardware Trace Macro data powerpc/perf: Reject duplicate HTM target reservations powerpc/perf: Add AUX buffer management to capture HTM trace data powerpc/perf: Capture the HTM memory configuration as part of perf
data
docs: ABI: sysfs-bus-event_source-devices-htm: Document sysfs event
format entries for htm pmu
powerpc/perf/htm: Add documentation for Hardware Trace Macro PMU

 .../sysfs-bus-event_source-devices-htm        |   36 +
 Documentation/arch/powerpc/htm.rst            |  158 ++-
 arch/powerpc/perf/Makefile                    |    2 +-
 arch/powerpc/perf/htm-perf.c                  | 1122 +++++++++++++++++
 4 files changed, 1314 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-event_source-devices-htm
 create mode 100644 arch/powerpc/perf/htm-perf.c
Signature · 1 line
2.53.0
#1 lore raw

PATCH v5 1/6 powerpc/perf: Add HTM PMU driver to expose Hardware Trace Macro data

The H_HTM hypervisor call (hcall) provides an interface to the Hardware Trace Macro (HTM) function on POWER systems. HTM captures hardware-level trace data for a specific node/chip/core target within a logical partition.

Add a new "htm" Performance Monitoring Unit (PMU) that exposes HTM control via the standard perf interface. The event configuration is a 28-bit value packed into the perf config field:

bits 0-3: htm_type (HTM_CORE=2, HTM_NEST=1, HTM_LLAT=3)
bits 4-11: nodeindex
bits 12-19: nodalchipindex
bits 20-27: coreindexonchip

PMU lifecycle:

add/del: Issue H_HTM_OP_CONFIGURE / H_HTM_OP_DECONFIGURE to reserve
and release the hardware trace resource.

start/stop: Issue H_HTM_OP_START / H_HTM_OP_STOP to control tracing.
HTM traces at node/chip/core scope continuously for the duration of the event. Context-switch-triggered start/stop callbacks (PERF_EF_RELOAD / PERF_EF_UPDATE) are ignored to keep tracing uninterrupted. Explicit ioctl(ENABLE/DISABLE) and event deletion do control the hardware.

State tracking uses event->pmu_private (HTM_TRACING_ACTIVE/INACTIVE) as the source of information, with event->hw.state kept in sync as a hint for the perf core. This avoids conflicts with infrastructure writes to event->hw.state.

H_BUSY, H_LONG_BUSY_* and other errors handling:

All PMU callbacks (add, del, start, stop) are invoked in an atomic context with interrupts disabled and hardware context locks held; sleeping is not possible anywhere in the driver.

H_BUSY (transient): retried in a spin loop up to MAX_RETRIES times.

H_LONG_BUSY_* (hypervisor requests a long delay before retry) and other errors: not retried. The correct response differs by callsite:

- pmu->add (H_HTM_OP_CONFIGURE): on any non-success result from the configure hcall, calls perf_event_disable_inatomic() and returns 0. event_sched_in() in the perf core converts any non-zero pmu->add() return to -EAGAIN and leaves the event as PERF_EVENT_STATE_INACTIVE, which the mux would retry on every tick. Returning 0 and calling perf_event_disable_inatomic() instead schedules a task-work callback that sets PERF_EVENT_STATE_OFF — permanently disabled, never rescheduled by the mux.

- pmu->stop (H_HTM_OP_STOP): exits immediately on any failure, leaving tracing_active as HTM_TRACING_ACTIVE. The perf core always calls pmu->del() after pmu->stop(), so htm_event_del() is the guaranteed retry point for the stop hcall.

- pmu->del (H_HTM_OP_STOP retry and H_HTM_OP_DECONFIGURE): retries the stop hcall first. H_HTM_OP_DECONFIGURE requires the trace to be stopped first; if the stop retry fails, the deconfigure will fail too. Both failures are surfaced via pr_err with target identifiers (node/chip/core/type).
A workqueue-based deferred cleanup was considered but rejected as over-engineering for a firmware-maintenance-only edge case that is consistent with how all other in-tree POWER hcall-backed PMU drivers

Note: this patch does not prevent two concurrent perf_event_open() calls for the same HTM hardware target (node/chip/core) from being opened simultaneously on different CPUs. PERF_PMU_CAP_EXCLUSIVE only enforces exclusivity within the same per-CPU context and does not cover this case. A global reserved-targets list to reject duplicate reservations is added in the next patch.

After this patch the PMU is visible under sysfs:

 # ls /sys/bus/event_source/devices/ |grep htm
 htm
 # ls /sys/bus/event_source/devices/htm/
 events  format  perf_event_mux_interval_ms  power  subsystem  type  uevent

---
Changes in V5:
- Add HTM_LLAT (htm_type=3) as a third supported HTM type alongside HTM_NEST and HTM_CORE. Add EVENT(HTM_LLAT, 0x3) and GENERIC_EVENT_ATTR/PTR entries, and extend the htm_type switch in htm_event_init() with case HTM_LLAT.
- htm_target_id: add int configured field to track whether H_HTM_OP_CONFIGURE succeeded for this event. Set to 1 in htm_event_add() after a successful CONFIGURE, cleared to 0 if the subsequent H_HTM_OP_START fails. htm_event_del() guards its H_HTM_OP_DECONFIGURE call with if (!target->configured) return; to prevent issuing DECONFIGURE when CONFIGURE was never completed or was already undone, which would destroy a concurrent trace session on the same target.
- htm_event_init(): extend the sample_type rejection to cover PERF_SAMPLE_CALLCHAIN, PERF_SAMPLE_STACK_USER, PERF_SAMPLE_REGS_USER, and PERF_SAMPLE_AUX in addition to the existing PERF_SAMPLE_REGS_INTR check. All of these either add variable-length data to the ring buffer record (overflowing the fixed HTM_MEM_BUF_SIZE budget), require kernel stack walking that is unsafe from the HTM read path, or conflict with AUX buffer ownership. A single combined check replaces the two separate guards.

Changes in V4:
- htm_event_add(): replace -ENODEV / -EIO returns on configure or start failure with perf_event_disable_inatomic(event) + return 0. event_sched_in() in the perf core overrides any non-zero pmu->add() return to -EAGAIN and sets PERF_EVENT_STATE_INACTIVE, which the mux retries on every tick; this would flood the hypervisor with H_HTM_OP_CONFIGURE hcalls when it has requested a long backoff. perf_event_disable_inatomic() schedules a task-work callback that sets PERF_EVENT_STATE_OFF, permanently excluding the event from the mux.
- PERF_EF_RELOAD comment in htm_event_start(): expanded to explain that HTM does not use frequency mode, so there is no period or counter to unthrottle, and that the guard is belt-and-suspenders because .task_ctx_nr = perf_invalid_context prevents pmu->start() from being called on context-switch-in entirely.
- PERF_EF_UPDATE comment in htm_event_stop(): expanded to explain that HTM has no counter to snapshot on context-switch-out (data flows into the AUX buffer via pmu->read), and that the guard is belt-and-suspenders for the same reason as above.
- Added explanation above HTM_TRACING_ACTIVE that pmu->add/del are never called on context switch: .task_ctx_nr = perf_invalid_context forces CPU-wide-only placement; perf_event_context_sched_out/in() only walks task->perf_event_ctxp which is NULL for tasks with no task-context events, so the switch path returns immediately without touching HTM.
- Fixed typos: "erros" -> "errors" (commit body and two in-code comments).
- htm_event_init(): reject attr.freq with -EINVAL. HTM is a hardware-scope bus tracer with no counter or sample period. Frequency mode makes the core call pmu->stop/start every tick to adjust the sample period — meaningless for HTM — and would corrupt event->count semantics (the driver uses it as a record count; the freq machinery would interpret it as a sample-rate measurement). perf record already forces attr.freq=0 in htm_recording_options(), but rejecting it in the kernel closes the gap for any direct perf_event_open() caller.
- htm_event_init(): reject PERF_SAMPLE_REGS_INTR with -EOPNOTSUPP. The HTM_MEM_BUF_SIZE record size calculation (patch 4) assumes a fixed 92-byte overhead; PERF_SAMPLE_REGS_INTR adds sizeof(struct pt_regs) (~296 bytes on PowerPC) to each sample, overflowing the __u16 perf_event_header.size limit and corrupting the ring buffer.

Changes in V3:
- Expanded the H_BUSY, H_LONG_BUSY_* and other errors handling section to give per-callsite rationale for each hcall (configure, stop, del). V2 described the retry policy but not why each site responds differently.
- Added explicit note that this patch does not yet prevent duplicate concurrent perf_event_open() calls for the same HTM target; that is handled in patch 2. V2 omitted this cross-reference.
- Diffstat grows from 379 to 422 lines added (the extra lines come from the expanded commit message body; no functional change to the driver code itself).

Changes in V2:
- Moved the HTM PMU driver from arch/powerpc/htm/ to arch/powerpc/perf/ and renamed the source file from htm.c to htm-perf.c to follow the naming convention of other PMU drivers in that directory.
- Replaced direct H_HTM_OP_CONFIGURE/DECONFIGURE calls in htm_event_add() and htm_event_del() with separate htm_event_init() and destroy paths. State tracking is now via event->pmu_private (HTM_TRACING_ACTIVE / HTM_TRACING_INACTIVE) as the authoritative source, with event->hw.state kept in sync as a hint for the perf core, avoiding conflicts with infrastructure writes to event->hw.state.
- Context-switch callbacks (PERF_EF_RELOAD / PERF_EF_UPDATE) are now explicitly ignored in htm_event_start()/stop() to keep tracing uninterrupted across task switches; previously these paths were absent.
- H_BUSY retry loop is capped at MAX_RETRIES; H_LONG_BUSY_* is not retried in atomic context to avoid deadlocks (was unconditionally retried in V1).

 arch/powerpc/perf/Makefile   |   2 +-
 arch/powerpc/perf/htm-perf.c | 517 +++++++++++++++++++++++++++++++++++
 2 files changed, 518 insertions(+), 1 deletion(-)
 create mode 100644 arch/powerpc/perf/htm-perf.c
arch/powerpc/perf/Makefile +1 -1
index 78dd7e25219e..26ef30c0693c 100644
@@ -14,7 +14,7 @@ obj-$(CONFIG_PPC_POWERNV)	+= imc-pmu.o
 obj-$(CONFIG_FSL_EMB_PERF_EVENT) += core-fsl-emb.o
 obj-$(CONFIG_FSL_EMB_PERF_EVENT_E500) += e500-pmu.o e6500-pmu.o
 
-obj-$(CONFIG_HV_PERF_CTRS) += hv-24x7.o hv-gpci.o hv-common.o vpa-dtl.o
+obj-$(CONFIG_HV_PERF_CTRS) += hv-24x7.o hv-gpci.o hv-common.o vpa-dtl.o htm-perf.o
 
 obj-$(CONFIG_VPA_PMU) += vpa-pmu.o
 
arch/powerpc/perf/htm-perf.c new file +517 -0

517 lines not on this page · raw message

Signature · 1 line
2.53.0
#3 lore raw

PATCH v5 2/6 powerpc/perf: Reject duplicate HTM target reservations

In reply to Athira Rajeev

HTM tracing is controlled through hypervisor calls and operates on a system-scoped target identified by HTM type, node index, chip index, and core index.

HTM events must be opened with cpu=N to pin the AUX buffer file descriptor to a specific CPU. The intended usage is:

perf record -e htm/nodeindex=0,nodalchipindex=2,htm_type=1,cpu=8/ ...

With cpu=N, the event is opened on exactly one CPU and perf_event_open() is called once for that event. Multiple HTM events for different targets (node/chip/core tuples) may be opened simultaneously on different CPUs.

However, two independent perf_event_open() calls can still target the same (node, chip, core, type) tuple from different CPUs or processes. Without driver-side target tracking, both opens succeed htm_event_init() independently and both proceed to htm_event_add(), where they issue duplicate H_HTM_OP_CONFIGURE and H_HTM_OP_START hcalls against the same hardware resource. This causes conflicts in the underlying H_HTM operations.

Track reserved HTM targets globally and reject duplicate reservations for the same target. The reservation is created during htm_event_init() and released through the event destroy path. This prevents concurrent duplicate opens of the same hardware target while still allowing different targets to be used simultaneously on different CPUs.

Returning -EBUSY from htm_event_init() for a duplicate open is intentional and correct. A user who mistakenly opens the same HTM target twice (or runs perf record without cpu=N, causing every online CPU to attempt an open of the same target) receives a clear "PMU counters are busy" error from the perf tool, directing them to add the required cpu=N qualifier. Opening the same HTM node/chip/core target from multiple CPUs simultaneously has no meaningful purpose: HTM hardware tracing operates on the target itself, not on the CPU that issued the hcall.

Extend the existing per-event htm_target_id structure with a list node, and use the stored htm_config in pmu_private for target comparison.

A cpumask-based approach was considered but not used: cpumask restricts which CPUs an event may be opened on, but HTM operates on a hardware target (node/chip/core) that is independent of the CPU opening the event. A user may open an HTM event for a specific node/chip/core target from any CPU in the system, not just CPUs that belong to that node. A cpumask would therefore either over-restrict valid opens or require a per-target mask that mirrors the target list anyway. The approach in this patch handles the real constraint: the same hardware target cannot be configured twice, regardless of which CPU does the event open.

---
Changes in V5: - No changes from V4.

Changes in V3:
- Commit message rewritten to clarify the intended usage model:
HTM events must be opened with cpu=N to pin the AUX buffer fd to a specific CPU. V2 framed the problem as a system-wide perf record -a race; V3 makes the cpu=N requirement and the explicit duplicate open scenario the primary motivation.
- Added explanation that -EBUSY from htm_event_init() is intentional:
the user receives a clear "PMU counters are busy" error directing them to add cpu=N.
- No functional change to the driver code in this patch.

Changes in V2:
- New patch. V1 did not protect against concurrent duplicate opens of the same HTM target when 'perf record -a' initialises system-wide events in parallel on all CPUs.
- Adds a global reserved-targets list. htm_event_init() rejects any open whose (node, chip, core, type) tuple is already reserved; the reservation is released through the event destroy path.
- Different targets can still be opened simultaneously on different CPUs.

 arch/powerpc/perf/htm-perf.c | 42 ++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)
arch/powerpc/perf/htm-perf.c +38 -4
index cbe4f62813ee..c1ce12605014 100644
@@ -80,10 +80,14 @@ struct htm_config {
  * htm_event_start() and htm_event_stop() to make hcall decisions.
  * event->hw.state is kept in sync for the perf core only.
  */
+static LIST_HEAD(htm_active_targets_list);
+static DEFINE_MUTEX(htm_targets_lock);
+
 struct htm_target_id {
 	struct htm_config cfg;
 	int tracing_active;		/* HTM_TRACING_ACTIVE / HTM_TRACING_INACTIVE */
 	int configured;			/* 1 after H_HTM_OP_CONFIGURE succeeds; 0 otherwise */
+	struct list_head list;
 };
 
 /* Helper to parse the 28-bit event config into distinct fields */
@@ -168,7 +172,17 @@ static ssize_t htm_return_check(int rc)
 
 static void reset_htm_active(struct perf_event *event)
 {
-	kfree(event->pmu_private);
+	struct htm_target_id *target = event->pmu_private;
+
+	if (!target)
+		return;
+
+	mutex_lock(&htm_targets_lock);
+	if (!list_empty(&target->list))
+		list_del(&target->list);
+	mutex_unlock(&htm_targets_lock);
+
+	kfree(target);
 	event->pmu_private = NULL;
 }
 
@@ -176,6 +190,7 @@ static int htm_event_init(struct perf_event *event)
 {
 	u64 config = event->attr.config;
 	struct htm_config cfg;
+	struct htm_target_id *target, *tmp;
 
 	if (event->attr.inherit)
 		return -EOPNOTSUPP;
@@ -239,11 +254,30 @@ static int htm_event_init(struct perf_event *event)
 	}
 
 	/* Allocate per-event private state; freed via event->destroy */
-	event->pmu_private = kzalloc(sizeof(struct htm_target_id), GFP_KERNEL);
-	if (!event->pmu_private)
+	target = kzalloc(sizeof(*target), GFP_KERNEL);
+	if (!target)
 		return -ENOMEM;
 
-	((struct htm_target_id *)event->pmu_private)->cfg = cfg;
+	target->cfg = cfg;
+	target->tracing_active = HTM_TRACING_INACTIVE;
+	INIT_LIST_HEAD(&target->list);
+
+	mutex_lock(&htm_targets_lock);
+	list_for_each_entry(tmp, &htm_active_targets_list, list) {
+		if (tmp->cfg.htmtype == cfg.htmtype &&
+			tmp->cfg.nodeindex == cfg.nodeindex &&
+			tmp->cfg.nodalchipindex == cfg.nodalchipindex &&
+			tmp->cfg.coreindexonchip == cfg.coreindexonchip) {
+			mutex_unlock(&htm_targets_lock);
+			kfree(target);
+			return -EBUSY;
+		}
+	}
+
+	list_add_tail(&target->list, &htm_active_targets_list);
+	mutex_unlock(&htm_targets_lock);
+
+	event->pmu_private = target;
 	event->destroy = reset_htm_active;
 	return 0;
 }
Signature · 1 line
2.53.0
#4 lore raw

PATCH v5 3/6 powerpc/perf: Add AUX buffer management to capture HTM trace data

In reply to Athira Rajeev

Implement support for auxiliary (AUX) ring buffers in the HTM PMU driver. This enables high-volume trace data to be streamed directly into a perf AUX buffer for deferred post-processing by the perf tool.

Introduce the PMU data structures htm_pmu_buf and htm_pmu_ctx, and implement the core lifecycle hooks:

htm_setup_aux(): Allocates per-CPU context and records the AUX buffer
base, head, and size for the active trace window.
htm_free_aux(): Releases the PMU-private tracking allocations.

perf_output_handle objects are declared on the stack in every function that calls perf_aux_output_begin() (aux_buf_reset_for_start() and htm_dump_sample_data()). A per-CPU handle embedded in a static variable would be shared between an outer AUX transaction and a nested call from NMI context on the same CPU: perf_aux_output_begin()'s error path writes handle->event = NULL on the handle it receives; if both the outer and nested caller share the same object, this clears the outer transaction's event pointer and causes perf_aux_output_end() to return early without decrementing rb->aux_nest, permanently stalling the ring buffer. Using stack-local handles eliminates the aliasing entirely.

Physical contiguity requirement:

The perf core AUX allocator (rb_alloc_aux) may return a page array with physical fragmentation gaps. H_HTM_OP_DUMP_DATA operates on raw physical addresses and requires a strictly contiguous region; crossing a gap would cause silent memory corruption.

To prevent this, opt into PERF_PMU_CAP_AUX_NO_SG | PERF_PMU_CAP_AUX_PREFER_LARGE to request large, physically contiguous allocations, and perform a page-by-page physical continuity scan in htm_event_read() before each H_HTM_OP_DUMP_DATA call. The scan verifies that virt_to_phys(page[n]) + PAGE_SIZE == virt_to_phys(page[n+1]) and breaks the loop on the first discontinuity, ensuring the dump to the verified safe window.

One-shot dump model:

HTM hardware fills a fixed physical memory buffer (configured by H_HTM_OP_CONFIGURE) while tracing is active. When pmu->read is first called, htm_dump_sample_data() issues H_HTM_OP_STOP to freeze that buffer, then copies its contents into the perf AUX ring buffer one chunk at a time across successive pmu->read calls (each call advances aux_buf->head by chunk_size and returns; the perf drain loop calls pmu->read again until event->count reaches zero).

The hardware is NOT restarted between pmu->read calls, and is NOT restarted after the dump finishes. This is intentional:

- H_HTM_OP_DUMP_DATA reads the same frozen hardware buffer on every call, addressed by the advancing aux_buf->head offset. Restarting the hardware mid-drain would cause it to overwrite the buffer content that has not been transferred yet, corrupting all subsequent chunks.

- The intended usage is a bounded recording session (e.g. perf record -C 8 -m,512 -e htm/.../ sleep 1): hardware traces for the duration of the sleep, then the perf tool drains the full buffer in one pass at event close. A new perf record invocation opens a fresh event, which issues H_HTM_OP_START again.

If H_HTM_OP_STOP fails on the first pmu->read call, the dump is aborted and event->count is set to 0. The hardware buffer is still running; it will be stopped by H_HTM_OP_DECONFIGURE in htm_event_del() when the event is closed, preventing a resource leak.

htm_dump_sample_data() returns the record count directly (already divided by the per-format record size) so htm_event_read() uses the value without format knowledge:

  - AUX trace path:   chunk_size / 128  (128-byte HTM records)
  - Memory cfg path:  to_copy    /  32  (32-byte entries, patch 4)

htm_event_read() sets event->count as follows:
- ret > 0: record count written; used directly as event->count.
- ret == -ENOSPC (AUX ring buffer full): event->count = 1 so the perf tool drain loop keeps retrying after the consumer drains the buffer.
- all other non-success paths: event->count = 0 so the drain loop stops cleanly.
event->count does not represent an instruction or cycle count; actual trace records are decoded in userspace by the perf tool.

HTM target identity and tracing state are kept in event->pmu_private (htm_target_id). AUX-private state holds only buffer metadata and dump progress; htm_target_id.tracing_active remains the source for tracing state.

Hardware buffer boundary check:

H_HTM_OP_STATUS returns the currently allocated HTM buffer size for the target. The status output buffer header byte 0x01 holds CurrentNestHtmBufferSizeInPowerOf2 (HTM_NEST) or CurrentCoreHtmBufferSizeInPowerOf2 (HTM_CORE); both types use the same offset and length (offset 0x01, 1 byte). The actual buffer size is 1 << byte[0x01].

htm_event_add() issues H_HTM_OP_STATUS after a successful H_HTM_OP_CONFIGURE, allocating a 32-byte scratch buffer (enough for the header), reads byte 0x01, computes hw_buf_size = 1ULL << val, stores it in target->hw_buf_size, then frees the scratch buffer. If the hcall fails, hw_buf_size remains 0.

In htm_dump_sample_data(), after the contiguous-window clamp and before the H_HTM_OP_DUMP_DATA call, hw_buf_size is used as a hard
ceiling: if aux_buf->head has reached hw_buf_size the hardware buffer is fully consumed — collect_htm_trace is cleared and the dump returns 0 immediately without issuing any further hcalls. chunk_size is also clamped to hw_buf_size - aux_buf->head so the final chunk never overshoots the hardware boundary. When hw_buf_size == 0 (status hcall failed) the check is skipped and the existing contiguous-window clamp and hcall EOF signal remain in effect.

---
Changes in V5:
- Use stack-local struct perf_output_handle in aux_buf_reset_for_start() and htm_dump_sample_data() instead of a per-CPU embedded handle. A shared per-CPU handle is corrupted when perf_aux_output_begin()'s error path writes handle->event = NULL on a nested (NMI) call to the same object, clearing the outer transaction's event pointer and permanently stalling rb->aux_nest. Stack-local handles eliminate the aliasing. As a consequence, struct htm_pmu_ctx (which contained only the handle) and its DEFINE_PER_CPU are removed; they are no longer needed.
- Add u64 hw_buf_size to struct htm_target_id. Populated in htm_event_init() by a GFP_KERNEL H_HTM_OP_STATUS hcall using a PAGE_SIZE-aligned buffer (the hypervisor requires page alignment):
status_buf[0x01] gives the current buffer size as a power-of-two exponent, so hw_buf_size = 1ULL << status_buf[0x01]. The hcall is issued in htm_event_init() (process context, GFP_KERNEL) rather than htm_event_add() (atomic, GFP_ATOMIC) to avoid unreliable PAGE_SIZE allocations in atomic context; H_HTM_OP_STATUS is independent of CONFIGURE and returns valid data before any session is opened. htm_dump_sample_data() uses hw_buf_size to clamp chunk_size and to detect end-of-data (aux_buf->head >= hw_buf_size) without a failed hcall. On boundary hit, pivot to htm_collect_memory_config() via goto out rather than returning 0, so the memory-config drain is not skipped.
- Add in_nmi() guard at the top of htm_event_read(). The function issues hypervisor calls and mutates target->tracing_active and aux_buf->head, none of which are NMI-safe. Returning early from NMI context preserves the existing event->count so the drain loop retries on the next scheduled pmu->read() call.

Changes in V4:
- htm_event_start(): on a genuine start (not PERF_EF_RELOAD), open a brief perf_aux_output_begin()/perf_aux_output_end(0) transaction to reset collect_htm_trace=1 and head=0 on the AUX buffer. Without this, collect_htm_trace cleared by a prior hard hcall error would permanently prevent trace data from being written for all subsequent sessions.
- htm_setup_aux(): reject snapshot (overwrite) mode by returning NULL when snapshot is true. In overwrite mode perf_aux_output_begin() leaves handle->size as zero, which causes htm_dump_sample_data() to return ENOSPC on every call and htm_event_read() to set event->count=1, creating an infinite drain loop in userspace. Returning NULL causes perf_event_open() to return EINVAL to the caller.
- Commit body: clarified the reentrancy description to make explicit that on a nested perf_aux_output_begin() call (e.g. from NMI context), it is the *nested* handle->event that is set to NULL in the err path, not the outer handle. The outer handle->event remains valid throughout the outer perf_aux_output_end() call.

Changes in V3:
- Added a dedicated Physical contiguity requirement section and a full per-condition htm_dump_sample_data() return values and event->count table in the commit body, covering all five exit paths (success, -ENOSPC, H_NOT_AVAILABLE, H_LONG_BUSY_*/hard error, stop-failed before dump). V2 had a brief paragraph.
- htm_dump_sample_data() return type changed from int to ssize_t; ret locals in htm_dump_sample_data() and htm_event_read() likewise changed to ssize_t. Prevents truncation of the upper 32 bits of chunk_size on 64-bit PowerPC.
- Success path now returns (ssize_t)(chunk_size / 128) , the number 128-byte HTM trace records - rather than raw chunk_size bytes. htm_event_read() uses the value directly (local64_set(&event->count, ret)) without any further division, keeping it free of format knowledge. The same contract is extended to the memory-config path in patch 4 (to_copy / 32).
- Removed the unused trace_records field from struct htm_pmu_buf and its initialisation and increment sites. V2 carried the field as dead code.
- Added event->count does not represent an instruction or cycle count sentence to both the commit body and the in-code comment in htm_event_read().

Changes in V2:
- Opted into PERF_PMU_CAP_AUX_NO_SG | PERF_PMU_CAP_AUX_PREFER_LARGE to request physically contiguous allocations, which H_HTM_OP_DUMP_DATA requires. V1 had no contiguity requirement and could silently corrupt memory if the allocator returned a fragmented page array.
- Added a page-by-page physical-continuity scan in htm_event_read() before every H_HTM_OP_DUMP_DATA call. The scan verifies that virt_to_phys(page[n]) + PAGE_SIZE == virt_to_phys(page[n+1]) and stops at the first gap, bounding the dump to a verified safe window.
- htm_dump_sample_data() now returns a record count (already divided by the per-format record size) rather than raw bytes, so htm_event_read() uses the value directly without format knowledge. AUX trace path returns chunk_size / 128; the memory config path added in patch 4 will return to_copy / 32. Three-way semantics:
ret > 0 -> count = ret; ret == -ENOSPC -> count = 1; otherwise count = 0. The V1 arch_record__collect_final_data callback loop is replaced by this mechanism.
- Removed the unused trace_records field from htm_pmu_buf; htm_dump_ sample_data() now returns chunk_size on success so htm_event_read() can derive the record count directly.
- Introduced distinct htm_pmu_buf and htm_pmu_ctx structures; V1 used a single struct htm_pmu_buf for both purposes.

 arch/powerpc/perf/htm-perf.c | 371 ++++++++++++++++++++++++++++++++++-
 1 file changed, 370 insertions(+), 1 deletion(-)
arch/powerpc/perf/htm-perf.c +370 -1
index c1ce12605014..f72ee661c084 100644
@@ -88,6 +88,7 @@ struct htm_target_id {
 	int tracing_active;		/* HTM_TRACING_ACTIVE / HTM_TRACING_INACTIVE */
 	int configured;			/* 1 after H_HTM_OP_CONFIGURE succeeds; 0 otherwise */
 	struct list_head list;
+	u64 hw_buf_size;	/* hardware buffer size from H_HTM_OP_STATUS (1<<byte[0x01]), 0 if unknown */
 };
 
 /* Helper to parse the 28-bit event config into distinct fields */
@@ -99,6 +100,38 @@ static inline void parse_htm_config(u64 config, struct htm_config *cfg)
 	cfg->coreindexonchip = (config >> 20) & 0xff;
 }
 
+struct htm_pmu_buf {
+	int     nr_pages;
+	bool    snapshot;
+	void    *base;
+	void	**pages;
+	u64	head;
+	u64     size;
+	int     collect_htm_trace;
+};
+
+/*
+ * Reset AUX buffer state at the start of a new trace session.
+ * collect_htm_trace is cleared on any hard hcall error; without
+ * this reset, restarting the event via ioctl(ENABLE) after such an
+ * error would permanently drop all future trace data.
+ *
+ * Uses a stack-local handle to avoid aliasing with an in-progress
+ * AUX transaction on the same CPU (e.g. from NMI context).
+ */
+static void aux_buf_reset_for_start(struct perf_event *event)
+{
+	struct perf_output_handle handle;
+	struct htm_pmu_buf *aux_buf;
+
+	aux_buf = perf_aux_output_begin(&handle, event);
+	if (aux_buf) {
+		aux_buf->collect_htm_trace = 1;
+		aux_buf->head = 0;
+		perf_aux_output_end(&handle, 0);
+	}
+}
+
 /*
  * Check the return code for H_HTM hcall.
  * Return 1 if either H_PARTIAL or H_SUCCESS is returned.
@@ -191,6 +224,10 @@ static int htm_event_init(struct perf_event *event)
 	u64 config = event->attr.config;
 	struct htm_config cfg;
 	struct htm_target_id *target, *tmp;
+	u8 *status_buf;
+	long src;
+	ssize_t sret;
+	int sretries = 0;
 
 	if (event->attr.inherit)
 		return -EOPNOTSUPP;
@@ -277,6 +314,32 @@ static int htm_event_init(struct perf_event *event)
 	list_add_tail(&target->list, &htm_active_targets_list);
 	mutex_unlock(&htm_targets_lock);
 
+	/*
+	 * Query the hardware-allocated HTM buffer size via H_HTM_OP_STATUS.
+	 * The status output buffer header byte 0x01 holds
+	 * CurrentNestHtmBufferSizeInPowerOf2 (for HTM_NEST) or
+	 * CurrentCoreHtmBufferSizeInPowerOf2 (for HTM_CORE); both types
+	 * use the same offset (0x01) and length (1 byte).
+	 * hw_buf_size is used in htm_dump_sample_data() to bound dump
+	 * offsets, preventing H_HTM_OP_DUMP_DATA calls past the end of the
+	 * hardware buffer.  On failure hw_buf_size stays 0 and the boundary
+	 * check is skipped gracefully — the contiguous-window clamp still
+	 * applies.
+	 */
+	status_buf = kzalloc(PAGE_SIZE, GFP_KERNEL);
+	if (status_buf) {
+		do {
+			src = htm_hcall_wrapper(htmflags, cfg.nodeindex,
+					cfg.nodalchipindex, cfg.coreindexonchip,
+					cfg.htmtype, H_HTM_OP_STATUS,
+					virt_to_phys(status_buf), PAGE_SIZE, 0);
+			sret = htm_return_check(src);
+		} while (sret == -EBUSY && ++sretries < MAX_RETRIES);
+		if (sret > 0)
+			target->hw_buf_size = 1ULL << status_buf[0x01];
+		kfree(status_buf);
+	}
+
 	event->pmu_private = target;
 	event->destroy = reset_htm_active;
 	return 0;
@@ -318,6 +381,9 @@ static void htm_event_start(struct perf_event *event, int flags)
 	if (ret > 0) {
 		target->tracing_active = HTM_TRACING_ACTIVE;
 		event->hw.state &= ~PERF_HES_STOPPED;
+
+		if (!(flags & PERF_EF_RELOAD))
+			aux_buf_reset_for_start(event);
 	}
 }
 
@@ -510,8 +576,308 @@ static void htm_event_del(struct perf_event *event, int flags)
 	/* pmu_private freed by event->destroy = reset_htm_active */
 }
 
+static ssize_t htm_dump_sample_data(struct perf_event *event)
+{
+	struct perf_output_handle handle;
+	struct htm_target_id *target = event->pmu_private;
+	struct htm_pmu_buf *aux_buf;
+	struct htm_config cfg = target->cfg;
+	u64 chunk_size, dump_offset, page_index, page_offset;
+	u64 max_contiguous_bytes, expected_phys, scan_index, actual_phys;
+	u64 hypervisor_target_phys;
+	void *target_page_virt;
+	ssize_t ret = 0;
+	int retries = 0;
+	long rc;
+
+	/* Start AUX transaction; use a stack-local handle to prevent
+	 * NMI reentrancy from corrupting an outer transaction's handle.
+	 */
+	aux_buf = perf_aux_output_begin(&handle, event);
+	if (!aux_buf)
+		return 0;
+
+	if (!aux_buf->collect_htm_trace) {
+		/*
+		 * collect_htm_trace is cleared on hcall error and reset to 1
+		 * in htm_event_start() when tracing restarts.  If it is still
+		 * 0 here the event was disabled due to a prior hard error;
+		 * end the AUX transaction and return 0 so the drain loop stops.
+		 */
+		perf_aux_output_end(&handle, 0);
+		return 0;
+	}
+
+	if (target->tracing_active == HTM_TRACING_ACTIVE) {
+		/*
+		 * First pmu->read call of the drain sequence: stop the hardware
+		 * to freeze the HTM buffer before reading it.  This is a
+		 * one-shot dump — the buffer is static for the entire drain;
+		 * the hardware is not restarted between chunks or after the
+		 * dump completes.  Restarting mid-drain would overwrite buffer
+		 * content that has not yet been transferred to the AUX ring.
+		 * A new perf record session issues H_HTM_OP_START afresh.
+		 */
+		htm_event_stop(event, 0);
+		if (target->tracing_active == HTM_TRACING_ACTIVE) {
+			/*
+			 * H_HTM_OP_STOP failed — cannot dump a live buffer.
+			 * Abort the dump; event->count = 0 stops the drain loop.
+			 * The hardware is still running; htm_event_del() will
+			 * call H_HTM_OP_DECONFIGURE which implicitly stops it,
+			 * preventing a resource leak.
+			 */
+			perf_aux_output_end(&handle, 0);
+			return -EIO;
+		}
+	}
+
+	/* Derive the exact target destination point directly out of active ring pointers */
+	dump_offset = handle.head & (aux_buf->size - 1);
+	page_index = dump_offset >> PAGE_SHIFT;
+	page_offset = dump_offset & (PAGE_SIZE - 1);
+
+	/*
+	 * Assess constraints regarding space remaining across the mapping
+	 * context boundary.
+	 * handle.size is always page-aligned: perf_aux_output_begin() computes
+	 * it as the distance from the write pointer to the wakeup boundary,
+	 * rounded to PAGE_SIZE.  Masking with PAGE_MASK is therefore a no-op
+	 * but is kept to make the page-granularity contract explicit.
+	 */
+	chunk_size = handle.size;
+	chunk_size &= PAGE_MASK;
+
+	if (chunk_size > (aux_buf->size - dump_offset))
+		chunk_size = aux_buf->size - dump_offset;
+
+	/*
+	 * HTM driver uses these capabilities:
+	 * PERF_PMU_CAP_AUX_NO_SG | PERF_PMU_CAP_AUX_PREFER_LARGE
+	 * the core perf ring-buffer allocator (rb_alloc_aux) tries to allocate
+	 * physically contiguous page block. If not available, it tries to allocate
+	 * largest possible contiguous block.
+	 *
+	 * Example: If we ask perf for 1024 pages (64MB), the kernel executes a loop
+	 * inside rb_alloc_aux() to fulfill that request using the buddy allocator. it
+	 * always tries to grab the largest possible contiguous block of memory it can
+	 * find first, then takes the next largest, and repeats until request is
+	 * completely filled. Here while writing to aux buffer, to eliminate any
+	 * virtual or physical boundary overruns, check for the page boundary.
+	 *
+	 * Dynamically scan forward page-by-page from our active page_index to
+	 * calculate the absolute boundary limit of this current physically
+	 * contiguous block chunk. Prevents hypervisor macro overruns across
+	 * asymmetrical fragmentation gaps.
+	 */
+	max_contiguous_bytes = PAGE_SIZE - page_offset;
+	scan_index = page_index + 1;
+	expected_phys = (u64)virt_to_phys(aux_buf->pages[page_index]) + PAGE_SIZE;
+
+	while (scan_index < aux_buf->nr_pages && max_contiguous_bytes < chunk_size) {
+		actual_phys = (u64)virt_to_phys(aux_buf->pages[scan_index]);
+
+		if (actual_phys != expected_phys)
+			break; /* Intersected a fragmentation boundary block link! */
+
+		max_contiguous_bytes += PAGE_SIZE;
+		expected_phys += PAGE_SIZE;
+		scan_index++;
+	}
+
+	/* Bound transfer length tightly within the validated contiguous window */
+	if (chunk_size > max_contiguous_bytes)
+		chunk_size = max_contiguous_bytes;
+
+	/*
+	 * Bound the dump to the hardware-allocated buffer size reported by
+	 * H_HTM_OP_STATUS (stored in target->hw_buf_size at configure time).
+	 * aux_buf->head is the byte offset of the next chunk to dump; once
+	 * it reaches hw_buf_size the hardware buffer is exhausted and no
+	 * further H_HTM_OP_DUMP_DATA calls should be issued.
+	 * hw_buf_size == 0 means the status hcall failed at configure time;
+	 * skip the check and let the hcall itself signal end-of-data.
+	 */
+	if (target->hw_buf_size) {
+		if (aux_buf->head >= target->hw_buf_size) {
+			aux_buf->collect_htm_trace = 0;
+			perf_aux_output_end(&handle, 0);
+			return 0;
+		}
+		if (chunk_size > target->hw_buf_size - aux_buf->head)
+			chunk_size = target->hw_buf_size - aux_buf->head;
+	}
+
+	if (!chunk_size) {
+		/*
+		 * No space in the AUX ring buffer right now.  Leave
+		 * collect_htm_trace set. Return -ENOSPC so htm_event_read()
+		 * keeps event->count non-zero, signalling to the caller that
+		 * collection is still ongoing and another pmu->read pass
+		 * should be attempted once the consumer has drained the buffer.
+		 */
+		perf_aux_output_end(&handle, 0);
+		return -ENOSPC;
+	}
+
+	/*
+	 * Compute the precise base target address using
+	 * localized page offset rules
+	 */
+	target_page_virt = aux_buf->pages[page_index];
+	hypervisor_target_phys = (u64)virt_to_phys(target_page_virt) + page_offset;
+
+	do {
+		/*
+		 * Invoke H_HTM call with:
+		 * - operation as htm dump (H_HTM_OP_DUMP_DATA)
+		 * - last three values are address, size and offset
+		 */
+		rc = htm_hcall_wrapper(htmflags, cfg.nodeindex, cfg.nodalchipindex,
+				cfg.coreindexonchip, cfg.htmtype, H_HTM_OP_DUMP_DATA,
+				hypervisor_target_phys, chunk_size, aux_buf->head);
+		ret = htm_return_check(rc);
+	} while (ret == -EBUSY && ++retries < MAX_RETRIES);
+
+	if (ret > 0) {
+		aux_buf->head += chunk_size;
+		perf_aux_output_end(&handle, chunk_size);
+		/*
+		 * Return the number of 128-byte HTM trace records written.
+		 * Dividing here keeps htm_event_read() free of format
+		 * knowledge: it can simply use the returned count directly,
+		 * regardless of which data path (AUX trace or memory config)
+		 * produced it.
+		 */
+		return (ssize_t)(chunk_size / 128);
+	}
+
+	/*
+	 * Hcall failed.  All non-success paths end collection for this
+	 * buffer session.
+	 */
+	aux_buf->collect_htm_trace = 0;
+	perf_aux_output_end(&handle, 0);
+	return ret;
+}
+
 static void htm_event_read(struct perf_event *event)
 {
+	ssize_t ret;
+
+	/*
+	 * Refuse to run from NMI context.  htm_dump_sample_data() issues
+	 * hypervisor calls, mutates target->tracing_active, and writes
+	 * aux_buf->head — none of which are NMI-safe.
+	 *
+	 * perf_event_read_local() (used by BPF helpers such as
+	 * bpf_perf_event_read_value()) does not check PERF_PMU_CAP_NO_NMI,
+	 * so an explicit in_nmi() guard here is required.
+	 *
+	 * Returning without touching event->count preserves whatever value
+	 * was set by the previous pmu->read() call.  If the drain is still
+	 * in progress, event->count remains non-zero and the drain loop
+	 * keeps retrying.  The next scheduled pmu->read() — which will not
+	 * be in NMI context — will proceed normally and complete the dump.
+	 * This mirrors the stack-local handle fix: both let the NMI path
+	 * return without mutating any shared state.
+	 */
+	if (in_nmi())
+		return;
+
+	ret = htm_dump_sample_data(event);
+	/*
+	 * htm_dump_sample_data() returns the record count directly
+	 * (already divided by the per-format record size):
+	 *   AUX trace path:   chunk_size / 128  (128-byte HTM records)
+	 *   Memory cfg path:  to_copy    /  32  (32-byte entries)
+	 *
+	 * ret > 0:        record count written; use directly as event->count.
+	 * ret == -ENOSPC: AUX buffer full, hypervisor stream intact;
+	 *                 count = 1 so the drain loop keeps retrying
+	 *                 once the consumer has drained the buffer.
+	 * ret <= 0:       EOF, stop failed, or hard error; count = 0
+	 *                 so the drain loop stops cleanly.
+	 *
+	 * event->count does not represent an instruction or cycle count;
+	 * actual trace records are decoded in userspace by the perf tool.
+	 */
+	if (ret > 0)
+		local64_set(&event->count, ret);
+	else if (ret == -ENOSPC)
+		local64_set(&event->count, 1);
+	else
+		local64_set(&event->count, 0);
+}
+
+/*
+ * Set up pmu-private data structures for an AUX area
+ * **pages contains the aux buffer allocated for this event
+ * for the corresponding cpu. rb_alloc_aux uses "alloc_pages_node"
+ * and returns pointer to each page address.
+ * PMU capabilities: PERF_PMU_CAP_AUX_NO_SG | PERF_PMU_CAP_AUX_PREFER_LARGE
+ * to try get closest possible physically contiguous page blocks.
+ *
+ * The aux private data structure ie, "struct htm_pmu_buf" mainly
+ * saves
+ * - buf->base: aux buffer base address
+ * - buf->head: offset from base address where data will be written to.
+ * - buf->size: Size of allocated memory
+ */
+static void *htm_setup_aux(struct perf_event *event, void **pages,
+		int nr_pages, bool snapshot)
+{
+	int cpu = event->cpu;
+	struct htm_pmu_buf *buf;
+
+	if (!nr_pages)
+		return NULL;
+
+	/*
+	 * Snapshot (overwrite) mode is not supported.  In overwrite mode
+	 * perf_aux_output_begin() leaves handle->size = 0, which would
+	 * cause htm_dump_sample_data() to return ENOSPC on every call,
+	 * setting event->count = 1 and creating an infinite drain loop
+	 * in userspace.  Reject it here so perf_event_open() returns
+	 * EINVAL to the caller.
+	 */
+	if (snapshot)
+		return NULL;
+
+	if (cpu == -1)
+		cpu = raw_smp_processor_id();
+
+	buf = kzalloc_node(sizeof(*buf), GFP_KERNEL, cpu_to_node(cpu));
+	if (!buf)
+		return NULL;
+
+	buf->nr_pages = nr_pages;
+	buf->snapshot = snapshot;
+	buf->size = (u64)nr_pages << PAGE_SHIFT;
+	buf->pages = pages;
+
+	buf->base = pages[0];
+	if (!buf->base) {
+		kfree(buf);
+		return NULL;
+	}
+
+	buf->collect_htm_trace = 1;
+	buf->head = 0;
+	return buf;
+}
+
+/*
+ * free pmu-private AUX data structures
+ */
+static void htm_free_aux(void *aux)
+{
+	struct htm_pmu_buf *buf = aux;
+
+	if (!buf)
+		return;
+
+	kfree(buf);
 }
 
 static struct pmu htm_pmu = {
@@ -524,7 +890,10 @@ static struct pmu htm_pmu = {
 	.read         = htm_event_read,
 	.start        = htm_event_start,
 	.stop         = htm_event_stop,
-	.capabilities = PERF_PMU_CAP_NO_EXCLUDE | PERF_PMU_CAP_EXCLUSIVE,
+	.setup_aux    = htm_setup_aux,
+	.free_aux     = htm_free_aux,
+	.capabilities = PERF_PMU_CAP_NO_EXCLUDE | PERF_PMU_CAP_EXCLUSIVE
+			| PERF_PMU_CAP_AUX_NO_SG | PERF_PMU_CAP_AUX_PREFER_LARGE,
 };
 
 static int htm_init(void)
Signature · 1 line
2.53.0
#6 lore raw

PATCH v5 4/6 powerpc/perf: Capture the HTM memory configuration as part of perf data

In reply to Athira Rajeev

The H_HTM hypervisor call can also return the system memory configuration, which describes the physical to logical real address mapping for logical partitions.

After dumping HTM trace data into the AUX buffer, capture the corresponding HTM system memory configuration records and emit them as raw perf sample data for userspace parsing.

Add AUX-private tracking for a hypervisor memory-configuration dump buffer and iterator state. Once AUX trace dumping completes, htm_event_read() calls htm_collect_memory_config() which issues one H_HTM_OP_DUMP_SYSMEM_CONF hcall and emits the result as a single PERF_SAMPLE_RAW record, then returns immediately. The perf drain loop calls htm_event_read() repeatedly until event->count reaches zero, giving userspace a chance to drain the ring buffer between every record. This mirrors the AUX trace path design and avoids the ring-buffer-overflow problem that a while(true) loop would create.

Trace payload continues to be written to the AUX buffer, while memory configuration records are emitted as raw perf samples. This keeps the AUX stream focused on trace data and allows the configuration records to be decoded separately in userspace.

The hypervisor fills as many 32-byte entries as fit within the buffer size passed to H_HTM_OP_DUMP_SYSMEM_CONF — it does not cap at a fixed entry count. Observed maximum fill is 64480 bytes (2015 entries at 32 bytes each plus a 32-byte header). HTM_MEM_BUF_SIZE is therefore defined as the allocation size (65440 bytes) and HTM_MEM_MAX_ENTRIES is derived from it ((HTM_MEM_BUF_SIZE - 32) / 32 = 2043), not the other way around. This ensures the hcall is always told the true buffer size and the WARN_ON_ONCE(to_copy > HTM_MEM_BUF_SIZE) guard is a genuine impossibility check rather than a post-overflow assertion.

HTM_MEM_BUF_SIZE = 65440 is the largest multiple of 32 that satisfies both constraints: it exceeds the observed 64480-byte maximum fill by 960 bytes of headroom, and the resulting perf record (65440 + 92 bytes of fixed overhead = 65532) stays below 65535, the __u16 limit of perf_event_header.size. The 92-byte overhead is: 8 (perf_event_header)
+ 64 (header_size worst case: 8 u64 sample fields) + 16 (id_header_size worst case) + 4 (PERF_SAMPLE_RAW u32 size prefix).

perf_fetch_caller_regs() is used to initialise the pt_regs argument passed to perf_event_overflow(). An uninitialised stack frame would leak kernel stack bytes to userspace if the event is opened with PERF_SAMPLE_REGS_INTR. This follows the pattern used by tracepoints and BPF perf-event helpers for synthetic sample emission.

When perf_event_overflow() throttles the event (returns non-zero), overflow_handler has already run unconditionally (writing the sample to the ring buffer) before the non-zero return. mem_start is therefore advanced so the same block is not emitted again, and -ENOSPC is returned so event->count is set to 1 and the drain loop keeps retrying to emit the next block once the event is unthrottled.

Keep HTM tracing state in event->pmu_private via htm_target_id. AUX private state is used only for dump progress and staging buffers.

Concurrency and locking:

target->tracing_active and target->configured:

Every read and write of these fields occurs in pmu->add(), pmu->del(), pmu->start(), pmu->stop(), and pmu->read(). All of these callbacks are invoked by the perf core under ctx->lock with IRQs disabled (event_sched_in/out, __perf_event_read). IRQs disabled means regular interrupts cannot preempt these paths. NMI can still fire — but see below.

aux_buf->head and aux_buf->collect_htm_trace:

These fields are only written from htm_dump_sample_data() (called from pmu->read()), which is also under ctx->lock with IRQs disabled. Additionally, perf_aux_output_begin() increments rb->aux_nest on entry and perf_aux_output_end() decrements it on exit. If an NMI fires while an AUX transaction is open (aux_nest > 0), any nested perf_aux_output_begin() call hits the WARN_ON_ONCE(nest) guard and returns NULL immediately — the NMI path exits without touching aux_buf->head or any other shared state.

BPF NMI path (perf_event_read_local):

The only kernel path that calls pmu->read() without holding ctx->lock is perf_event_read_local(), used by BPF helpers such as bpf_perf_event_read_value(). perf_event_read_local() does not check PERF_PMU_CAP_NO_NMI, so it can invoke pmu->read() from NMI context.

htm_event_read() guards against this with an explicit in_nmi() check at entry: if called from NMI, it returns immediately without touching event->count, target->tracing_active, aux_buf->head, or issuing any hcall. event->count retains its previous value, so if the drain is in progress the drain loop remains alive and the next scheduled pmu->read() (not in NMI context) completes the dump.

Additionally, htm_event_init() (patch 2) prevents a second perf_event_open() for the same target (returns -EBUSY), so a BPF session and a perf session cannot hold the same target concurrently. The in_nmi() guard is defence-in-depth against any future path that bypasses this reservation.

No additional locking is required beyond ctx->lock (for target fields) and rb->aux_nest (for AUX buffer fields).

Ring buffer full and silent drop of memory configuration records:

htm_collect_memory_config() uses perf_event_overflow() to emit records to the main ring buffer. perf_event_overflow() returns non-zero only when the event is throttled; it returns 0 both when the sample is written successfully and when perf_output_begin() fails because the ring buffer is full (in the latter case the sample is silently dropped inside perf_output_sample()). In both 0-return cases aux_buf->mem_start is advanced. This is the same behaviour as tracepoints and BPF perf event helpers: when the ring buffer is full, records are dropped and the iterator advances. The alternative — stalling the iterator on drop — would loop forever whenever the ring buffer stayed full, blocking the drain loop. Dropped records are visible to userspace through the PERF_RECORD_LOST counter in the ring buffer header.

---
Changes in V5:
- htm_collect_memory_config(): zero struct pt_regs regs with memset() before calling perf_fetch_caller_regs(). perf_fetch_caller_regs() only initialises nip, msr, and gpr[1]; the remaining fields are left as uninitialised stack bytes. Defensive zeroing prevents potential kernel stack leakage and matches the pattern in trace_event_perf.c and bpf_trace.c.
- htm_dump_sample_data(): handle perf_aux_output_begin() returning NULL while memory-configuration collection is still in progress. When the AUX ring buffer is full, perf_aux_output_begin() returns NULL and the function previously returned 0, signalling EOF to htm_event_read() and permanently abandoning the mem-config drain. The fix retrieves aux_buf via perf_get_aux() and, if collect_htm_trace is already clear but collect_htm_mem is still set, calls htm_collect_memory_config() directly, keeping the drain alive independently of AUX ring pressure.

Changes in V4:
- htm_collect_memory_config(): restructured from a while(true) loop to a single-hcall-per-call design, mirroring the AUX trace path. The old loop had no way to break out when the ring buffer filled mid-loop:
perf_event_overflow() returns 0 for both "written" and "ring buffer full / dropped", so iteration would continue, dropping every subsequent record with no chance for userspace to drain the buffer. With one hcall per call, the drain loop (arch_perf_record__need_read) calls htm_event_read() → htm_collect_memory_config() once per pass, userspace drains the ring buffer between passes, and ring buffer pressure is handled naturally.
- htm_collect_memory_config(): on non-zero return from perf_event_overflow() (event throttled), advance mem_start before returning -ENOSPC. overflow_handler runs unconditionally inside __perf_event_overflow() before the non-zero return, so the sample WAS written to the ring buffer. The old code did not advance mem_start on throttle, causing the same block to be emitted again on the next call — a duplicate sample bug.
- htm_setup_aux() / htm_free_aux(): removed emit_buf. emit_buf was a second HTM_MEM_BUF_SIZE allocation used to keep raw.frag.data stable across loop iterations (htm_mem_buf was overwritten by the next hcall). With no loop, htm_mem_buf is not reused within a single call, so it is stable throughout perf_event_overflow() and no memcpy or second buffer is needed.
- htm_setup_aux(): changed kmalloc_node to kzalloc_node for htm_mem_buf. The buffer is passed to the hypervisor and subsequently read by the perf core; kzalloc_node ensures uninitialized heap bytes are never exposed if the hypervisor leaves reserved fields or padding untouched.
- HTM_MEM_BUF_SIZE / PERF_SAMPLE_REGS_INTR: no change needed here. PERF_SAMPLE_REGS_INTR is now rejected in htm_event_init() (patch 1), so the 92-byte fixed overhead used in the HTM_MEM_BUF_SIZE calculation is accurate for all sample types this driver accepts.
- struct pt_regs initialisation: no change needed. perf_fetch_caller_regs() was already added in V3 (see "Changes in V3" below). The reviewer was looking at V2 code.

Changes in V3:
- Fixed HTM_MEM_BUF_SIZE defined as (32 + 2013 * 32 = 64448 bytes) while the hypervisor actually fills up to 64480 bytes (2015 entries) when given a sufficiently large buffer — overflowing the allocation by 32 bytes. The hypervisor fills as many entries as fit within the given buffer size; it does not cap at a fixed entry count. Fixed by redefining HTM_MEM_BUF_SIZE as 65440U (the largest multiple of 32 fitting in perf_event_header.size __u16 with 92 bytes of worst-case header overhead: 65440 + 92 = 65532 < 65535) and deriving HTM_MEM_MAX_ENTRIES from it ((HTM_MEM_BUF_SIZE - 32) / 32 = 2043). The buffer now covers the observed maximum with 960 bytes headroom, and the WARN_ON_ONCE guard is a genuine impossibility check.
- Fixed htm_mem_buf allocated as PAGE_SIZE (4096 bytes on 4K-page configs) while the hypervisor was told the buffer length is HTM_MEM_BUF_SIZE. Changed to kmalloc_node with HTM_MEM_BUF_SIZE.
- Fixed uninitialized struct pt_regs regs passed to perf_event_overflow(). If the event is opened with PERF_SAMPLE_REGS_INTR the perf core reads these bytes into the ring buffer, leaking kernel stack memory to userspace. Added perf_fetch_caller_regs(&regs) after the declaration block, following the pattern in kernel/trace/trace_event_perf.c and kernel/trace/bpf_trace.c.
- Clarified the perf_event_overflow() throttle path: added a comment distinguishing the throttle path (collect_htm_mem left set, -ENOSPC returned) from the error/EOF paths that clear collect_htm_mem.

Changes in V2:
- Memory configuration records are now emitted as PERF_SAMPLE_RAW samples directly by htm_event_read() after the AUX trace dump completes, using H_HTM_OP_DUMP_SYSMEM_CONF. V1 embedded the configuration data inside the AUX buffer itself and used two PERF_SAMPLE_RAW boundary markers (start/end) to delimit it.
- The two-marker boundary scheme is removed. There is no longer any interleaving of memory configuration data inside the AUX stream; the AUX buffer carries only bus-trace data.
- Separate AUX-private fields for a hypervisor dump buffer and iterator state are introduced to manage the SYSMEM_CONF drain.
- Tracing state remains in event->pmu_private (htm_target_id); AUX private state is used only for dump progress and staging buffers, consistent with the restructuring in patches 1 and 3.

 arch/powerpc/perf/htm-perf.c | 210 ++++++++++++++++++++++++++++++++++-
 1 file changed, 206 insertions(+), 4 deletions(-)
arch/powerpc/perf/htm-perf.c +206 -4
index f72ee661c084..ec1ce1457764 100644
@@ -108,6 +108,9 @@ struct htm_pmu_buf {
 	u64	head;
 	u64     size;
 	int     collect_htm_trace;
+	void    *htm_mem_buf;	/* Staging area for H_HTM_OP_DUMP_SYSMEM_CONF hcall */
+	u64     mem_start;	/* Hypervisor iterator position for DUMP_SYSMEM_CONF */
+	int     collect_htm_mem;	/* State flag tracking whether memory logging is ongoing */
 };
 
 /*
@@ -203,6 +206,168 @@ static ssize_t htm_return_check(int rc)
 #define HTM_TRACING_ACTIVE	1
 #define HTM_TRACING_INACTIVE	0
 
+/*
+ * HTM_MEM_BUF_SIZE is the allocation size for the hcall staging buffer.
+ * The hypervisor fills as many 32-byte entries as fit within the buffer
+ * size passed to H_HTM_OP_DUMP_SYSMEM_CONF — it does not cap at a fixed
+ * entry count.
+ *
+ * HTM_MEM_BUF_SIZE is chosen to satisfy two constraints:
+ *
+ *   1. The full perf record (perf_event_header + fixed sample fields +
+ *      PERF_SAMPLE_RAW u32 size prefix + to_copy) must fit in
+ *      perf_event_header.size which is __u16 (max 65535):
+ *        overhead = 8 (perf_event_header)
+ *                 + 64 (header_size, worst case: 8 u64 sample fields)
+ *                 + 16 (id_header_size, worst case)
+ *                 +  4 (PERF_SAMPLE_RAW u32 size prefix)
+ *                 = 92 bytes
+ *        to_copy <= 65535 - 92 = 65443
+ *        round down to multiple of 32: 65440
+ *
+ *   2. HTM_MEM_BUF_SIZE must be a multiple of 32 so a whole number of
+ *      32-byte entries fill it exactly.
+ *
+ * 65440 = 32 + 2043 * 32 is the largest multiple of 32 satisfying all
+ * constraints:
+ *   - total record: 65440 + 92 = 65532 < 65535 (3-byte u16 margin)
+ *
+ * HTM_MEM_MAX_ENTRIES is derived from HTM_MEM_BUF_SIZE — not the other
+ * way around — so the hcall is always given the true buffer size and
+ * the WARN_ON_ONCE(to_copy > HTM_MEM_BUF_SIZE) guard is a genuine
+ * impossibility check rather than a post-overflow assertion.
+ */
+#define HTM_MEM_BUF_SIZE	65440U
+#define HTM_MEM_MAX_ENTRIES	((HTM_MEM_BUF_SIZE - 32) / 32)	/* 2043 */
+
+/*
+ * htm_collect_memory_config - issue one H_HTM_OP_DUMP_SYSMEM_CONF hcall
+ * and emit the result as a single PERF_SAMPLE_RAW record.
+ *
+ * Mirrors the AUX trace path: one hcall per call, return immediately.
+ * htm_dump_sample_data() calls this once per htm_event_read() invocation;
+ * the perf drain loop calls htm_event_read() repeatedly until
+ * event->count reaches zero, giving userspace a chance to drain the ring
+ * buffer between every record.  This avoids the ring-buffer-overflow
+ * problem that a while(true) loop would create: if the ring buffer fills
+ * mid-loop there is no way to break out and let userspace drain it.
+ *
+ * Returns the number of 32-byte memory configuration entries emitted
+ * (to_copy / 32) on success, -ENOSPC if throttled (sample was written,
+ * event temporarily paused — advance mem_start, retry next block next
+ * call), 0 if the stream ended normally, or a negative error code on
+ * hard failure.  The caller uses the return value directly as
+ * event->count, consistent with the AUX trace path returning count..
+ */
+static ssize_t htm_collect_memory_config(struct perf_event *event,
+					 struct htm_pmu_buf *aux_buf)
+{
+	struct perf_sample_data data;
+	struct perf_raw_record raw;
+	struct pt_regs regs;
+	u8 *htm_mem_buf = aux_buf->htm_mem_buf;
+	__be64 *num_entries;
+	u64 next_start;
+	u64 to_copy;
+	long rc;
+	ssize_t ret;
+	int retries = 0;
+
+	/*
+	 * Zero the full pt_regs before fetching the caller context.
+	 * perf_fetch_caller_regs() on PowerPC only initialises nip, msr,
+	 * gpr[1], and result; all other fields (link, ctr, xer, remaining
+	 * GPRs) would otherwise contain uninitialized stack bytes.  If the
+	 * event is opened with PERF_SAMPLE_CALLCHAIN, perf_callchain_kernel()
+	 * reads regs->link and writes it to the ring buffer, leaking kernel
+	 * stack memory to userspace.  PERF_SAMPLE_CALLCHAIN is rejected in
+	 * htm_event_init(), but zeroing here is the safe defensive practice
+	 * used by tracepoints and BPF perf-event helpers.
+	 */
+	memset(&regs, 0, sizeof(regs));
+	perf_fetch_caller_regs(&regs);
+
+	/* Issue one hcall with the current iterator position */
+	do {
+		rc = htm_hcall_wrapper(htmflags, 0, 0, 0,
+				       0, H_HTM_OP_DUMP_SYSMEM_CONF,
+				       virt_to_phys(aux_buf->htm_mem_buf),
+				       HTM_MEM_BUF_SIZE, aux_buf->mem_start);
+		ret = htm_return_check(rc);
+	} while (ret == -EBUSY && ++retries < MAX_RETRIES);
+
+	/*
+	 * ret == 0 (H_NOT_AVAILABLE): normal end of stream.
+	 * ret < 0 (error): hard failure.
+	 * Both cases: clear collect_htm_mem so the next htm_event_read()
+	 * call does not re-enter, and return so event->count is set to 0.
+	 */
+	if (ret <= 0) {
+		aux_buf->collect_htm_mem = 0;
+		return ret;
+	}
+
+	/*
+	 * Read next iterator value and payload size from the hcall response.
+	 * next_start == 0 means this is the last batch.
+	 */
+	next_start = be64_to_cpu(*((__be64 *)(htm_mem_buf + 0x8)));
+	num_entries = (__be64 *)(htm_mem_buf + 0x10);
+	to_copy = 32 + (be64_to_cpu(*num_entries) * 32);
+
+	if (WARN_ON_ONCE(to_copy > HTM_MEM_BUF_SIZE)) {
+		aux_buf->collect_htm_mem = 0;
+		return -EIO;
+	}
+
+	/*
+	 * htm_mem_buf is stable for the duration of this single call —
+	 * no loop reuse, so raw.frag.data remains valid throughout
+	 * perf_event_overflow().  No memcpy to a separate emit_buf needed.
+	 */
+	perf_sample_data_init(&data, 0, event->hw.last_period);
+	memset(&raw, 0, sizeof(raw));
+	raw.frag.data = htm_mem_buf;
+	raw.frag.size = to_copy;
+	perf_sample_save_raw_data(&data, event, &raw);
+
+	if (perf_event_overflow(event, &data, &regs)) {
+		/*
+		 * Event throttled: overflow_handler ran unconditionally before
+		 * returning, so the sample WAS written to the ring buffer.
+		 * Advance mem_start so the same block is not emitted again.
+		 * Return -ENOSPC so htm_event_read() sets event->count=1,
+		 * keeping the drain loop alive to emit the next block once
+		 * the event is unthrottled.
+		 */
+		aux_buf->mem_start = next_start;
+		if (!next_start)
+			aux_buf->collect_htm_mem = 0;
+		return -ENOSPC;
+	}
+
+	/*
+	 * perf_event_overflow() returns 0 for both "sample written" and
+	 * "ring buffer full, sample dropped" (perf_output_begin() failure
+	 * inside perf_output_sample() is silent).  Advance the iterator in
+	 * both cases.  This matches tracepoint / BPF perf-event helper
+	 * behaviour: when the ring buffer is full, records are dropped and
+	 * the stream continues.  Stalling the iterator on drop would loop
+	 * forever if the ring stayed full.  Dropped records are counted in
+	 * the PERF_RECORD_LOST entry in the ring buffer header.
+	 */
+	aux_buf->mem_start = next_start;
+	if (!next_start)
+		aux_buf->collect_htm_mem = 0;
+
+	/*
+	 * Return the number of 32-byte entries emitted.  Dividing here keeps
+	 * htm_event_read() free of format knowledge, consistent with the AUX
+	 * trace path returning chunk_size / 128.
+	 */
+	return (ssize_t)(to_copy / 32);
+}
+
 static void reset_htm_active(struct perf_event *event)
 {
 	struct htm_target_id *target = event->pmu_private;
@@ -594,10 +759,25 @@ static ssize_t htm_dump_sample_data(struct perf_event *event)
 	 * NMI reentrancy from corrupting an outer transaction's handle.
 	 */
 	aux_buf = perf_aux_output_begin(&handle, event);
-	if (!aux_buf)
+	if (!aux_buf) {
+		/*
+		 * AUX ring buffer is full: perf_aux_output_begin() returned NULL.
+		 * If the AUX trace dump is already complete but memory
+		 * configuration collection is still in progress, we must not
+		 * return 0 here — that would signal EOF to htm_event_read() and
+		 * permanently abandon the mem config drain.  Memory config
+		 * records go to the main ring buffer via perf_event_overflow(),
+		 * which is entirely independent of the AUX ring.  Retrieve the
+		 * aux_buf from the ring's aux_private and call directly.
+		 */
+		struct htm_pmu_buf *fb = perf_get_aux(&handle);
+
+		if (fb && !fb->collect_htm_trace && fb->collect_htm_mem)
+			return htm_collect_memory_config(event, fb);
 		return 0;
+	}
 
-	if (!aux_buf->collect_htm_trace) {
+	if (!aux_buf->collect_htm_trace && !aux_buf->collect_htm_mem) {
 		/*
 		 * collect_htm_trace is cleared on hcall error and reset to 1
 		 * in htm_event_start() when tracing restarts.  If it is still
@@ -632,6 +812,11 @@ static ssize_t htm_dump_sample_data(struct perf_event *event)
 		}
 	}
 
+	if (!aux_buf->collect_htm_trace) {
+		ret = htm_collect_memory_config(event, aux_buf);
+		goto out;
+	}
+
 	/* Derive the exact target destination point directly out of active ring pointers */
 	dump_offset = handle.head & (aux_buf->size - 1);
 	page_index = dump_offset >> PAGE_SHIFT;
@@ -701,8 +886,8 @@ static ssize_t htm_dump_sample_data(struct perf_event *event)
 	if (target->hw_buf_size) {
 		if (aux_buf->head >= target->hw_buf_size) {
 			aux_buf->collect_htm_trace = 0;
-			perf_aux_output_end(&handle, 0);
-			return 0;
+			ret = htm_collect_memory_config(event, aux_buf);
+			goto out;
 		}
 		if (chunk_size > target->hw_buf_size - aux_buf->head)
 			chunk_size = target->hw_buf_size - aux_buf->head;
@@ -757,6 +942,8 @@ static ssize_t htm_dump_sample_data(struct perf_event *event)
 	 * buffer session.
 	 */
 	aux_buf->collect_htm_trace = 0;
+	ret = htm_collect_memory_config(event, aux_buf);
+out:
 	perf_aux_output_end(&handle, 0);
 	return ret;
 }
@@ -862,7 +1049,21 @@ static void *htm_setup_aux(struct perf_event *event, void **pages,
 		return NULL;
 	}
 
+	/*
+	 * htm_mem_buf is the staging area passed directly to the
+	 * H_HTM_OP_DUMP_SYSMEM_CONF hcall.  The hypervisor is told the
+	 * buffer length is HTM_MEM_BUF_SIZE; allocate exactly
+	 * that amount.  See the HTM_MEM_BUF_SIZE comment for the derivation.
+	 */
+	buf->htm_mem_buf = kzalloc_node(HTM_MEM_BUF_SIZE, GFP_KERNEL, cpu_to_node(cpu));
+	if (!buf->htm_mem_buf) {
+		kfree(buf);
+		return NULL;
+	}
+
 	buf->collect_htm_trace = 1;
+	buf->collect_htm_mem = 1;
+	buf->mem_start = 0;
 	buf->head = 0;
 	return buf;
 }
@@ -877,6 +1078,7 @@ static void htm_free_aux(void *aux)
 	if (!buf)
 		return;
 
+	kfree(buf->htm_mem_buf);
 	kfree(buf);
 }
 
Signature · 1 line
2.53.0
#8 lore raw

PATCH v5 5/6 docs: ABI: sysfs-bus-event_source-devices-htm: Document sysfs event format entries for htm pmu

In reply to Athira Rajeev

Add ABI documentation for the sysfs entries exposed by the "htm" PMU under /sys/bus/event_source/devices/htm/.

Document the format attribute group, which describes the bit layout of perf_event_attr.config accepted by the htm PMU:

  event            config bits  0-27  (composite: all fields combined)
  htm_type         config bits  0-3   (HTM_CORE=2, HTM_NEST=1, HTM_LLAT=3)
  nodeindex        config bits  4-11
  nodalchipindex   config bits 12-19
  coreindexonchip  config bits 20-27

Document the events attribute group, which provides named aliases for the three supported HTM event types. Users can pass these names directly to perf:

  # perf record -e htm/htm_core/ ...
  # perf record -e htm/htm_nest/ ...
  # perf record -e htm/htm_llat/ ...

---
Changes in V5:
- Document HTM_LLAT=3 in the htm_type format attribute entry.

Changes in V3:
- Fixed the format/ attribute table: the doc listed only the composite 'event' attribute (config:0-27) but omitted the four individual format attributes (htm_type, nodeindex, nodalchipindex, coreindexonchip) that the commit message described and the driver exposes. Added all four with their correct bit ranges and a 'For example::' block showing htm_core and htm_nest mappings.
- Fixed the events/ example in the commit message: the previous example used format-group key=value syntax (htm/nodalchipindex=2,nodeindex=0,htm_type=1/) which conflates the format group with the events group. The events group provides named aliases; the correct examples are 'htm/htm_core/' and 'htm/htm_nest/'.
- Fixed grammar: "Supported attribute are" -> "Supported attributes are".

Changes in V2:
- Updated the bit-range descriptions to match the V2 config layout:
htm_type is bits 0-3 (was listed inconsistently in V1), nodeindex is bits 4:11, nodalchipindex is bits 12:19, coreindexonchip is bits 20-27.
- Added documentation for the events/ sysfs group which lists named events users can pass directly to perf. This group was not documented in V1.
- Patch is now 5/6 instead of 4/5.

 .../sysfs-bus-event_source-devices-htm        | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-event_source-devices-htm
Documentation/ABI/testing/sysfs-bus-event_source-devices-htm new file +36 -0
new file mode 100644
index 000000000000..141fe8e9952b
@@ -0,0 +1,36 @@
+What:           /sys/bus/event_source/devices/htm/format
+Date:           June 2026
+Contact:        Linux on PowerPC Developer List <linuxppc-dev at lists.ozlabs.org>
+Description:    Read-only. Attribute group to describe the magic bits
+                that go into perf_event_attr.config for a particular pmu.
+                (See ABI/testing/sysfs-bus-event_source-devices-format).
+
+                Each attribute under this group defines a bit range of the
+                perf_event_attr.config. Supported attributes are listed
+                below::
+
+                  event           = "config:0-27"  - composite event ID
+                  htm_type        = "config:0-3"   - HTM type (HTM_CORE=2, HTM_NEST=1, HTM_LLAT=3)
+                  nodeindex       = "config:4-11"  - node index
+                  nodalchipindex  = "config:12-19" - nodal chip index
+                  coreindexonchip = "config:20-27" - core index on chip
+
+                For example::
+
+                  htm_core = "htm_type=2"
+                  htm_nest = "htm_type=1"
+		  htm_llat = "htm_type=3"
+
+What:           /sys/bus/event_source/devices/htm/events
+Date:           June 2026
+Contact:        Linux on PowerPC Developer List <linuxppc-dev at lists.ozlabs.org>
+Description:    Read-only. Attribute group to describe performance monitoring
+                events for the Hardware Trace Macro (HTM) trace. Each attribute
+                in this group describes a single performance monitoring event
+                supported by htm pmu.  The name of the file is the name of
+                the event (See ABI/testing/sysfs-bus-event_source-devices-events).
+
+                For example::
+			# perf record -e htm/htm_core/
+			# perf record -e htm/htm_nest/
+			# perf record -e htm/htm_llat/
Signature · 1 line
2.53.0
#9 lore raw

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

In reply to Athira Rajeev

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.tX raw bus-trace AUX data
translation.nX.pX.cX.tX 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.

---
Changes in V5:
- Update all output filenames in examples to include the .tX trace-type suffix (e.g. htm.bin.n0.p2.c0.t1, translation.n0.p2.c0.t1) to match the new write_htm() naming scheme that disambiguates core HTM (htm_type=2) from nest HTM (htm_type=1) and HTM_LLAT (htm_type=3) targets that share the same node/chip/core coordinates.

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.tX and translation.nX.pX.cX.tX), 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(-)
Documentation/arch/powerpc/htm.rst +155 -3
index fcb4eb6306b1..42ad9924a7f6 100644
@@ -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**.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
+
+.. 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
+
+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.t1
+   ls translation.*      # translation.n0.p2.c0.t1
+   ls perf.data
+
+   # Step 4: Decode the trace
+   htmdecoder <decode_options> htm.bin.n0.p2.c0.t1
+
+Benefits of using HTM interface
 =======================================
 
 It is now possible to collect traces for a particular core/chip
Signature · 1 line
2.53.0
#10 lore raw

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

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…

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 <[email protected]>

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.

Quoted 4 lines
Documentation/arch/powerpc/htm.rst +0 -0
index fcb4eb6306b16..42ad9924a7f6a 100644

[ ... ]

Quoted 7 lines
Documentation/arch/powerpc/htm.rst +2 -1
@@ -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
+========================

[ ... ]

Documentation/arch/powerpc/htm.rst This trace file will contain the relevant instruction traces · line 200

Quoted 8 lines
Documentation/arch/powerpc/htm.rst +8 -0
+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.

Quoted 6 lines
Documentation/arch/powerpc/htm.rst +6 -0
+
+.. code-block:: sh
+
+   # perf report
+   # ls htm.bin.* translation.*
+   htm.bin.n0.p2.c0.t1  translation.n0.p2.c0.t1

Documentation/arch/powerpc/htm.rst This trace file will contain the relevant instruction traces · line 216

Quoted 10 lines
Documentation/arch/powerpc/htm.rst +10 -0
+
+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.

Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=6
#7 lore raw

Re: [PATCH V5 4/6] powerpc/perf: Capture the HTM memory configuration as part of perf data

In reply to Athira Rajeev
Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider: - [Critical] The fallback logic for draining memory configuration records uses an uninitialized stack…

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Critical] The fallback logic for draining memory configuration records uses an uninitialized stack variable handle when perf_aux_output_begin() fails, leading to a wild pointer dereference and a kernel crash.
- [High] The HTM_MEM_BUF_SIZE calculation assumes a worst-case fixed overhead of 92 bytes, failing to account for dynamic sample sizes when PERF_SAMPLE_READ is combined with PERF_FORMAT_GROUP. This allows the sample size to exceed 65535, overflowing perf_event_header.size and corrupting the ring buffer. --

--- Patch [4]: [PATCH V5 4/6] powerpc/perf: Capture the HTM memory configuration as part of perf data --- commit 46bf60d42ede8a36ee43812e6bfd3aeda1d041a9
Author: Athira Rajeev <[email protected]>

powerpc/perf: Capture the HTM memory configuration as part of perf data

This commit captures the HTM system memory configuration during AUX trace dumps and emits it as raw perf sample data. It adds a staging buffer for the hypervisor call and handles drain iteration alongside the AUX data path.

Quoted 4 lines
arch/powerpc/perf/htm-perf.c +0 -0
index 90d26a721616b..7e8ae35269852 100644

[ ... ]

Quoted 1 line
arch/powerpc/perf/htm-perf.c +0 -0
@@ -203,6 +206,168 @@ static ssize_t htm_return_check(int rc)

[ ... ]

arch/powerpc/perf/htm-perf.c static ssize_t htm_return_check(int rc) · line 241

Quoted 11 lines

+ * 65440 = 32 + 2043 * 32 is the largest multiple of 32 satisfying all
+ * constraints:
+ * - total record: 65440 + 92 = 65532 < 65535 (3-byte u16 margin)
+ *
+ * HTM_MEM_MAX_ENTRIES is derived from HTM_MEM_BUF_SIZE — not the other
+ * way around — so the hcall is always given the true buffer size and
+ * the WARN_ON_ONCE(to_copy > HTM_MEM_BUF_SIZE) guard is a genuine
+ * impossibility check rather than a post-overflow assertion.
+ */

arch/powerpc/perf/htm-perf.c +2 -0
+#define HTM_MEM_BUF_SIZE	65440U
+#define HTM_MEM_MAX_ENTRIES	((HTM_MEM_BUF_SIZE - 32) / 32)	/* 2043 */

[Severity: High]
Does this buffer size properly account for dynamic sample sizes when PERF_SAMPLE_READ is combined with PERF_FORMAT_GROUP?

If a large group of siblings is configured, the read format payload can scale up significantly. When htm_collect_memory_config() emits a memory configuration sample, could the computed size (65440 bytes plus the read format overhead) exceed 65535?

If it exceeds 65535, wouldn't this overflow the u16 perf_event_header.size, causing perf_output_begin() to reserve much less space than perf_output_sample() actually writes, resulting in ring buffer corruption?

[ ... ]

Quoted 7 lines
arch/powerpc/perf/htm-perf.c +2 -1
@@ -594,10 +759,25 @@ static ssize_t htm_dump_sample_data(struct perf_event *event)
 	 * NMI reentrancy from corrupting an outer transaction's handle.
 	 */
 	aux_buf = perf_aux_output_begin(&handle, event);
-	if (!aux_buf)
+	if (!aux_buf) {
+		/*

arch/powerpc/perf/htm-perf.c static ssize_t htm_dump_sample_data(struct perf_event *event) · line 773

Quoted 10 lines
arch/powerpc/perf/htm-perf.c +10 -0
+		 * AUX ring buffer is full: perf_aux_output_begin() returned NULL.
+		 * If the AUX trace dump is already complete but memory
+		 * configuration collection is still in progress, we must not
+		 * return 0 here — that would signal EOF to htm_event_read() and
+		 * permanently abandon the mem config drain.  Memory config
+		 * records go to the main ring buffer via perf_event_overflow(),
+		 * which is entirely independent of the AUX ring.  Retrieve the
+		 * aux_buf from the ring's aux_private and call directly.
+		 */
+		struct htm_pmu_buf *fb = perf_get_aux(&handle);

[Severity: Critical]
If perf_aux_output_begin() returns NULL (for instance, if the user didn't mmap an AUX buffer), does this leave the stack variable handle uninitialized?

If handle is uninitialized, wouldn't perf_get_aux(&handle) dereference uninitialized stack memory when it reads handle.event and handle.rb->aux_priv?

Quoted 6 lines
arch/powerpc/perf/htm-perf.c +4 -0
+
+		if (fb && !fb->collect_htm_trace && fb->collect_htm_mem)
+			return htm_collect_memory_config(event, fb);
 		return 0;
+	}
 
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=4
#5 lore raw

Re: [PATCH V5 3/6] powerpc/perf: Add AUX buffer management to capture HTM trace data

In reply to Athira Rajeev
Thank you for your contribution! Sashiko AI review found 3 potential issue(s) to consider: - [High] Applying PAGE_MASK to handle.size incorrectly truncates the available AUX buffer size, causing an…

Thank you for your contribution! Sashiko AI review found 3 potential issue(s) to consider:
- [High] Applying PAGE_MASK to handle.size incorrectly truncates the available AUX buffer size, causing an infinite loop for 1-page buffers and capacity loss.
- [High] Treating H_PARTIAL as a full success for H_HTM_OP_DUMP_DATA without adjusting the dump length causes trace data corruption.
- [Medium] The driver reads an untrusted power-of-two exponent from the hypervisor and uses it in an unbounded bitwise shift.
--

--- Patch [3]: [PATCH V5 3/6] powerpc/perf: Add AUX buffer management to capture HTM trace data --- commit f3228c159ff40b8eb4da824d28f5361ecc14dfbf
Author: Athira Rajeev <[email protected]>

powerpc/perf: Add AUX buffer management to capture HTM trace data

Implement support for auxiliary (AUX) ring buffers in the HTM PMU driver. This enables high-volume trace data to be streamed directly into a perf AUX buffer for deferred post-processing by the perf tool.

Quoted 21 lines
arch/powerpc/perf/htm-perf.c +13 -0
index c1ce12605014b..90d26a721616b 100644
@@ -277,6 +314,32 @@ static int htm_event_init(struct perf_event *event)
 	list_add_tail(&target->list, &htm_active_targets_list);
 	mutex_unlock(&htm_targets_lock);
 
+	/*
+	 * Query the hardware-allocated HTM buffer size via H_HTM_OP_STATUS.
+	 * The status output buffer header byte 0x01 holds
+	 * CurrentNestHtmBufferSizeInPowerOf2 (for HTM_NEST) or
+	 * CurrentCoreHtmBufferSizeInPowerOf2 (for HTM_CORE); both types
+	 * use the same offset (0x01) and length (1 byte).
+	 * hw_buf_size is used in htm_dump_sample_data() to bound dump
+	 * offsets, preventing H_HTM_OP_DUMP_DATA calls past the end of the
+	 * hardware buffer.  On failure hw_buf_size stays 0 and the boundary
+	 * check is skipped gracefully — the contiguous-window clamp still
+	 * applies.
+	 */
+	status_buf = kzalloc(PAGE_SIZE, GFP_KERNEL);

arch/powerpc/perf/htm-perf.c static int htm_event_init(struct perf_event *event) · line 339

Quoted 10 lines
arch/powerpc/perf/htm-perf.c +10 -0
+	if (status_buf) {
+		do {
+			src = htm_hcall_wrapper(htmflags, cfg.nodeindex,
+					cfg.nodalchipindex, cfg.coreindexonchip,
+					cfg.htmtype, H_HTM_OP_STATUS,
+					virt_to_phys(status_buf), PAGE_SIZE, 0);
+			sret = htm_return_check(src);
+		} while (sret == -EBUSY && ++sretries < MAX_RETRIES);
+		if (sret > 0)
+			target->hw_buf_size = 1ULL << status_buf[0x01];

[Severity: Medium]
Can this shift result in undefined behavior? If the hypervisor returns a value greater than or equal to 64 for status_buf[0x01], the left shift will invoke undefined behavior. Should there be a bounds check on the exponent before performing the shift?

Quoted 6 lines
arch/powerpc/perf/htm-perf.c +3 -0
+		kfree(status_buf);
+	}
+
 	event->pmu_private = target;
 	event->destroy = reset_htm_active;
 	return 0;

[ ... ]

Quoted 17 lines
arch/powerpc/perf/htm-perf.c +13 -0
@@ -510,8 +576,308 @@ static void htm_event_del(struct perf_event *event, int flags)
 	/* pmu_private freed by event->destroy = reset_htm_active */
 }
 
+static ssize_t htm_dump_sample_data(struct perf_event *event)
+{
+	struct perf_output_handle handle;
+	struct htm_target_id *target = event->pmu_private;
+	struct htm_pmu_buf *aux_buf;
+	struct htm_config cfg = target->cfg;
+	u64 chunk_size, dump_offset, page_index, page_offset;
+	u64 max_contiguous_bytes, expected_phys, scan_index, actual_phys;
+	u64 hypervisor_target_phys;
+	void *target_page_virt;
+	ssize_t ret = 0;
+	int retries = 0;
+	long rc;

[ ... ]

arch/powerpc/perf/htm-perf.c static void htm_event_del(struct perf_event *event, int flags) · line 652

Quoted 13 lines
arch/powerpc/perf/htm-perf.c +13 -0
+	/*
+	 * Assess constraints regarding space remaining across the mapping
+	 * context boundary.
+	 * handle.size is always page-aligned: perf_aux_output_begin() computes
+	 * it as the distance from the write pointer to the wakeup boundary,
+	 * rounded to PAGE_SIZE.  Masking with PAGE_MASK is therefore a no-op
+	 * but is kept to make the page-granularity contract explicit.
+	 */
+	chunk_size = handle.size;
+	chunk_size &= PAGE_MASK;
+
+	if (chunk_size > (aux_buf->size - dump_offset))
+		chunk_size = aux_buf->size - dump_offset;

[Severity: High]
Does masking with PAGE_MASK artificially truncate the available AUX buffer size?

When the perf core allocator prepares a 1-page AUX buffer, perf_aux_output_begin() computes handle.size as CIRC_SPACE(), which returns at most size - 1 (e.g., 4095 for a 4096-byte page).

The bitwise AND with PAGE_MASK (~4095) evaluates to 0. For a 1-page buffer, the usable capacity becomes 0, causing the driver to indefinitely return -ENOSPC and potentially trapping userspace in an infinite loop.

[ ... ]

Quoted 5 lines
arch/powerpc/perf/htm-perf.c +5 -0
+	do {
+		/*
+		 * Invoke H_HTM call with:
+		 * - operation as htm dump (H_HTM_OP_DUMP_DATA)
+		 * - last three values are address, size and offset

arch/powerpc/perf/htm-perf.c static void htm_event_del(struct perf_event *event, int flags) · line 744

Quoted 10 lines
arch/powerpc/perf/htm-perf.c +10 -0
+		 */
+		rc = htm_hcall_wrapper(htmflags, cfg.nodeindex, cfg.nodalchipindex,
+				cfg.coreindexonchip, cfg.htmtype, H_HTM_OP_DUMP_DATA,
+				hypervisor_target_phys, chunk_size, aux_buf->head);
+		ret = htm_return_check(rc);
+	} while (ret == -EBUSY && ++retries < MAX_RETRIES);
+
+	if (ret > 0) {
+		aux_buf->head += chunk_size;
+		perf_aux_output_end(&handle, chunk_size);

[Severity: High]
If the hypervisor partially completes the dump, does this code advance the offsets incorrectly?

htm_return_check() maps H_PARTIAL to a success value (1):

arch/powerpc/perf/htm-perf.c:htm_return_check() {
...

	switch (rc) {
	case H_SUCCESS:
	case H_PARTIAL:
		return 1;

...
}

Because htm_return_check() discards the actual bytes written, and this condition assumes the entire chunk_size was written on any success code, could uninitialized or stale memory be exposed to userspace as valid trace records, and subsequent chunks be desynchronized?

Quoted 9 lines
arch/powerpc/perf/htm-perf.c +9 -0
+		/*
+		 * Return the number of 128-byte HTM trace records written.
+		 * Dividing here keeps htm_event_read() free of format
+		 * knowledge: it can simply use the returned count directly,
+		 * regardless of which data path (AUX trace or memory config)
+		 * produced it.
+		 */
+		return (ssize_t)(chunk_size / 128);
+	}
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=3
#2 lore raw

Re: [PATCH V5 1/6] powerpc/perf: Add HTM PMU driver to expose Hardware Trace Macro data

In reply to Athira Rajeev
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [High] Missing state reset in htm_event_del() causes spurious STOP and DECONFIGURE hcalls on subsequent…

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [High] Missing state reset in htm_event_del() causes spurious STOP and DECONFIGURE hcalls on subsequent htm_event_add() failures. --

--- Patch [1]: [PATCH V5 1/6] powerpc/perf: Add HTM PMU driver to expose Hardware Trace Macro data --- commit 482e76cb25a86207519e7500e8ca689e3b600e86
Author: Athira Rajeev <[email protected]>

powerpc/perf: Add HTM PMU driver to expose Hardware Trace Macro data

This commit adds a new PMU driver for the Hardware Trace Macro (HTM) on POWER systems. It maps the PMU lifecycle to HTM hypervisor calls and implements state tracking to handle hcall retries and error conditions.

Quoted 5 lines
arch/powerpc/perf/htm-perf.c new file +0 -0
new file mode 100644
index 0000000000000..cbe4f62813ee0

[ ... ]

Quoted 5 lines
arch/powerpc/perf/htm-perf.c new file +5 -0
+static void htm_event_del(struct perf_event *event, int flags)
+{
+	int rc, ret, retries = 0;
+	struct htm_target_id *target = event->pmu_private;
+	struct htm_config cfg = target->cfg;

[ ... ]

Quoted 22 lines
arch/powerpc/perf/htm-perf.c new file +22 -0
+	htm_event_stop(event, 0);
+
+	/*
+	 * Only issue H_HTM_OP_DECONFIGURE if this driver successfully issued
+	 * the paired H_HTM_OP_CONFIGURE.  If htm_event_add() failed before or
+	 * during CONFIGURE (configured == 0), there is nothing to tear down.
+	 * Issuing DECONFIGURE without a prior CONFIGURE would silently destroy
+	 * a concurrent trace session that owns the same hardware target and
+	 * produce spurious pr_err() noise for an expected H_STATE / H_NOT_AVAILABLE
+	 * response.
+	 */
+	if (!target->configured)
+		return;
+
+	/*
+	 * Deconfigure the hardware resource.  Only H_BUSY is retried.
+	 * If H_LONG_BUSY_* or any other error is returned, the resource
+	 * cannot be reclaimed in this atomic context; log the failure so it
+	 * is visible in the kernel log.
+	 */
+	do {
+		rc = htm_hcall_wrapper(htmflags, cfg.nodeindex, cfg.nodalchipindex,

arch/powerpc/perf/htm-perf.c line 477

Quoted 10 lines
arch/powerpc/perf/htm-perf.c new file +10 -0
+				       cfg.coreindexonchip, cfg.htmtype,
+				       H_HTM_OP_DECONFIGURE, 0, 0, 0);
+		ret = htm_return_check(rc);
+	} while (ret == -EBUSY && ++retries < MAX_RETRIES);
+	if (ret <= 0) {
+		pr_err("DECONFIGURE failed in htm event del (ret=%d) node:%u chip:%u core:%u type:%u;\n",
+				ret, cfg.nodeindex, cfg.nodalchipindex, cfg.coreindexonchip, cfg.htmtype);
+	}
+	/* pmu_private freed by event->destroy = reset_htm_active */
+}

[Severity: High]
Does this code need to reset target->configured to 0 after issuing the H_HTM_OP_DECONFIGURE hcall?

If Process A disables an event via ioctl(PERF_EVENT_IOC_DISABLE), htm_event_del() correctly deconfigures the hardware but leaves target->configured as 1.

If Process B then opens and enables the same HTM target, it takes ownership. If Process A subsequently re-enables its event, the H_HTM_OP_CONFIGURE in htm_event_add() will fail. When Process A's htm_event_del() runs on the error path, it will see the stale configured == 1 state and spuriously issue H_HTM_OP_DECONFIGURE.

Can this silently destroy Process B's active trace?

Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1