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