PEPC-PSTATES(1)

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

👑 PEPC-PSTATES(1) — the pstates glow-up 👑

okay bestie, welcome to PEPC-PSTATES(1), a General Commands Manual moment. this is the page for the command pstates and she is that girl. buckle up, we're going module by module. 🦋

✨ Command 'pstates' ✨

🌸 General options 🌸

these are the ones that apply no matter what you're doing. the little black dresses of flags. 💅

  • -h — shows you a short help message and then dips. bye! 👋
  • -q — be quiet mode. only important messages get through (think: warnings). lowkey a vibe. 🤫
  • -d — print debugging information. yes, all of it. it's giving loud. 🗣️
  • --debug-modules MODNAME[,MODNAME1,...] — so -d turns on every debug message ever, which is a lot. this option narrows it down to just the modules you name. like, -d --debug-modules MSR will only show debug messages from the MSR module. slay, targeted. 🎯
  • --version — prints the version number and exits. periodt. ⭐
  • -H HOSTNAME, --host HOSTNAME — host name or IP address of the target system. the pepc command gets executed over on that system using SSH instead of running locally. if you don't specify it, the command just runs locally. homebody behavior, honestly. 🏠
  • -U USERNAME, --username USERNAME — the name of the user you're logging into the remote host as, over SSH. by default it looks the user name up in SSH configuration files, and if it's not there, it uses the current user name. ✨
  • -K PRIVKEY, --priv-key PRIVKEY — path to the private SSH key for logging into the remote host. if you don't specify one, the keys configured for the host in SSH configuration files (e.g. ~/.ssh/config) get used. if nothing's configured there, standard key files (e.g. ~/.ssh/id_rsa) and the SSH agent get tried. the full backup plan energy. 🔑
  • -D DATASET, --dataset DATASET — for debugging and testing. it specifies the dataset to use for emulating the host that the command runs on. the datasets live in the pepc source code repository.

the argument can be a dataset path or a name. if you give a name, these locations get searched, in this order:

  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 — forces colorized output even when the output stream isn't a terminal. yes, it adds ANSI escape codes. rainbow whether you asked or not 🌈
  • --print-man-path — prints the pepc manual pages directory path and exits. add this path to the MANPATH environment variable so the manual pages become available to the man tool. very helpful of her. 🫶
  • --override-cpu-model VFM — for debugging and testing only. overrides the target host CPU model and forces 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 you omit them, the target host values get used. family and model can be written in decimal or hexadecimal. 🧚

🎀 Target CPU specification options 🎀

all the subcommands (info, config) support these target CPU specification options. it's giving "pick your fighter". 💖

  • --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. heads up: 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're relative to the package. it depends, bestie. 🤷
  • --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. 😭
  • --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' 🦋

retrieves CPU P-states information for the CPUs you specify. by default it displays all details for all CPUs. use the target CPU specification options above to define a subset of CPUs, cores, dies, or packages. the way that this subcommand just hands you the whole picture… obsessed. 💖

  • -m MECHANISMS, --mechanisms MECHANISMS — a comma-separated list of mechanisms for retrieving information. use --list-mechanisms to view the available ones. many options support only one mechanism (e.g., sysfs), while others may support multiple (e.g., sysfs and msr). mechanisms get tried in the order you specified. by default, all mechanisms are allowed, and the most preferred ones are tried first. ✨
  • --list-mechanisms — displays the available mechanisms for retrieving CPU P-states information. 👀
  • --min-freq — retrieves the minimum CPU frequency from /sys/devices/system/cpu/cpu<N>/cpufreq/scaling_min_freq.
  • --max-freq — retrieves the maximum CPU frequency from /sys/devices/system/cpu/cpu<N>/cpufreq/scaling_max_freq.
  • --min-freq-limit — retrieves the minimum supported CPU frequency from /sys/devices/system/cpu/cpu<N>/cpufreq/cpuinfo_min_freq.
  • --max-freq-limit — retrieves the maximum supported CPU frequency from /sys/devices/system/cpu/cpu<N>/cpufreq/cpuinfo_max_freq.
  • --hwp — checks if hardware power management is enabled. when it's enabled, CPUs can scale their frequency automatically without OS involvement. mechanism: msr, reads MSR_PM_ENABLE (0x770), bit 0. this setting has global scope. 🌍
  • --frequencies — lists the CPU frequencies supported by the Linux kernel for the --min-freq and --max-freq options. if /sys/devices/system/cpu/cpufreq/policy<N>/scaling_available_frequencies is available (usually the case with the acpi_cpufreq driver), it retrieves the data from there. otherwise, in the case of an Intel platform, it assumes that all frequencies from --min-freq-limit to --max-freq-limit are available with a step equal to --bus-clock. 🎶
  • --base-freq — retrieves the base CPU frequency from /sys/devices/system/cpu/cpu<N>/cpufreq/base_frequency. if that file is unavailable, it falls back to /sys/devices/system/cpu/cpu<N>/cpufreq/bios_limit. 🔄
  • --fixed-base-freq — retrieves the CPU fixed base frequency from MSR_PLATFORM_INFO (0xCE), bits 15:8.
  • --bus-clock — retrieves the bus clock frequency, one of the CPU's reference clocks. the msr mechanism reads MSR_FSB_FREQ (0xCD), bits 2:0, for legacy Intel platforms. for modern Intel platforms, the doc mechanism assumes a 100MHz bus clock. ⏰
  • --turbo — checks if turbo is enabled or disabled. when it's enabled, CPUs can run at frequencies above the base frequency if the OS and thermal conditions allow it. it reads the sysfs file based on the CPU frequency driver: intel_pstate — /sys/devices/system/cpu/intel_pstate/no_turbo, acpi-cpufreq — /sys/devices/system/cpu/cpufreq/boost. the setting has global scope. 🚀
  • --epp — retrieves EPP (Energy Performance Preference) using sysfs (preferred) or msr mechanisms. EPP is a hint to the CPU on energy efficiency versus performance. on Intel CPUs, both msr and sysfs mechanisms are supported, with values ranging from 0-255 (maximum energy efficiency to maximum performance) or policy names (sysfs mechanism only). on AMD CPUs, only sysfs is supported, with policy names only. the sysfs mechanism reads /sys/devices/system/cpu/cpufreq/policy<N>/energy_performance_preference, while the msr mechanism reads MSR_HWP_REQUEST (0x774), bits 31:24. 🌱
  • --epb — retrieves EPB (Energy Performance Bias) using sysfs (preferred) or msr mechanisms. EPB is a hint to the CPU on energy efficiency versus performance. the value ranges from 0-15 (maximum performance to maximum energy efficiency) or can be a policy name (supported by sysfs only). the sysfs mechanism reads /sys/devices/system/cpu/cpu<N>/power/energy_perf_bias, while the msr mechanism reads MSR_ENERGY_PERF_BIAS (0x1B0), bits 3:0. 🍃
  • --driver — retrieves the CPU frequency driver name. the driver enumerates and manages CPU P-states on the platform. the name is read from /sys/devices/system/cpu/cpufreq/policy<N>/scaling_driver. while sysfs provides a per-CPU API, Intel platforms typically use a single driver. 🚗
  • --intel-pstate-mode — retrieves the intelpstate driver mode: active, passive, or off. in active mode, custom intelpstate governors are used. in passive mode, generic Linux governors are employed. the mode is read from /sys/devices/system/cpu/intel_pstate/status. 🎛️

okay that's part 1 bestie, don't go anywhere, there's more coming 💅

  • --governor — pulls the CPU frequency governor for you 💅 and yes, the governor is literally the thing that picks the P-state based on CPU load and other factors. Reads the name straight outta /sys/devices/system/cpu/cpufreq/policy<N>/scaling_governor.
  • --governors — shows you the whole menu of available CPU frequency governors. Every governor decides a CPU's P-state from its activity and other factors, and each one runs its own little selection policy like it's the main character. The lineup lives in /sys/devices/system/cpu/cpufreq/policy<N>/scaling_available_governors.
  • --cppc-lowest-perf — grabs the ACPI CPPC lowest performance level value for the CPUs you asked for, from /sys/devices/system/cpu/cpu<N>/acpi_cppc/lowest_perf.
  • --cppc-lowest-nonlinear-perf — same energy, different stat: the ACPI CPPC lowest nonlinear performance level value for specified CPUs, from /sys/devices/system/cpu/cpu<N>/acpi_cppc/lowest_nonlinear_perf.
  • --cppc-guaranteed-perf — yanks the ACPI CPPC guaranteed performance level value for specified CPUs out of /sys/devices/system/cpu/cpu<N>/acpi_cppc/guaranteed_perf.
  • --cppc-nominal-perf — the ACPI CPPC nominal performance level value for specified CPUs, served fresh from /sys/devices/system/cpu/cpu<N>/acpi_cppc/nominal_perf.
  • --cppc-highest-perf — the ACPI CPPC highest performance level value for specified CPUs, from /sys/devices/system/cpu/cpu<N>/acpi_cppc/highest_perf.
  • --cppc-nominal-freq — the ACPI CPPC nominal frequency for specified CPUs, sitting pretty in /sys/devices/system/cpu/cpu<N>/acpi_cppc/nominal_freq.
  • --hwp-lowest-perf — the HWP lowest performance level for specified CPUs. It reads MSR_HWP_CAPABILITIES (0x771), bits 31:24 ✨
  • --hwp-efficient-perf — the HWP most efficient performance level for specified CPUs. Reads MSR_HWP_CAPABILITIES (0x771), bits 23:16.
  • --hwp-guaranteed-perf — the HWP guaranteed performance level for specified CPUs. Reads MSR_HWP_CAPABILITIES (0x771), bits 15:8.
  • --hwp-highest-perf — the HWP highest performance level for specified CPUs. Reads MSR_HWP_CAPABILITIES (0x771), bits 7:0.
  • --hwp-min-perf — the minimum HWP performance level for specified CPUs. Reads MSR_HWP_REQUEST (0x774), bits 7:0. ⚠️ But if package-level control is enabled, it reads from MSR_HWP_REQUEST_PKG (0x772) instead.
  • --hwp-max-perf — the maximum HWP performance level for specified CPUs. Reads MSR_HWP_REQUEST (0x774), bits 15:8. Same plot twist: if package-level control is on, it goes to MSR_HWP_REQUEST_PKG (0x772) instead.
  • --yaml — outputs everything in YAML format. Clean, structured, lowkey gorgeous 🌸

🎀 Subcommand 'config' 🎀

Okay bestie, this is the doing mode: configure CPU P-states for specified CPUs. If you don't pass any parameter, it just shows you the current value(s) instead — a lil vibe check, no changes. Use the target CPU specification options to define the subset of CPUs, cores, dies, or packages you're messing with.

  • -m MECHANISMS, --mechanisms MECHANISMS — a comma-separated list of the mechanisms allowed for configuring CPU P-states. Run --list-mechanisms to see what's available. Heads up: lots of options only support one mechanism (like 'sysfs'), while some support multiple (like 'sysfs' and 'msr'). Mechanisms get tried in the order you list them. By default, all mechanisms are allowed and the most preferred ones are tried first.
  • --list-mechanisms — shows the available mechanisms for configuring CPU P-states. iykyk 👑
  • --min-freq [MIN_FREQ] — sets the minimum CPU frequency via /sys/devices/system/cpu/cpu<N>/cpufreq/scaling_min_freq. Default unit is 'Hz', but you can also use 'kHz', 'MHz', and 'GHz' (like "900MHz").

And the special values, because of course there are special values:

  • min — minimum frequency supported by the Linux CPU frequency driver (see '--min-freq-limit').
  • max — maximum frequency supported by the Linux CPU frequency driver (see '--max-freq-limit').
  • base, hfm — base CPU frequency (see '--base-freq').
  • --max-freq [MAX_FREQ] — basically '--min-freq''s twin, except it sets the maximum CPU frequency via /sys/devices/system/cpu/cpu<N>/cpufreq/scaling_max_freq.
  • --turbo [on|off] — toggles turbo mode globally via sysfs. When it's on, CPUs can exceed the base frequency if the OS and thermal conditions allow it. 🔥 For the 'intel_pstate' driver, it uses /sys/devices/system/cpu/intel_pstate/no_turbo. For the 'acpi-cpufreq' driver, it uses /sys/devices/system/cpu/cpufreq/boost.
  • --epp [EPP] — sets EPP (Energy Performance Preference) using the 'sysfs' (preferred) or 'msr' mechanism. EPP is a hint to the CPU about energy efficiency versus performance. The value ranges from 0-255 (maximum energy efficiency all the way to maximum performance), or you can pass a policy name (that one's 'sysfs'-only, bestie). The 'sysfs' mechanism writes to /sys/devices/system/cpu/cpufreq/policy<N>/energy_performance_preference, while the 'msr' mechanism writes to MSR_HWP_REQUEST (0x774), bits 31:24.
  • --epb [EPB] — sets EPB (Energy Performance Bias) using 'sysfs' (preferred) or 'msr'. EPB is also a hint to the CPU on energy efficiency versus performance — note the range runs the other way: 0-15 (maximum performance to maximum energy efficiency), or a policy name ('sysfs' only, again). The 'sysfs' mechanism writes to /sys/devices/system/cpu/cpu<N>/power/energy_perf_bias, while the 'msr' mechanism writes to MSR_ENERGY_PERF_BIAS (0x1B0), bits 3:0.
  • --intel-pstate-mode [INTELPSTATEMODE] — sets the 'intelpstate' driver mode: 'active', 'passive', or 'off'. In 'active' mode, custom 'intelpstate' governors get used. In 'passive' mode, the generic Linux governors are employed instead. Writes to /sys/devices/system/cpu/intel_pstate/status.
  • --governor [GOVERNOR] — sets the CPU frequency governor, the lil decision-maker that determines the P-state based on CPU load and other factors. Writes to /sys/devices/system/cpu/cpufreq/policy<N>/scaling_governor.
  • --hwp-min-perf [HWPMINPERF] — sets the minimum HWP performance level for specified CPUs. Writes to MSR_HWP_REQUEST (0x774), bits 7:0. ⚠️ If package-level control is enabled, it gets overridden so you can have per-CPU control.
  • --hwp-max-perf [HWPMAXPERF] — sets the maximum HWP performance level for specified CPUs. Writes to MSR_HWP_REQUEST (0x774), bits 15:8. Same deal: if package-level control is enabled, it's overridden to allow per-CPU control.

And that's a wrap on the options, bestie 💖 the footer of this page reads PEPC-PSTATES(1) — that's the manual's source/version-and-date sign-off, so shoutout to whoever packaged it up for you. Go forth and slay those P-states 👑✨

📦 where this page comes from