Power Capping Framework

Framework 목적

Power capping framework는 kernel과 사용자 공간 사이에 일관된 interface를 제공해 power capping driver가 설정을 사용자 공간에 통일된 방식으로 노출하게 합니다.

=======================
Power Capping Framework
=======================

The power capping framework provides a consistent interface between the kernel
and the user space that allows power capping drivers to expose the settings to
user space in a uniform way.

Control type, power zone과 subzone

Framework는 power capping device를 sysfs object tree로 사용자 공간에 노출합니다. Root level object는 power capping 방법을 나타내는 `control type`입니다. `intel-rapl` control type은 Intel Running Average Power Limit(RAPL)을, `idle-injection`은 idle injection을 이용한 power 제어를 뜻합니다.

Power zone은 해당 zone이 속한 control type의 방법으로 monitoring하고 제어할 수 있는 system 일부를 나타냅니다. 각 zone에는 power monitoring attribute와 power constraint 형태의 control이 있습니다.

System의 power zone이 계층적이라면 parent power zone 아래에 여러 subzone을 두는 방식으로 system의 power-control topology를 반영할 수 있습니다. Parent zone으로 device 집합 전체를 함께 제한하고, 더 세밀한 제어가 필요하면 subzone별로 제한할 수 있습니다.

Terminology
===========

The framework exposes power capping devices to user space via sysfs in the
form of a tree of objects. The objects at the root level of the tree represent
'control types', which correspond to different methods of power capping.  For
example, the intel-rapl control type represents the Intel "Running Average
Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
corresponds to the use of idle injection for controlling power.

Power zones represent different parts of the system, which can be controlled and
monitored using the power capping method determined by the control type the
given zone belongs to. They each contain attributes for monitoring power, as
well as controls represented in the form of power constraints.  If the parts of
the system represented by different power zones are hierarchical (that is, one
bigger part consists of multiple smaller parts that each have their own power
controls), those power zones may also be organized in a hierarchy with one
parent power zone containing multiple subzones and so on to reflect the power
control topology of the system.  In that case, it is possible to apply power
capping to a set of devices together using the parent power zone and if more
fine grained control is required, it can be applied through the subzones.

Intel RAPL sysfs tree

예제 sysfs root는 `/sys/devices/virtual/powercap`입니다. 그 아래 `intel-rapl` control type이 있고 `intel-rapl:0`과 `intel-rapl:1` package power zone이 있습니다. 각 package 아래에는 `intel-rapl:j:0`과 `intel-rapl:j:1` subzone이 있습니다.

Package zone에는 `constraint_0_*`, `constraint_1_*`, `device`, `energy_uj`, `max_energy_range_uj`, `max_power_range_uw`, `name`, `enabled`, `power`, `subsystem`, `uevent` 등이 있습니다.

각 subzone에도 constraint, `device`, `energy_uj`, `max_energy_range_uj`, `name`, `enabled`, `power`, `subsystem`, `uevent`가 있습니다. `power/async`는 device power 관리 하위 항목입니다.

Control type level에도 `enabled`, `power`, `subsystem`, `uevent`가 나타납니다. 원문의 tree-drawing 문자가 손상되어 있으므로 아래 표와 흐름은 경로와 parent-child 관계를 기준으로 같은 구조를 깨끗하게 재구성한 것입니다.

Example sysfs interface tree::

  /sys/devices/virtual/powercap
  └──intel-rapl
      ├──intel-rapl:0
      │   ├──constraint_0_name
      │   ├──constraint_0_power_limit_uw
      │   ├──constraint_0_time_window_us
      │   ├──constraint_1_name
      │   ├──constraint_1_power_limit_uw
      │   ├──constraint_1_time_window_us
      │   ├──device -> ../../intel-rapl
      │   ├──energy_uj
      │   ├──intel-rapl:0:0
      │   │   ├──constraint_0_name
      │   │   ├──constraint_0_power_limit_uw
      │   │   ├──constraint_0_time_window_us
      │   │   ├──constraint_1_name
      │   │   ├──constraint_1_power_limit_uw
      │   │   ├──constraint_1_time_window_us
      │   │   ├──device -> ../../intel-rapl:0
      │   │   ├──energy_uj
      │   │   ├──max_energy_range_uj
      │   │   ├──name
      │   │   ├──enabled
      │   │   ├──power
      │   │   │   ├──async
      │   │   │   []
      │   │   ├──subsystem -> ../../../../../../class/power_cap
      │   │   └──uevent
      │   ├──intel-rapl:0:1
      │   │   ├──constraint_0_name
      │   │   ├──constraint_0_power_limit_uw
      │   │   ├──constraint_0_time_window_us
      │   │   ├──constraint_1_name
      │   │   ├──constraint_1_power_limit_uw
      │   │   ├──constraint_1_time_window_us
      │   │   ├──device -> ../../intel-rapl:0
      │   │   ├──energy_uj
      │   │   ├──max_energy_range_uj
      │   │   ├──name
      │   │   ├──enabled
      │   │   ├──power
      │   │   │   ├──async
      │   │   │   []
      │   │   ├──subsystem -> ../../../../../../class/power_cap
      │   │   └──uevent
      │   ├──max_energy_range_uj
      │   ├──max_power_range_uw
      │   ├──name
      │   ├──enabled
      │   ├──power
      │   │   ├──async
      │   │   []
      │   ├──subsystem -> ../../../../../class/power_cap
      │   ├──enabled
      │   ├──uevent
      ├──intel-rapl:1
      │   ├──constraint_0_name
      │   ├──constraint_0_power_limit_uw
      │   ├──constraint_0_time_window_us
      │   ├──constraint_1_name
      │   ├──constraint_1_power_limit_uw
      │   ├──constraint_1_time_window_us
      │   ├──device -> ../../intel-rapl
      │   ├──energy_uj
      │   ├──intel-rapl:1:0
      │   │   ├──constraint_0_name
      │   │   ├──constraint_0_power_limit_uw
      │   │   ├──constraint_0_time_window_us
      │   │   ├──constraint_1_name
      │   │   ├──constraint_1_power_limit_uw
      │   │   ├──constraint_1_time_window_us
      │   │   ├──device -> ../../intel-rapl:1
      │   │   ├──energy_uj
      │   │   ├──max_energy_range_uj
      │   │   ├──name
      │   │   ├──enabled
      │   │   ├──power
      │   │   │   ├──async
      │   │   │   []
      │   │   ├──subsystem -> ../../../../../../class/power_cap
      │   │   └──uevent
      │   ├──intel-rapl:1:1
      │   │   ├──constraint_0_name
      │   │   ├──constraint_0_power_limit_uw
      │   │   ├──constraint_0_time_window_us
      │   │   ├──constraint_1_name
      │   │   ├──constraint_1_power_limit_uw
      │   │   ├──constraint_1_time_window_us
      │   │   ├──device -> ../../intel-rapl:1
      │   │   ├──energy_uj
      │   │   ├──max_energy_range_uj
      │   │   ├──name
      │   │   ├──enabled
      │   │   ├──power
      │   │   │   ├──async
      │   │   │   []
      │   │   ├──subsystem -> ../../../../../../class/power_cap
      │   │   └──uevent
      │   ├──max_energy_range_uj
      │   ├──max_power_range_uw
      │   ├──name
      │   ├──enabled
      │   ├──power
      │   │   ├──async
      │   │   []
      │   ├──subsystem -> ../../../../../class/power_cap
      │   ├──uevent
      ├──power
      │   ├──async
      │   []
      ├──subsystem -> ../../../../class/power_cap
      ├──enabled
      └──uevent

RAPL topology와 zone 이름

이 예제는 Intel IA-64와 IA-32 Processor Architecture에서 제공되는 Intel RAPL 기술을 사용합니다. `intel-rapl` control type 하나에 CPU package를 나타내는 `intel-rapl:0`과 `intel-rapl:1` power zone 두 개가 있습니다.

각 package zone에는 해당 CPU package의 `core`와 `uncore` 부분을 각각 나타내는 `intel-rapl:j:0`과 `intel-rapl:j:1` subzone이 있습니다. 모든 zone과 subzone에는 `energy_uj`, `max_energy_range_uj` energy monitoring attribute와 control을 적용하는 `constraint_*` attribute가 있습니다.

Package power zone의 constraint는 CPU package 전체에 적용되고 subzone constraint는 해당 package의 각 부분에만 적용됩니다. Intel RAPL은 instantaneous power 값을 제공하지 않으므로 `power_uw` attribute가 없습니다.

각 power zone에는 자신이 나타내는 system 부분을 식별하는 `name` attribute도 있습니다. 예를 들어 `cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name`의 결과는 `package-0`입니다.

The above example illustrates a case in which the Intel RAPL technology,
available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
control type called intel-rapl which contains two power zones, intel-rapl:0 and
intel-rapl:1, representing CPU packages.  Each of these power zones contains
two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
"core" and the "uncore" parts of the given CPU package, respectively.  All of
the zones and subzones contain energy monitoring attributes (energy_uj,
max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
to be applied (the constraints in the 'package' power zones apply to the whole
CPU packages and the subzone constraints only apply to the respective parts of
the given package individually). Since Intel RAPL doesn't provide instantaneous
power value, there is no power_uw attribute.

In addition to that, each power zone contains a name attribute, allowing the
part of the system represented by that zone to be identified.
For example::

        cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name

package-0
---------

RAPL constraint 이름과 time window

Power zone에 따라 Intel RAPL은 short-term, long-term, peak power 같은 하나 이상의 constraint를 서로 다른 time window와 함께 적용할 수 있습니다.

모든 zone에는 constraint name, power limit, time-window size를 나타내는 attribute가 있습니다. Peak power에는 time window가 적용되지 않습니다. `constraint_j_*`는 j번째 constraint를 뜻하며 여기서 j는 0, 1, 2입니다.

예제 attribute는 각 j에 대해 `constraint_j_name`, `constraint_j_power_limit_uw`, `constraint_j_time_window_us`입니다.

Depending on different power zones, the Intel RAPL technology allows
one or multiple constraints like short term, long term and peak power,
with different time windows to be applied to each power zone.
All the zones contain attributes representing the constraint names,
power limits and the sizes of the time windows. Note that time window
is not applicable to peak power. Here, constraint_j_* attributes
correspond to the jth constraint (j = 0,1,2).

For example::

        constraint_0_name
        constraint_0_power_limit_uw
        constraint_0_time_window_us
        constraint_1_name
        constraint_1_power_limit_uw
        constraint_1_time_window_us
        constraint_2_name
        constraint_2_power_limit_uw
        constraint_2_time_window_us

Power zone monitoring attribute

`energy_uj`는 microjoule 단위의 현재 energy counter이며 읽기·쓰기가 가능합니다. `0`을 쓰면 reset합니다. Counter를 reset할 수 없는 구현에서는 read-only입니다.

`max_energy_range_uj`는 energy counter의 microjoule 단위 range입니다. `power_uw`는 microwatt 단위의 현재 power이고 `max_power_range_uw`는 그 power 값의 microwatt 단위 range입니다. `name`은 power zone 이름입니다.

일부 domain에는 power range와 energy-counter range가 모두 있을 수 있지만 둘 중 하나만 있어도 됩니다.

Power Zone Attributes
=====================

Monitoring attributes
---------------------

energy_uj (rw)
        Current energy counter in micro joules. Write "0" to reset.
        If the counter can not be reset, then this attribute is read only.

max_energy_range_uj (ro)
        Range of the above energy counter in micro-joules.

power_uw (ro)
        Current power in micro watts.

max_power_range_uw (ro)
        Range of the above power value in micro-watts.

name (ro)
        Name of this power zone.

It is possible that some domains have both power ranges and energy counter ranges;
however, only one is mandatory.

Power constraint attribute

`constraint_X_power_limit_uw`는 `constraint_X_time_window_us`가 지정하는 기간에 적용할 microwatt 단위 power limit이며 읽기·쓰기가 가능합니다. `constraint_X_time_window_us`는 microsecond 단위 time window이며 역시 읽기·쓰기가 가능합니다.

`constraint_X_name`은 optional read-only constraint 이름입니다. `constraint_X_max_power_uw`와 `constraint_X_min_power_uw`는 허용되는 maximum·minimum power를 microwatt로 나타냅니다.

`constraint_X_max_time_window_us`와 `constraint_X_min_time_window_us`는 허용되는 maximum·minimum time window를 microsecond로 나타냅니다.

`power_limit_uw`와 `time_window_us`를 제외한 나머지 field는 optional입니다.

Constraints
-----------

constraint_X_power_limit_uw (rw)
        Power limit in micro watts, which should be applicable for the
        time window specified by "constraint_X_time_window_us".

constraint_X_time_window_us (rw)
        Time window in micro seconds.

constraint_X_name (ro)
        An optional name of the constraint

constraint_X_max_power_uw(ro)
        Maximum allowed power in micro watts.

constraint_X_min_power_uw(ro)
        Minimum allowed power in micro watts.

constraint_X_max_time_window_us(ro)
        Maximum allowed time window in micro seconds.

constraint_X_min_time_window_us(ro)
        Minimum allowed time window in micro seconds.

Except power_limit_uw and time_window_us other fields are optional.

공통 zone과 control type attribute

`enabled`는 읽기·쓰기가 가능한 공통 attribute입니다. Zone level의 control을 enable/disable하거나 control type을 통해 모든 zone의 control을 한꺼번에 enable/disable합니다.

Common zone and control type attributes
---------------------------------------

enabled (rw): Enable/Disable controls at zone level or for all zones using
a control type.

Power Cap client driver interface

`powercap_register_control_type()`을 호출해 control type object를 등록합니다.

`powercap_register_zone()`을 호출해 지정한 control type 아래에 power zone을 등록합니다. Top-level power zone으로 등록하거나 앞서 등록한 다른 power zone의 subzone으로 등록할 수 있습니다.

Power zone의 constraint 수와 각 callback은 `powercap_register_zone()`을 호출하기 전에 정의해야 합니다.

Power zone을 해제하려면 `powercap_unregister_zone()`을, control type object를 해제하려면 `powercap_unregister_control_type()`을 호출합니다. 상세 API 문서는 `include/linux/powercap.h`에 kernel-doc을 실행해 생성할 수 있습니다.

Power Cap Client Driver Interface
=================================

The API summary:

Call powercap_register_control_type() to register control type object.
Call powercap_register_zone() to register a power zone (under a given
control type), either as a top-level power zone or as a subzone of another
power zone registered earlier.
The number of constraints in a power zone and the corresponding callbacks have
to be defined prior to calling powercap_register_zone() to register that zone.

To Free a power zone call powercap_unregister_zone().
To free a control type object call powercap_unregister_control_type().
Detailed API can be generated using kernel-doc on include/linux/powercap.h.