geopmwrite(1) – modify platform state

Synopsis

Print All Control Names

geopmwrite

Print Domain Name And Size

geopmwrite --domain

Print Control Description

geopmwrite --info CONTROL_NAME

Print All Control Descriptions

geopmwrite --info-all

Write Control

geopmwrite CONTROL_NAME DOMAIN_TYPE DOMAIN_INDEX VALUE

Create Cache

geopmwrite --cache

Get Help Or Version

geopmwrite --help
geopmwrite --version

Description

Provides a command line interface to PlatformIO and PlatformTopo. This tool can be used to write hardware/OS state through high-level control aliases and query other information about the platform such as the type and number of hardware domains. Details of the hardware domains can also be inferred from the output of lscpu(1).

When run without any arguments, the default behavior is to print a summary of available controls.

To write a specific control, geopmwrite should be run with four arguments. CONTROL_NAME is the name of the control of interest. DOMAIN_TYPE is hardware domain to which the control should be applied. DOMAIN_INDEX is used to indicate which instance of the domain to write to; indexing starts from 0 and goes up to the domain size - 1. VALUE is the floating-point number in SI units that the control will be adjusted to. If the DOMAIN_TYPE is a larger containing domain than that of the control, the same value will be applied to every contained subdomain. Refer to the domain hierarchy described in geopm::PlatformTopo(3) for the descriptions of the domains and how they are contained within one another.

board - domain for node-wide signals and controls
++ package - socket
++++ core - physical core
++++++ cpu - Linux logical CPU
++++ package_integrated_memory - on-package memory
++++ package_integrated_nic - NIC within the package
++++ package_integrated_gpu - domain for GPUs within the package
++ memory - other memory outside the package
++ nic - NIC attached to the board
++ gpu - domain for GPUs on the board

This utility can be used to create a geopm::PlatformTopo cache file in the tmpfs. When this file is not present the geopmread(1), geopmwrite(1), geopmctl(1) and geopmlaunch(1) will popen(3) a subprocess which provides the platform topology information. This subprocess will not be created if the cache file exists. See the --cache option below for more information.

Options

-d, --domain: Print a list of all domains on the system.
-i, --info: Print description of the provided CONTROL_NAME.
-I, --info-all: Print a list of all available controls with their descriptions, if any.
-c, --cache: Create a cache file for the geopm::PlatformTopo object if one does not exist or if the existing cache is from a previous boot cycle. If a privileged user requests this option (e.g. root or if invoked with sudo) the file path will be /run/geopm/geopm-topo-cache. If a non-privileged user requests this option the file path will be /tmp/geopm-topo-cache-<UID>. In either case, the permissions will be -rw-------, i.e. 600. If the file exists from the current boot cycle and has the proper permissions no operation will be performed. To force the creation of a new cache file, remove the existing cache file prior to executing this command.
-h, --help: Print brief summary of the command line usage information, then exit.
-v, --version: Print version of geopm(7) to standard output, then exit.

Examples

List domains and size:

$ geopmwrite --domain
board                1
package              2
core                 64
cpu                  128
memory         2
package_integrated_memory       1
nic            1
package_integrated_nic          0
gpu    0
package_integrated_gpu  0

List all available controls on the system with domain type and number:

$ geopmwrite
CPU_FREQUENCY_MAX_CONTROL
CPU_POWER_LIMIT_CONTROL

Show the description for a control:

$ geopmwrite --info CPU_FREQUENCY_MAX_CONTROL
CPU_FREQUENCY_MAX_CONTROL: Set processor frequency

Show domain type for CPU_POWER control:

$ geopmwrite --domain CPU_POWER
package

Set the frequency of CPU 2 to 1.9 GHz:

$ geopmwrite CPU_FREQUENCY_MAX_CONTROL cpu 2 1.9e9
$ geopmread CPU_FREQUENCY_MAX_CONTROL cpu 2
1.9e9

Set all CPUs on package 0 to 1.5 GHz (cpu 1 is on package 0):

$ geopmwrite CPU_FREQUENCY_MAX_CONTROL package 0 1.5e9
$ geopmread CPU_FREQUENCY_MAX_CONTROL cpu 1
1.5e9