[PATCH v3 0/3] perf pmu: Add tool-provided NVMe PMU

From: Ian Rogers

Date: Fri Nov 13 2026 - 14:24:13 EST


This series adds a tool-provided PMU for NVMe controllers using libnvme,
following the same pattern as the existing tool, hwmon, and drm PMUs.
Each discovered controller is exposed as an 'nvme_<ctrl>' PMU (with
alias '<ctrl>', e.g. 'nvme_nvme0' and 'nvme0') providing events from
standard NVMe log pages: SMART / Health Information, Endurance Group
Information, Flexible Data Placement (FDP) Statistics, Error
Information, and Zoned Namespaces (ZNS) Changed Zones.

Motivation / Use Cases
======================
While standalone tools such as nvme-cli can dump individual log pages on
demand, exposing NVMe controller log metrics as a perf tool PMU allows
storage metrics (host/media bytes written, write amplification and FDP
efficiency, read/write command counts, controller busy time, error
counters, and device temperature) to be sampled on a unified timeline
alongside CPU hardware counters, kernel/block events, uncore counters,
and hwmon/drm sensors in 'perf stat' (including interval mode '-I', CSV
'-x', JSON '-j', and perf metric formulas), without custom wrapper
scripts. Discovery and log-page probing are gated behind
PERF_TOOL_PMU_TYPE_NVME_MASK so commands that do not request NVMe events
incur zero overhead.

Example Output
==============
Listing available NVMe events (unsupported log pages on the controller
are marked deprecated and hidden from default 'perf list'):

$ perf list nvme

List of pre-defined events (to be used in -e or -M):

nvme:
smart_crit_comp_time
[Critical composite temperature time. Unit: nvme_nvme0]
smart_ctrl_busy_time
[Controller busy time. Unit: nvme_nvme0]
smart_data_units_read
[Data units read (in 1000s of 512-byte units). Unit: nvme_nvme0]
smart_data_units_written
[Data units written (in 1000s of 512-byte units). Unit: nvme_nvme0]
smart_host_read_commands
[Host read commands. Unit: nvme_nvme0]
smart_host_write_commands
[Host write commands. Unit: nvme_nvme0]
smart_media_errors
[Media errors. Unit: nvme_nvme0]
smart_num_err_log_entries
[Number of error log entries. Unit: nvme_nvme0]
smart_power_cycles
[Power cycles. Unit: nvme_nvme0]
smart_power_on_hours
[Power on hours. Unit: nvme_nvme0]
smart_temperature
[Temperature. Unit: nvme_nvme0]
smart_unsafe_shutdowns
[Unsafe shutdowns. Unit: nvme_nvme0]
smart_warning_temp_time
[Warning temperature time. Unit: nvme_nvme0]

$ perf list --details nvme_nvme0/smart_temperature/

List of pre-defined events (to be used in -e or -M):

nvme:
smart_temperature
[Temperature. Unit: nvme_nvme0]
nvme_nvme0/config=0x20001/

Interval 'perf stat' output (captured with mocked libnvme SMART log
responses on /dev/nvme0):

$ perf stat -a -I 500 -e smart_temperature,smart_data_units_read,\
smart_data_units_written,smart_host_read_commands,\
smart_host_write_commands -- sleep 1
# time counts unit events
0.500432960 311 K smart_temperature
0.500432960 36,864,000 B smart_data_units_read
0.500432960 12,288,000 B smart_data_units_written
0.500432960 900 smart_host_read_commands
0.500432960 270 smart_host_write_commands
1.001068028 311 K smart_temperature
1.001068028 36,864,000 B smart_data_units_read
1.001068028 12,288,000 B smart_data_units_written
1.001068028 900 smart_host_read_commands
1.001068028 270 smart_host_write_commands

Changes in v3:
- Remove accidental internal tracking tags from commit messages
(Christoph Hellwig).
- Document use cases and include actual 'perf list' and 'perf stat'
example output in the cover letter and Patch 2 commit message, and
document NVMe events in Documentation/perf-list.txt (Christoph
Hellwig, Namhyung Kim).
- Rely on $(FEATURE_CHECK_LDFLAGS-libnvme) from pkg-config when building
test-libnvme.bin instead of hardcoding -lnvme, and add test-libnvme.bin
to FILES in tools/build/feature/Makefile.
- Report smart_temperature in native Kelvins ('1K') to avoid unsigned
uint64_t underflow on sub-zero Celsius or 0 K readings; metrics can
convert Kelvin to Celsius.
- Support advertised 'config=0x...' raw encodings, 'event=<name>', and
standard event qualifiers ('name=', 'metric-id=', 'cpu='), and guard
NULL term->config when formatting parse errors.
- Check xyarray__new() allocation failure (-ENOMEM), propagate initial
log read errors (-EPERM / -EOPNOTSUPP) in evsel__nvme_pmu_open(), and
bound incremental open error unwind by start_cpu_map_idx.
- Use an aligned union of NVMe log structures in nvme_pmu__read_val(),
use valid Endurance Group ID 1 (0 is reserved in NVMe) for Endurance
Group and FDP logs, fix Endurance Group data/media unit scaling to
billions of bytes ('1000000000B') per NVMe Base Spec, wire up
perf_pmus__find_by_type() for NVMe PMU types, and propagate
nvme_pmu__check_alias() errors in perf_pmu__check_alias().
- Expand unit tests to cover alias PMUs, 'event=', 'config=0x...',
'name=' qualifiers, unit/scale checks, and invalid term rejection.

Changes in v2:
https://lore.kernel.org/linux-perf-users/20260609165726.786694-1-irogers@xxxxxxxxxx/
- Include test-libnvme.c in test-all.c and add libnvme to
FEATURE_PKG_CONFIG.
- Use get_unaligned_le*() helpers when reading NVMe log fields.
- Move baseline initial_values xyarray from tool-owned evsel->priv into
struct evsel's tool union (evsel->nvme.initial_values) and free it in
evsel__exit().

v1:
https://lore.kernel.org/linux-perf-users/20260609070348.541964-1-irogers@xxxxxxxxxx/

Ian Rogers (3):
perf build: Add libnvme feature detection
perf pmu: Implement tool-provided NVMe PMU
perf tests: Add NVMe PMU event parsing test

tools/build/Makefile.feature | 5 +-
tools/build/feature/Makefile | 4 +
tools/build/feature/test-all.c | 5 +
tools/build/feature/test-libnvme.c | 11 +
tools/perf/Documentation/perf-list.txt | 10 +-
tools/perf/Makefile.config | 12 +
tools/perf/tests/Build | 1 +
tools/perf/tests/builtin-test.c | 1 +
tools/perf/tests/nvme_pmu.c | 303 +++++++++++
tools/perf/tests/tests.h | 1 +
tools/perf/util/Build | 1 +
tools/perf/util/evsel.c | 13 +-
tools/perf/util/evsel.h | 4 +
tools/perf/util/nvme_pmu.c | 691 +++++++++++++++++++++++++
tools/perf/util/nvme_pmu.h | 144 ++++++
tools/perf/util/pmu.c | 17 +
tools/perf/util/pmu.h | 8 +-
tools/perf/util/pmus.c | 24 +
tools/perf/util/pmus.h | 1 +
19 files changed, 1250 insertions(+), 6 deletions(-)
create mode 100644 tools/build/feature/test-libnvme.c
create mode 100644 tools/perf/tests/nvme_pmu.c
create mode 100644 tools/perf/util/nvme_pmu.c
create mode 100644 tools/perf/util/nvme_pmu.h

--
2.56.1.703.gf848ed807c-goog