1CSTATES() CSTATES()
2
6 General options
7 -h Show a short help message and exit.
8 -q Be quiet.
10 -d Print debugging information.
12 --version
14 Print version and exit.
15 -H HOSTNAME, --host HOSTNAME
17 Name of the host to run the command on.
18 -U USERNAME, --username USERNAME
20 Name of the user to use for logging into the remote host over
21 SSH. The default user name is 'root'.
22 -K PRIVKEY, --priv-key PRIVKEY
24 Path to the private SSH key that should be used for logging into
25 the remote host. By default the key is automatically found from
26 standard paths like '$HOME/.ssh'.
27 -T TIMEOUT, --timeout TIMEOUT
29 SSH connection timeout in seconds, default is 8.
30 -D DATASET, --dataset DATASET
32 This option is for debugging and testing purposes only, it de‐
33 fines the dataset that will be used to emulate a host for run‐
34 ning the command on. This option is typically used when running
35 'pepc' from the source directory, which includes datasets for
36 many different systems.
37 The argument can be the dataset path, 'all' to specify all
39 available dataset or name in which case the following locations
40 will be searched for.
41 1. './tests/data', in the directory of the running program
43 2. '$PEPC_DATA_PATH/tests/data'
45 3. '$HOME/.local/share/pepc/tests/data'
47 4. '/usr/local/share/pepc/tests/data'
49 5. '/usr/share/pepc/tests/data'
51 --force-color
53 Force coloring of the text output.
54 Subcommand 'info'
56 Get information about C-states on specified CPUs. By default, prints
57 all information for all CPUs.
58 --cpus CPUS
60 List of CPUs to get information about. The list can include in‐
61 dividual CPU numbers and CPU number ranges. For exam‐
62 ple,'1-4,7,8,10-12' would mean CPUs 1 to 4, CPUs 7, 8, and 10 to
63 12. Use the special keyword 'all' to specify all CPUs.
64 --cores CORES
66 List of cores to get information about. The list can include
67 individual core numbers and core number ranges. For example,
68 '1-4,7,8,10-12' would mean cores 1 to 4, cores 7, 8, and 10 to
69 12. Use the special keyword 'all' to specify all cores. This
70 option has to be accompanied by '--package' option, because core
71 numbers are per-package
72 --packages PACKAGES
74 List of packages to get information about. The list can include
75 individual package numbers and package number ranges. For exam‐
76 ple, '0,2-4' would mean package 0 and packages 2 to 4. Use the
77 special keyword 'all' to specify all packages.
78 --core-siblings CORE_SIBLINGS
80 List of core sibling indices to get information about. The list
81 can include individual core sibling indices or index ranges.
82 For example, core x includes CPUs 3 and 4, '0' would mean CPU 3
83 and '1' would mean CPU 4. This option can only be used to ref‐
84 erence online CPUs, because Linux does not provide topology in‐
85 formation for offline CPUs. In the previous example if CPU 3
86 was offline, then '0' would mean CPU 4.
87 --yaml Print information in YAML format.
89 --override-cpu-model
91 This option is for debugging and testing purposes only. Provide
92 the CPU model number which the tool treats the target system CPU
93 as. For example, use 0x8F to treat the target system as Sap‐
94 phire Rapids Xeon.
95 --cstates [CSTATES]
97 Comma-separated list of C-states to get information about. C-
98 states should be specified by name (e.g., 'C1'). Use 'all' to
99 specify all the available Linux C-states (this is the default).
100 Note, there is a difference between Linux C-states (e.g., 'C6')
101 and hardware C-states (e.g., Core C6 or Package C6 on many Intel
102 platforms). The former is what Linux can request, and on Intel
103 hardware this is usually about various 'mwait' instruction
104 hints. The latter are platform-specific hardware state, entered
105 upon a Linux request.
106 --pkg-cstate-limit
108 Get package C-state limit (details in 'pkg_cstate_limit'),
109 available package C-state limits (details in 'pkg_cstate_lim‐
110 its'), package C-state limit lock (details in 'pkg_cstate_lim‐
111 it_lock'), and package C-state limit aliases (details in
112 'pkg_cstate_limit_aliases').
113 --c1-demotion
115 Get current setting for C1 demotion (details in 'c1_demotion').
116 --c1-undemotion
118 Get current setting for C1 undemotion (details in 'c1_undemo‐
119 tion').
120 --c1e-autopromote
122 Get current setting for C1E autopromote (details in 'c1e_auto‐
123 promote').
124 --cstate-prewake
126 Get current setting for C-state prewake (details in 'cstate_pre‐
127 wake').
128 --idle-driver
130 Get idle driver (details in 'idle_driver').
131 --governor
133 Get idle governor (details in 'governor').
134 --governors
136 Get list of available idle governors (details in 'governors').
137 Subcommand 'config'
139 Configure C-states on specified CPUs. All options can be used without
140 a parameter, in which case the currently configured value(s) will be
141 printed.
142 --cpus CPUS
144 List of CPUs to configure C-States on. The list can include in‐
145 dividual CPU numbers and CPU number ranges. For exam‐
146 ple,'1-4,7,8,10-12' would mean CPUs 1 to 4, CPUs 7, 8, and 10 to
147 12. Use the special keyword 'all' to specify all CPUs.
148 --cores CORES
150 List of cores to configure C-States on. The list can include
151 individual core numbers and core number ranges. For example,
152 '1-4,7,8,10-12' would mean cores 1 to 4, cores 7, 8, and 10 to
153 1. Use the special keyword 'all' to specify all cores. This
154 option has to be accompanied by '--package' option, because core
155 numbers are per-package
156 --packages PACKAGES
158 List of packages to configure C-States on. The list can include
159 individual package numbers and package number ranges. For exam‐
160 ple, '0,2-4' would mean package 0 and packages 2 to 4. Use the
161 special keyword 'all' to specify all packages.
162 --core-siblings CORE_SIBLINGS
164 List of core sibling indices to configure C-States on. The list
165 can include individual core sibling indices or index ranges.
166 For example, core x includes CPUs 3 and 4, '0' would mean CPU 3
167 and '1' would mean CPU 4. This option can only be used to ref‐
168 erence online CPUs, because Linux does not provide topology in‐
169 formation for offline CPUs. In the previous example if CPU 3
170 was offline, then '0' would mean CPU 4.
171 --override-cpu-model
173 This option is for debugging and testing purposes only. Provide
174 the CPU model number which the tool treats the target system CPU
175 as. For example, use 0x8F to treat the target system as Sap‐
176 phire Rapids Xeon.
177 --enable [CSTATES]
179 Comma-separated list of C-states to enable. C-states should be
180 specified by name (e.g., 'C1'). Use 'all' to specify all the
181 available Linux C-states (this is the default). Note, there is
182 a difference between Linux C-states (e.g., 'C6') and hardware C-
183 states (e.g., Core C6 or Package C6 on many Intel platforms).
184 The former is what Linux can request, and on Intel hardware this
185 is usually about various 'mwait' instruction hints. The latter
186 are platform-specific hardware state, entered upon a Linux re‐
187 quest.
188 --disable [CSTATES]
190 Similar to '--enable', but specifies the list of C-states to
191 disable.
192 --pkg-cstate-limit [PKG_CSTATE_LIMIT]
194 Set package C-state limit (details in 'pkg_cstate_limit').
195 --c1-demotion [C1_DEMOTION]
197 Enable or disable C1 demotion (details in 'c1_demotion').
198 --c1-undemotion [C1_UNDEMOTION]
200 Enable or disable C1 undemotion (details in 'c1_undemotion').
201 --c1e-autopromote [C1E_AUTOPROMOTE]
203 Enable or disable C1E autopromote (details in 'c1e_autopro‐
204 mote').
205 --cstate-prewake [CSTATE_PREWAKE]
207 Enable or disable C-state prewake (details in 'cstate_prewake').
208 --governor [GOVERNOR]
210 Set idle governor (details in 'governor').
211 Subcommand 'save'
213 Save all the modifiable C-state settings into a file. This file can
214 later be used for restoring C-state settings with the 'pepc cstates re‐
215 store' command.
216 --cpus CPUS
218 List of CPUs to save C-state information about. The list can
219 include individual CPU numbers and CPU number ranges. For exam‐
220 ple,'1-4,7,8,10-12' would mean CPUs 1 to 4, CPUs 7, 8, and 10 to
221 12. Use the special keyword 'all' to specify all CPUs.
222 --cores CORES
224 List of cores to save C-state information about. The list can
225 include individual core numbers and core number ranges. For ex‐
226 ample, '1-4,7,8,10-12' would mean cores 1 to 4, cores 7, 8, and
227 10 to 12. Use the special keyword 'all' to specify all cores.
228 This option has to be accompanied by '--package' option, because
229 core numbers are per-package
230 --packages PACKAGES
232 List of packages to save C-state information about. The list
233 can include individual package numbers and package number
234 ranges. For example, '0,2-4' would mean package 0 and packages
235 2 to 4. Use the special keyword 'all' to specify all packages.
236 --core-siblings CORE_SIBLINGS
238 List of core sibling indices to save C-state information about.
239 The list can include individual core sibling indices or index
240 ranges. For example, core x includes CPUs 3 and 4, '0' would
241 mean CPU 3 and '1' would mean CPU 4. This option can only be
242 used to reference online CPUs, because Linux does not provide
243 topology information for offline CPUs. In the previous example
244 if CPU 3 was offline, then '0' would mean CPU 4.
245 -o OUTFILE, --outfile OUTFILE
247 Name of the file to save the settings to.
248 Subcommand 'restore'
250 Restore C-state settings from a file previously created with the 'pepc
251 cstates save' command.
252 -f INFILE, --from INFILE
254 Name of the file from which to restore the settings from, use
255 "-" to read from the standard output.
256 * * * * *
258
260 pkg_cstate_limit
261 pkg_cstate_limit - Package C-state limit
262 Synopsis
264 pepc cstates info [--pkg-cstate-limit]
265 pepc cstates config [--pkg-cstate-limit=<value>]
266 Description
268 The deepest package C-state the platform is allowed to enter.
269 MSR_PKG_CST_CONFIG_CONTROL (0xE2) register can be locked, in which case
270 the package C-state limit can only be read, but cannot be modified,
271 please refer to property pkg_cstate_limit_lock.
272 Source
274 MSR_PKG_CST_CONFIG_CONTROL (0xE2)
275 Package C-state limits are documented in Intel SDM, but it describes
277 all the possible package C-states for a CPU model. In practice, howev‐
278 er, specific platforms often do not support many of package C-states.
279 For example, Xeons typically do not support anything deeper than PC6.
280 Refer to 'PCStateConfigCtl.py' for all platforms and bits.
282 Scope
284 This option has core scope. With the following exceptions: Silvermonts
285 and Airmonts have module scope, Xeon Phis have package scope.
286 * * * * *
288 pkg_cstate_limits
290 pkg_cstate_limits - Available package C-state limits
291 Synopsis
293 pepc cstates info [--pkg-cstate-limits]
294 Description
296 All available package C-state limits.
297 Source
299 Hardcoded in 'PCStateConfigCtl.py' for platforms that we have verified.
300 Scope
302 This option has global scope.
303 * * * * *
305 pkg_cstate_limit_lock
307 pkg_cstate_limit_lock - Package C-state limit lock
308 Synopsis
310 pepc cstates info [--pkg-cstate-limit-lock]
311 Description
313 Whether the package C-state limit can be modified. When 'True', prop‐
314 erty 'pkg_cstate_limit' is read-only.
315 Source
317 MSR_PKG_CST_CONFIG_CONTROL (0xE2) Refer to 'PCStateConfigCtl.py' for
318 all platforms and bits.
319 Scope
321 This option has package scope.
322 * * * * *
324 pkg_cstate_limit_aliases
326 pkg_cstate_limit_aliases - Package C-state limit aliases
327 Synopsis
329 pepc cstates info [--pkg-cstate-limit-aliases]
330 Description
332 Package C-state limit aliases, for example on Ice Lakes 'PC6' is an
333 alias for 'PC6R'.
334 Source
336 Hardcoded in 'PCStateConfigCtl.py' for platforms that we have verified.
337 Scope
339 This option has global scope.
340 * * * * *
342 c1_demotion
344 c1_demotion - C1 demotion
345 Synopsis
347 pepc cstates info [--c1-demotion]
348 pepc cstates config [--c1-demotion=<value>]
349 Description
351 Allow or disallow the CPU to demote C6 or C7 requests to C1.
352 Source
354 MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 26.
355 Scope
357 This option has core scope. With the following exceptions, Silvermonts
358 and Airmonts have module scope, Xeon Phis have package scope.
359 * * * * *
361 c1_undemotion
363 c1_demotion - C1 undemotion
364 Synopsis
366 pepc cstates info [--c1-undemotion]
367 pepc cstates config [--c1-undemotion=<value>]
368 Description
370 Allow or disallow the CPU to un-demote previously demoted requests back
371 from C1 to C6 or C7.
372 Source
374 MSR_PKG_CST_CONFIG_CONTROL (0xE2), bit 28.
375 Scope
377 This option has core scope. With the following exceptions, Silvermonts
378 and Airmonts have module scope, Xeon Phis have package scope.
379 * * * * *
381 c1e_autopromote
383 c1e_autopromote - C1E autopromote
384 Synopsis
386 pepc cstates info [--c1e-autopromote]
387 pepc cstates config [--c1e-autopromote=<value>]
388 Description
390 When enabled, the CPU automatically converts all C1 requests to C1E re‐
391 quests.
392 Source
394 MSR_POWER_CTL (0x1FC), bit 1.
395 Scope
397 This option has package scope.
398 * * * * *
400 cstate_prewake
402 cstate_prewake - C-state prewake
403 Synopsis
405 pepc cstates info [--cstate-prewake]
406 pepc cstates config [--cstate-prewake=<value>]
407 Description
409 When enabled, the CPU will start exiting the C6 idle state in advance,
410 prior to the next local APIC timer event.
411 Source
413 MSR_POWER_CTL (0x1FC), bit 30.
414 Scope
416 This option has package scope.
417 * * * * *
419 idle_driver
421 idle_driver - Idle driver
422 Synopsis
424 pepc cstates info [--idle-driver]
425 Description
427 Idle driver is responsible for enumerating and requesting the C-states
428 available on the platform.
429 Source
431 "/sys/devices/system/cpu/cpuidle/current_governor"
432 Scope
434 This option has global scope.
435 * * * * *
437 governor
439 governor - Idle governor
440 Synopsis
442 pepc cstates info [--governor]
443 pepc cstates config [--governor=<value>]
444 Description
446 Idle governor decides which C-state to request on an idle CPU.
447 Source
449 "/sys/devices/system/cpu/cpuidle/scaling_governor"
450 Scope
452 This option has global scope.
453 * * * * *
455 governors
457 governors - Available idle governors
458 Synopsis
460 pepc cstates info [--governors]
461 Description
463 Idle governors decide which C-state to request on an idle CPU. Differ‐
464 ent governors implement different selection policy.
465 Source
467 "/sys/devices/system/cpu/cpuidle/available_governors"
468 Scope
470 This property has global scope.
471 09-03-2023 CSTATES()