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 11/12] tools/arch/x86/pmtctl: Add man page
Date: Sun, 22 Nov 2026 11:34:06 -0800	[thread overview]
Message-ID: <a5acc483018649a7fdd18dec50ab6fe875b12f85.1795374925.git.david.e.box@linux.intel.com> (raw)
In-Reply-To: <cover.1795374925.git.david.e.box@linux.intel.com>

Add the pmtctl(8) man page, which describes the global options, the
'list' and 'stat' commands with their options and output, the metric
definition files and the exit status. 'make install' installs it to
$(MANDIR)/man8, /usr/share/man/man8 by default, and the README refers
to it.

Signed-off-by: David E. Box <david.e.box@linux.intel.com>
---
V2 changes:
  - Replaces v1 17, rewritten for v2. v1 wrongly said -e and --raw were
    mutually exclusive.
  - Installed by 'make install'.

 tools/arch/x86/pmtctl/Makefile |   3 +
 tools/arch/x86/pmtctl/README   |   3 +
 tools/arch/x86/pmtctl/pmtctl.8 | 284 +++++++++++++++++++++++++++++++++
 3 files changed, 290 insertions(+)
 create mode 100644 tools/arch/x86/pmtctl/pmtctl.8

diff --git a/tools/arch/x86/pmtctl/Makefile b/tools/arch/x86/pmtctl/Makefile
index 564931794086..5f07c3345b78 100644
--- a/tools/arch/x86/pmtctl/Makefile
+++ b/tools/arch/x86/pmtctl/Makefile
@@ -3,6 +3,7 @@
 
 BINDIR ?= /usr/sbin
 DEFSDIR ?= /usr/share/pmtctl
+MANDIR ?= /usr/share/man
 
 CFLAGS = -Wextra
 
@@ -96,6 +97,8 @@ clean:
 install: pmtctl
 	install -d $(DESTDIR)$(BINDIR)
 	install -m 755 -p pmtctl $(DESTDIR)$(BINDIR)/pmtctl
+	install -d $(DESTDIR)$(MANDIR)/man8
+	install -m 644 -p pmtctl.8 $(DESTDIR)$(MANDIR)/man8/pmtctl.8
 	@# Metric definitions, if 'make defs-json-fetch' was run
 	@if ls $(DEFS_DIR)/*.json >/dev/null 2>&1; then \
 		install -d $(DESTDIR)$(DEFSDIR); \
diff --git a/tools/arch/x86/pmtctl/README b/tools/arch/x86/pmtctl/README
index 7d9a57cf3925..296dccba52ff 100644
--- a/tools/arch/x86/pmtctl/README
+++ b/tools/arch/x86/pmtctl/README
@@ -22,6 +22,8 @@ Debian and Ubuntu, jansson-devel on Fedora and RHEL).
 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.
+The pmtctl(8) man page is installed to /usr/share/man/man8, under
+DESTDIR too, and MANDIR changes its location.
 
 
 Metric definitions
@@ -84,6 +86,7 @@ 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.
+The pmtctl(8) man page describes them in more detail.
 
 
 Exit status
diff --git a/tools/arch/x86/pmtctl/pmtctl.8 b/tools/arch/x86/pmtctl/pmtctl.8
new file mode 100644
index 000000000000..c547af73db1d
--- /dev/null
+++ b/tools/arch/x86/pmtctl/pmtctl.8
@@ -0,0 +1,284 @@
+.\" SPDX-License-Identifier: GPL-2.0-only
+.TH PMTCTL 8 "November 2026" "Linux" "System Administration"
+.SH NAME
+pmtctl \- query Intel Platform Monitoring Technology (PMT) telemetry metrics
+.SH SYNOPSIS
+.B pmtctl
+.RI [ "global options" ]
+.B list
+.RI [ options ]
+.br
+.B pmtctl
+.RI [ "global options" ]
+.B stat
+.RI [ options ]
+.BR \-e\ \fImetric\fR[,\fImetric\fR...]\ ...
+.br
+.B pmtctl
+.RI [ "global options" ]
+.B stat
+.RI [ options ]
+.BR \-\-raw\ id= \fIN\fR [,lsb= \fIN\fR ][,msb= \fIN\fR ]\ ...
+.SH DESCRIPTION
+.B pmtctl
+is a command-line tool for inspecting and sampling Intel Platform
+Monitoring Technology (PMT) telemetry exposed through the kernel
+.B pmt_telemetry
+auxiliary driver
+.RB ( /sys/bus/auxiliary/drivers/pmt_telemetry ).
+.PP
+The driver registers a telemetry device,
+.BI telem N\fR,
+for each telemetry region of the platform. Its data is an array of
+64-bit samples, and its GUID identifies the layout: which bits of
+which sample hold which metric.
+.B pmtctl
+uses metric definitions, one JSON file per GUID, to name and decode
+the data. The definitions are generated from the layouts published in
+the Intel-PMT repository; see
+.BR FILES .
+.PP
+The telemetry data files can only be read by
+.BR root ,
+so
+.B stat
+must run as root.
+.B list
+does not need to.
+.SH GLOBAL OPTIONS
+.TP
+.BR \-h ", " \-\-help
+Show help and exit.
+.TP
+.BR \-V ", " \-\-version
+Show version and exit.
+.TP
+.BR \-J ", " "\-\-json\-file " \fIpath\fR
+Load the metric definitions from
+.IR path ,
+a definition file or a directory of them. Without
+.BR \-J ,
+the definitions installed in
+.I /usr/share/pmtctl
+(set with DEFSDIR at build time) are used, if that directory exists.
+.SH COMMANDS
+.SS list
+.B pmtctl list
+.RI [ options ]
+.PP
+List the metrics of the telemetry devices on the system. The metrics
+are grouped by GUID, each group with its platform, number of metrics
+and description, and a GUID shared by several devices is listed once.
+On a terminal, descriptions are wrapped to its width.
+.TP
+.BR \-h ", " \-\-help
+Show help for
+.B list
+and exit.
+.TP
+.BI "\-\-guid " hex
+Restrict the listing to the devices with this GUID.
+.TP
+.BI "\-\-device " name
+Restrict the listing to one device, for example
+.BR telem3 .
+.TP
+.B \-\-summary
+List the GUIDs and their devices instead of the metrics. This works
+without metric definitions.
+.SS stat
+.B pmtctl stat
+.RI [ options ]
+.B \-e
+.IR metric [,\fImetric\fR...]
+\&...
+.br
+.B pmtctl stat
+.RI [ options ]
+.BR \-\-raw\ id= \fIN\fR [,lsb= \fIN\fR ][,msb= \fIN\fR ]\ ...
+.PP
+Sample metrics, or raw sample values, of the telemetry devices at an
+interval, in a manner similar to
+.BR "perf stat" .
+Samples are scheduled from the start time, so the interval doesn't
+drift, and the time column shows when each sample was taken. A sample
+that is due before the previous one finished is skipped. Sampling ends
+after the given number of samples or on
+.BR SIGINT ,
+which takes effect immediately, even during a long interval.
+.TP
+.BR \-h ", " \-\-help
+Show help for
+.B stat
+and exit.
+.TP
+.BR \-e ", " "\-\-event " \fIspec\fR
+Metric name, or a comma-separated list of metric names. May be
+repeated and combined with
+.BR \-\-raw .
+.TP
+.B \-\-raw \fBid=\fIN\fR[\fB,lsb=\fIN\fR][\fB,msb=\fIN\fR]
+Read bits
+.B lsb
+to
+.B msb
+of sample
+.B id
+of each device, without metric definitions. The items are separated by
+commas, without spaces.
+.B lsb
+defaults to 0 and
+.B msb
+to 63, and 0 \(<=
+.B lsb
+\(<=
+.B msb
+\(<= 63. May be repeated and combined with
+.BR \-e .
+.TP
+.BI "\-\-guid " hex
+Restrict sampling to the devices with this GUID.
+.TP
+.BI "\-\-device " name
+Restrict sampling to one device, for example
+.BR telem3 .
+.TP
+.BR \-i ", " "\-\-interval " \fIms\fR
+Sampling interval in milliseconds. Must be greater than 0. Default
+is 1000 ms.
+.TP
+.BR \-c ", " "\-\-count " \fIN\fR
+Number of samples to take. Must be greater than 0. Default is to
+sample until interrupted.
+.TP
+.B \-\-no\-header
+Don't print the header.
+.TP
+.B \-\-hex
+Print sample values in hexadecimal.
+.TP
+.B \-\-vertical
+One line per value per sample: the sample number, the time in ms, the
+device, the metric and the value. Required when more than one value is
+requested. The default layout has one line per device per sample.
+.PP
+Metric names are looked up in the definitions of each device's GUID, so
+a metric is sampled on every selected device that has it, at that
+device's location. A device that has none of the requested values is
+left out. With
+.BR \-\-vertical ,
+a value that a device doesn't have is printed as
+.BR \- ,
+as is a
+.B \-\-raw
+sample outside the device's telemetry region. A metric or raw sample
+that no selected device has is an error. A value that can't be read is
+printed as
+.BR NaN ;
+.B stat
+fails only if no value could be read at all.
+.SH EXAMPLES
+List the metrics, using the installed definitions:
+.PP
+.RS 4
+.nf
+pmtctl list
+.fi
+.RE
+.PP
+List the GUIDs and devices of the system, with definitions from
+.IR defs/ :
+.PP
+.RS 4
+.nf
+pmtctl \-J defs list \-\-summary
+.fi
+.RE
+.PP
+Sample a metric every 500 ms until interrupted:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e package_energy \-\-interval 500
+.fi
+.RE
+.PP
+Take a single sample of a metric on the devices with one GUID:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e pch_temp \-\-guid 03086000 \-c 1
+.fi
+.RE
+.PP
+Sample two metrics five times (requires \fB\-\-vertical\fR):
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e package_energy,pch_temp \-\-vertical \-c 5
+.fi
+.RE
+.PP
+Print a value in hexadecimal:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e firmware_version \-c 1 \-\-hex
+.fi
+.RE
+.PP
+Read raw sample values, slicing bit fields out of two samples:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-\-vertical \-\-raw id=2,msb=7 \-\-raw id=3,lsb=8,msb=15
+.fi
+.RE
+.SH FILES
+.TP
+.B /sys/bus/auxiliary/drivers/pmt_telemetry
+Sysfs entry point for the kernel
+.B pmt_telemetry
+auxiliary driver that
+.B pmtctl
+reads from.
+.TP
+.I /usr/share/pmtctl
+The installed metric definitions,
+.BI pmt_ guid .json
+for each GUID. They are generated from the Intel-PMT repository with
+.B make defs\-json\-fetch
+in the
+.B pmtctl
+source directory and installed with
+.BR "make install" .
+.SH EXIT STATUS
+.TP
+.B 0
+Success.
+.TP
+.B 1
+The request is wrong: an invalid option or value, or nothing matches
+the selection.
+.TP
+.B 2
+Something failed while carrying out the request, such as reading the
+devices or the metric definitions.
+.SH SEE ALSO
+.BR perf (1),
+.BR turbostat (8)
+.PP
+Intel Platform Monitoring Technology XML metric definitions:
+.UR https://github.com/intel/Intel-PMT
+.UE .
+.SH AUTHORS
+.B pmtctl
+was written by David E. Box <david.e.box@linux.intel.com>.
+.SH REPORTING BUGS
+Report bugs via the Linux kernel mailing lists; see the
+.B MAINTAINERS
+file in the kernel source tree for current maintainers of the
+Intel PMT subsystem.
+.SH COPYRIGHT
+.B pmtctl
+is licensed under GPL-2.0-only.
-- 
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 ` [PATCH v2 10/12] tools/arch/x86/pmtctl: Add README David E. Box
2026-11-22 19:34 ` David E. Box [this message]
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=a5acc483018649a7fdd18dec50ab6fe875b12f85.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®