]>
Commit | Line | Data |
---|---|---|
e23feb16 SP |
1 | Power Capping Framework |
2 | ================================== | |
3 | ||
4 | The power capping framework provides a consistent interface between the kernel | |
5 | and the user space that allows power capping drivers to expose the settings to | |
6 | user space in a uniform way. | |
7 | ||
8 | Terminology | |
9 | ========================= | |
10 | The framework exposes power capping devices to user space via sysfs in the | |
11 | form of a tree of objects. The objects at the root level of the tree represent | |
12 | 'control types', which correspond to different methods of power capping. For | |
13 | example, the intel-rapl control type represents the Intel "Running Average | |
14 | Power Limit" (RAPL) technology, whereas the 'idle-injection' control type | |
15 | corresponds to the use of idle injection for controlling power. | |
16 | ||
17 | Power zones represent different parts of the system, which can be controlled and | |
18 | monitored using the power capping method determined by the control type the | |
19 | given zone belongs to. They each contain attributes for monitoring power, as | |
20 | well as controls represented in the form of power constraints. If the parts of | |
21 | the system represented by different power zones are hierarchical (that is, one | |
22 | bigger part consists of multiple smaller parts that each have their own power | |
23 | controls), those power zones may also be organized in a hierarchy with one | |
24 | parent power zone containing multiple subzones and so on to reflect the power | |
25 | control topology of the system. In that case, it is possible to apply power | |
26 | capping to a set of devices together using the parent power zone and if more | |
27 | fine grained control is required, it can be applied through the subzones. | |
28 | ||
29 | ||
30 | Example sysfs interface tree: | |
31 | ||
32 | /sys/devices/virtual/powercap | |
33 | ??? intel-rapl | |
34 | ??? intel-rapl:0 | |
35 | ? ??? constraint_0_name | |
36 | ? ??? constraint_0_power_limit_uw | |
37 | ? ??? constraint_0_time_window_us | |
38 | ? ??? constraint_1_name | |
39 | ? ??? constraint_1_power_limit_uw | |
40 | ? ??? constraint_1_time_window_us | |
41 | ? ??? device -> ../../intel-rapl | |
42 | ? ??? energy_uj | |
43 | ? ??? intel-rapl:0:0 | |
44 | ? ? ??? constraint_0_name | |
45 | ? ? ??? constraint_0_power_limit_uw | |
46 | ? ? ??? constraint_0_time_window_us | |
47 | ? ? ??? constraint_1_name | |
48 | ? ? ??? constraint_1_power_limit_uw | |
49 | ? ? ??? constraint_1_time_window_us | |
50 | ? ? ??? device -> ../../intel-rapl:0 | |
51 | ? ? ??? energy_uj | |
52 | ? ? ??? max_energy_range_uj | |
53 | ? ? ??? name | |
54 | ? ? ??? enabled | |
55 | ? ? ??? power | |
56 | ? ? ? ??? async | |
57 | ? ? ? [] | |
58 | ? ? ??? subsystem -> ../../../../../../class/power_cap | |
59 | ? ? ??? uevent | |
60 | ? ??? intel-rapl:0:1 | |
61 | ? ? ??? constraint_0_name | |
62 | ? ? ??? constraint_0_power_limit_uw | |
63 | ? ? ??? constraint_0_time_window_us | |
64 | ? ? ??? constraint_1_name | |
65 | ? ? ??? constraint_1_power_limit_uw | |
66 | ? ? ??? constraint_1_time_window_us | |
67 | ? ? ??? device -> ../../intel-rapl:0 | |
68 | ? ? ??? energy_uj | |
69 | ? ? ??? max_energy_range_uj | |
70 | ? ? ??? name | |
71 | ? ? ??? enabled | |
72 | ? ? ??? power | |
73 | ? ? ? ??? async | |
74 | ? ? ? [] | |
75 | ? ? ??? subsystem -> ../../../../../../class/power_cap | |
76 | ? ? ??? uevent | |
77 | ? ??? max_energy_range_uj | |
78 | ? ??? max_power_range_uw | |
79 | ? ??? name | |
80 | ? ??? enabled | |
81 | ? ??? power | |
82 | ? ? ??? async | |
83 | ? ? [] | |
84 | ? ??? subsystem -> ../../../../../class/power_cap | |
85 | ? ??? enabled | |
86 | ? ??? uevent | |
87 | ??? intel-rapl:1 | |
88 | ? ??? constraint_0_name | |
89 | ? ??? constraint_0_power_limit_uw | |
90 | ? ??? constraint_0_time_window_us | |
91 | ? ??? constraint_1_name | |
92 | ? ??? constraint_1_power_limit_uw | |
93 | ? ??? constraint_1_time_window_us | |
94 | ? ??? device -> ../../intel-rapl | |
95 | ? ??? energy_uj | |
96 | ? ??? intel-rapl:1:0 | |
97 | ? ? ??? constraint_0_name | |
98 | ? ? ??? constraint_0_power_limit_uw | |
99 | ? ? ??? constraint_0_time_window_us | |
100 | ? ? ??? constraint_1_name | |
101 | ? ? ??? constraint_1_power_limit_uw | |
102 | ? ? ??? constraint_1_time_window_us | |
103 | ? ? ??? device -> ../../intel-rapl:1 | |
104 | ? ? ??? energy_uj | |
105 | ? ? ??? max_energy_range_uj | |
106 | ? ? ??? name | |
107 | ? ? ??? enabled | |
108 | ? ? ??? power | |
109 | ? ? ? ??? async | |
110 | ? ? ? [] | |
111 | ? ? ??? subsystem -> ../../../../../../class/power_cap | |
112 | ? ? ??? uevent | |
113 | ? ??? intel-rapl:1:1 | |
114 | ? ? ??? constraint_0_name | |
115 | ? ? ??? constraint_0_power_limit_uw | |
116 | ? ? ??? constraint_0_time_window_us | |
117 | ? ? ??? constraint_1_name | |
118 | ? ? ??? constraint_1_power_limit_uw | |
119 | ? ? ??? constraint_1_time_window_us | |
120 | ? ? ??? device -> ../../intel-rapl:1 | |
121 | ? ? ??? energy_uj | |
122 | ? ? ??? max_energy_range_uj | |
123 | ? ? ??? name | |
124 | ? ? ??? enabled | |
125 | ? ? ??? power | |
126 | ? ? ? ??? async | |
127 | ? ? ? [] | |
128 | ? ? ??? subsystem -> ../../../../../../class/power_cap | |
129 | ? ? ??? uevent | |
130 | ? ??? max_energy_range_uj | |
131 | ? ??? max_power_range_uw | |
132 | ? ??? name | |
133 | ? ??? enabled | |
134 | ? ??? power | |
135 | ? ? ??? async | |
136 | ? ? [] | |
137 | ? ??? subsystem -> ../../../../../class/power_cap | |
138 | ? ??? uevent | |
139 | ??? power | |
140 | ? ??? async | |
141 | ? [] | |
142 | ??? subsystem -> ../../../../class/power_cap | |
143 | ??? enabled | |
144 | ??? uevent | |
145 | ||
146 | The above example illustrates a case in which the Intel RAPL technology, | |
147 | available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one | |
148 | control type called intel-rapl which contains two power zones, intel-rapl:0 and | |
149 | intel-rapl:1, representing CPU packages. Each of these power zones contains | |
150 | two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the | |
151 | "core" and the "uncore" parts of the given CPU package, respectively. All of | |
152 | the zones and subzones contain energy monitoring attributes (energy_uj, | |
153 | max_energy_range_uj) and constraint attributes (constraint_*) allowing controls | |
154 | to be applied (the constraints in the 'package' power zones apply to the whole | |
155 | CPU packages and the subzone constraints only apply to the respective parts of | |
156 | the given package individually). Since Intel RAPL doesn't provide instantaneous | |
157 | power value, there is no power_uw attribute. | |
158 | ||
159 | In addition to that, each power zone contains a name attribute, allowing the | |
160 | part of the system represented by that zone to be identified. | |
161 | For example: | |
162 | ||
163 | cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name | |
164 | package-0 | |
165 | ||
166 | The Intel RAPL technology allows two constraints, short term and long term, | |
167 | with two different time windows to be applied to each power zone. Thus for | |
168 | each zone there are 2 attributes representing the constraint names, 2 power | |
169 | limits and 2 attributes representing the sizes of the time windows. Such that, | |
170 | constraint_j_* attributes correspond to the jth constraint (j = 0,1). | |
171 | ||
172 | For example: | |
173 | constraint_0_name | |
174 | constraint_0_power_limit_uw | |
175 | constraint_0_time_window_us | |
176 | constraint_1_name | |
177 | constraint_1_power_limit_uw | |
178 | constraint_1_time_window_us | |
179 | ||
180 | Power Zone Attributes | |
181 | ================================= | |
182 | Monitoring attributes | |
183 | ---------------------- | |
184 | ||
185 | energy_uj (rw): Current energy counter in micro joules. Write "0" to reset. | |
186 | If the counter can not be reset, then this attribute is read only. | |
187 | ||
188 | max_energy_range_uj (ro): Range of the above energy counter in micro-joules. | |
189 | ||
190 | power_uw (ro): Current power in micro watts. | |
191 | ||
192 | max_power_range_uw (ro): Range of the above power value in micro-watts. | |
193 | ||
194 | name (ro): Name of this power zone. | |
195 | ||
196 | It is possible that some domains have both power ranges and energy counter ranges; | |
197 | however, only one is mandatory. | |
198 | ||
199 | Constraints | |
200 | ---------------- | |
201 | constraint_X_power_limit_uw (rw): Power limit in micro watts, which should be | |
202 | applicable for the time window specified by "constraint_X_time_window_us". | |
203 | ||
204 | constraint_X_time_window_us (rw): Time window in micro seconds. | |
205 | ||
206 | constraint_X_name (ro): An optional name of the constraint | |
207 | ||
208 | constraint_X_max_power_uw(ro): Maximum allowed power in micro watts. | |
209 | ||
210 | constraint_X_min_power_uw(ro): Minimum allowed power in micro watts. | |
211 | ||
212 | constraint_X_max_time_window_us(ro): Maximum allowed time window in micro seconds. | |
213 | ||
214 | constraint_X_min_time_window_us(ro): Minimum allowed time window in micro seconds. | |
215 | ||
216 | Except power_limit_uw and time_window_us other fields are optional. | |
217 | ||
218 | Common zone and control type attributes | |
219 | ---------------------------------------- | |
220 | enabled (rw): Enable/Disable controls at zone level or for all zones using | |
221 | a control type. | |
222 | ||
223 | Power Cap Client Driver Interface | |
224 | ================================== | |
225 | The API summary: | |
226 | ||
227 | Call powercap_register_control_type() to register control type object. | |
228 | Call powercap_register_zone() to register a power zone (under a given | |
229 | control type), either as a top-level power zone or as a subzone of another | |
230 | power zone registered earlier. | |
231 | The number of constraints in a power zone and the corresponding callbacks have | |
232 | to be defined prior to calling powercap_register_zone() to register that zone. | |
233 | ||
234 | To Free a power zone call powercap_unregister_zone(). | |
235 | To free a control type object call powercap_unregister_control_type(). | |
236 | Detailed API can be generated using kernel-doc on include/linux/powercap.h. |