geopm_pio_c(3) -- interfaces to query and modify platform

SYNOPSIS

Link with -lgeopm (MPI) or -lgeopmpolicy (non-MPI)

int geopm_pio_num_signal_name(void);

int geopm_pio_signal_name(int name_idx,
                          size_t result_max,
                          char *result);

int geopm_pio_num_control_name(void);

int geopm_pio_control_name(int name_index,
                           size_t result_max,
                           char *result);

int geopm_pio_signal_description(const char *signal_name,
                                 size_t description_max,
                                 char *description);

int geopm_pio_control_description(const char *control_name,
                                  size_t description_max,
                                  char *description);

int geopm_pio_signal_domain_type(const char *signal_name);

int geopm_pio_control_domain_type(const char *control_name);

int geopm_pio_read_signal(const char *signal_name,
                          int domain_type,
                          int domain_idx,
                          double *result);

int geopm_pio_write_control(const char *control_name,
                            int domain_type,
                            int domain_idx,
                            double setting);

int geopm_pio_save_control(void);

int geopm_pio_restore_control(void);

int geopm_pio_save_control_dir(const char *save_dir);

int geopm_pio_restore_control_dir(const char *save_dir);

int geopm_pio_push_signal(const char *signal_name,
                          int domain_type,
                          int domain_idx);

int geopm_pio_push_control(const char *control_name,
                           int domain_type,
                           int domain_idx);

int geopm_pio_sample(int signal_idx,
                     double *result);

int geopm_pio_adjust(int control_idx,
                     double setting);

int geopm_pio_read_batch(void);

int geopm_pio_write_batch(void);

int geopm_pio_signal_info(const char *signal_name,
                          int *aggregation_type,
                          int *format_type,
                          int *behavior_type);

int geopm_pio_start_batch_server(int client_pid,
                                 int num_signal,
                                 const struct geopm_request_s *signal_config,
                                 int num_control,
                                 const struct geopm_request_s *control_config,
                                 int *server_pid,
                                 int key_size,
                                 char *server_key);

int geopm_pio_stop_batch_server(int server_pid);

int geopm_pio_format_signal(double signal,
                            int format_type,
                            size_t result_max,
                            char *result);

DESCRIPTION

The interfaces described in this man page are the C language bindings for the geopm::PlatformIO(3) C++ class. Please refer to the geopm::PlatformIO(3) and geopm::PlatformTopo(3) man pages for a general overview of the GEOPM platform interface layer. The geopm_topo_c(3) man page describes the C wrappers for the geopm::PlatformTopo(3) C++ class and documents the geopm_domain_e enum. The caller selects from the geopm_domain_e enum for the domain_type parameter to many functions in the geopm_pio_*() interface. The return value from geopm_pio_signal_domain_type() and geopm_pio_control_domain_type() is also a value from the geopm_domain_e enum.

INSPECTION FUNCTIONS

geopm_pio_num_signal_name(): Returns the number of signal names that can be indexed with the name_idx parameter to the geopm_pio_signal_name() function. Any error in loading the platform will result in a negative error code describing the failure.
geopm_pio_signal_name(): Sets the result string to the name of the signal indexed by name_idx. At most result_max bytes are written to the result string. The value of name_idx must be greater than zero and less than the return value from geopm_pio_num_signal_name() or else an error will occur. Providing a string of NAME_MAX length (from limits.h) will be sufficient for storing any result. If result_max is too small to contain the signal name an error will occur. Zero is returned on success and a negative error code is returned if any error occurs.
geopm_pio_num_control_name(): Returns the number of control names that can be indexed with the name_idx parameter to the geopm_pio_control_name() function. Any error in loading the platform will result in a negative error code describing the failure.
geopm_pio_control_name(): Sets the result string to the name of the control indexed by name_idx. At most result_max bytes are written to the result string. The value of name_idx must be greater than zero and less than the return value from geopm_pio_num_control_name() or else an error will occur. Providing a string of NAME_MAX length (from limits.h) will be sufficient for storing any result. If result_max is too small to contain the control name an error will occur. Zero is returned on success and a negative error code is returned if any error occurs.
geopm_pio_signal_description(): Sets the description string to the signal description associated with signal_name. At most description_max bytes are written to the description string. Providing a string of NAME_MAX length (from limits.h) will be sufficient for storing any description. If description_max is too small to contain the description an error will occur. Zero is returned on success and a negative error code is returned if any error occurs.
geopm_pio_control_description(): Sets the description string to the control description associated with control_name. At most description_max bytes are written to the description string. Providing a string of NAME_MAX length (from limits.h) will be sufficient for storing any description. If description_max is too small to contain the description an error will occur. Zero is returned on success and a negative error code is returned if any error occurs.
geopm_pio_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 a negative error code if any error occurs, e.g. a request for a signal_name that is not supported by the platform.
geopm_pio_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 a negative error code if any error occurs, e.g. a request for a control_name that is not supported by the platform.
geopm_pio_signal_info(): C interface to get enums associated with a signal name. This interface supports DBus PlatformGetSignalInfo method. This C interface is implemented using several PlatformIO methods unlike the other wrappers in this header. The parameters: in signal_name, name of signal to query. out aggregation_type One of the Agg::m_type_e enum values describing the way the signal is aggregated. out format_type One of the geopm::string_format_e enums defined in Helper.hpp that defines how to format the signal as a string. out behavior_type One of the IOGroup::m_signal_behavior_e enum values that decribes the signals behavior over time. Returns zero on success, error value on failure.
geopm_pio_format_signal(): Format the signal according to the format type specified, and write the output into the result string. The parameters: in signal value to be formatted and written to the result string. in format_type One of the values in the string_format_e enum for specifying how to format the signal as a string. in result_max At most result_max bytes are written to the result string. If result_max is too small to contain the written output string an error will occur. out result Sets the result string to the value of the signal formatted as specified by the format_type. Providing a string of NAME_MAX length (from limits.h) will be sufficient for storing any result. Returns zero on success, error value on failure.

SERIAL FUNCTIONS

geopm_pio_read_signal(): Read from the platform and interpret into SI units a signal associated with signal_name and store the value in result. This value is read from the geopm_topo_e domain_type domain indexed by domain_idx. If the signal is native to a domain contained within domain_type, the values from the contained domains are aggregated to form result. Calling this function does not modify values stored by calling geopm_pio_read_batch(). If an error occurs then negative error code is returned. Zero is returned upon success.
geopm_pio_write_control(): Interpret the setting in SI units associated with control_name and write it to the platform. This value is written to the geopm_topo_e domain_type domain indexed by domain_idx. If the control is native to a domain contained within domain_type, then the setting is written to all contained domains. Calling this function does not modify values stored by calling geopm_pio_adjust(). If an error occurs then negative error code is returned. Zero is returned upon success.
geopm_pio_save_control(): Save the state of all controls so that any subsequent changes made through geopm_pio_write_control() or geopm_pio_write_batch() may be reverted with a call to geopm_pio_restore_control(). The control settings are stored in memory managed by GEOPM. If an error occurs then negative error code is returned. Zero is returned upon success.
geopm_pio_restore_control(): Restore the state recorded by the last call to geopm_pio_save_control() so that all subsequent changes made through geopm_pio_write_control() or geopm_pio_write_batch() are reverted to their previous settings. If an error occurs then negative error code is returned. Zero is returned upon success.
geopm_pio_save_control_dir(): Save the state of all controls in the directory save_dir so that any subsequent changes made through geopm_pio_write_control() or geopm_pio_write_batch() may be reverted with a call to geopm_pio_restore_control(). The control settings are stored in memory managed by GEOPM. If an error occurs then negative error code is returned. Zero is returned upon success.
geopm_pio_restore_control_dir(): Restore the state recorded by the last call to geopm_pio_save_control() in the directory save_dir so that all subsequent changes made through geopm_pio_write_control() or geopm_pio_write_batch() are reverted to their previous settings. If an error occurs then negative error code is returned. Zero is returned upon success.

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 FUNCTIONS

geopm_pio_push_signal(): Push a signal onto the stack of batch access signals. The signal is defined by selecting a signal_name from one of the values returned by the geopm_pio_signal_name() function, the domain_type from one of the geopm_domain_e values, and the domain_idx between zero to the value returned by geopm_topo_num_domain(domain_type). Subsequent calls to the geopm_pio_read_batch() function will read the signal and update the internal state used to store batch signals. The return value of geopm_pio_push_signal() is an index that can be passed as the sample_idx parameter to geopm_pio_sample() to access the signal value stored in the internal state from the last update. A distinct signal index will be returned for each unique combination of input parameters. All signals must be pushed onto the stack prior to the first call to geopm_pio_sample() or geopm_pio_read_batch(). Attempts to push a signal onto the stack after the first call to geopm_pio_sample() or geopm_pio_read_batch() or attempts to push a signal_name that is not a value provided by geopm_pio_signal_name() will result in a negative return value.
geopm_pio_push_control(): Push a control onto the stack of batch access controls. The control is defined by selecting a control_name from one of the values returned by the geopm_pio_control_name() function, the domain_type from one of the geopm_domain_e values, and the domain_idx between zero to the value returned by geopm_topo_num_domain(domain_type). The return value of geopm_pio_push_control() can be passed to the geopm_pio_adjust() function which will update the internal state used to store batch controls. Subsequent calls to the geopm_pio_write_batch() function access the control values in the internal state and write the values to the hardware. A distinct control index will be returned for each unique combination of input parameters. All controls must be pushed onto the stack prior to the first call to geopm_pio_adjust() or geopm_pio_write_batch(). Attempts to push a controls onto the stack after the first call to geopm_pio_adjust() or geopm_pio_write_batch() or attempts to push a control_name that is not a value provided by geopm_pio_control_name() will result in a negative return value.
geopm_pio_sample(): Samples cached value of a single signal that has been pushed via geopm_pio_push_signal() and writes the value into result. The signal_idx provided matches the return value from geopm_pio_push_signal() when the signal was pushed. The cached value is updated at the time of call to geopm_pio_read_batch().
geopm_pio_adjust(): Updates cached value for single control that has been pushed via geopm_pio_push_control() to the value setting. The control_idx provided matches the return value from geopm_pio_push_control() when the control was pushed. The cached value will be written to the platform at time of call to geopm_pio_write_batch().
geopm_pio_read_batch(): Read all push signals from the platform so that the next call to geopm_pio_sample() will reflect the updated data.
geopm_pio_write_batch(): Write all pushed controls so that values provided to geopm_pio_adjust() are written to the platform.
geopm_pio_start_batch_server(): Creates a batch server with the following signals and controls. The list of signals is represented by the array signal_config of num_signal elements. The list of controls is represented by the array control_config of num_control elements. It would be an error to create a batch server without any signals or 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. At most key_size bytes are written to the server_key string. Providing a string of NAME_MAX length (from limits.h) will be sufficient for storing any server_key. If key_size is too small to contain the server_key an error will occur. Zero is returned on success and a negative error code is returned 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 returns a negative error code. Call through to BatchServer::stop_batch().

RETURN VALUE

If an error occurs in any call to an interface documented here, the return value of the function will be a negative integer corresponding to one of the error codes documented in geopm_error(3).