1 =======================
2 Power Capping Framework
3 =======================
4
5 The power capping framework provides a consist
6 and the user space that allows power capping d
7 user space in a uniform way.
8
9 Terminology
10 ===========
11
12 The framework exposes power capping devices to
13 form of a tree of objects. The objects at the
14 'control types', which correspond to different
15 example, the intel-rapl control type represent
16 Power Limit" (RAPL) technology, whereas the 'i
17 corresponds to the use of idle injection for c
18
19 Power zones represent different parts of the s
20 monitored using the power capping method deter
21 given zone belongs to. They each contain attri
22 well as controls represented in the form of po
23 the system represented by different power zone
24 bigger part consists of multiple smaller parts
25 controls), those power zones may also be organ
26 parent power zone containing multiple subzones
27 control topology of the system. In that case,
28 capping to a set of devices together using the
29 fine grained control is required, it can be ap
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_limi
39 │ ├──constraint_0_time_windo
40 │ ├──constraint_1_name
41 │ ├──constraint_1_power_limi
42 │ ├──constraint_1_time_windo
43 │ ├──device -> ../../intel-r
44 │ ├──energy_uj
45 │ ├──intel-rapl:0:0
46 │ │ ├──constraint_0_na
47 │ │ ├──constraint_0_po
48 │ │ ├──constraint_0_ti
49 │ │ ├──constraint_1_na
50 │ │ ├──constraint_1_po
51 │ │ ├──constraint_1_ti
52 │ │ ├──device -> ../..
53 │ │ ├──energy_uj
54 │ │ ├──max_energy_rang
55 │ │ ├──name
56 │ │ ├──enabled
57 │ │ ├──power
58 │ │ │ ├──async
59 │ │ │ []
60 │ │ ├──subsystem -> ..
61 │ │ └──uevent
62 │ ├──intel-rapl:0:1
63 │ │ ├──constraint_0_na
64 │ │ ├──constraint_0_po
65 │ │ ├──constraint_0_ti
66 │ │ ├──constraint_1_na
67 │ │ ├──constraint_1_po
68 │ │ ├──constraint_1_ti
69 │ │ ├──device -> ../..
70 │ │ ├──energy_uj
71 │ │ ├──max_energy_rang
72 │ │ ├──name
73 │ │ ├──enabled
74 │ │ ├──power
75 │ │ │ ├──async
76 │ │ │ []
77 │ │ ├──subsystem -> ..
78 │ │ └──uevent
79 │ ├──max_energy_range_uj
80 │ ├──max_power_range_uw
81 │ ├──name
82 │ ├──enabled
83 │ ├──power
84 │ │ ├──async
85 │ │ []
86 │ ├──subsystem -> ../../../.
87 │ ├──enabled
88 │ ├──uevent
89 ├──intel-rapl:1
90 │ ├──constraint_0_name
91 │ ├──constraint_0_power_limi
92 │ ├──constraint_0_time_windo
93 │ ├──constraint_1_name
94 │ ├──constraint_1_power_limi
95 │ ├──constraint_1_time_windo
96 │ ├──device -> ../../intel-r
97 │ ├──energy_uj
98 │ ├──intel-rapl:1:0
99 │ │ ├──constraint_0_na
100 │ │ ├──constraint_0_po
101 │ │ ├──constraint_0_ti
102 │ │ ├──constraint_1_na
103 │ │ ├──constraint_1_po
104 │ │ ├──constraint_1_ti
105 │ │ ├──device -> ../..
106 │ │ ├──energy_uj
107 │ │ ├──max_energy_rang
108 │ │ ├──name
109 │ │ ├──enabled
110 │ │ ├──power
111 │ │ │ ├──async
112 │ │ │ []
113 │ │ ├──subsystem -> ..
114 │ │ └──uevent
115 │ ├──intel-rapl:1:1
116 │ │ ├──constraint_0_na
117 │ │ ├──constraint_0_po
118 │ │ ├──constraint_0_ti
119 │ │ ├──constraint_1_na
120 │ │ ├──constraint_1_po
121 │ │ ├──constraint_1_ti
122 │ │ ├──device -> ../..
123 │ │ ├──energy_uj
124 │ │ ├──max_energy_rang
125 │ │ ├──name
126 │ │ ├──enabled
127 │ │ ├──power
128 │ │ │ ├──async
129 │ │ │ []
130 │ │ ├──subsystem -> ..
131 │ │ └──uevent
132 │ ├──max_energy_range_uj
133 │ ├──max_power_range_uw
134 │ ├──name
135 │ ├──enabled
136 │ ├──power
137 │ │ ├──async
138 │ │ []
139 │ ├──subsystem -> ../../../.
140 │ ├──uevent
141 ├──power
142 │ ├──async
143 │ []
144 ├──subsystem -> ../../../../class/
145 ├──enabled
146 └──uevent
147
148 The above example illustrates a case in which
149 available in Intel® IA-64 and IA-32 Processor
150 control type called intel-rapl which contains
151 intel-rapl:1, representing CPU packages. Each
152 two subzones, intel-rapl:j:0 and intel-rapl:j:
153 "core" and the "uncore" parts of the given CPU
154 the zones and subzones contain energy monitori
155 max_energy_range_uj) and constraint attributes
156 to be applied (the constraints in the 'package
157 CPU packages and the subzone constraints only
158 the given package individually). Since Intel R
159 power value, there is no power_uw attribute.
160
161 In addition to that, each power zone contains
162 part of the system represented by that zone to
163 For example::
164
165 cat /sys/class/power_cap/intel-rapl/in
166
167 package-0
168 ---------
169
170 Depending on different power zones, the Intel
171 one or multiple constraints like short term, l
172 with different time windows to be applied to e
173 All the zones contain attributes representing
174 power limits and the sizes of the time windows
175 is not applicable to peak power. Here, constra
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
198 If the counter can not be reset, then
199
200 max_energy_range_uj (ro)
201 Range of the above energy counter in m
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 micr
208
209 name (ro)
210 Name of this power zone.
211
212 It is possible that some domains have both pow
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 shou
220 time window specified by "constraint_X
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 s
236
237 constraint_X_min_time_window_us(ro)
238 Minimum allowed time window in micro s
239
240 Except power_limit_uw and time_window_us other
241
242 Common zone and control type attributes
243 ---------------------------------------
244
245 enabled (rw): Enable/Disable controls at zone
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 regis
254 Call powercap_register_zone() to register a po
255 control type), either as a top-level power zon
256 power zone registered earlier.
257 The number of constraints in a power zone and
258 to be defined prior to calling powercap_regist
259
260 To Free a power zone call powercap_unregister_
261 To free a control type object call powercap_un
262 Detailed API can be generated using kernel-doc
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.