[PATCH v2 1/6] PowerCap: Documentation

From: Srinivas Pandruvada
Date: Fri Oct 04 2013 - 12:40:30 EST


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.

Reviewed-by: Rafael J. Wysocki <rafael.j.wysocki@xxxxxxxxx>
Reviewed-by: Len Brown <len.brown@xxxxxxxxx>
Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx>
Signed-off-by: Jacob Pan <jacob.jun.pan@xxxxxxxxxxxxxxx>
Signed-off-by: Arjan van de Ven <arjan@xxxxxxxxxxxxxxx>
---
Documentation/ABI/testing/sysfs-class-powercap | 152 ++++++++++++++++
Documentation/power/powercap/powercap.txt | 236 +++++++++++++++++++++++++
2 files changed, 388 insertions(+)
create mode 100644 Documentation/ABI/testing/sysfs-class-powercap
create mode 100644 Documentation/power/powercap/powercap.txt

diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
new file mode 100644
index 0000000..db3b3ff
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-powercap
@@ -0,0 +1,152 @@
+What: /sys/class/powercap/
+Date: September 2013
+KernelVersion: 3.13
+Contact: linux-pm@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+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@xxxxxxxxxxxxxxx
+Description
+ This allows to enable/disable power capping at power zone level.
+ This applies to current power zone and its children.
diff --git a/Documentation/power/powercap/powercap.txt b/Documentation/power/powercap/powercap.txt
new file mode 100644
index 0000000..8d83bb3
--- /dev/null
+++ b/Documentation/power/powercap/powercap.txt
@@ -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.
--
1.8.3.1

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/