PowerCap: Documentation (e23feb16) · Commits · 戴 / test

Documentation/ABI/testing/sysfs-class-powercap

0 → 100644

+152 −0

Original line number	Diff line number	Diff line
		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.

Documentation/power/powercap/powercap.txt

0 → 100644

+236 −0

Original line number	Diff line number	Diff line
		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.

Admin message