summaryrefslogtreecommitdiff
path: root/Documentation/power/powercap
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+samsung@kernel.org>2019-06-13 07:10:36 -0300
committerBjorn Helgaas <bhelgaas@google.com>2019-06-14 16:08:36 -0500
commit151f4e2bdc7a04020ae5c533896fb91a16e1f501 (patch)
tree20c8504f4fea46bf421107074f511fd51acf44fc /Documentation/power/powercap
parent9595aee2a389be5dfa9a0121a14e8fba70f17278 (diff)
docs: power: convert docs to ReST and rename to *.rst
Convert the PM documents to ReST, in order to allow them to build with Sphinx. The conversion is actually: - add blank lines and indentation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Bjorn Helgaas <bhelgaas@google.com> Acked-by: Mark Brown <broonie@kernel.org> Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
Diffstat (limited to 'Documentation/power/powercap')
-rw-r--r--Documentation/power/powercap/powercap.rst257
-rw-r--r--Documentation/power/powercap/powercap.txt236
2 files changed, 257 insertions, 236 deletions
diff --git a/Documentation/power/powercap/powercap.rst b/Documentation/power/powercap/powercap.rst
new file mode 100644
index 000000000000..7ae3b44c7624
--- /dev/null
+++ b/Documentation/power/powercap/powercap.rst
@@ -0,0 +1,257 @@
+=======================
+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.
diff --git a/Documentation/power/powercap/powercap.txt b/Documentation/power/powercap/powercap.txt
deleted file mode 100644
index 1e6ef164e07a..000000000000
--- a/Documentation/power/powercap/powercap.txt
+++ /dev/null
@@ -1,236 +0,0 @@
-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.