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", "amperes", "volts"] },
          "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. Furthermore, the i915 DRM devices may link to i915 hwmon devices. If the hwmon links are present, this IOGroup also exposes signals and controls from the i915 hwmon interface.

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.

If a GEOPM sysfs-based signal came from the DRM system, then its name begins with DRM. The driver (e.g., i915 that made that signal available to DRM can be viewed by running geopmread --info SIGNAL_NAME. For example:

$ geopmread --info DRM::HWMON::ENERGY1_INPUT::GPU
DRM::HWMON::ENERGY1_INPUT::GPU:
    description: GPU card-level energy counter
    units: joules
    aggregation: sum
    domain: gpu
    iogroup: DRM from driver: i915

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::HWMON::IN0_INPUT

The current voltage

  • Maps to attribute: in0_input

  • Aggregation: average

  • Domain: Determined by GEOPM at time of query (Expected: gpu)

  • Format: double

  • Unit: volts

DRM::HWMON::POWER1_RATED_MAX

Default thermal design power limit

  • Maps to attribute: power1_max

  • Aggregation: sum

  • Domain: Determined by GEOPM at time of query (Expected: gpu)

  • Format: double

  • Unit: watts

DRM::HWMON::ENERGY1_INPUT::GPU

GPU card-level energy counter

  • Maps to attribute: energy1_input

  • Aggregation: sum

  • Domain: Determined by GEOPM at time of query (Expected: gpu)

  • Format: double

  • Unit: joules

DRM::HWMON::ENERGY1_INPUT::GPU_CHIP

GPU tile-level energy counter

  • Maps to attribute: energy1_input

  • Aggregation: sum

  • Domain: Determined by GEOPM at time of query (Expected: gpu_chip)

  • Format: double

  • Unit: joules

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::HWMON::POWER1_MAX

Requested power limit, sustained on average over DRM::HWMON::POWER1_MAX_INTERVAL

  • Maps to attribute: power1_max

  • Aggregation: sum

  • Domain: Determined by GEOPM at time of query (Expected: gpu)

  • Format: double

  • Unit: watts

DRM::HWMON::POWER1_MAX_INTERVAL

Requested time window over which DRM::HWMON::POWER1_MAX is sustained on average

  • Maps to attribute: power1_max_interval

  • Aggregation: expect_same

  • Domain: Determined by GEOPM at time of query (Expected: gpu)

  • Format: double

  • Unit: seconds

DRM::HWMON::POWER1_CRIT

Critical power limit, influencing the power manager’s throttling decisions

  • Maps to attribute: power1_crit

  • Aggregation: sum

  • Domain: Determined by GEOPM at time of query (Expected: gpu)

  • Format: double

  • Unit: watts

DRM::HWMON::CURR1_CRIT

Critical current limit, influencing the power manager’s throttling decisions

  • Maps to attribute: curr1_crit

  • Aggregation: sum

  • Domain: Determined by GEOPM at time of query (Expected: gpu)

  • Format: double

  • Unit: amperes

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

GPU_POWER_LIMIT_DEFAULT

Maps to: DRM::HWMON::POWER1_RATED_MAX

GPU_ENERGY

Maps to: DRM::HWMON::ENERGY1_INPUT::GPU

GPU_CHIP_ENERGY

Maps to: DRM::HWMON::ENERGY1_INPUT::GPU_CHIP

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

GPU_POWER_LIMIT_CONTROL

Maps to: DRM::HWMON::POWER1_MAX

GPU_POWER_TIME_WINDOW_CONTROL

Maps to: DRM::HWMON::POWER1_MAX_INTERVAL

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

See Also

geopm_pio(7), geopm(7), geopm::IOGroup(3), geopmwrite(1), geopmread(1)