Concepts

The vocabulary used throughout the GEOPM documentation and command line tools. Everything else in these guides builds on the five ideas below, so this page is the right place to start if you have not used GEOPM before.

Signal

A signal is something GEOPM can read: a measurement or a status value reported by the platform. Examples are CPU_POWER (Watts), CPU_ENERGY (Joules), CPU_FREQUENCY_STATUS (Hz), and TIME (seconds).

Signal names are the stable public interface to the platform. The same name means the same thing on every system GEOPM supports, even when the underlying mechanism differs between vendors or hardware generations.

List every signal your platform provides, with a description of each:

geopmread --info-all

Control

A control is something GEOPM can write: a hardware setting that changes how the platform behaves. Examples are CPU_POWER_LIMIT_CONTROL (a package power cap in Watts) and CPU_FREQUENCY_MAX_CONTROL (a maximum core frequency in Hz).

Every control is also readable, so you can always ask what a setting currently is before changing it. Controls are generally exposed as a signal of the same name, which is why geopmread CPU_POWER_LIMIT_CONTROL package 0 works. List the controls available to you:

geopmwrite --info-all

Not every signal has a matching control. Reading CPU_POWER tells you what the processor is consuming; it does not imply you can set the power consumption directly.

Domain

Hardware settings and measurements apply at different scopes. GEOPM calls these scopes domains, and arranges them in a hierarchy: board contains package, a package contains core, a core contains cpu, and so on. Other domain types include memory, gpu, and nic.

Every read and write names both a domain type and a domain index. The index selects which instance of that domain type you mean — package 0 is the first processor socket, package 1 the second.

# Power for the whole board
geopmread CPU_POWER board 0

# Frequency of the first socket only
geopmread CPU_FREQUENCY_STATUS package 0

Each signal and control has a native domain: the finest scope at which the hardware actually implements it. Requesting a coarser domain aggregates the underlying values, using an aggregation function appropriate to the signal (power sums, frequency averages). Requesting a finer domain than the native one is an error.

Two wildcards are accepted in the tools that take request lines, such as geopmsession(1). A * in the domain-type field means “use this signal’s native domain”, and a * in the domain-index field means “every index of that domain”.

# Energy for every package on the system
echo 'CPU_ENERGY package *' | geopmsession

For the full list of domain types and how they nest, see Domain Types. To inspect your own machine’s topology, run geopmread --domain.

Session

A session is the lifetime of your connection to the GEOPM Access Service. It opens when a GEOPM tool first contacts the service and closes when your process ends.

Sessions are what make GEOPM safe for unprivileged users. The first time a session writes a control, the service records the previous value. When the session closes — normally, or because the process was killed, or because the shell exited — the service restores every control that session changed.

This means a tuning experiment cannot permanently misconfigure the machine, and an interrupted run leaves nothing behind to clean up. It also means a setting you apply with geopmwrite(1) will not outlive the command unless you keep a session open, for example with geopmsession --control-config.

Privileged and unprivileged writes

The save/restore guarantee is a property of the Access Service, so it applies only to writes that pass through the service. Whether a given write does depends on the privilege of the writer:

An unprivileged user cannot reach the hardware directly. GEOPM routes every read and write through geopmd, opening a session on first contact, records each control the session writes, and restores it when the session ends. This is the safe, and usual, way to run an experiment.
A privileged writer (root, or any process holding CAP_SYS_ADMIN) is given the direct hardware interfaces instead, and the service-backed layer that would open a session is not loaded at all. Writes go straight to the MSR or sysfs attribute: they take effect immediately, outlive the command, and are not restored. A root geopmwrite leaves the setting in place until something changes it back.

Two consequences follow. First, the SERVICE:: name prefix, which selects the service-backed interface explicitly, is only available to an unprivileged process; under root those names do not resolve, because that layer was never loaded. Second, if you want a change reverted automatically, make it as an unprivileged user that has been granted the control rather than as root. Write as root only when you intend a change to persist, and then save and restore the prior value yourself.

Access list

By default an ordinary user may read and write nothing. An administrator uses geopmaccess(1) to grant access to specific signals and controls, either as a system-wide default or per user and per group.

The practical consequence: a command that fails with a permission error is usually missing an access-list entry rather than encountering a bug. Check what you have been granted with:

# Signals and controls available to you
geopmaccess
geopmaccess --controls

An administrator can see everything the platform is capable of, whether or not it has been granted, by adding --all.

Putting it together

A short worked example that uses all five ideas — read a signal at a domain, change a control, and let the session revert it:

# What is the current package power cap?
geopmread CPU_POWER_LIMIT_CONTROL package 0

# Trace board power once per second for ten seconds
printf 'TIME board 0\nCPU_POWER board 0\n' | geopmsession -p 1.0 -t 10.0

# Apply a 200 W cap to package 0 for the duration of a run,
# reverted automatically when the session ends
echo 'CPU_POWER_LIMIT_CONTROL package 0 200' > cap.conf
geopmsession -c cap.conf -- ./my_workload.sh