PEPC-TPMI(1)

📦
version 2.0.7 · 2 versions
, in epel 10, epel 9, fedora 44

💖 PEPC-TPMI(1)

okay so bestie, welcome to the General Commands Manual page for the tpmi command 💅 — this is pepc's whole lil corner of the world for talking to TPMI, and it is genuinely giving main character energy, no cap. let's get into it 🦋

🌸 Background

TPMI — aka Topology Aware Register and PM Capsule Interface — is a memory-mapped interface for accessing processor registers related to power management on Intel CPUs ✨

Those registers are exposed via PCIe VSEC (Vendor-Specific Extended Capabilities) and they're grouped into TPMI features. for example:

  • the ufs feature includes registers for uncore frequency scaling 🌈
  • the rapl feature covers Running Average Power Limit (RAPL) registers 🔥
  • the sst feature includes registers for Intel Speed Select Technology (SST) 👑

To decode TPMI features, the pepc tool requires a spec file describing register names, bits, and offsets in the PCIe memory-mapped address space. Features without a spec file cannot be decoded. periodt.

The pepc project includes spec files for some, but not all TPMI features. Spec files for other features can be requested from Intel Corporation via customer support channels 📨

The spec files are searched in the following locations and order:

  1. ./tpmi, in the directory of the running program
  2. $PEPC_TPMI_DATA_PATH/tpmi
  3. $HOME/.local/share/pepc/tpmi
  4. $VIRTUAL_ENV/share/pepc/tpmi
  5. /usr/local/share/pepc/tpmi
  6. /usr/share/pepc/tpmi

The PEPC_TPMI_DATA_PATH provides a mechanism for replacing or extending the standard spec files 🫶 Just set it to a directory with spec files to have pepc use them.

Spec files are YAML files, but they are generated from Intel proprietary XML files using the tpmi-spec-files-generator tool available in the pepc source code repository. iykyk 💜

🎀 General options

  • -h — show a short help message and exit. bye 👋
  • -q — be quiet (print only important messages like warnings). lowkey mode 🤫
  • -d — print debugging information. the girlies love a trace 🔍
  • --debug-modules MODNAME[,MODNAME1,...] — the -d option enables all debug messages. this option limits them to the specified modules. for example, -d --debug-modules MSR will only show debug messages from the MSR module.
  • --version — print the version number and exit ⭐
  • -H HOSTNAME, --host HOSTNAME — host name or IP address of the target system. the pepc command will be executed on this system using SSH, instead of running it locally. if not specified, the command will be run locally 🌐
  • -U USERNAME, --username USERNAME — name of the user to use for logging into the remote host over SSH. by default, look up the user name in SSH configuration files. if not found, use the current user name 🧚
  • -K PRIVKEY, --priv-key PRIVKEY — path to the private SSH key for logging into the remote host. if not specified, keys configured for the host in SSH configuration files (e.g. ~/.ssh/config) are used. if no keys are configured there, standard key files (e.g. ~/.ssh/id_rsa) and the SSH agent are tried 🔑
  • -D DATASET, --dataset DATASET — this option is for debugging and testing. it specifies the dataset to use for emulating the host for running the command on. the datasets are available in pepc source code repository.

The argument can be a dataset path or name. If specified by name, the following locations are searched for the dataset.

  1. ./tests/emul-data in the program's directory
  2. $PEPC_DATA_PATH/tests/emul-data
  3. $VIRTUAL_ENV/share/pepc/tests/emul-data
  4. $HOME/.local/share/pepc/tests/emul-data
  5. /usr/local/share/pepc/tests/emul-data
  6. /usr/share/pepc/tests/emul-data
  • --force-color — force colorized output even if the output stream is not a terminal (adds ANSI escape codes). serving looks on purpose 💅🌈
  • --print-man-path — print the pepc manual pages directory path and exit. add this path to the MANPATH environment variable to make the manual pages available to the man tool 📖

🔍 Subcommand 'ls'

Display supported TPMI features. it discovers features by listing /sys/kernel/debug/tpmi-<PCI-addr>/tpmi-id-<ID> directories in debugfs. when --topology is used, it also reads /sys/kernel/debug/tpmi-<PCI-addr>/tpmi-id-<ID>/mem_dump to enumerate instances 👀

  • -B BASE, --base BASE — path to a copy of the TPMI debugfs contents (a debugfs dump directory). by default, pepc reads from the live system's debugfs at /sys/kernel/debug, searching for tpmi-<PCI-addr> subdirectories within it. this option overrides the default with a custom path, intended for decoding TPMI debugfs dumps captured from a different system 🗂️
  • --vfm VFM — VFM (Vendor, Family, Model) identifier of the target CPU as an integer or in [Vendor:]Family:Model format. use this option with --base when decoding a TPMI debugfs dump to identify the CPU model of the system the dump was captured from 🧬
  • --list-specs — display information about TPMI spec files for the target system and exit. show the detected CPU model and available spec files for that model. spec directories may contain files for different CPU models. select files matching the target system. note that the target system may not support all TPMI features described in the spec files 📋
  • -t, --topology — display TPMI topology (PCI addresses, instance numbers, etc.) 🗺️
  • --unimplemented — include unimplemented TPMI instances. unimplemented instances have version number 0xFF and represent "empty slots" in the instances table of a TPMI feature. for example, instance 0 may be implemented, instance 1 may be unimplemented (version 0xFF), and instance 2 may be implemented. by default, unimplemented instances are not shown in the output 🙈
  • -F FEATURES, --features FEATURES — comma-separated list of TPMI feature names to include in the output. defaults to all supported features ✨

📖 Subcommand 'read'

Read one or more TPMI registers. it reads TPMI data from /sys/kernel/debug/tpmi-<PCI-addr>/tpmi-id-<ID>/mem_dump 📥

  • -B BASE, --base BASE — path to a copy of the TPMI debugfs contents (a debugfs dump directory). by default, pepc reads from the live system's debugfs at /sys/kernel/debug, searching for tpmi-<PCI-addr> subdirectories within it. this option overrides the default with a custom path, intended for decoding TPMI debugfs dumps captured from a different system 🗂️
  • --vfm VFM — VFM (Vendor, Family, Model) identifier of the target CPU as an integer or in [Vendor:]Family:Model format. use this option with --base when decoding a TPMI debugfs dump to identify the CPU model of the system the dump was captured from 🧬
  • -F FEATURES, --features FEATURES — comma-separated list of TPMI feature names to read the registers for. defaults to all supported features ✨
  • -a ADDRS, --addresses ADDRS — comma-separated list of TPMI device PCI addresses to read the registers from. defaults to all devices 📍
  • --packages PACKAGES — comma-separated list of package numbers to read TPMI registers for (defaults to all packages) 📦
  • -i INSTANCES, --instances INSTANCES — comma-separated list of TPMI instance numbers to read registers from (defaults to all instances) 🔢
  • -c CLUSTERS, --clusters CLUSTERS — comma-separated list of cluster numbers to read registers from (defaults to all clusters). this option is only relevant for the ufs TPMI feature, because there may be multiple copies of UFS control registers within a TPMI instance, and the copies are referred to as clusters. all other TPMI features have only one cluster — cluster 0 🍇
  • -R REGISTERS, --registers REGISTERS — comma-separated list of TPMI register names to read. defaults to all registers 📚
  • -b BITFIELDS, --bitfields BITFIELDS — comma-separated list of TPMI register bit field names to decode. defaults to decoding all bit fields 🧩
  • -n, --no-bitfields — do not decode and display TPMI register bit field values. when this option is specified, only register values will be displayed without decoding the individual bit fields within them 🚫
  • --yaml — display information in YAML format 🐍

✍️ Subcommand 'write'

Write a value to a TPMI register or its bit field. it reads and writes TPMI data via /sys/kernel/debug/tpmi-<PCI-addr>/tpmi-id-<ID>/mem_dump (reads) and /sys/kernel/debug/tpmi-<PCI-addr>/tpmi-id-<ID>/mem_write (writes) 📤

bestie be careful here — this one actually writes to your hardware. know what you're doing, fr fr 💀
  • -B BASE, --base BASE — path to a copy of the TPMI debugfs contents (a debugfs dump directory). by default, pepc reads from the live system's debugfs at /sys/kernel/debug, searching for tpmi-<PCI-addr> subdirectories within it. this option overrides the default with a custom path, intended for decoding TPMI debugfs dumps captured from a different system 🗂️
  • --vfm VFM — VFM (Vendor, Family, Model) identifier of the target CPU as an integer or in [Vendor:]Family:Model format. use this option with --base when decoding a TPMI debugfs dump to identify the CPU model of the system the dump was captured from 🧬
  • -F FEATURE, --feature FEATURE — name of the TPMI feature the register belongs to ✨
  • -a ADDRS, --addresses ADDRS — comma-separated list of PCI addresses of TPMI devices to write to 📍
  • --packages PACKAGES — comma-separated list of package numbers to write to (defaults to all packages) 📦
  • -i INSTANCES, --instances INSTANCES — comma-separated list of TPMI instance numbers to write to. defaults to all instances 🔢
  • -c CLUSTERS, --clusters CLUSTERS — comma-separated list of cluster numbers to write to (defaults to all clusters). this option is only relevant for the ufs TPMI feature, because there may be multiple copies of UFS control registers within a TPMI instance, and the copies are referred to as clusters. all other TPMI features have only one cluster — cluster 0 🍇
  • -R REGNAME, --register REGNAME — name of the TPMI register to write ✏️
  • -b BITFIELD, --bitfield BITFIELD — name of the TPMI register bit field to write to. if this option is not specified, the value will be written to the entire register. when specified, only the specified bit field within the register will be modified 🧩
  • -V VALUE, --value VALUE — value to write to the TPMI register or bit field 💾

and that's the whole page bestie 💖 this was PEPC-TPMI(1), straight out of the General Commands Manual — go forth and decode some registers, you absolute icon 👑🦋✨

📦 where this page comes from