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 10/12] tools/arch/x86/pmtctl: Add README
Date: Sun, 22 Nov 2026 11:34:05 -0800 [thread overview]
Message-ID: <00e4e34485ad03a608a20b199264111c1cc5116f.1795374925.git.david.e.box@linux.intel.com> (raw)
In-Reply-To: <cover.1795374925.git.david.e.box@linux.intel.com>
Add a README that describes how to build and install pmtctl, how to
get the metric definitions from the Intel-PMT repository, and how to
use the 'list' and 'stat' commands, including the privileges they need
and the exit status.
Signed-off-by: David E. Box <david.e.box@linux.intel.com>
---
V2 changes:
- Replaces v1 16 (README.md), rewritten for v2 as plain text like the
other READMEs in tools/.
tools/arch/x86/pmtctl/README | 96 ++++++++++++++++++++++++++++++++++++
1 file changed, 96 insertions(+)
create mode 100644 tools/arch/x86/pmtctl/README
diff --git a/tools/arch/x86/pmtctl/README b/tools/arch/x86/pmtctl/README
new file mode 100644
index 000000000000..7d9a57cf3925
--- /dev/null
+++ b/tools/arch/x86/pmtctl/README
@@ -0,0 +1,96 @@
+pmtctl
+======
+
+pmtctl lists and samples the telemetry of Intel Platform Monitoring
+Technology (PMT) devices. The pmt_telemetry driver registers a telemetry
+device, telemN, for each telemetry region of a platform. Its data is an
+array of 64-bit samples, and its GUID identifies the layout: which bits
+of which sample hold which metric. pmtctl uses metric definitions
+generated from the layouts Intel publishes to name and decode the data.
+
+
+Building
+--------
+
+ make
+
+This needs libjansson and its development files (libjansson-dev on
+Debian and Ubuntu, jansson-devel on Fedora and RHEL).
+
+ make install
+
+installs pmtctl to /usr/sbin, and the metric definitions, if they were
+fetched, to /usr/share/pmtctl. BINDIR and DEFSDIR change the locations,
+and DESTDIR is prefixed to both.
+
+
+Metric definitions
+------------------
+
+The layouts are published as XML in the Intel-PMT repository
+(https://github.com/intel/Intel-PMT). scripts/pmtxml2json.py converts
+them into one JSON file per GUID:
+
+ make defs-json-fetch # clone Intel-PMT once and convert it into defs/
+ make defs-json-pull # update the clone and convert again
+ make defs-clean # remove defs/
+
+These targets need Python 3 with lxml, and are not part of the default
+build, so a plain 'make' never accesses the network. The clone is kept in
+~/.cache/pmtctl (PMT_CACHE_DIR). The JSON format and how event names are
+derived from the XML are described in scripts/pmtxml2json.md.
+
+pmtctl reads the definitions from the installed directory, or from the
+file or directory given with -J:
+
+ pmtctl -J defs list
+
+
+Usage
+-----
+
+ pmtctl [global options] <command> [command options]
+
+'list' shows the metrics of the telemetry devices on the system, grouped
+by GUID. 'list --summary' shows the GUIDs and their devices instead:
+
+ pmtctl list
+ pmtctl list --summary
+
+'stat' samples metrics at an interval, once a second by default. -i sets
+the interval in milliseconds and -c the number of samples:
+
+ pmtctl stat -e package_energy
+ pmtctl stat -e package_energy -i 500 -c 10
+
+The default layout has one row per device. More than one value needs
+--vertical, which prints one line per device and value:
+
+ pmtctl stat --vertical -e package_energy,pch_temp
+
+--raw samples a bit range of a sample by its position, without metric
+definitions. --hex prints values in hex:
+
+ pmtctl stat --raw id=2,lsb=16,msb=31
+ pmtctl stat --raw id=0,msb=31 --hex
+
+--guid and --device restrict both commands to the devices with a GUID
+or to one device:
+
+ pmtctl list --guid 03086000
+ pmtctl stat -e pch_temp --device telem3
+
+The telemetry data files can only be read by root, so 'stat' must run
+as root; 'list' doesn't need to.
+
+'pmtctl --help' and 'pmtctl <command> --help' describe all options.
+
+
+Exit status
+-----------
+
+ 0 success
+ 1 the request is wrong: an invalid option or value, or nothing
+ matches the selection
+ 2 something failed while carrying it out, such as reading the devices
+ or the metric definitions
--
2.53.0
next prev parent 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 [PATCH v2 00/12] tools/arch/x86/pmtctl: Add Intel PMT command-line tool David E. Box
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 ` David E. Box [this message]
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=00e4e34485ad03a608a20b199264111c1cc5116f.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
all inboxes | Powered by JetHome®