mirror of https://lore.kernel.org/lkml/
 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 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


  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®