geopm_pio_sysfs(7) – Signals and controls for sysfs attributes

Description

The SysfsIOGroup implements the geopm::IOGroup(3) interface to provide hardware signals and controls for sysfs attribute files.

The set of signals and controls supported by an instance of SysfsIOGroup is configurable through a JSON file used by the IOGroup. The JSON file informs the IOGroup about which sysfs attributes to expose through GEOPM, and how to interpret those attributes.

The JSON files must follow this schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "https://geopm.github.io/sysfs_attributes.schema.json",
    "title": "SysfsIOGroup attributes specification",
    "type": "object",
    "properties": {
      "attributes": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/definitions/sysfsAttributeDescription"
        }
      }
    },
    "definitions" : {
      "sysfsAttributeDescription": {
        "type": "object",
        "required": ["attribute", "scalar", "description", "aggregation", "behavior", "format", "units", "writeable", "alias"],
        "properties": {
          "attribute": { "description": "Name of the sysfs attribute", "type": "string" },
          "scalar": { "description": "Scaling factor to multiply after reads and divide before writes to sysfs", "type": "number" },
          "description": { "description": "Description of what the attribute represents", "type": "string" },
          "doc_domain": { "description": "Which GEOPM domain to note as the expected domain for this attribute in the documentation. The actual domain may differ based on platform interrogation at execution time.",
                          "enum": ["board", "package", "core", "cpu", "memory", "package_integrated_memory", "nic", "package_integrated_nic", "gpu", "package_integrated_gpu", "gpu_chip"] },
          "aggregation": { "description": "How to aggregate sampled values across domains",
                           "enum": ["sum", "average", "median", "logical_and", "logical_or", "region_hash", "region_hint", "min", "max", "stddev", "select_first", "expect_same"] },
          "behavior": { "description": "How to interpret differences between read values",
                        "enum": ["constant", "monotone", "variable", "label"] },
          "format": { "description": "How to present read values",
                      "enum": ["double", "integer", "hex", "raw64"] },
          "units": { "description": "Which units are represented by the attribute's read values",
                      "enum": ["none", "seconds", "hertz", "watts", "joules", "celsius"] },
          "writeable": { "description": "True if the attribute is also writeable as a control",
                         "type": "boolean" },
          "alias": { "description": "An alias signal/control to create for this attribute. An empty string if no alias is desired.",
                     "type": "string" }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
}

For an example of a sysfs configuration file, please see: <sysfs_attributes.json>

This guide includes a list of signals and controls that are available in instances of SysfsIOGroup that are bundled with GEOPM. Your system may expose a subset of these signals and controls (e.g., if a driver is not loaded, or if it is loaded but in a state that does not expose all of the attributes), or may expose additional signals and controls (e.g., if you have configured additional instances of SysfsIOGroup that are not bundled with GEOPM). Use geopmread and geopmwrite to query the full set of signals and controls that are available on a particular system.

Signals and controls in this IOGroup come from multiple drivers that provide sysfs attributes. Some signals and controls come from the cpufreq driver. For more information, see the cpufreq documentation.

Some signals and controls are made available to GEOPM through the sysfs interface to the i915 DRM (Direct Rendering Manager) driver. For more information, see the i915 documentation and the oneAPI GPU Optimization Guide. The i915 driver is available in upstream Linux. Additional features are available in the out-of-tree version of the driver. This IOGroup is intended for use with either version of the driver.

Signals

Cpufreq Signals 

The following signals are made available to GEOPM through the sysfs interface to the cpufreq driver.

CPUFREQ::BIOS_LIMIT

Maximum CPU frequency, limited by BIOS settings.

Maps to attribute: bios_limit
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

CPUFREQ::CPUINFO_CUR_FREQ

The current operating frequency reported by the CPU hardware.

Maps to attribute: cpuinfo_cur_freq
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

CPUFREQ::CPUINFO_MAX_FREQ

The maximum allowed frequency to set on the CPU.

Maps to attribute: cpuinfo_max_freq
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

CPUFREQ::CPUINFO_MIN_FREQ

The minimum allowed frequency to set on the CPU.

Maps to attribute: cpuinfo_min_freq
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

CPUFREQ::CPUINFO_TRANSITION_LATENCY

The time delay to switch from one P-State to another.

Maps to attribute: cpuinfo_transition_latency
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: seconds

CPUFREQ::SCALING_CUR_FREQ

The current requested CPU frequency by the cpufreq scaling driver.

Maps to attribute: scaling_cur_freq
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

i915 DRM Signals 

The following signals are made available to GEOPM through the sysfs interface to the i915 DRM driver.

DRM::RPS_MIN_FREQ_DEFAULT

The platform’s default setting for DRM::RPS_MIN_FREQ

Maps to attribute: .defaults/rps_min_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RPS_MAX_FREQ_DEFAULT

The platform’s default setting for DRM::RPS_MAX_FREQ

Maps to attribute: .defaults/rps_max_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RPS_CUR_FREQ

Latest GPU frequency cached by the driver

Maps to attribute: rps_cur_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RPS_ACT_FREQ

Actual latest GPU frequency

Maps to attribute: rps_act_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RPS_BOOST_FREQ

GPU boost frequency

Maps to attribute: rps_boost_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::BASE_ACT_FREQ

Actual GPU base-die frequency selected by the power manager

Maps to attribute: base_act_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::MEDIA_ACT_FREQ

Actual GPU media frequency

Maps to attribute: media_act_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::BASE_FREQ_FACTOR_STEP_DEFAULT

The platform’s default setting for DRM::BASE_FREQ_FACTOR_STEP

Maps to attribute: .defaults/base_freq_factor
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::BASE_FREQ_FACTOR_SCALE

Scaling factor for DRM::BASE_FREQ_FACTOR_STEP

Maps to attribute: base_freq_factor.scale
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::MEDIA_FREQ_FACTOR_STEP_DEFAULT

The platform’s default setting for DRM::MEDIA_FREQ_FACTOR_STEP

Maps to attribute: .defaults/media_freq_factor
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::MEDIA_FREQ_FACTOR_SCALE

Scaling factor for DRM::MEDIA_FREQ_FACTOR_STEP

Maps to attribute: media_freq_factor.scale
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::RPS_RP0_FREQ

Maximum non-overclocked GPU frequency

Maps to attribute: rps_RP0_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::BASE_RP0_FREQ

GPU base-die RP0 frequency

Maps to attribute: base_RP0_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::MEDIA_RP0_FREQ

GPU media RP0 frequency

Maps to attribute: media_RP0_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::MEM_RP0_FREQ

GPU memory-die RP0 frequency

Maps to attribute: mem_RP0_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RPS_RP1_FREQ

GPU RP1 nominal frequency

Maps to attribute: rps_RP1_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::BASE_RPN_FREQ

GPU base-die RPn frequency

Maps to attribute: base_RPn_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RPS_RPN_FREQ

GPU minimum requestable frequency

Maps to attribute: rps_RPn_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::MEDIA_RPN_FREQ

GPU media RPn frequency

Maps to attribute: media_RPn_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::MEM_RPN_FREQ

GPU memory-die RPn frequency

Maps to attribute: mem_RPn_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::PUNIT_REQ_FREQ

PUnit requested GPU frequency

Maps to attribute: punit_req_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RAPL_PL1_FREQ

GPU RAPL PL1 frequency

Maps to attribute: rapl_PL1_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RC6_RESIDENCY

Time spent in RC6 state

Maps to attribute: rc6_residency_ms
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: seconds

DRM::THROTTLE_REASON_PL1

Whether the GPU is currently being throttled due to PL1 (average power)

Maps to attribute: throttle_reason_pl1
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_PL2

Whether the GPU is currently being throttled due to PL2 (burst power)

Maps to attribute: throttle_reason_pl2
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_PL4

Whether the GPU is currently being throttled due to PL4 (current)

Maps to attribute: throttle_reason_pl4
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_PROCHOT

Whether the GPU is currently being throttled due to prochot

Maps to attribute: throttle_reason_prochot
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_RATL

Whether the GPU is currently being throttled due to RATL

Maps to attribute: throttle_reason_ratl
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_STATUS

Whether the GPU is currently being throttled for any reason

Maps to attribute: throttle_reason_status
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_THERMAL

Whether the GPU is currently being throttled for thermal reasons

Maps to attribute: throttle_reason_thermal
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_VR_TDC

Whether the GPU is currently being throttled for VR TDC reasons

Maps to attribute: throttle_reason_vr_tdc
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::THROTTLE_REASON_VR_THERMALERT

Whether the GPU is currently being throttled for VR thermal alert reasons

Maps to attribute: throttle_reason_thermalert
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

Controls

Cpufreq Controls 

The following controls are made available to GEOPM through the sysfs interface to the cpufreq driver.

CPUFREQ::SCALING_MAX_FREQ

The maximum frequency allowed by the cpufreq scaling driver.

Maps to attribute: scaling_max_freq
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

CPUFREQ::SCALING_MIN_FREQ

The minimum frequency allowed by the cpufreq scaling driver.

Maps to attribute: scaling_min_freq
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

CPUFREQ::SCALING_SETSPEED

The latest frequency request sent to the userspace scaling governor.

Maps to attribute: scaling_setspeed
Aggregation: average
Domain: Determined by GEOPM at time of query
Format: double
Unit: hertz

i915 DRM Controls 

The following controls are made available to GEOPM through the sysfs interface to the i915 DRM driver.

DRM::RPS_MIN_FREQ

User-configured requested power state (RPS) for minimum GPU frequency

Maps to attribute: rps_min_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::RPS_MAX_FREQ

User-configured requested power state (RPS) for maximum GPU frequency

Maps to attribute: rps_max_freq_mhz
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: hertz

DRM::BASE_FREQ_FACTOR_STEP

GPU base-die frequency factor scaled by 1/DRM::BASE_FREQ_FACTOR_SCALE

Maps to attribute: base_freq_factor
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::MEDIA_FREQ_FACTOR_STEP

GPU media frequency factor scaled by 1/DRM::MEDIA_FREQ_FACTOR_SCALE

Maps to attribute: media_freq_factor
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

DRM::RC6_ENABLE

Enable RC6

Maps to attribute: rc6_enable
Aggregation: average
Domain: Determined by GEOPM at time of query (Expected: gpu_chip)
Format: double
Unit: none

Aliases

This IOGroup provides the following high-level aliases. Note that some aliases may map to multiple potential sysfs attributes. Your system will map only one attribute to a given alias, depending on the driver’s configuration. Use geopmread and geopmwrite to query information about each alias on your system.

Signal Aliases

CPU_FREQUENCY_MAX_AVAIL: Maps to: CPUFREQ::CPUINFO_MAX_FREQ
CPU_FREQUENCY_MIN_AVAIL: Maps to: CPUFREQ::CPUINFO_MIN_FREQ
CPU_FREQUENCY_STATUS: Maps to: CPUFREQ::SCALING_CUR_FREQ

Control Aliases

CPU_FREQUENCY_MAX_CONTROL: Maps to: CPUFREQ::SCALING_MAX_FREQ
CPU_FREQUENCY_MIN_CONTROL: Maps to: CPUFREQ::SCALING_MIN_FREQ
CPU_FREQUENCY_DESIRED_CONTROL: Maps to: CPUFREQ::SCALING_SETSPEED

Example

The following example uses geopmread and geopmwrite command-line tools. These steps can also be followed within an agent.

Setting Frequency

Set the maximum allowed operating frequency on core 0 to 1.7 GHz:

geopmwrite CPU_FREQUENCY_MAX_CONTROL core 0 1700000000

Read the current maximum allowed frequency and the recent operating frequency of core 0:

geopmread CPU_FREQUENCY_MAX_CONTROL core 0

geopmread CPU_FREQUENCY_STATUS core 0