pepc-cstates - Man Page

Command 'cstates'

General options

-h

Show a short help message and exit.

-q

Be quiet.

-d

Print debugging information.

--version

Print version and exit.

-H HOSTNAME, --host HOSTNAME

Name of the host to run the command on.

-U USERNAME, --username USERNAME

Name of the user to use for logging into the remote host over SSH. The default user name is 'root'.

-K PRIVKEY, --priv-key PRIVKEY

Path to the private SSH key that should be used for logging into the remote host. By default the key is automatically found from standard paths like '$HOME/.ssh'.

-T TIMEOUT, --timeout TIMEOUT

SSH connection timeout in seconds, default is 8.

-D DATASET, --dataset DATASET

This option is for debugging and testing purposes only, it defines the dataset that will be used to emulate a host for running the command on. This option is typically used when running 'pepc' from the source code directory, which includes datasets for many different systems.

The argument can be the dataset path, 'all' to specify all available dataset or name in which case the following locations will be searched for.

  1. './tests/data', in the directory of the running program
  2. '$PEPC_DATA_PATH/tests/data'
  3. '$HOME/.local/share/pepc/tests/data'
  4. '/usr/local/share/pepc/tests/data'
  5. '/usr/share/pepc/tests/data'
--force-color

Force coloring of the text output.

Target CPU specification options

All sub-commans ('info', 'config', 'save') support the following target CPU specification options.

--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 1. Use the special keyword 'all' to specify all cores. This option has to be accompanied by the '--package' option, because core numbers are per-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, 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. In the latter case, this option has to be accompanied by the '--package' option.

--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, and idex '3' would mean CPU 5. 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.

Subcommand 'info'

Get information about C-states on specified CPUs. By default, prints all information for all CPUs.

Use target CPU specification options to specify the subset of CPUs, cores, dies, or packages.

--yaml

Print information in YAML format.

--override-cpu-model MODEL

This option is for debugging and testing purposes only. Provide the CPU model number which the tool treats the target system CPU as. For example, use 0x8F to treat the target system as Sapphire Rapids Xeon.

-m MECHANISMS, --mechanisms MECHANISMS

Comma-separated list of mechanisms that are allowed to be used for configuring C-states. Use '--list-mechanisms' to get the list of available mechanisms. Note, many options support only one mechanism (e.g., 'sysfs'), some may support multiple (e.g., 'sysfs' and 'msr'). The mechanisms are tried in the specified order. By default, all mechanisms are allowed and the most preferred mechanisms will be tried first.

--list-mechanisms

List mechanisms available for reading C-states information.

--cstates [CSTATES]

Comma-separated list of C-states to get information about. C-states should be specified by name (e.g., 'C1'). Use 'all' to specify all the available Linux C-states (this is the default). Note, there is a difference between Linux C-states (e.g., 'C6') and hardware C-states (e.g., Core C6 or Package C6 on many Intel platforms). The former is what Linux can request, and on Intel hardware this is usually about various 'mwait' instruction hints. The latter are platform-specific hardware state, entered upon a Linux request.

--pkg-cstate-limit

Get package C-state limit (details in 'pkg_cstate_limit'), available package C-state limits (details in 'pkg_cstate_limits'), package C-state limit lock (details in 'pkg_cstate_limit_lock'), and package C-state limit aliases (details in 'pkg_cstate_limit_aliases').

--c1-demotion

Check if C1 demotion is enabled or disabled (details in 'c1_demotion').

--c1-undemotion

Check if C1 undemotion is enabled or disabled (details in 'c1_undemotion').

--c1e-autopromote

Check if C1E autopromote is enabled or disabled (details in 'c1e_autopromote').

--cstate-prewake

Check if C-state prewake is enabled or disabled (details in 'cstate_prewake').

--idle-driver

Get idle driver (details in 'idle_driver').

--governor

Get idle governor (details in 'governor').

--governors

Get list of available idle governors (details in 'governors').

Subcommand 'config'

Configure C-states on specified CPUs. All options can be used without a parameter, in which case the currently configured value(s) will be printed.

Use target CPU specification options to specify the subset of CPUs, cores, dies, or packages.

--override-cpu-model MODEL

This option is for debugging and testing purposes only. Provide the CPU model number which the tool treats the target system CPU as. For example, use 0x8F to treat the target system as Sapphire Rapids Xeon.

--list-mechanisms

List mechanisms available for configuring C-states.

--enable CSTATES

Comma-separated list of C-states to enable. C-states should be specified by name (e.g., 'C1'). Use 'all' to specify all the available Linux C-states (this is the default). Note, there is a difference between Linux C-states (e.g., 'C6') and hardware C-states (e.g., Core C6 or Package C6 on many Intel platforms). The former is what Linux can request, and on Intel hardware this is usually about various 'mwait' instruction hints. The latter are platform-specific hardware state, entered upon a Linux request.

--disable CSTATES

Similar to '--enable', but specifies the list of C-states to disable.

--pkg-cstate-limit PKG_CSTATE_LIMIT

Set package C-state limit (details in 'pkg_cstate_limit').

--c1-demotion on|off

Enable or disable C1 demotion (details in 'c1_demotion').

--c1-undemotion on|off

Enable or disable C1 undemotion (details in 'c1_undemotion').

--c1e-autopromote on|off

Enable or disable C1E autopromote (details in 'c1e_autopromote').

--cstate-prewake on|off

Enable or disable C-state prewake (details in 'cstate_prewake').

--governor NAME

Set idle governor (details in 'governor').

Subcommand 'save'

Save all the modifiable C-state settings into a file. This file can later be used for restoring C-state settings with the 'pepc cstates restore' command.

Use target CPU specification options to specify the subset of CPUs, cores, dies, or packages.

-o OUTFILE, --outfile OUTFILE

Name of the file to save the settings to.

Subcommand 'restore'

Restore C-state settings from a file previously created with the 'pepc cstates save' command.

-f INFILE, --from INFILE

Name of the file from which to restore the settings from, use "-" to read from the standard output.

  *   *   *   *   *

Properties

pkg_cstate_limit

pkg_cstate_limit - Package C-state limit

Synopsis

pepc cstates info --pkg-cstate-limit

pepc cstates config --pkg-cstate-limit=<on|off>

Description

The deepest package C-state the platform is allowed to enter. MSR_PKG_CST_CONFIG_CONTROL (0xE2) register can be locked, in which case the package C-state limit can only be read, but cannot be modified (please, refer to 'pkg_cstate_limit_lock' for more information).

Mechanism

msr MSR_PKG_CST_CONFIG_CONTROL (0xE2), bits 2:0 or 3:0, depending on CPU model.

Scope

This option has core scope. Exceptions: module scope on Silvermonts and Airmonts, package scope on Xeon Phi processors.

  *   *   *   *   *

pkg_cstate_limits

pkg_cstate_limits - Available package C-state limits

Synopsis

pepc cstates info --pkg-cstate-limits

Description

All available package C-state limits.

Mechanism

doc Intel SDM (Software Developer Manual) and Intel EDS (External Design Specification).

Scope

This option has global scope.

  *   *   *   *   *

pkg_cstate_limit_lock

pkg_cstate_limit_lock - Package C-state limit lock

Synopsis

pepc cstates info --pkg-cstate-limit-lock

Description

Whether the package C-state limit can be modified. When 'True', 'pkg_cstate_limit' is read-only.

Mechanism

msr MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 15.

Scope

This option has package scope.

  *   *   *   *   *

pkg_cstate_limit_aliases

pkg_cstate_limit_aliases - Package C-state limit aliases

Synopsis

pepc cstates info --pkg-cstate-limit-aliases

Description

Package C-state limit aliases. For example on Ice Lake Xeon, 'PC6' is an alias for 'PC6R'.

Mechanism

doc Intel SDM (Software Developer Manual) or Intel EDS (External Design Specification).

Scope

This option has global scope.

  *   *   *   *   *

c1_demotion

c1_demotion - C1 demotion

Synopsis

pepc cstates info --c1-demotion

pepc cstates config --c1-demotion=<on|off>

Description

Allow or disallow the CPU to demote 'C6' or 'C7' C-state requests to 'C1'.

Mechanism

MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 26.

Scope

This option has core scope. Exceptions: module scope on Silvermonts and Airmonts, package scope on Xeon Phis.

  *   *   *   *   *

c1_undemotion

c1_demotion - C1 undemotion

Synopsis

pepc cstates info --c1-undemotion

pepc cstates config --c1-undemotion=<on|off>

Description

Allow or disallow the CPU to un-demote previously demoted requests back from 'C1' C-state to 'C6' or 'C7l.

Mechanism

msr MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 28.

Scope

This option has core scope. Exceptions: module scope on Silvermonts and Airmonts, package scope on Xeon Phis.

  *   *   *   *   *

c1e_autopromote

c1e_autopromote - C1E autopromote

Synopsis

pepc cstates info --c1e-autopromote

pepc cstates config --c1e-autopromote=<on|off>

Description

When enabled, the CPU automatically converts all 'C1' C-state requests to 'C1E' requests.

Mechanism

msr MSR_POWER_CTL (0x1FC), bit 1.

Scope

This option has package scope.

  *   *   *   *   *

cstate_prewake

cstate_prewake - C-state prewake

Synopsis

pepc cstates info --cstate-prewake

pepc cstates config --cstate-prewake=<on|off>

Description

When enabled, the CPU will start exiting the 'C6' C-state in advance, prior to the next local APIC timer event.

Mechanism

msr MSR_POWER_CTL (0x1FC), bit 30.

Scope

This option has package scope.

  *   *   *   *   *

idle_driver

idle_driver - Idle driver

Synopsis

pepc cstates info --idle-driver

Description

Idle driver is responsible for enumerating and requesting the C-states available on the platform.

Mechanism

sysfs* "/sys/devices/system/cpu/cpuidle/current_governor"

Scope

This option has global scope.

  *   *   *   *   *

governor

governor - Idle governor

Synopsis

pepc cstates info --governor

pepc cstates config --governor=<name>

Description

Idle governor decides which C-state to request on an idle CPU.

Mechanism

sysfs "/sys/devices/system/cpu/cpuidle/scaling_governor"

Scope

This option has global scope.

  *   *   *   *   *

governors

governors - Available idle governors

Synopsis

pepc cstates info --governors

Description

Idle governors decide which C-state to request on an idle CPU. Different governors implement different selection policy.

Mechanism

sysfs "/sys/devices/system/cpu/cpuidle/available_governors"

Scope

This property has global scope.

Info

09-03-2023