263 lines · plain
1=======================2Power Capping Framework3=======================4 5The power capping framework provides a consistent interface between the kernel6and the user space that allows power capping drivers to expose the settings to7user space in a uniform way.8 9Terminology10===========11 12The framework exposes power capping devices to user space via sysfs in the13form of a tree of objects. The objects at the root level of the tree represent14'control types', which correspond to different methods of power capping. For15example, the intel-rapl control type represents the Intel "Running Average16Power Limit" (RAPL) technology, whereas the 'idle-injection' control type17corresponds to the use of idle injection for controlling power.18 19Power zones represent different parts of the system, which can be controlled and20monitored using the power capping method determined by the control type the21given zone belongs to. They each contain attributes for monitoring power, as22well as controls represented in the form of power constraints. If the parts of23the system represented by different power zones are hierarchical (that is, one24bigger part consists of multiple smaller parts that each have their own power25controls), those power zones may also be organized in a hierarchy with one26parent power zone containing multiple subzones and so on to reflect the power27control topology of the system. In that case, it is possible to apply power28capping to a set of devices together using the parent power zone and if more29fine grained control is required, it can be applied through the subzones.30 31 32Example sysfs interface tree::33 34 /sys/devices/virtual/powercap35 └──intel-rapl36 ├──intel-rapl:037 │ ├──constraint_0_name38 │ ├──constraint_0_power_limit_uw39 │ ├──constraint_0_time_window_us40 │ ├──constraint_1_name41 │ ├──constraint_1_power_limit_uw42 │ ├──constraint_1_time_window_us43 │ ├──device -> ../../intel-rapl44 │ ├──energy_uj45 │ ├──intel-rapl:0:046 │ │ ├──constraint_0_name47 │ │ ├──constraint_0_power_limit_uw48 │ │ ├──constraint_0_time_window_us49 │ │ ├──constraint_1_name50 │ │ ├──constraint_1_power_limit_uw51 │ │ ├──constraint_1_time_window_us52 │ │ ├──device -> ../../intel-rapl:053 │ │ ├──energy_uj54 │ │ ├──max_energy_range_uj55 │ │ ├──name56 │ │ ├──enabled57 │ │ ├──power58 │ │ │ ├──async59 │ │ │ []60 │ │ ├──subsystem -> ../../../../../../class/power_cap61 │ │ └──uevent62 │ ├──intel-rapl:0:163 │ │ ├──constraint_0_name64 │ │ ├──constraint_0_power_limit_uw65 │ │ ├──constraint_0_time_window_us66 │ │ ├──constraint_1_name67 │ │ ├──constraint_1_power_limit_uw68 │ │ ├──constraint_1_time_window_us69 │ │ ├──device -> ../../intel-rapl:070 │ │ ├──energy_uj71 │ │ ├──max_energy_range_uj72 │ │ ├──name73 │ │ ├──enabled74 │ │ ├──power75 │ │ │ ├──async76 │ │ │ []77 │ │ ├──subsystem -> ../../../../../../class/power_cap78 │ │ └──uevent79 │ ├──max_energy_range_uj80 │ ├──max_power_range_uw81 │ ├──name82 │ ├──enabled83 │ ├──power84 │ │ ├──async85 │ │ []86 │ ├──subsystem -> ../../../../../class/power_cap87 │ ├──enabled88 │ ├──uevent89 ├──intel-rapl:190 │ ├──constraint_0_name91 │ ├──constraint_0_power_limit_uw92 │ ├──constraint_0_time_window_us93 │ ├──constraint_1_name94 │ ├──constraint_1_power_limit_uw95 │ ├──constraint_1_time_window_us96 │ ├──device -> ../../intel-rapl97 │ ├──energy_uj98 │ ├──intel-rapl:1:099 │ │ ├──constraint_0_name100 │ │ ├──constraint_0_power_limit_uw101 │ │ ├──constraint_0_time_window_us102 │ │ ├──constraint_1_name103 │ │ ├──constraint_1_power_limit_uw104 │ │ ├──constraint_1_time_window_us105 │ │ ├──device -> ../../intel-rapl:1106 │ │ ├──energy_uj107 │ │ ├──max_energy_range_uj108 │ │ ├──name109 │ │ ├──enabled110 │ │ ├──power111 │ │ │ ├──async112 │ │ │ []113 │ │ ├──subsystem -> ../../../../../../class/power_cap114 │ │ └──uevent115 │ ├──intel-rapl:1:1116 │ │ ├──constraint_0_name117 │ │ ├──constraint_0_power_limit_uw118 │ │ ├──constraint_0_time_window_us119 │ │ ├──constraint_1_name120 │ │ ├──constraint_1_power_limit_uw121 │ │ ├──constraint_1_time_window_us122 │ │ ├──device -> ../../intel-rapl:1123 │ │ ├──energy_uj124 │ │ ├──max_energy_range_uj125 │ │ ├──name126 │ │ ├──enabled127 │ │ ├──power128 │ │ │ ├──async129 │ │ │ []130 │ │ ├──subsystem -> ../../../../../../class/power_cap131 │ │ └──uevent132 │ ├──max_energy_range_uj133 │ ├──max_power_range_uw134 │ ├──name135 │ ├──enabled136 │ ├──power137 │ │ ├──async138 │ │ []139 │ ├──subsystem -> ../../../../../class/power_cap140 │ ├──uevent141 ├──power142 │ ├──async143 │ []144 ├──subsystem -> ../../../../class/power_cap145 ├──enabled146 └──uevent147 148The above example illustrates a case in which the Intel RAPL technology,149available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one150control type called intel-rapl which contains two power zones, intel-rapl:0 and151intel-rapl:1, representing CPU packages. Each of these power zones contains152two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the153"core" and the "uncore" parts of the given CPU package, respectively. All of154the zones and subzones contain energy monitoring attributes (energy_uj,155max_energy_range_uj) and constraint attributes (constraint_*) allowing controls156to be applied (the constraints in the 'package' power zones apply to the whole157CPU packages and the subzone constraints only apply to the respective parts of158the given package individually). Since Intel RAPL doesn't provide instantaneous159power value, there is no power_uw attribute.160 161In addition to that, each power zone contains a name attribute, allowing the162part of the system represented by that zone to be identified.163For example::164 165 cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name166 167package-0168---------169 170Depending on different power zones, the Intel RAPL technology allows171one or multiple constraints like short term, long term and peak power,172with different time windows to be applied to each power zone.173All the zones contain attributes representing the constraint names,174power limits and the sizes of the time windows. Note that time window175is not applicable to peak power. Here, constraint_j_* attributes176correspond to the jth constraint (j = 0,1,2).177 178For example::179 180 constraint_0_name181 constraint_0_power_limit_uw182 constraint_0_time_window_us183 constraint_1_name184 constraint_1_power_limit_uw185 constraint_1_time_window_us186 constraint_2_name187 constraint_2_power_limit_uw188 constraint_2_time_window_us189 190Power Zone Attributes191=====================192 193Monitoring attributes194---------------------195 196energy_uj (rw)197 Current energy counter in micro joules. Write "0" to reset.198 If the counter can not be reset, then this attribute is read only.199 200max_energy_range_uj (ro)201 Range of the above energy counter in micro-joules.202 203power_uw (ro)204 Current power in micro watts.205 206max_power_range_uw (ro)207 Range of the above power value in micro-watts.208 209name (ro)210 Name of this power zone.211 212It is possible that some domains have both power ranges and energy counter ranges;213however, only one is mandatory.214 215Constraints216-----------217 218constraint_X_power_limit_uw (rw)219 Power limit in micro watts, which should be applicable for the220 time window specified by "constraint_X_time_window_us".221 222constraint_X_time_window_us (rw)223 Time window in micro seconds.224 225constraint_X_name (ro)226 An optional name of the constraint227 228constraint_X_max_power_uw(ro)229 Maximum allowed power in micro watts.230 231constraint_X_min_power_uw(ro)232 Minimum allowed power in micro watts.233 234constraint_X_max_time_window_us(ro)235 Maximum allowed time window in micro seconds.236 237constraint_X_min_time_window_us(ro)238 Minimum allowed time window in micro seconds.239 240Except power_limit_uw and time_window_us other fields are optional.241 242Common zone and control type attributes243---------------------------------------244 245enabled (rw): Enable/Disable controls at zone level or for all zones using246a control type.247 248Power Cap Client Driver Interface249=================================250 251The API summary:252 253Call powercap_register_control_type() to register control type object.254Call powercap_register_zone() to register a power zone (under a given255control type), either as a top-level power zone or as a subzone of another256power zone registered earlier.257The number of constraints in a power zone and the corresponding callbacks have258to be defined prior to calling powercap_register_zone() to register that zone.259 260To Free a power zone call powercap_unregister_zone().261To free a control type object call powercap_unregister_control_type().262Detailed API can be generated using kernel-doc on include/linux/powercap.h.263