1=======================
2Power Capping Framework
3=======================
4
5The power capping framework provides a consistent interface between the kernel
6and the user space that allows power capping drivers to expose the settings to
7user space in a uniform way.
8
9Terminology
10===========
11
12The framework exposes power capping devices to user space via sysfs in the
13form 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
15example, the intel-rapl control type represents the Intel "Running Average
16Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
17corresponds to the use of idle injection for controlling power.
18
19Power zones represent different parts of the system, which can be controlled and
20monitored using the power capping method determined by the control type the
21given zone belongs to. They each contain attributes for monitoring power, as
22well as controls represented in the form of power constraints.  If the parts of
23the system represented by different power zones are hierarchical (that is, one
24bigger part consists of multiple smaller parts that each have their own power
25controls), those power zones may also be organized in a hierarchy with one
26parent power zone containing multiple subzones and so on to reflect the power
27control topology of the system.  In that case, it is possible to apply power
28capping to a set of devices together using the parent power zone and if more
29fine grained control is required, it can be applied through the subzones.
30
31
32Example 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
148The above example illustrates a case in which the Intel RAPL technology,
149available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
150control type called intel-rapl which contains two power zones, intel-rapl:0 and
151intel-rapl:1, representing CPU packages.  Each of these power zones contains
152two 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
154the zones and subzones contain energy monitoring attributes (energy_uj,
155max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
156to be applied (the constraints in the 'package' power zones apply to the whole
157CPU packages and the subzone constraints only apply to the respective parts of
158the given package individually). Since Intel RAPL doesn't provide instantaneous
159power value, there is no power_uw attribute.
160
161In addition to that, each power zone contains a name attribute, allowing the
162part of the system represented by that zone to be identified.
163For example::
164
165	cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
166
167package-0
168---------
169
170Depending on different power zones, the Intel RAPL technology allows
171one or multiple constraints like short term, long term and peak power,
172with different time windows to be applied to each power zone.
173All the zones contain attributes representing the constraint names,
174power limits and the sizes of the time windows. Note that time window
175is not applicable to peak power. Here, constraint_j_* attributes
176correspond to the jth constraint (j = 0,1,2).
177
178For 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
190Power Zone Attributes
191=====================
192
193Monitoring attributes
194---------------------
195
196energy_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
200max_energy_range_uj (ro)
201	Range of the above energy counter in micro-joules.
202
203power_uw (ro)
204	Current power in micro watts.
205
206max_power_range_uw (ro)
207	Range of the above power value in micro-watts.
208
209name (ro)
210	Name of this power zone.
211
212It is possible that some domains have both power ranges and energy counter ranges;
213however, only one is mandatory.
214
215Constraints
216-----------
217
218constraint_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
222constraint_X_time_window_us (rw)
223	Time window in micro seconds.
224
225constraint_X_name (ro)
226	An optional name of the constraint
227
228constraint_X_max_power_uw(ro)
229	Maximum allowed power in micro watts.
230
231constraint_X_min_power_uw(ro)
232	Minimum allowed power in micro watts.
233
234constraint_X_max_time_window_us(ro)
235	Maximum allowed time window in micro seconds.
236
237constraint_X_min_time_window_us(ro)
238	Minimum allowed time window in micro seconds.
239
240Except power_limit_uw and time_window_us other fields are optional.
241
242Common zone and control type attributes
243---------------------------------------
244
245enabled (rw): Enable/Disable controls at zone level or for all zones using
246a control type.
247
248Power Cap Client Driver Interface
249=================================
250
251The API summary:
252
253Call powercap_register_control_type() to register control type object.
254Call powercap_register_zone() to register a power zone (under a given
255control type), either as a top-level power zone or as a subzone of another
256power zone registered earlier.
257The number of constraints in a power zone and the corresponding callbacks have
258to be defined prior to calling powercap_register_zone() to register that zone.
259
260To Free a power zone call powercap_unregister_zone().
261To free a control type object call powercap_unregister_control_type().
262Detailed API can be generated using kernel-doc on include/linux/powercap.h.
263