The Linux Kernel Mailing List
 help / color / mirror / Atom feed
From: "David E. Box" <david.e.box@linux.intel.com>
To: "Ilpo Järvinen" <ilpo.jarvinen@linux.intel.com>,
	"Hans de Goede" <hansg@kernel.org>
Cc: "David E. Box" <david.e.box@linux.intel.com>,
	Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
	platform-driver-x86@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: [PATCH v2 00/12] tools/arch/x86/pmtctl: Add Intel PMT command-line tool
Date: Sun, 22 Nov 2026 11:33:55 -0800	[thread overview]
Message-ID: <cover.1795374925.git.david.e.box@linux.intel.com> (raw)

Intel Platform Monitoring Technology (PMT) exposes hardware telemetry
through the pmt_telemetry auxiliary driver. Each telemetry device, telemN,
provides a data file of 64-bit samples, and its GUID identifies the layout
of the samples, which Intel publishes as XML in the Intel-PMT repository.

This series adds pmtctl, a command-line tool that lists the metrics of the
telemetry devices on a system and samples them, similar to 'perf stat'. It
lives under tools/arch/x86/pmtctl/ next to the other x86 platform tools.

  pmtctl list                         # metrics of the devices, by GUID
  pmtctl list --summary               # GUIDs and their devices
  pmtctl stat -e package_energy       # sample a metric once a second
  pmtctl stat --raw id=2,msb=7        # sample bits 0-7 of sample 2

The metric definitions are not part of the tree. 'make defs-json-fetch'
clones the Intel-PMT repository and converts its XML into one JSON file
per GUID with scripts/pmtxml2json.py; 'make install' installs them, and
pmtctl loads them at run time.

V2 is a rework of V1 following Ilpo's review, and about half its size
(3.9k lines).

Testing: on a Panther Lake system, where the metrics of both published
telemetry layouts were sampled and checked against --raw reads of the
same samples, and on a QEMU guest with an emulated PMT device (KASAN
kernel). Also with a fake sysfs tree under ASan/UBSan and
allocation-failure injection. Reading telemetry needs root, because the
kernel creates the data files with mode 0440; 'list' does not.

This rework was done with the help of an AI coding assistant (Claude
Code). I reviewed every patch by hand, and the structure, conventions and
behavior of the tool are my decisions.

Changes since v1, in summary (each patch's changelog has the details and
the v1 patches it replaces):

- Restructured: the tool is built up in working steps, so every patch
  builds and adds one thing. v1 added library components bottom-up, and
  nothing built until patch 9.
- Smaller: no installed library, no pager, and no built-in definition
  tables (deferred to a follow-up). Definitions are JSON only, read from
  the installed directory or -J, in a format reduced to what pmtctl uses.
- Command line: per-command --guid and --device filters replace the -d
  selector; 'list --summary' replaces 'list --devices'; --guids, --once,
  --header, -q and --debug are gone. The tool says "device" throughout,
  as the sysfs ABI does.
- Code conventions follow the v1 review: errors are 0 or -errno and map
  to documented exit statuses, no exit() in library code, explicit
  context ownership, size_t for counts, and no hand-rolled arrays,
  string pools or magic numbers.
- Several v1 bugs are fixed, for example 7 published GUIDs converted
  under the wrong number, a directory load that depended on readdir
  order, and a time column computed instead of measured.

V1: https://lore.kernel.org/r/20260526014719.2248380-1-david.e.box@linux.intel.com

David E. Box (12):
  tools/arch/x86/pmtctl: Add pmtctl skeleton
  tools/arch/x86/pmtctl: Add PMT telemetry device discovery
  tools/arch/x86/pmtctl: Add pmtxml2json conversion tool
  tools/arch/x86/pmtctl: Add JSON metric definition loading
  tools/arch/x86/pmtctl: Add 'list' command
  tools/arch/x86/pmtctl: Add 'list --summary'
  tools/arch/x86/pmtctl: Add 'stat' command
  tools/arch/x86/pmtctl: Add 'stat --hex'
  tools/arch/x86/pmtctl: Add 'stat --raw'
  tools/arch/x86/pmtctl: Add README
  tools/arch/x86/pmtctl: Add man page
  tools/arch/x86/pmtctl: Add MAINTAINERS entry

 MAINTAINERS                                  |   2 +
 tools/arch/x86/pmtctl/.gitignore             |   3 +
 tools/arch/x86/pmtctl/Makefile               | 107 +++
 tools/arch/x86/pmtctl/README                 |  99 ++
 tools/arch/x86/pmtctl/include/lib/common.h   |  71 ++
 tools/arch/x86/pmtctl/include/lib/device.h   |  21 +
 tools/arch/x86/pmtctl/include/lib/log.h      |  23 +
 tools/arch/x86/pmtctl/include/lib/pmtctl.h   |  52 ++
 tools/arch/x86/pmtctl/include/lib/tss.h      |  43 +
 tools/arch/x86/pmtctl/include/pmtctl_cli.h   |  19 +
 tools/arch/x86/pmtctl/lib/common.c           |  81 ++
 tools/arch/x86/pmtctl/lib/device_telem.c     | 297 ++++++
 tools/arch/x86/pmtctl/lib/log.c              |  41 +
 tools/arch/x86/pmtctl/lib/pmtctl.c           | 114 +++
 tools/arch/x86/pmtctl/lib/tss.c              |  45 +
 tools/arch/x86/pmtctl/lib/tss_json.c         | 406 +++++++++
 tools/arch/x86/pmtctl/pmtctl.8               | 284 ++++++
 tools/arch/x86/pmtctl/scripts/pmtxml2json.md | 189 ++++
 tools/arch/x86/pmtctl/scripts/pmtxml2json.py | 639 +++++++++++++
 tools/arch/x86/pmtctl/src/cmd_list.c         | 330 +++++++
 tools/arch/x86/pmtctl/src/cmd_stat.c         | 897 +++++++++++++++++++
 tools/arch/x86/pmtctl/src/main.c             |  91 ++
 22 files changed, 3854 insertions(+)
 create mode 100644 tools/arch/x86/pmtctl/.gitignore
 create mode 100644 tools/arch/x86/pmtctl/Makefile
 create mode 100644 tools/arch/x86/pmtctl/README
 create mode 100644 tools/arch/x86/pmtctl/include/lib/common.h
 create mode 100644 tools/arch/x86/pmtctl/include/lib/device.h
 create mode 100644 tools/arch/x86/pmtctl/include/lib/log.h
 create mode 100644 tools/arch/x86/pmtctl/include/lib/pmtctl.h
 create mode 100644 tools/arch/x86/pmtctl/include/lib/tss.h
 create mode 100644 tools/arch/x86/pmtctl/include/pmtctl_cli.h
 create mode 100644 tools/arch/x86/pmtctl/lib/common.c
 create mode 100644 tools/arch/x86/pmtctl/lib/device_telem.c
 create mode 100644 tools/arch/x86/pmtctl/lib/log.c
 create mode 100644 tools/arch/x86/pmtctl/lib/pmtctl.c
 create mode 100644 tools/arch/x86/pmtctl/lib/tss.c
 create mode 100644 tools/arch/x86/pmtctl/lib/tss_json.c
 create mode 100644 tools/arch/x86/pmtctl/pmtctl.8
 create mode 100644 tools/arch/x86/pmtctl/scripts/pmtxml2json.md
 create mode 100755 tools/arch/x86/pmtctl/scripts/pmtxml2json.py
 create mode 100644 tools/arch/x86/pmtctl/src/cmd_list.c
 create mode 100644 tools/arch/x86/pmtctl/src/cmd_stat.c
 create mode 100644 tools/arch/x86/pmtctl/src/main.c


base-commit: 9c82959c37bf69c2ace8a0f975cf2129ec1fd982
-- 
2.53.0


             reply	other threads:[~2026-11-22 19:34 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-22 19:33 David E. Box [this message]
2026-11-22 19:33 ` [PATCH v2 01/12] tools/arch/x86/pmtctl: Add pmtctl skeleton David E. Box
2026-11-22 19:33 ` [PATCH v2 02/12] tools/arch/x86/pmtctl: Add PMT telemetry device discovery David E. Box
2026-11-22 19:33 ` [PATCH v2 03/12] tools/arch/x86/pmtctl: Add pmtxml2json conversion tool David E. Box
2026-11-22 19:33 ` [PATCH v2 04/12] tools/arch/x86/pmtctl: Add JSON metric definition loading David E. Box
2026-11-22 19:34 ` [PATCH v2 05/12] tools/arch/x86/pmtctl: Add 'list' command David E. Box
2026-11-22 19:34 ` [PATCH v2 06/12] tools/arch/x86/pmtctl: Add 'list --summary' David E. Box
2026-11-22 19:34 ` [PATCH v2 07/12] tools/arch/x86/pmtctl: Add 'stat' command David E. Box
2026-11-22 19:34 ` [PATCH v2 08/12] tools/arch/x86/pmtctl: Add 'stat --hex' David E. Box
2026-11-22 19:34 ` [PATCH v2 09/12] tools/arch/x86/pmtctl: Add 'stat --raw' David E. Box
2026-11-22 19:34 ` [PATCH v2 10/12] tools/arch/x86/pmtctl: Add README David E. Box
2026-11-22 19:34 ` [PATCH v2 11/12] tools/arch/x86/pmtctl: Add man page David E. Box
2026-11-22 19:34 ` [PATCH v2 12/12] tools/arch/x86/pmtctl: Add MAINTAINERS entry David E. Box

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=cover.1795374925.git.david.e.box@linux.intel.com \
    --to=david.e.box@linux.intel.com \
    --cc=andriy.shevchenko@linux.intel.com \
    --cc=hansg@kernel.org \
    --cc=ilpo.jarvinen@linux.intel.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=platform-driver-x86@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox