PEPC-UNCORE(1)

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

okay bestie, welcome to the PEPC-UNCORE(1) manual page — that's the uncore command, from the General Commands Manual section. 💖 no cap, we're gonna keep every single detail, just with extra sparkle. ✨

Command 'uncore' 👑

General options ✨

  • -h — bestie, this just shows a short help message and exits. 👋
  • -q — quiet mode: only the important messages like warnings get printed. 🤫
  • -d — prints debugging information. 🐛
  • --debug-modules MODNAME[,MODNAME1,...] — so -d turns on all debug messages, but this one limits them to the modules you list. for example, -d --debug-modules MSR will only show debug messages from the MSR module. 🎯
  • --version — prints the version number and exits. 💌
  • -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 you don't specify it, the command runs 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 it's 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 the pepc source code repository. 📚

the argument can be a dataset path or name. if specified by name, these 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). 🌈
  • --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. 📖
  • --override-cpu-model VFM — for debugging and testing only. override the target host CPU model and force pepc to treat the host as a specific CPU model. the format is [<Vendor>:][<Family>:]<Model>, where <Vendor> is the CPU vendor (e.g., GenuineIntel or AuthenticAMD), <Family> is the CPU family (e.g., 6), and <Model> is the CPU model (e.g., 0x8F). example: GenuineIntel:6:0x8F treats the target as a Sapphire Rapids Xeon. vendor and family are optional. if omitted, the target host values are used. family and model can be specified in decimal or hexadecimal format. 🧠
heads up bestie: --override-cpu-model is for debugging and testing only. no cap. 🫶

Target domain specification options 🎯

all subcommands (info, config) support these target domain specification options. periodt. 💅

  • --cpus CPUS — the list can include individual CPU numbers and CPU number ranges. for example, 1-4,7,8,10-12 would mean CPUs 1 to 4, CPUs 7, 8, and 10 to 12. use the special keyword all to specify all CPUs. 🧮
  • --cores CORES — the list can include individual core numbers and core number ranges. for example, 1-4,7,8,10-12 would mean cores 1 to 4, cores 7, 8, and 10 to 12. use the special keyword all to specify all cores. core numbers are relative to the package. 🍩
  • --modules MODULES — the list can include individual module numbers and module number ranges. for example, 0,2-5 would mean module 0 and modules 2, 3, 4, and 5. use the special keyword all to specify all modules. note that unlike core and die numbers, module numbers are absolute. 📦
  • --dies DIES — the list can include individual die numbers and die number ranges. for example, 0-3,5 would mean dies 0 to 3, and die 5. use the special keyword all to specify all dies. on some systems, die numbers are globally unique, while on other systems they are relative to the package. 🎲
  • --packages PACKAGES — the list can include individual package numbers and package number ranges. for example, 0,2-4 would mean package 0 and packages 2 to 4. use the special keyword all to specify all packages. 🎁
  • --core-siblings CORE_SIBLINGS — core siblings are CPUs sharing the same core. the list can include individual core sibling indices or index ranges. for example, if a core includes CPUs 3 and 4, index 0 would mean CPU 3 and index 1 would mean CPU 4. this option can only be used to reference online CPUs, because Linux does not provide topology information for offline CPUs. in the example with CPUs 3 and 4, if CPU 3 was offline, then index 0 would mean CPU 4 and index 1 would be invalid. 👯
  • --module-siblings MODULE_SIBLINGS — module siblings are CPUs sharing the same module. the list can include individual module sibling indices or index ranges. for example, if a module includes CPUs 3, 4, 5, and 6, index 0 would mean CPU 3, index 1 would mean CPU 4, index 2 would mean CPU 5, and index 3 would mean CPU 6. this option can only be used to reference online CPUs, because Linux does not provide topology information for offline CPUs. in the example with CPUs 3, 4, 5, and 6, if CPU 4 was offline, then index 1 would mean CPU 5, index 2 would mean CPU 6, and index 3 would be invalid. 👯‍♀️

Subcommand 'info' 🔍

retrieve uncore information for specified dies. by default, display all details for all dies. use target domain specification options to define a subset of CPUs, cores, dies, or packages. 💖

  • -m MECHANISMS, --mechanisms MECHANISMS — a comma-separated list of mechanisms for retrieving information. use --list-mechanisms to view available mechanisms. many options support only one mechanism (e.g., sysfs), while others may support multiple (e.g., sysfs and tpmi). mechanisms are tried in the specified order. by default, all mechanisms are allowed, and the most preferred ones are tried first. 🧰
  • --list-mechanisms — display available mechanisms for retrieving uncore information. 📋
  • --min-freq — retrieve the minimum uncore frequency. the supported mechanisms are: sysfs, tpmi. in case of the sysfs mechanism, the sysfs path depends on what uncore driver is used. in case of the inteluncorefrequencytpmi driver, use /sys/devices/system/cpu/intel_uncore_frequency/uncore<NUMBER>/min_freq_khz. in case of the inteluncore_frequency driver, use /sys/devices/system/cpu/intel_uncore_frequency/package_<NUMBER>_die_<NUMBER>/min_freq_khz. 📉

the tpmi mechanism uses the tpmi driver debugfs interface to access TPMI registers. the exact path depends on the target die number. example of the debugfs file path is /sys/kernel/debug/tpmi-0000:00:03.1/tpmi-id-02/mem_dump. 🧬

  • --max-freq — retrieve the maximum uncore frequency. similar to --min-freq, but for the maximum uncore frequency. uses the same mechanisms as --min-freq, but the sysfs mechanism uses the maxfreqkhz file instead of minfreqkhz. 📈
  • --min-freq-limit — retrieve the minimum uncore frequency limit supported by the kernel. the supported mechanism is sysfs. in case of the inteluncorefrequencytpmi driver, read /sys/devices/system/cpu/intel_uncore_frequency/uncore<NUMBER>/initial_min_freq_khz. in case of the inteluncore_frequency driver, read /sys/devices/system/cpu/intel_uncore_frequency/package_<NUMBER>_die_<NUMBER>/initial_min_freq_khz. 🚧

the tpmi mechanism does not provide minimum or maximum uncore frequency limits (the allowed range). the Linux uncore frequency driver determines these limits by reading and storing the default minimum and maximum frequencies from TPMI during initialization, assuming they were correctly configured by the BIOS during platform boot. 🧠

  • --max-freq-limit — retrieve the maximum uncore frequency limit. similar to --min-freq-limit, but for the maximum uncore frequency limit. uses the same mechanisms as --min-freq-limit, but the sysfs mechanism uses the initialmaxfreqkhz file instead of initialminfreqkhz. 🚧
  • --elc-low-zone-min-freq — retrieve the ELC low zone minimum uncore frequency. the supported mechanisms are: sysfs, tpmi. in case of the sysfs mechanism, read /sys/devices/system/cpu/intel_uncore_frequency/uncore<NUMBER>/elc_floor_freq_khz. 🌊

the tpmi mechanism uses the tpmi driver debugfs interface to access TPMI registers. the exact path depends on the target die number. example of the debugfs file path is /sys/kernel/debug/tpmi-0000:00:03.1/tpmi-id-02/mem_dump. 🧬

when the aggregate die utilization falls below or equals the ELC low threshold value (--elc-low-threshold), the die enters the ELC low zone. its uncore frequency floor is set to the ELC low zone minimum frequency (--elc-low-zone-min-freq), unless the global minimum uncore frequency (--min-freq) is higher, in which case the global minimum uncore frequency is used as the floor. 📉

  • --elc-mid-zone-min-freq — retrieve the ELC middle zone minimum uncore frequency. only the tpmi mechanism is supported. reads the same TPMI debugfs files as --elc-low-zone-min-freq. 🌊

when the aggregate die utilization is above the ELC low threshold value (--elc-low-threshold), but below the ELC high threshold value (--elc-high-threshold), the die enters the ELC middle zone. its uncore frequency floor is set to the ELC middle zone minimum frequency (--elc-mid-zone-min-freq), unless the global minimum uncore frequency (--min-freq) is higher, in which case the global minimum uncore frequency is used as the floor. 📉

  • --elc-low-threshold — bestie, this one gets the uncore ELC low threshold 💖. The threshold is literally the aggregate die utilization percentage. When utilization falls below this threshold, the platform sets the uncore frequency floor to the low ELC frequency (but it's subject to the --min-freq-limit — if the limit is higher than the low ELC frequency, the limit is used as the floor instead, no cap). Supported mechanisms are: sysfs, tpmi. The sysfs mechanism reads the /sys/devices/system/cpu/intel_uncore_frequency/uncore<NUMBER>/elc_low_threshold_percent. The tpmi reads the same debugfs files as --min-freq.
  • --elc-high-threshold — get the uncore ELC high threshold ✨. The threshold defines the aggregate die utilization percentage. When die utilization exceeds this threshold, the platform rapidly raises the uncore frequency until die utilization drops below the threshold or the frequency reaches the --max-freq limit. In addition, uncore frequency increases may be prevented by other constraints, such as thermal or power limits. So it's giving "go fast but also chill" energy 🔥. Supported mechanisms are: sysfs, tpmi. The sysfs mechanism reads the /sys/devices/system/cpu/intel_uncore_frequency/uncore<NUMBER>/elc_high_threshold_percent. The tpmi reads the same debugfs files as --max-freq.
  • --elc-high-threshold-status — get the uncore ELC high threshold enabled/disabled status 💅. If disabled, the high threshold is ignored and the platform manages uncore frequency using the default algorithm. So it's like, "do you even want the high threshold, bestie?" 🙈. Supported mechanisms are: sysfs, tpmi. The sysfs mechanism reads the /sys/devices/system/cpu/intel_uncore_frequency/uncore<NUMBER>/elc_high_threshold_enable. The tpmi reads the same debugfs files as --max-freq.
  • --yaml — Display output in YAML format. So aesthetic ✨.
  • --dies-info — Display detailed information about dies and how they map to uncore frequency driver sysfs paths and TPMI UFS feature addresses. Like a whole map of the squad 💖.

✨ Subcommand config ✨

Configure uncore properties for specified dies. If no parameter is provided, the current value(s) will be displayed. Use target domain specification options to define the subset of CPUs, cores, dies, or packages. You can pick your faves, no cap 🎀.

  • -m, --mechanisms MECHANISMS — A comma-separated list of mechanisms allowed for configuring uncore properties. Use --list-mechanisms to view available mechanisms. Many options support only one mechanism (e.g., sysfs), while some support multiple (e.g., sysfs and tpmi). Mechanisms are tried in the specified order. By default, all mechanisms are allowed, and the most preferred ones are tried first. So it's a priority list, periodt 💅.
  • --list-mechanisms — Display available mechanisms for configuring uncore properties. Basically the menu of options 📋.
  • --min-freq [MIN_FREQ] — Set the minimum uncore frequency. The default unit is Hz, but kHz, MHz, and GHz can also be used (for example 900MHz). Uses the same mechanisms as described in the info sub-command. The following special values can also be used:
    • min — Minimum uncore frequency supported (see --min-freq-limit). Regardless of the --mechanisms option, the sysfs mechanism is always used to resolve min to the actual minimum frequency.
    • max — Maximum uncore frequency supported (see --max-freq-limit). Regardless of the --mechanisms option, the sysfs mechanism is always used to resolve max to the actual maximum frequency.
    • mdl — The middle uncore frequency value between minimum and maximum rounded to nearest 100MHz. Regardless of the --mechanisms option, the sysfs mechanism is always used to resolve mdl to the actual middle frequency. Note, the tpmi mechanism does not provide minimum or maximum uncore frequency limits (the allowed range). As a result, it is possible to set uncore frequency values outside the supported limits, such as setting the minimum frequency below the actual minimum limit. Use caution when configuring uncore frequencies with the tpmi mechanism. ⚠️
  • --max-freq [MAX_FREQ] — Set the maximum uncore frequency. Uses the same mechanisms as described in the info sub-command. Similar to --min-freq, but applies to the maximum frequency. So the max version, periodt 💅.
  • --elc-low-zone-min-freq [ELCLOWZONEMINFREQ] — Set the ELC low zone minimum uncore frequency. Uses the same mechanisms as described in the info sub-command. Supports special values min, max, and mdl, similar to --min-freq. Low zone, but make it minimum 💖.
  • --elc-mid-zone-min-freq [ELCMIDZONEMINFREQ] — Set the ELC middle zone minimum uncore frequency. Uses the same mechanisms as described in the info sub-command. Supports special values min, max, and mdl, similar to --min-freq. Middle child energy, but for uncore ✨.
  • --elc-low-threshold [ELCLOWTHRESHOLD] — Set the uncore ELC low threshold. Same as in the info sub-command, but sets the ELC low threshold. So like, you're setting it now, not getting it 💅.
  • --elc-high-threshold [ELCHIGHTHRESHOLD] — Set the uncore ELC high threshold. Same as in the info sub-command, but sets the ELC high threshold. High threshold, but set it, bestie 🔥.
  • --elc-high-threshold-status [on/off] — Set the uncore ELC high threshold enabled/disabled status. Same as in the info sub-command, but sets the ELC high threshold status. On or off, like your notifications 📱.

And that's a wrap on PEPC-UNCORE(1) 💖 — go forth and configure, bestie. No cap. 🫶

📦 where this page comes from