geopm::PlatformIO(3) – GEOPM platform interface

Namespaces

The PlatformIO class, the IOGroup class, and the platform_io() singleton accessor function are members of the namespace geopm, but the full names, geopm::PlatformIO, geopm::IOGroup and geopm::platform_io(), have been abbreviated in this manual. Similarly, the std:: namespace specifier has been omitted from the interface definitions for the following standard types: std::shared_ptr, std::set, std::string, std::function, std::vector, to enable better rendering of this manual.

Note that the PlatformIO class is an abstract base class that the user interacts with. The concrete implementation, PlatformIOImp, is hidden by the singleton accessor.

Synopsis

#include <geopm/PlatformIO.hpp>

Link with -lgeopmd

PlatformIO &platform_io(void);

PlatformIO::PlatformIO() = default;

void PlatformIO::register_iogroup(shared_ptr<IOGroup> iogroup);

set<string> PlatformIO::signal_names(void) const;

set<string> PlatformIO::control_names(void) const;

int PlatformIO::signal_domain_type(const string &signal_name) const;

int PlatformIO::control_domain_type(const string &control_name) const;

int PlatformIO::push_signal(const string &signal_name,
                            int domain_type,
                            int domain_idx);

int PlatformIO::push_control(const string &control_name,
                             int domain_type,
                             int domain_idx);

double PlatformIO::sample(int signal_idx);

double PlatformIO::sample_combined(int signal_idx);

void PlatformIO::adjust(int control_idx,
                        double setting);

void PlatformIO::read_batch(void);

void PlatformIO::write_batch(void);

double PlatformIO::read_signal(const string &signal_name,
                               int domain_type,
                               int domain_idx);

void PlatformIO::write_control(const string &control_name,
                               int domain_type,
                               int domain_idx,
                               double setting);

void PlatformIO::save_control(void);

void PlatformIO::restore_control(void);

void PlatformIO::save_control(const string &save_dir);

void PlatformIO::restore_control(const string &save_dir);

function<double(const vector<double> &)>
PlatformIO::agg_function(const string &signal_name) const;

function<string(double)>
PlatformIO::format_function(const string &signal_name) const;

string PlatformIO::signal_description(const string &signal_name) const;

string PlatformIO::control_description(const string &control_name) const;

int PlatformIO::signal_behavior(const string &signal_name) const;

void PlatformIO::start_batch_server(int client_pid,
                                    const vector<geopm_request_s> &signal_config,
                                    const vector<geopm_request_s> &control_config,
                                    int &server_pid,
                                    string &server_key);

void PlatformIO::stop_batch_server(int server_pid);

static bool PlatformIO::is_valid_value(double value);

Description

The C++ bindings for the geopm_pio(7) interface.

Structure Type

This structure is part of the global C namespace. It contains information about a particular request, a signal or a control, and all the relevant information such as the name of the request, the domain type, and the domain index. This structure is used as a parameter to interface functions.

struct geopm_request_s {
    int domain_type;
    int domain_idx;
    char name[NAME_MAX];
};

Singleton Accessor

platform_io(): There is only one PlatformIO object, and the only way to access this object is through this function. The function returns a reference to the single PlatformIO object that gives access to all of the CLASS METHODS described below. See EXAMPLE section below.

Static Class Methods

is_valid_value(): In geopm, the values for signals and controls can be invalid due to errors or absent sampling data. This function determines if the current value of the signal or control is a valid value. It returns true if the value is valid, and false if the value is not valid.

Inspection Class Methods

signal_names(): Returns the names of all available signals that can be requested. This includes all signals and aliases provided through IOGroup extensions as well as signals provided by PlatformIO itself. The set of strings that are returned can be passed as a signal_name to all PlatformIO methods that accept a signal_name input parameter.
control_names(): Returns the names of all available controls. This includes all controls and aliases provided by IOGroups as well as controls provided by PlatformIO itself. The set of strings that are returned can be passed as a control_name to all PlatformIO methods that accept a control_name input parameter.
signal_description(): Returns the description of the signal as defined by the IOGroup that provides this signal.
control_description(): Returns the description of the control as defined by the IOGroup that provides this control.
signal_domain_type(): Query the domain for the signal with name signal_name. Returns one of the geopm_domain_e values signifying the granularity at which the signal is measured. Will return GEOPM_DOMAIN_INVALID if the signal name is not supported.
control_domain_type(): Query the domain for the control with the name control_name. Returns one of the geopm_domain_e values signifying the granularity at which the control can be adjusted. Will return GEOPM_DOMAIN_INVALID if the control name is not supported.
agg_function(): Returns the function that should be used to aggregate signal_name. If one was not previously specified by this class, the default function is select_first from geopm::Agg(3).
signal_behavior(): Returns one of the IOGroup::m_signal_behavior_e values which describes about how a signal will change as a function of time. This can be used when generating reports to decide how to summarize a signal’s value for the entire application run.
format_function(): Returns a function that can be used to convert a signal of the given signal_name into a printable string. The returned function takes the double value of the signal and returns a formatted string.

Serial Class Methods

read_signal(): Read from the platform and interpret into SI units a signal given its name and domain. Does not modify values stored by calling read_batch(). The parameters correspond to the struct geopm_request_s. The domain_type is from the enum geopm_domain_e described in geopm_topo.h
write_control(): Interpret the setting and write it to the platform. Does not modify the values stored by calling adjust(). The first three parameters correspond to the struct geopm_request_s. The domain_type is from the enum geopm_domain_e described in geopm_topo.h setting is new value in SI units of the setting for the control.
save_control(): Save the state of all controls so that any subsequent changes made through PlatformIO may be reverted with a call to restore_control(). This function also has an overload which takes a save_dir parameter the directory to save the state of the control. Each IOGroup that supports controls will populate one file in the save directory that contains the saved state and name the file after the IOGroup name.
restore_control(): Restore all controls to values recorded in previous call to save_control(). This function also has an overload which takes a save_dir parameter the directory which contains the result of the previous saved state.

When controls are saved, the data is stored in JSON format with the following schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "https://geopm.github.io/saved_controls.schema.json",
    "title": "Saved IOGroup controls",
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "domain_type": {
          "type": "integer"
        },
        "domain_idx": {
          "type": "integer"
        },
        "setting": {
          "type": "number"
        }
      },
      "required": ["name", "domain_type", "domain_idx", "setting"],
      "additionalProperties": false
    }
}

Batch Class Methods

push_signal(): Push a signal onto the stack of batch access signals. The signal is defined by selecting a signal_name from the set returned by the signal_names() method, the domain_type from one of the geopm_domain_e values, and the domain_idx between zero to the value returned by PlatformTopo::num_domain(domain_type). Subsequent calls to the read_batch() method will read the signal and update the internal state used to store batch signals. The return value of the method can be passed to the sample() method to access the signal stored in the internal state from the last update. The returned signal index will be repeated for each unique tuple of push_signal input parameters. All signals must be pushed onto the stack prior to the first call to sample() or read_batch(). Attempts to push a signal onto the stack after the first call to sample() or read_batch() or attempts to push a signal_name that is not from the set returned by signal_names() will result in a thrown geopm::Exception with error number GEOPM_ERROR_INVALID.
push_control(): Push a control onto the stack of batch access controls. The control is defined by selecting a control_name from the set returned by the control_names() method, the domain_type from one of the geopm_domain_e values, and the domain_idx between zero to the value returned by PlatformTopo::num_domain(domain_type). The return value of the method can be passed to the adjust() method which will update the internal state used to store batch controls. Subsequent calls to the write_batch() method access the control values in the internal state and write the values to the hardware. The returned control index will be repeated for each unique tuple of push_control() input parameters. All controls must be pushed onto the stack prior to the first call to adjust() or write_batch(). Attempts to push a controls onto the stack after the first call to adjust() or write_batch() or attempts to push a control_name that is not from the set returned by control_names() will result in a thrown geopm::Exception with error number GEOPM_ERROR_INVALID.
sample(): Samples cached value of a single signal that has been pushed via push_signal(), which is identified by the signal_idx The cached value is updated at the time of call to read_batch(), this function must be called after the update. The value of the signal is returned by the function.
adjust(): Updates cached value for single control, which is the setting, that has been pushed via push_control(), which is identified by the control_idx. The cached value will be written to the platform at time of call to write_batch().
read_batch(): Read all pushed signals from the platform so that the next call to sample() will reflect the updated data.
write_batch(): Write all pushed controls so that values provided to adjust() are written to the platform.
start_batch_server(): Creates a batch server with the following signals and controls. The list of signals is represented by the vector signal_config. The list of controls is represented by the vector control_config. Both vectors are containing geopm_request_s objects. It would be an error to create a batch server with no signals and no controls. In order to create a batch server, we also need to specify the PID of the client process as the client_pid. If the batch server is created successfully, it will populate the server_pid with the PID of the created server process, and the server_key with a key used to identify the server connection: a substring in interprocess shared memory keys used for communication. An exception is thrown if any error occurs.
geopm_pio_stop_batch_server(): This function is called directly by geopmd in order to end a batch session and kill the batch server process created by start_batch_server(), which is the server_pid parameter. If the PID of the server process is not found, then it is an error, and this function throws an exception. Call through to BatchServer::stop_batch().

Plugin Class Methods

register_iogroup(): Registers an IOGroup with the PlatformIO so that the signals and controls provided by the object are available through the PlatformIO interface. The iogroup is a shared pointer to a class derived from the geopm::IOGroup(3). This method provides the mechanism for extending the PlatformIO interface at runtime.

Example

/* Print a signal for all CPUs on the system. */

#include <iostream>
#include <string>
#include <geopm/PlatformIO.hpp>
#include <geopm/PlatformTopo.hpp>

int main(int argc, char **argv)
{
    if (argc != 2) {
        std::cerr << "Usage: " << argv[0] << " SIGNAL_NAME" << std::endl;
        return -1;
    }
    std::string signal_name = argv[1];
    geopm::PlatformIO &pio = geopm::platform_io();
    geopm::PlatformTopo &topo = geopm::platform_topo();
    const int DOMAIN = pio.signal_domain_type(signal_name);
    const int NUM_DOMAIN = topo.num_domain(DOMAIN);
    std::cout << "cpu_idx    " << signal_name << std::endl;
    for (int domain_idx = 0; domain_idx != NUM_DOMAIN; ++domain_idx) {
        double signal = pio.read_signal(signal_name, DOMAIN, domain_idx);
        for (const auto &cpu_idx : topo.domain_cpus(DOMAIN, domain_idx)) {
            std::cout << cpu_idx << "    " << signal << std::endl;
        }
    }
    return 0;
}

Errors

All functions described on this man page throw geopm::Exception(3) on error.