[PATCH 17/17] tools/arch/x86/pmtctl: Add man page

["David E. Box" <david.e.box@linux.intel.com>]

Add a man page for pmtctl describing the command-line interface, the
list and stat subcommands, common options, and output formats.

Assisted-by: GitHub-Copilot:claude-opus-4.7
Signed-off-by: David E. Box <david.e.box@linux.intel.com>
---
 tools/arch/x86/pmtctl/Makefile  |   6 +
 tools/arch/x86/pmtctl/README.md |   3 +
 tools/arch/x86/pmtctl/pmtctl.8  | 317 ++++++++++++++++++++++++++++++++
 3 files changed, 326 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 d55819372f79..a8e76e84d7c5 100644
--- a/tools/arch/x86/pmtctl/Makefile
+++ b/tools/arch/x86/pmtctl/Makefile
@@ -152,6 +152,7 @@ $(GENERATED_DIR)/builtin_defs.c: $(GEN_DEFS_SCRIPT) $(DEFS_JSON)
 # Install settings
 PREFIX ?= /usr/local
 DESTDIR ?=
+MANDIR ?= $(PREFIX)/share/man
 
 
 .PHONY: install uninstall install-lib install-headers install-pkgconfig uninstall-lib uninstall-headers uninstall-pkgconfig
@@ -159,7 +160,10 @@ DESTDIR ?=
 install: $(TARGET) install-lib install-headers install-pkgconfig
 	install -d $(DESTDIR)$(PREFIX)/bin
 	install -m 0755 $(TARGET) $(DESTDIR)$(PREFIX)/bin
+	install -d $(DESTDIR)$(MANDIR)/man8
+	install -m 0644 pmtctl.8 $(DESTDIR)$(MANDIR)/man8/pmtctl.8
 	@echo "Installed $(TARGET) to $(DESTDIR)$(PREFIX)/bin/"
+	@echo "Installed pmtctl.8 to $(DESTDIR)$(MANDIR)/man8/"
 
 install-lib:
 	$(MAKE) -C $(LIBDIR) BUILD=$(BUILD) PREFIX=$(PREFIX) DESTDIR=$(DESTDIR) install-lib
@@ -172,10 +176,12 @@ install-pkgconfig:
 
 uninstall:
 	rm -f $(DESTDIR)$(PREFIX)/bin/$(TARGET)
+	rm -f $(DESTDIR)$(MANDIR)/man8/pmtctl.8
 	$(MAKE) -C $(LIBDIR) BUILD=$(BUILD) PREFIX=$(PREFIX) DESTDIR=$(DESTDIR) uninstall-lib
 	$(MAKE) -C $(LIBDIR) BUILD=$(BUILD) PREFIX=$(PREFIX) DESTDIR=$(DESTDIR) uninstall-headers
 	$(MAKE) -C $(LIBDIR) BUILD=$(BUILD) PREFIX=$(PREFIX) DESTDIR=$(DESTDIR) uninstall-pkgconfig
 	@echo "Removed $(DESTDIR)$(PREFIX)/bin/$(TARGET) (if present)"
+	@echo "Removed $(DESTDIR)$(MANDIR)/man8/pmtctl.8 (if present)"
 defs: $(GENERATED_DIR)/builtin_defs.c
 	@if [ -f $(GENERATED_DIR)/builtin_defs.c ]; then \
 		echo "Generated defs in $(GENERATED_DIR)/builtin_defs.c"; \
diff --git a/tools/arch/x86/pmtctl/README.md b/tools/arch/x86/pmtctl/README.md
index 0827ff20fc86..865c7af2c266 100644
--- a/tools/arch/x86/pmtctl/README.md
+++ b/tools/arch/x86/pmtctl/README.md
@@ -260,6 +260,9 @@ Installs:
 - `lib/libpmtctl_core.a`
 - `include/pmtctl/{pmtctl.h,metrics_db.h,device.h}`
 - `lib/pkgconfig/libpmtctl-core.pc`
+- `share/man/man8/pmtctl.8`
+
+Override `MANDIR` (default `$(PREFIX)/share/man`) to relocate the man page.
 
 Uninstall:
 
diff --git a/tools/arch/x86/pmtctl/pmtctl.8 b/tools/arch/x86/pmtctl/pmtctl.8
new file mode 100644
index 000000000000..f79480f9febf
--- /dev/null
+++ b/tools/arch/x86/pmtctl/pmtctl.8
@@ -0,0 +1,317 @@
+.\" SPDX-License-Identifier: GPL-2.0-only
+.TH PMTCTL 8 "May 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
+Metric definitions can come from one of two sources:
+.IP \(bu 2
+Built-in definitions compiled into the binary at build time from
+the Intel PMT XML descriptions (used when
+.B \-J
+is not given).
+.IP \(bu 2
+A runtime JSON file or directory supplied with
+.BR \-J / \-\-json\-file .
+.PP
+Most operations require access to PMT telemetry files and therefore
+typically need to be run as
+.BR root .
+.PP
+.B pmtctl
+also installs a reusable C library
+.RB ( libpmtctl_core )
+and public headers under
+.IR <prefix>/include/pmtctl/ ;
+see
+.B SEE ALSO
+below.
+.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 metric definitions from the given JSON file or directory at
+runtime. When omitted, the built-in definitions (if any) compiled
+into the binary are used.
+.TP
+.BR \-d ", " "\-\-device " \fIselector\fR
+Restrict operation to a single PMT endpoint. The selector takes one
+of the following forms:
+.RS
+.IP \fBguid=\fIhex\fR
+Match by 32-bit PMT GUID, e.g. \fBguid=27971628\fR.
+.IP \fBep=\fIname\fR
+Match by endpoint name as reported by \fBpmtctl list \-\-devices\fR.
+.RE
+.IP
+The selector may also be supplied after the command name as a
+fallback; if both are given, the global value takes precedence.
+.TP
+.BR \-q ", " \-\-quiet
+Suppress non-essential messages.
+.TP
+.B \-\-debug
+Enable debug logging on stderr.
+.SH COMMANDS
+.SS list
+.B pmtctl list
+.RI [ options ]
+.PP
+List PMT metrics known to
+.B pmtctl
+and, optionally, the PMT devices/endpoints discovered on the running
+system. Without options, metrics are grouped by GUID.
+.TP
+.BR \-h ", " \-\-help
+Show help for
+.B list
+and exit.
+.TP
+.BR \-d ", " "\-\-device " \fIselector\fR
+Restrict the listing to a single endpoint. See
+.B GLOBAL OPTIONS
+above for selector syntax.
+.TP
+.B \-\-devices
+List discovered PMT devices/endpoints only; do not list metric
+definitions.
+.TP
+.B \-\-guids
+Emit a report that shows the GUIDs present in the loaded metric
+definitions, the GUIDs discovered on the system, and the
+intersection of the two.
+.TP
+.BR \-X ", " \-\-keep
+Keep the last pager screen visible after quitting. Useful when
+the output will be referenced immediately (for example, to copy a
+metric name for use with
+.BR "pmtctl stat" ).
+.SS stat
+.B pmtctl stat
+.RI [ options ]
+.B \-e
+.IR metric [,\fImetric\fR...]
+\&...
+.br
+.B pmtctl stat
+.RI [ options ]
+.B \-\-raw
+.BI id= N
+.RI [,\fBlsb=\fP N ][,\fBmsb=\fP N ]
+\&...
+.PP
+Sample one or more PMT metrics (or raw sample values) over time, in
+a manner similar to
+.BR "perf stat" .
+On a metric read failure the value is printed as
+.BR NaN .
+.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. When more than one metric is requested, the
+.B \-\-vertical
+output mode is required. Mutually exclusive with
+.BR \-\-raw .
+.TP
+.BR \-d ", " "\-\-device " \fIselector\fR
+Restrict to a single device/endpoint. See
+.B GLOBAL OPTIONS
+above for selector syntax.
+.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 indefinitely.
+.TP
+.B \-\-once
+Take a single snapshot and exit (equivalent to
+.B "\-\-count 1"
+with no inter-sample delay).
+.TP
+.B \-\-raw \fBid=\fIN\fR[\fB,lsb=\fIN\fR][\fB,msb=\fIN\fR]
+Read raw sample values by sample
+.B id
+with optional bit-field slicing. Constraints:
+.B id
+must be \(>= 0;
+.B lsb
+defaults to 0 and
+.B msb
+defaults to 63; both must satisfy
+0 \(<=
+.B lsb
+\(<=
+.B msb
+\(<= 63. May be specified multiple times. Mutually exclusive with
+.BR \-e .
+.TP
+.BR \-\-header ", " \-\-no\-header
+Force header printing on or off.
+.TP
+.B \-\-hex
+Print sample values in hexadecimal.
+.TP
+.B \-\-vertical
+One line per metric per sample (sample index, time in ms, device,
+metric, value). Required when more than one metric is selected.
+.SH EXAMPLES
+List all known metrics (built-in or loaded via \fB\-J\fR):
+.PP
+.RS 4
+.nf
+pmtctl list
+.fi
+.RE
+.PP
+Show the GUID overlap between definitions and the running system:
+.PP
+.RS 4
+.nf
+pmtctl list \-\-guids
+.fi
+.RE
+.PP
+Load definitions from a directory at runtime and list devices only:
+.PP
+.RS 4
+.nf
+pmtctl \-J /path/to/metrics/ list \-\-devices
+.fi
+.RE
+.PP
+Keep the last screen visible on exit (handy before running stat):
+.PP
+.RS 4
+.nf
+pmtctl list \-X
+.fi
+.RE
+.PP
+Sample a single metric every 500 ms until interrupted:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e socket_power \-\-interval 500
+.fi
+.RE
+.PP
+Take a single snapshot and exit:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e fw_version_0 \-\-once
+.fi
+.RE
+.PP
+Take a single snapshot of a metric on a specific GUID:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e temp_core0 \-d guid=27971628 \-\-once
+.fi
+.RE
+.PP
+Sample multiple metrics (requires \fB\-\-vertical\fR):
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e temp_socket,socket_power \-\-vertical \-c 5
+.fi
+.RE
+.PP
+Print a value in hexadecimal:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-e fw_version_0 \-\-once \-\-hex
+.fi
+.RE
+.PP
+Read raw sample values, slicing bit fields out of two samples:
+.PP
+.RS 4
+.nf
+sudo pmtctl stat \-\-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
+.IR <prefix>/include/pmtctl/
+Public C headers for
+.BR libpmtctl_core .
+.TP
+.IR <prefix>/lib/pkgconfig/libpmtctl\-core.pc
+pkg-config file for
+.BR libpmtctl_core .
+.SH EXIT STATUS
+.TP
+.B 0
+Success.
+.TP
+.B 1
+Usage or user error (for example, invalid command-line options).
+.TP
+.B 2
+Device, system, or runtime error (for example, the PMT telemetry
+driver is not loaded or a read failed).
+.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.43.0