diff options
Diffstat (limited to 'Documentation/power/powercap/powercap.txt')
| -rw-r--r-- | Documentation/power/powercap/powercap.txt | 236 |
1 files changed, 0 insertions, 236 deletions
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. |