PEPC-CSTATES(1)

🦋 PEPC-CSTATES(1) 🦋

General Commands Manual — the one and only cstates command, bestie 💖

okay so. cstates is part of the pepc family and it's literally the main character of CPU idle-state management. it reads your C-states, it configures your C-states, it talks to remote hosts over SSH like it's nothing. no cap. let's get into it 🫶

---

💅 Command 'cstates' 💅

✨ General options ✨

these are the universal vibes — they work everywhere. 🌈

• -h — show a short help message and then exit. the classic "wait what do i do" button.
• -q — be quiet. like, only print the important stuff (warnings and things of that nature). shhh 🤫
• -d — print debugging information. the "tell me everything that's happening" mode.
• --debug-modules MODNAME[,MODNAME1,...] — so -d turns on ALL the debug messages, and this option is the vibe check that narrows them down to the modules you name. for example, -d --debug-modules MSR will only show debug messages coming from the MSR module. slay, targeted debugging 💅
• --version — print the version number and exit. identity check ✨
• -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. 🏠
• -U USERNAME, --username USERNAME — the name of the user to log into the remote host as, over SSH. by default it looks up the user name in SSH configuration files. if it can't find it 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, 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 get tried. 🔑
• -D DATASET, --dataset DATASET — this one is for debugging and testing. it specifies the dataset to use for emulating the host for running the command on. the datasets live in the pepc source code repository.

the argument can be a dataset path or a name. if you specify it by name, these locations get searched, in 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 — force colorized output even if the output stream is not a terminal (it adds ANSI escape codes). for when you want the ✨aesthetic✨ anyway.
• --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. it 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 specified in decimal or hexadecimal format. 🔥

---

🔥 Target CPU specification options 🔥

all the subcommands (info, config) support these target CPU specification options. they're how you pick which CPUs you're even talking about. 🎯

• --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. important detail, don't forget it 💫
• --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. it's giving "depends on your platform" 🦋
• --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' 🎀

retrieve C-state information for specified CPUs. by default, it displays all details for all CPUs. use the target CPU 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 msr). 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 C-states information.
• --cstates [CSTATES] — a comma-separated list of C-states to retrieve information about, specified by name (e.g., C1). use all to include all available Linux C-states (default). Linux C-states (e.g., C6) are requests Linux can make, while hardware C-states (e.g., Core C6 or Package C6 on Intel platforms) are platform-specific states entered upon such requests. see https://github.com/dedekind/dedekind-share/blob/master/2025/cstate-namespaces.md for details. reads C-state information from /sys/devices/system/cpu/cpu<N>/cpuidle/state<M>/. 🌸
• --pkg-cstate-limit — retrieve the current package C-state limit, available limits, and lock status. the package C-state limit defines the deepest hardware package C-state the platform can enter. it is read from MSR_PKG_CST_CONFIG_CONTROL (0xE2), bits 2:0 or 3:0, depending on the CPU model. the lock bit (bit 15) in the same MSR determines if the OS can modify the limit. 🔒
• --c1-demotion — check if C1 demotion is enabled or disabled. on Intel platforms, this feature monitors CPU wake-up rates. if the rate exceeds a threshold, deep C-state requests are demoted to C1 to improve performance at the cost of higher power consumption. read from MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 26.
• --c1-undemotion — check if C1 undemotion is enabled or disabled. when enabled, the CPU can reverse previously demoted requests from C1 back to deeper C-states (e.g., C6) if frequent wake-ups have stopped. read from MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 28.
• --c1e-autopromote — check if C1E autopromotion is enabled. when enabled, the CPU converts all C1 C-state requests to C1E requests. read from MSR_POWER_CTL (0x1FC), bit 1.
• --cstate-prewake — check if C-state prewake is enabled. when enabled, the CPU considers idle timers and starts exiting deep C-states early, before the next local APIC timer event. this ensures the CPU is nearly awake by the time the timer fires. read from MSR_POWER_CTL (0x1FC), bit 30. ⏰
• --idle-driver — retrieve the idle driver name. the idle driver enumerates available C-states and issues C-state requests. read from /sys/devices/system/cpu/cpuidle/current_driver.
• --governor — retrieve the idle governor name, which determines the C-state to request for an idle CPU. read from /sys/devices/system/cpu/cpuidle/current_governor.
• --governors — retrieve the list of available idle governors, which determine the C-state to request for an idle CPU. different governors implement various selection policies. read from /sys/devices/system/cpu/cpuidle/available_governors. the plural is a whole list, bestie 🗂️
• --yaml — display output in YAML format. for the structured-output girlies 💜

---

🍓 Subcommand 'config' 🍓

configure C-states for specified CPUs. if no parameter is provided, the current value(s) will be displayed. use the target CPU specification options to define the subset of CPUs, cores, dies, or packages. 🛠️

• -m MECHANISMS, --mechanisms MECHANISMS — a comma-separated list of mechanisms allowed for configuring C-states. use --list-mechanisms to view available mechanisms. many options support only one mechanism (e.g., sysfs), while some support multiple (e.g., sysfs and msr). 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 configuring C-states.
• --enable [CSTATES] — a comma-separated list of C-state names to enable. use all to include all available Linux C-states (default). Linux C-states (e.g., C6) are requests Linux can make, while hardware C-states (e.g., Core C6 or Package C6 on Intel platforms) are platform-specific states entered upon such requests. see https://github.com/dedekind/dedekind-share/blob/master/2025/cstate-namespaces.md for details. enables a C-state by writing 0 to /sys/devices/system/cpu/cpu<N>/cpuidle/state<M>/disable. ✅
• --disable [CSTATES] — the evil twin of --enable 🙈 but like, not evil, just the off switch. You tell it which C-states to disable, and it does the thing by writing 1 to /sys/devices/system/cpu/cpu<N>/cpuidle/state<M>/disable.
  • so yes, same path shape as its sibling, <N> is the CPU, <M> is the state index, and 1 = "girl, stay awake". slay 💅
• --pkg-cstate-limit [PKGCSTATELIMIT] — sets the package C-state limit, aka the deepest hardware package C-state your platform is even allowed to enter. It's giving "this is the floor, we do not go below this" 👑
  • writes to MSR_PKG_CST_CONFIG_CONTROL (0xE2), bits 2:0 or 3:0 depending on your CPU model — yes, it literally changes based on the model, iykyk.
  • > ⚠️ writing is refused if the lock bit (bit 15) in that same MSR is set. locked means locked, bestie, no cap. 🔒
• --c1-demotion [on|off] — turns C1 demotion on or off. On Intel platforms this feature is literally monitoring your CPU wake-up rates like a nosy group chat 👀 and if that rate goes over a threshold, deep C-state requests get demoted to C1. Translation: better performance, but at the cost of higher power consumption. It's a trade, not a freebie. ⚡
  • writes to MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 26.
• --c1-undemotion [on|off] — turns C1 undemotion on or off. When it's on, the CPU can reverse those previously demoted C1 requests back to deeper C-states (think C6) if the frequent wake-ups have stopped. it's giving "the drama is over, we can rest again" 😭✨
  • writes to MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 28.
• --c1e-autopromote [on|off] — toggles C1E autopromotion. When enabled, all C1 C-state requests get converted to C1E. all of them. every single one. 🎀
  • writes to MSR_POWER_CTL (0x1FC), bit 1.
• --cstate-prewake [on|off] — toggles C-state prewake. When it's on, the CPU looks at idle timers and starts exiting deep C-states early, before the next local APIC timer event even happens. The whole point? Making sure the CPU is nearly awake by the time that timer fires. it's the "setting 3 alarms so you're actually up" of power management ⏰💅
  • writes to MSR_POWER_CTL (0x1FC), bit 30.
• --governor [GOVERNOR] — configures the idle governor, which is the little decision-maker that picks which C-state to request for an idle CPU. main character energy fr fr 👑
  • updates /sys/devices/system/cpu/cpuidle/current_governor.

---

and that's the whole page, bestie!! 🫶 no more options, we made it to the bottom, and the footer down there just says PEPC-CSTATES(1) — that's the page name, the source, and the version/date vibe all rolled into one iconic little line. screenshot it, cite it, live laugh cpuidle 💖✨🦋