geopm_pio_const_config(7) – Signals for ConstConfigIOGroup

Description

ConstConfigIOGroup implements the geopm::IOGroup(3) interface to provide a predefined set of signals with constant values. This is mainly useful to provide configuration information needed by some agents (e.g. system characterization information).

Signals

This IOGroup doesn’t provide any signals by default. In order to define signals, a configuration file in JSON format needs to be provided to the IOGroup via the GEOPM_CONST_CONFIG_PATH environment variable. If not provided, it will default to looking for a file named const_config_io.json in the GEOPM configuration path (/etc/geopm). In either case, the configuration file must comply with the following schema:

    {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "id": "https://geopm.github.io/const_config_io.schema.json",
        "title": "ConstConfigIOGroup config file specification",
        "definitions": {
            "signal_info": {
                "type": "object",
                "properties": {
                    "description": {
                        "type": "string"
                    },
                    "units": {
                        "enum": ["none", "seconds", "hertz", "watts", "joules", "celsius", "amperes", "volts"]
                    },
                    "domain": {
                        "enum": ["board", "package", "core", "cpu", "memory", "package_integrated_memory", "nic", "package_integrated_nic", "gpu", "package_integrated_gpu", "gpu_chip"]
                    },
                    "aggregation": {
                        "enum": ["sum", "average", "median", "logical_and", "logical_or", "region_hash", "region_hint", "min", "max", "stddev", "select_first", "expect_same"]
                    },
                    "values": {
                        "type": "array",
                        "items": {
                            "type": "number"
                        },
                        "minItems": 1
                    },
                    "common_value": {
                        "type": "number"
                    }
                },
                "required": ["description", "units", "domain", "aggregation"],
                "oneOf": [
                    {"required": ["values"]},
                    {"required": ["common_value"]}
                ],
                "additionalProperties": false
            }
        },
        "type": "object",
        "additionalProperties": {
            "$ref": "#/definitions/signal_info"
        }
    }

Notice how all signal fields are required. The values field is an array that should contain a value per domain item. The name of the signal will be derived from the object’s name and prefixing it with CONST_CONFIG::.

The following example helps illustrate the schema:

{
    "GPU_CORE_FREQUENCY_MAX": {
        "domain": "gpu",
        "description": "Defines the max core frequency to use for available GPUs",
        "units": "hertz",
        "aggregation": "average",
        "values": [1200, 1300, 1500]
    }
}

This basic example only defines one signal. Its name, once processed by the IOGroup, will be: CONST_CONFIG::GPU_CORE_FREQUENCY_MAX. Also, it can be inferred that for the system being characterized, there are three available GPUs, each with the specified max frequency.

Controls

Due to the nature of this IOGroup, it doesn’t provide any controls.

Aliases

To avoid a configuration from introducing signals that may collide with signals provided by other IOGroups, this IOGroup does not provide any high-level aliases.

Example

Following the example configuration provided earlier, geopmread could be used to read configuration values for the defined signal, for example:

geopmread CONST_CONFIG::GPU_CORE_FREQUENCY_MAX gpu 1

This example would return the signal value at domain index 1 (1300).

Using geopmread like this would be useful for manually checking the loaded configuration values from a configuration file, but the main use case for this will be to provide agents with configuration information.