About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / power / powercap / powercap.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog