| 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. |