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>
This commit is contained in:
Srinivas Pandruvada
Rafael J. Wysocki
parent
61e6cfa80d
commit
e23feb1668
2 changed files with 388 additions and 0 deletions
152
Documentation/ABI/testing/sysfs-class-powercap
Normal file
152
Documentation/ABI/testing/sysfs-class-powercap
Normal file
|
|
@ -0,0 +1,152 @@
|
|||
What: /sys/class/powercap/
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
The powercap/ class sub directory belongs to the power cap
|
||||
subsystem. Refer to
|
||||
Documentation/power/powercap/powercap.txt for details.
|
||||
|
||||
What: /sys/class/powercap/<control type>
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
A <control type> is a unique name under /sys/class/powercap.
|
||||
Here <control type> determines how the power is going to be
|
||||
controlled. A <control type> can contain multiple power zones.
|
||||
|
||||
What: /sys/class/powercap/<control type>/enabled
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
This allows to enable/disable power capping for a "control type".
|
||||
This status affects every power zone using this "control_type.
|
||||
|
||||
What: /sys/class/powercap/<control type>/<power zone>
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
A power zone is a single or a collection of devices, which can
|
||||
be independently monitored and controlled. A power zone sysfs
|
||||
entry is qualified with the name of the <control type>.
|
||||
E.g. intel-rapl:0:1:1.
|
||||
|
||||
What: /sys/class/powercap/<control type>/<power zone>/<child power zone>
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Power zones may be organized in a hierarchy in which child
|
||||
power zones provide monitoring and control for a subset of
|
||||
devices under the parent. For example, if there is a parent
|
||||
power zone for a whole CPU package, each CPU core in it can
|
||||
be a child power zone.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/name
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Specifies the name of this power zone.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/energy_uj
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Current energy counter in micro-joules. Write "0" to reset.
|
||||
If the counter can not be reset, then this attribute is
|
||||
read-only.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/max_energy_range_uj
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Range of the above energy counter in micro-joules.
|
||||
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/power_uw
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Current power in micro-watts.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/max_power_range_uw
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Range of the above power value in micro-watts.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/constraint_X_name
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Each power zone can define one or more constraints. Each
|
||||
constraint can have an optional name. Here "X" can have values
|
||||
from 0 to max integer.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/constraint_X_power_limit_uw
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Power limit in micro-watts should be applicable for
|
||||
the time window specified by "constraint_X_time_window_us".
|
||||
Here "X" can have values from 0 to max integer.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/constraint_X_time_window_us
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Time window in micro seconds. This is used along with
|
||||
constraint_X_power_limit_uw to define a power constraint.
|
||||
Here "X" can have values from 0 to max integer.
|
||||
|
||||
|
||||
What: /sys/class/powercap/<control type>/.../constraint_X_max_power_uw
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Maximum allowed power in micro watts for this constraint.
|
||||
Here "X" can have values from 0 to max integer.
|
||||
|
||||
What: /sys/class/powercap/<control type>/.../constraint_X_min_power_uw
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Minimum allowed power in micro watts for this constraint.
|
||||
Here "X" can have values from 0 to max integer.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/constraint_X_max_time_window_us
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Maximum allowed time window in micro seconds for this
|
||||
constraint. Here "X" can have values from 0 to max integer.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/constraint_X_min_time_window_us
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description:
|
||||
Minimum allowed time window in micro seconds for this
|
||||
constraint. Here "X" can have values from 0 to max integer.
|
||||
|
||||
What: /sys/class/powercap/.../<power zone>/enabled
|
||||
Date: September 2013
|
||||
KernelVersion: 3.13
|
||||
Contact: linux-pm@vger.kernel.org
|
||||
Description
|
||||
This allows to enable/disable power capping at power zone level.
|
||||
This applies to current power zone and its children.
|
||||
236
Documentation/power/powercap/powercap.txt
Normal file
236
Documentation/power/powercap/powercap.txt
Normal file
|
|
@ -0,0 +1,236 @@
|
|||
Power Capping Framework
|
||||
==================================
|
||||
|
||||
The power capping framework provides a consistent interface between the kernel
|
||||
and the user space that allows power capping drivers to expose the settings to
|
||||
user space in a uniform way.
|
||||
|
||||
Terminology
|
||||
=========================
|
||||
The framework exposes power capping devices to user space via sysfs in the
|
||||
form of a tree of objects. The objects at the root level of the tree represent
|
||||
'control types', which correspond to different methods of power capping. For
|
||||
example, the intel-rapl control type represents the Intel "Running Average
|
||||
Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
|
||||
corresponds to the use of idle injection for controlling power.
|
||||
|
||||
Power zones represent different parts of the system, which can be controlled and
|
||||
monitored using the power capping method determined by the control type the
|
||||
given zone belongs to. They each contain attributes for monitoring power, as
|
||||
well as controls represented in the form of power constraints. If the parts of
|
||||
the system represented by different power zones are hierarchical (that is, one
|
||||
bigger part consists of multiple smaller parts that each have their own power
|
||||
controls), those power zones may also be organized in a hierarchy with one
|
||||
parent power zone containing multiple subzones and so on to reflect the power
|
||||
control topology of the system. In that case, it is possible to apply power
|
||||
capping to a set of devices together using the parent power zone and if more
|
||||
fine grained control is required, it can be applied through the subzones.
|
||||
|
||||
|
||||
Example sysfs interface tree:
|
||||
|
||||
/sys/devices/virtual/powercap
|
||||
??? intel-rapl
|
||||
??? intel-rapl:0
|
||||
? ??? constraint_0_name
|
||||
? ??? constraint_0_power_limit_uw
|
||||
? ??? constraint_0_time_window_us
|
||||
? ??? constraint_1_name
|
||||
? ??? constraint_1_power_limit_uw
|
||||
? ??? constraint_1_time_window_us
|
||||
? ??? device -> ../../intel-rapl
|
||||
? ??? energy_uj
|
||||
? ??? intel-rapl:0:0
|
||||
? ? ??? constraint_0_name
|
||||
? ? ??? constraint_0_power_limit_uw
|
||||
? ? ??? constraint_0_time_window_us
|
||||
? ? ??? constraint_1_name
|
||||
? ? ??? constraint_1_power_limit_uw
|
||||
? ? ??? constraint_1_time_window_us
|
||||
? ? ??? device -> ../../intel-rapl:0
|
||||
? ? ??? energy_uj
|
||||
? ? ??? max_energy_range_uj
|
||||
? ? ??? name
|
||||
? ? ??? enabled
|
||||
? ? ??? power
|
||||
? ? ? ??? async
|
||||
? ? ? []
|
||||
? ? ??? subsystem -> ../../../../../../class/power_cap
|
||||
? ? ??? uevent
|
||||
? ??? intel-rapl:0:1
|
||||
? ? ??? constraint_0_name
|
||||
? ? ??? constraint_0_power_limit_uw
|
||||
? ? ??? constraint_0_time_window_us
|
||||
? ? ??? constraint_1_name
|
||||
? ? ??? constraint_1_power_limit_uw
|
||||
? ? ??? constraint_1_time_window_us
|
||||
? ? ??? device -> ../../intel-rapl:0
|
||||
? ? ??? energy_uj
|
||||
? ? ??? max_energy_range_uj
|
||||
? ? ??? name
|
||||
? ? ??? enabled
|
||||
? ? ??? power
|
||||
? ? ? ??? async
|
||||
? ? ? []
|
||||
? ? ??? subsystem -> ../../../../../../class/power_cap
|
||||
? ? ??? uevent
|
||||
? ??? max_energy_range_uj
|
||||
? ??? max_power_range_uw
|
||||
? ??? name
|
||||
? ??? enabled
|
||||
? ??? power
|
||||
? ? ??? async
|
||||
? ? []
|
||||
? ??? subsystem -> ../../../../../class/power_cap
|
||||
? ??? enabled
|
||||
? ??? uevent
|
||||
??? intel-rapl:1
|
||||
? ??? constraint_0_name
|
||||
? ??? constraint_0_power_limit_uw
|
||||
? ??? constraint_0_time_window_us
|
||||
? ??? constraint_1_name
|
||||
? ??? constraint_1_power_limit_uw
|
||||
? ??? constraint_1_time_window_us
|
||||
? ??? device -> ../../intel-rapl
|
||||
? ??? energy_uj
|
||||
? ??? intel-rapl:1:0
|
||||
? ? ??? constraint_0_name
|
||||
? ? ??? constraint_0_power_limit_uw
|
||||
? ? ??? constraint_0_time_window_us
|
||||
? ? ??? constraint_1_name
|
||||
? ? ??? constraint_1_power_limit_uw
|
||||
? ? ??? constraint_1_time_window_us
|
||||
? ? ??? device -> ../../intel-rapl:1
|
||||
? ? ??? energy_uj
|
||||
? ? ??? max_energy_range_uj
|
||||
? ? ??? name
|
||||
? ? ??? enabled
|
||||
? ? ??? power
|
||||
? ? ? ??? async
|
||||
? ? ? []
|
||||
? ? ??? subsystem -> ../../../../../../class/power_cap
|
||||
? ? ??? uevent
|
||||
? ??? intel-rapl:1:1
|
||||
? ? ??? constraint_0_name
|
||||
? ? ??? constraint_0_power_limit_uw
|
||||
? ? ??? constraint_0_time_window_us
|
||||
? ? ??? constraint_1_name
|
||||
? ? ??? constraint_1_power_limit_uw
|
||||
? ? ??? constraint_1_time_window_us
|
||||
? ? ??? device -> ../../intel-rapl:1
|
||||
? ? ??? energy_uj
|
||||
? ? ??? max_energy_range_uj
|
||||
? ? ??? name
|
||||
? ? ??? enabled
|
||||
? ? ??? power
|
||||
? ? ? ??? async
|
||||
? ? ? []
|
||||
? ? ??? subsystem -> ../../../../../../class/power_cap
|
||||
? ? ??? uevent
|
||||
? ??? max_energy_range_uj
|
||||
? ??? max_power_range_uw
|
||||
? ??? name
|
||||
? ??? enabled
|
||||
? ??? power
|
||||
? ? ??? async
|
||||
? ? []
|
||||
? ??? subsystem -> ../../../../../class/power_cap
|
||||
? ??? uevent
|
||||
??? power
|
||||
? ??? async
|
||||
? []
|
||||
??? subsystem -> ../../../../class/power_cap
|
||||
??? enabled
|
||||
??? uevent
|
||||
|
||||
The above example illustrates a case in which the Intel RAPL technology,
|
||||
available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
|
||||
control type called intel-rapl which contains two power zones, intel-rapl:0 and
|
||||
intel-rapl:1, representing CPU packages. Each of these power zones contains
|
||||
two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
|
||||
"core" and the "uncore" parts of the given CPU package, respectively. All of
|
||||
the zones and subzones contain energy monitoring attributes (energy_uj,
|
||||
max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
|
||||
to be applied (the constraints in the 'package' power zones apply to the whole
|
||||
CPU packages and the subzone constraints only apply to the respective parts of
|
||||
the given package individually). Since Intel RAPL doesn't provide instantaneous
|
||||
power value, there is no power_uw attribute.
|
||||
|
||||
In addition to that, each power zone contains a name attribute, allowing the
|
||||
part of the system represented by that zone to be identified.
|
||||
For example:
|
||||
|
||||
cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
|
||||
package-0
|
||||
|
||||
The Intel RAPL technology allows two constraints, short term and long term,
|
||||
with two different time windows to be applied to each power zone. Thus for
|
||||
each zone there are 2 attributes representing the constraint names, 2 power
|
||||
limits and 2 attributes representing the sizes of the time windows. Such that,
|
||||
constraint_j_* attributes correspond to the jth constraint (j = 0,1).
|
||||
|
||||
For example:
|
||||
constraint_0_name
|
||||
constraint_0_power_limit_uw
|
||||
constraint_0_time_window_us
|
||||
constraint_1_name
|
||||
constraint_1_power_limit_uw
|
||||
constraint_1_time_window_us
|
||||
|
||||
Power Zone Attributes
|
||||
=================================
|
||||
Monitoring attributes
|
||||
----------------------
|
||||
|
||||
energy_uj (rw): Current energy counter in micro joules. Write "0" to reset.
|
||||
If the counter can not be reset, then this attribute is read only.
|
||||
|
||||
max_energy_range_uj (ro): Range of the above energy counter in micro-joules.
|
||||
|
||||
power_uw (ro): Current power in micro watts.
|
||||
|
||||
max_power_range_uw (ro): Range of the above power value in micro-watts.
|
||||
|
||||
name (ro): Name of this power zone.
|
||||
|
||||
It is possible that some domains have both power ranges and energy counter ranges;
|
||||
however, only one is mandatory.
|
||||
|
||||
Constraints
|
||||
----------------
|
||||
constraint_X_power_limit_uw (rw): Power limit in micro watts, which should be
|
||||
applicable for the time window specified by "constraint_X_time_window_us".
|
||||
|
||||
constraint_X_time_window_us (rw): Time window in micro seconds.
|
||||
|
||||
constraint_X_name (ro): An optional name of the constraint
|
||||
|
||||
constraint_X_max_power_uw(ro): Maximum allowed power in micro watts.
|
||||
|
||||
constraint_X_min_power_uw(ro): Minimum allowed power in micro watts.
|
||||
|
||||
constraint_X_max_time_window_us(ro): Maximum allowed time window in micro seconds.
|
||||
|
||||
constraint_X_min_time_window_us(ro): Minimum allowed time window in micro seconds.
|
||||
|
||||
Except power_limit_uw and time_window_us other fields are optional.
|
||||
|
||||
Common zone and control type attributes
|
||||
----------------------------------------
|
||||
enabled (rw): Enable/Disable controls at zone level or for all zones using
|
||||
a control type.
|
||||
|
||||
Power Cap Client Driver Interface
|
||||
==================================
|
||||
The API summary:
|
||||
|
||||
Call powercap_register_control_type() to register control type object.
|
||||
Call powercap_register_zone() to register a power zone (under a given
|
||||
control type), either as a top-level power zone or as a subzone of another
|
||||
power zone registered earlier.
|
||||
The number of constraints in a power zone and the corresponding callbacks have
|
||||
to be defined prior to calling powercap_register_zone() to register that zone.
|
||||
|
||||
To Free a power zone call powercap_unregister_zone().
|
||||
To free a control type object call powercap_unregister_control_type().
|
||||
Detailed API can be generated using kernel-doc on include/linux/powercap.h.
|
||||
Loading…
Reference in a new issue