tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
PowerCap: Documentation
Added power cap framework documentation. This explains the use of power
capping framework, sysfs and programming interface.
There are two documents:
- Documentation/power/powercap/powercap.txt : Explains use case and APIs.
- Documentation/ABI/testing/sysfs-class-powercap: Explains ABIs.
Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@linux.intel.com>
Signed-off-by: Jacob Pan <jacob.jun.pan@linux.intel.com>
Signed-off-by: Arjan van de Ven <arjan@linux.intel.com>
Reviewed-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Reviewed-by: Len Brown <len.brown@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
authored by
Srinivas Pandruvada
and committed by
Rafael J. Wysocki
e23feb16
61e6cfa8
+388
+152
Documentation/ABI/testing/sysfs-class-powercap
+152
Documentation/ABI/testing/sysfs-class-powercap
···
1
+
What: /sys/class/powercap/
2
+
Date: September 2013
3
+
KernelVersion: 3.13
4
+
Contact: linux-pm@vger.kernel.org
5
+
Description:
6
+
The powercap/ class sub directory belongs to the power cap
7
+
subsystem. Refer to
8
+
Documentation/power/powercap/powercap.txt for details.
9
+
10
+
What: /sys/class/powercap/<control type>
11
+
Date: September 2013
12
+
KernelVersion: 3.13
13
+
Contact: linux-pm@vger.kernel.org
14
+
Description:
15
+
A <control type> is a unique name under /sys/class/powercap.
16
+
Here <control type> determines how the power is going to be
17
+
controlled. A <control type> can contain multiple power zones.
18
+
19
+
What: /sys/class/powercap/<control type>/enabled
20
+
Date: September 2013
21
+
KernelVersion: 3.13
22
+
Contact: linux-pm@vger.kernel.org
23
+
Description:
24
+
This allows to enable/disable power capping for a "control type".
25
+
This status affects every power zone using this "control_type.
26
+
27
+
What: /sys/class/powercap/<control type>/<power zone>
28
+
Date: September 2013
29
+
KernelVersion: 3.13
30
+
Contact: linux-pm@vger.kernel.org
31
+
Description:
32
+
A power zone is a single or a collection of devices, which can
33
+
be independently monitored and controlled. A power zone sysfs
34
+
entry is qualified with the name of the <control type>.
35
+
E.g. intel-rapl:0:1:1.
36
+
37
+
What: /sys/class/powercap/<control type>/<power zone>/<child power zone>
38
+
Date: September 2013
39
+
KernelVersion: 3.13
40
+
Contact: linux-pm@vger.kernel.org
41
+
Description:
42
+
Power zones may be organized in a hierarchy in which child
43
+
power zones provide monitoring and control for a subset of
44
+
devices under the parent. For example, if there is a parent
45
+
power zone for a whole CPU package, each CPU core in it can
46
+
be a child power zone.
47
+
48
+
What: /sys/class/powercap/.../<power zone>/name
49
+
Date: September 2013
50
+
KernelVersion: 3.13
51
+
Contact: linux-pm@vger.kernel.org
52
+
Description:
53
+
Specifies the name of this power zone.
54
+
55
+
What: /sys/class/powercap/.../<power zone>/energy_uj
56
+
Date: September 2013
57
+
KernelVersion: 3.13
58
+
Contact: linux-pm@vger.kernel.org
59
+
Description:
60
+
Current energy counter in micro-joules. Write "0" to reset.
61
+
If the counter can not be reset, then this attribute is
62
+
read-only.
63
+
64
+
What: /sys/class/powercap/.../<power zone>/max_energy_range_uj
65
+
Date: September 2013
66
+
KernelVersion: 3.13
67
+
Contact: linux-pm@vger.kernel.org
68
+
Description:
69
+
Range of the above energy counter in micro-joules.
70
+
71
+
72
+
What: /sys/class/powercap/.../<power zone>/power_uw
73
+
Date: September 2013
74
+
KernelVersion: 3.13
75
+
Contact: linux-pm@vger.kernel.org
76
+
Description:
77
+
Current power in micro-watts.
78
+
79
+
What: /sys/class/powercap/.../<power zone>/max_power_range_uw
80
+
Date: September 2013
81
+
KernelVersion: 3.13
82
+
Contact: linux-pm@vger.kernel.org
83
+
Description:
84
+
Range of the above power value in micro-watts.
85
+
86
+
What: /sys/class/powercap/.../<power zone>/constraint_X_name
87
+
Date: September 2013
88
+
KernelVersion: 3.13
89
+
Contact: linux-pm@vger.kernel.org
90
+
Description:
91
+
Each power zone can define one or more constraints. Each
92
+
constraint can have an optional name. Here "X" can have values
93
+
from 0 to max integer.
94
+
95
+
What: /sys/class/powercap/.../<power zone>/constraint_X_power_limit_uw
96
+
Date: September 2013
97
+
KernelVersion: 3.13
98
+
Contact: linux-pm@vger.kernel.org
99
+
Description:
100
+
Power limit in micro-watts should be applicable for
101
+
the time window specified by "constraint_X_time_window_us".
102
+
Here "X" can have values from 0 to max integer.
103
+
104
+
What: /sys/class/powercap/.../<power zone>/constraint_X_time_window_us
105
+
Date: September 2013
106
+
KernelVersion: 3.13
107
+
Contact: linux-pm@vger.kernel.org
108
+
Description:
109
+
Time window in micro seconds. This is used along with
110
+
constraint_X_power_limit_uw to define a power constraint.
111
+
Here "X" can have values from 0 to max integer.
112
+
113
+
114
+
What: /sys/class/powercap/<control type>/.../constraint_X_max_power_uw
115
+
Date: September 2013
116
+
KernelVersion: 3.13
117
+
Contact: linux-pm@vger.kernel.org
118
+
Description:
119
+
Maximum allowed power in micro watts for this constraint.
120
+
Here "X" can have values from 0 to max integer.
121
+
122
+
What: /sys/class/powercap/<control type>/.../constraint_X_min_power_uw
123
+
Date: September 2013
124
+
KernelVersion: 3.13
125
+
Contact: linux-pm@vger.kernel.org
126
+
Description:
127
+
Minimum allowed power in micro watts for this constraint.
128
+
Here "X" can have values from 0 to max integer.
129
+
130
+
What: /sys/class/powercap/.../<power zone>/constraint_X_max_time_window_us
131
+
Date: September 2013
132
+
KernelVersion: 3.13
133
+
Contact: linux-pm@vger.kernel.org
134
+
Description:
135
+
Maximum allowed time window in micro seconds for this
136
+
constraint. Here "X" can have values from 0 to max integer.
137
+
138
+
What: /sys/class/powercap/.../<power zone>/constraint_X_min_time_window_us
139
+
Date: September 2013
140
+
KernelVersion: 3.13
141
+
Contact: linux-pm@vger.kernel.org
142
+
Description:
143
+
Minimum allowed time window in micro seconds for this
144
+
constraint. Here "X" can have values from 0 to max integer.
145
+
146
+
What: /sys/class/powercap/.../<power zone>/enabled
147
+
Date: September 2013
148
+
KernelVersion: 3.13
149
+
Contact: linux-pm@vger.kernel.org
150
+
Description
151
+
This allows to enable/disable power capping at power zone level.
152
+
This applies to current power zone and its children.
+236
Documentation/power/powercap/powercap.txt
+236
Documentation/power/powercap/powercap.txt
···
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.