geopmread(1) – query platform information

Synopsis

Read Signal

geopmread SIGNAL_NAME DOMAIN_TYPE DOMAIN_INDEX

Create Cache

geopmread --cache

Get Help Or Version

geopmread --help
geopmread --version

Description

Provides a command line interface to PlatformIO and PlatformTopo. This tool can be used to read hardware/OS state through high-level signal 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 signals. Signal names ending in # represent the raw bits of MSRs without any interpretation and will be printed in hex. This feature is mainly useful for debugging; for profiling, the signal aliases should be preferred.

To read a specific signal, geopmread should be run with the three arguments. SIGNAL_NAME is the name of the signal of interest. DOMAIN_TYPE is the hardware domain for which this signal should be read. The domain type should be a lowercase string from the list shown by --domain. DOMAIN_INDEX is used to indicate which instance of the domain to read; indexing starts from 0 and goes up to the domain size - 1. Values read for signals are in SI units. Note that the domain can be the native domain of the signal (as shown in the summary) or any larger containing domain, in which case the signal value will be aggregated into a single value for the larger domain. Refer to the domain hierarchy described in geopm::PlatformTopo(3) for the descriptions of the domains and how they are contained within one another.

The aggregation functions used for each signal are described in geopm(7) under the description for GEOPM_TRACE_SIGNALS. The same functions are used to aggregate signals in the trace into the board domain. Note that not all signals have aggregation functions, and if a signal is not readable at board domain, it cannot be printed in the trace.

This utility can be used to create a geopm::PlatformTopo cache file in the tmpfs. When this file is not present 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 SIGNAL_NAME.

-I, --info-all

Print a list of all available signals 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. Additionally when this command is executed any existing GEOPM HPC Runtime shared memory keys owned by the user running the command will be deleted.

-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:

$ geopmread --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 signals on the system:

$ geopmread
TIME
CPU_ENERGY
DRAM_ENERGY
CPU_POWER
DRAM_POWER
CPU_FREQUENCY_STATUS

Show the description for a signal:

$ geopmread --info TIME
TIME: Time in seconds since the IOGroup load.

Show domain type for DRAM_ENERGY signal:

$ geopmread --domain DRAM_ENERGY
memory

Read the current energy for package 1:

$ geopmread CPU_ENERGY package 1
34567

Read the total energy for both packages:

$ geopmread CPU_ENERGY board 0
56789

See Also

geopm(7), geopmwrite(1), lscpu(1)