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 Depending on different power zones, the Intel RAPL technology allows
 171 one or multiple constraints like short term, long term and peak power,
 172 with different time windows to be applied to each power zone.
 173 All the zones contain attributes representing the constraint names,
 174 power limits and the sizes of the time windows. Note that time window
 175 is not applicable to peak power. Here, constraint_j_* attributes
 176 correspond to the jth constraint (j = 0,1,2).
 177
 178 For example::
 179
 180         constraint_0_name
 181         constraint_0_power_limit_uw
 182         constraint_0_time_window_us
 183         constraint_1_name
 184         constraint_1_power_limit_uw
 185         constraint_1_time_window_us
 186         constraint_2_name
 187         constraint_2_power_limit_uw
 188         constraint_2_time_window_us
 189
 190 Power Zone Attributes
 191 =====================
 192
 193 Monitoring attributes
 194 ---------------------
 195
 196 energy_uj (rw)
 197         Current energy counter in micro joules. Write "0" to reset.
 198         If the counter can not be reset, then this attribute is read only.
 199
 200 max_energy_range_uj (ro)
 201         Range of the above energy counter in micro-joules.
 202
 203 power_uw (ro)
 204         Current power in micro watts.
 205
 206 max_power_range_uw (ro)
 207         Range of the above power value in micro-watts.
 208
 209 name (ro)
 210         Name of this power zone.
 211
 212 It is possible that some domains have both power ranges and energy counter ranges;
 213 however, only one is mandatory.
 214
 215 Constraints
 216 -----------
 217
 218 constraint_X_power_limit_uw (rw)
 219         Power limit in micro watts, which should be applicable for the
 220         time window specified by "constraint_X_time_window_us".
 221
 222 constraint_X_time_window_us (rw)
 223         Time window in micro seconds.
 224
 225 constraint_X_name (ro)
 226         An optional name of the constraint
 227
 228 constraint_X_max_power_uw(ro)
 229         Maximum allowed power in micro watts.
 230
 231 constraint_X_min_power_uw(ro)
 232         Minimum allowed power in micro watts.
 233
 234 constraint_X_max_time_window_us(ro)
 235         Maximum allowed time window in micro seconds.
 236
 237 constraint_X_min_time_window_us(ro)
 238         Minimum allowed time window in micro seconds.
 239
 240 Except power_limit_uw and time_window_us other fields are optional.
 241
 242 Common zone and control type attributes
 243 ---------------------------------------
 244
 245 enabled (rw): Enable/Disable controls at zone level or for all zones using
 246 a control type.
 247
 248 Power Cap Client Driver Interface
 249 =================================
 250
 251 The API summary:
 252
 253 Call powercap_register_control_type() to register control type object.
 254 Call powercap_register_zone() to register a power zone (under a given
 255 control type), either as a top-level power zone or as a subzone of another
 256 power zone registered earlier.
 257 The number of constraints in a power zone and the corresponding callbacks have
 258 to be defined prior to calling powercap_register_zone() to register that zone.
 259
 260 To Free a power zone call powercap_unregister_zone().
 261 To free a control type object call powercap_unregister_control_type().
 262 Detailed API can be generated using kernel-doc on include/linux/powercap.h.