Documentation/power/powercap/powercap.rst

   1 =======================
   2 Power Capping Framework
   3 =======================
   4
   5 The power capping framework provides a consistent interface between the kernel
   6 and the user space that allows power capping drivers to expose the settings to
   7 user space in a uniform way.
   8
   9 Terminology
  10 ===========
  11
  12 The framework exposes power capping devices to user space via sysfs in the
  13 form of a tree of objects. The objects at the root level of the tree represent
  14 'control types', which correspond to different methods of power capping.  For
  15 example, the intel-rapl control type represents the Intel "Running Average
  16 Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
  17 corresponds to the use of idle injection for controlling power.
  18
  19 Power zones represent different parts of the system, which can be controlled and
  20 monitored using the power capping method determined by the control type the
  21 given zone belongs to. They each contain attributes for monitoring power, as
  22 well as controls represented in the form of power constraints.  If the parts of
  23 the system represented by different power zones are hierarchical (that is, one
  24 bigger part consists of multiple smaller parts that each have their own power
  25 controls), those power zones may also be organized in a hierarchy with one
  26 parent power zone containing multiple subzones and so on to reflect the power
  27 control topology of the system.  In that case, it is possible to apply power
  28 capping to a set of devices together using the parent power zone and if more
  29 fine grained control is required, it can be applied through the subzones.
  30
  31
  32 Example sysfs interface tree::
  33
  34   /sys/devices/virtual/powercap
  35   └──intel-rapl
  36       ├──intel-rapl:0
  37       │   ├──constraint_0_name
  38       │   ├──constraint_0_power_limit_uw
  39       │   ├──constraint_0_time_window_us
  40       │   ├──constraint_1_name
  41       │   ├──constraint_1_power_limit_uw
  42       │   ├──constraint_1_time_window_us
  43       │   ├──device -> ../../intel-rapl
  44       │   ├──energy_uj
  45       │   ├──intel-rapl:0:0
  46       │   │   ├──constraint_0_name
  47       │   │   ├──constraint_0_power_limit_uw
  48       │   │   ├──constraint_0_time_window_us
  49       │   │   ├──constraint_1_name
  50       │   │   ├──constraint_1_power_limit_uw
  51       │   │   ├──constraint_1_time_window_us
  52       │   │   ├──device -> ../../intel-rapl:0
  53       │   │   ├──energy_uj
  54       │   │   ├──max_energy_range_uj
  55       │   │   ├──name
  56       │   │   ├──enabled
  57       │   │   ├──power
  58       │   │   │   ├──async
  59       │   │   │   []
  60       │   │   ├──subsystem -> ../../../../../../class/power_cap
  61       │   │   └──uevent
  62       │   ├──intel-rapl:0:1
  63       │   │   ├──constraint_0_name
  64       │   │   ├──constraint_0_power_limit_uw
  65       │   │   ├──constraint_0_time_window_us
  66       │   │   ├──constraint_1_name
  67       │   │   ├──constraint_1_power_limit_uw
  68       │   │   ├──constraint_1_time_window_us
  69       │   │   ├──device -> ../../intel-rapl:0
  70       │   │   ├──energy_uj
  71       │   │   ├──max_energy_range_uj
  72       │   │   ├──name
  73       │   │   ├──enabled
  74       │   │   ├──power
  75       │   │   │   ├──async
  76       │   │   │   []
  77       │   │   ├──subsystem -> ../../../../../../class/power_cap
  78       │   │   └──uevent
  79       │   ├──max_energy_range_uj
  80       │   ├──max_power_range_uw
  81       │   ├──name
  82       │   ├──enabled
  83       │   ├──power
  84       │   │   ├──async
  85       │   │   []
  86       │   ├──subsystem -> ../../../../../class/power_cap
  87       │   ├──enabled
  88       │   ├──uevent
  89       ├──intel-rapl:1
  90       │   ├──constraint_0_name
  91       │   ├──constraint_0_power_limit_uw
  92       │   ├──constraint_0_time_window_us
  93       │   ├──constraint_1_name
  94       │   ├──constraint_1_power_limit_uw
  95       │   ├──constraint_1_time_window_us
  96       │   ├──device -> ../../intel-rapl
  97       │   ├──energy_uj
  98       │   ├──intel-rapl:1:0
  99       │   │   ├──constraint_0_name
 100       │   │   ├──constraint_0_power_limit_uw
 101       │   │   ├──constraint_0_time_window_us
 102       │   │   ├──constraint_1_name
 103       │   │   ├──constraint_1_power_limit_uw
 104       │   │   ├──constraint_1_time_window_us
 105       │   │   ├──device -> ../../intel-rapl:1
 106       │   │   ├──energy_uj
 107       │   │   ├──max_energy_range_uj
 108       │   │   ├──name
 109       │   │   ├──enabled
 110       │   │   ├──power
 111       │   │   │   ├──async
 112       │   │   │   []
 113       │   │   ├──subsystem -> ../../../../../../class/power_cap
 114       │   │   └──uevent
 115       │   ├──intel-rapl:1:1
 116       │   │   ├──constraint_0_name
 117       │   │   ├──constraint_0_power_limit_uw
 118       │   │   ├──constraint_0_time_window_us
 119       │   │   ├──constraint_1_name
 120       │   │   ├──constraint_1_power_limit_uw
 121       │   │   ├──constraint_1_time_window_us
 122       │   │   ├──device -> ../../intel-rapl:1
 123       │   │   ├──energy_uj
 124       │   │   ├──max_energy_range_uj
 125       │   │   ├──name
 126       │   │   ├──enabled
 127       │   │   ├──power
 128       │   │   │   ├──async
 129       │   │   │   []
 130       │   │   ├──subsystem -> ../../../../../../class/power_cap
 131       │   │   └──uevent
 132       │   ├──max_energy_range_uj
 133       │   ├──max_power_range_uw
 134       │   ├──name
 135       │   ├──enabled
 136       │   ├──power
 137       │   │   ├──async
 138       │   │   []
 139       │   ├──subsystem -> ../../../../../class/power_cap
 140       │   ├──uevent
 141       ├──power
 142       │   ├──async
 143       │   []
 144       ├──subsystem -> ../../../../class/power_cap
 145       ├──enabled
 146       └──uevent
 147
 148 The above example illustrates a case in which the Intel RAPL technology,
 149 available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
 150 control type called intel-rapl which contains two power zones, intel-rapl:0 and
 151 intel-rapl:1, representing CPU packages.  Each of these power zones contains
 152 two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
 153 "core" and the "uncore" parts of the given CPU package, respectively.  All of
 154 the zones and subzones contain energy monitoring attributes (energy_uj,
 155 max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
 156 to be applied (the constraints in the 'package' power zones apply to the whole
 157 CPU packages and the subzone constraints only apply to the respective parts of
 158 the given package individually). Since Intel RAPL doesn't provide instantaneous
 159 power value, there is no power_uw attribute.
 160
 161 In addition to that, each power zone contains a name attribute, allowing the
 162 part of the system represented by that zone to be identified.
 163 For example::
 164
 165         cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
 166
 167 package-0
 168 ---------
 169
 170 The Intel RAPL technology allows two constraints, short term and long term,
 171 with two different time windows to be applied to each power zone.  Thus for
 172 each zone there are 2 attributes representing the constraint names, 2 power
 173 limits and 2 attributes representing the sizes of the time windows. Such that,
 174 constraint_j_* attributes correspond to the jth constraint (j = 0,1).
 175
 176 For example::
 177
 178         constraint_0_name
 179         constraint_0_power_limit_uw
 180         constraint_0_time_window_us
 181         constraint_1_name
 182         constraint_1_power_limit_uw
 183         constraint_1_time_window_us
 184
 185 Power Zone Attributes
 186 =====================
 187
 188 Monitoring attributes
 189 ---------------------
 190
 191 energy_uj (rw)
 192         Current energy counter in micro joules. Write "0" to reset.
 193         If the counter can not be reset, then this attribute is read only.
 194
 195 max_energy_range_uj (ro)
 196         Range of the above energy counter in micro-joules.
 197
 198 power_uw (ro)
 199         Current power in micro watts.
 200
 201 max_power_range_uw (ro)
 202         Range of the above power value in micro-watts.
 203
 204 name (ro)
 205         Name of this power zone.
 206
 207 It is possible that some domains have both power ranges and energy counter ranges;
 208 however, only one is mandatory.
 209
 210 Constraints
 211 -----------
 212
 213 constraint_X_power_limit_uw (rw)
 214         Power limit in micro watts, which should be applicable for the
 215         time window specified by "constraint_X_time_window_us".
 216
 217 constraint_X_time_window_us (rw)
 218         Time window in micro seconds.
 219
 220 constraint_X_name (ro)
 221         An optional name of the constraint
 222
 223 constraint_X_max_power_uw(ro)
 224         Maximum allowed power in micro watts.
 225
 226 constraint_X_min_power_uw(ro)
 227         Minimum allowed power in micro watts.
 228
 229 constraint_X_max_time_window_us(ro)
 230         Maximum allowed time window in micro seconds.
 231
 232 constraint_X_min_time_window_us(ro)
 233         Minimum allowed time window in micro seconds.
 234
 235 Except power_limit_uw and time_window_us other fields are optional.
 236
 237 Common zone and control type attributes
 238 ---------------------------------------
 239
 240 enabled (rw): Enable/Disable controls at zone level or for all zones using
 241 a control type.
 242
 243 Power Cap Client Driver Interface
 244 =================================
 245
 246 The API summary:
 247
 248 Call powercap_register_control_type() to register control type object.
 249 Call powercap_register_zone() to register a power zone (under a given
 250 control type), either as a top-level power zone or as a subzone of another
 251 power zone registered earlier.
 252 The number of constraints in a power zone and the corresponding callbacks have
 253 to be defined prior to calling powercap_register_zone() to register that zone.
 254
 255 To Free a power zone call powercap_unregister_zone().
 256 To free a control type object call powercap_unregister_control_type().
 257 Detailed API can be generated using kernel-doc on include/linux/powercap.h.