driver-api/thermal/power_allocator.rst

2 Power allocator governor tunables
6 -----------
10 1.  "switch on" trip point: temperature above which the governor
15     "switch on" trip point.  This the target temperature the governor
20 --------------
22 The power allocator governor implements a
23 Proportional-Integral-Derivative controller (PID controller) with
24 temperature as the control input and power as the controlled output:
29    -  e = desired_temperature - current_temperature
30    -  err_integral is the sum of previous errors
31    -  diff_err = e - previous_error
39        |              +----------+   +---+
40        |       +----->| diff_err |-->| X |------+
41        |       |      +----------+   +---+      |
47      +---+     |      +-------+      +---+    +---+   +---+   +----------+
48      | S |-----+----->| sum e |----->| X |--->| S |-->| S |-->|power     |
49      +---+     |      +-------+      +---+    +---+   +---+   |allocation|
50        ^       |                                ^             +----------+
52        |       |        +---+                   |                |     |
53        |       +------->| X |-------------------+                v     v
54        |                +---+                               granted performance
60 Sustainable power
61 -----------------
63 An estimate of the sustainable dissipatable power (in mW) should be
65 sustained power that can be dissipated at the desired control
66 temperature.  This is the maximum sustained power for allocation at
67 the desired maximum temperature.  The actual sustained power can vary
70 to the speed-grade of the silicon.  `sustainable_power` is therefore
72 the thermal ramp. For reference, the sustainable power of a 4" phone
73 is typically 2000mW, while on a 10" tablet is around 4500mW (may vary
74 depending on screen size). It is possible to have the power value
75 expressed in an abstract scale. The sustained power should be aligned
79 thermal-zone.  For example::
81 	thermal-zones {
83 			polling-delay = <1000>;
84 			polling-delay-passive = <100>;
85 			sustainable-power = <2500>;
101 -------------
103 The implementation of the PID controller in the power allocator
114 available capacity at a low temperature.  On the other hand, a high
115 value of `k_pu` will result in the governor granting very high power
120     2 * sustainable_power / (desired_temperature - switch_on_temp)
126     sustainable_power / (desired_temperature - switch_on_temp)
128 Focusing on the proportional and feed forward values of the PID
138 an estimate, which is the reason for closed-loop control such as this.
142     P_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) +
147     - T_set is the desired temperature
148     - T is the current temperature
149     - T_on is the switch on temperature
154     P_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) +
158 Therefore, the proportional term alone linearly decreases power from
160 rises from the switch on temperature to the desired temperature.
163 -----------------------
168 the exact power that the governor requests.  When the temperature
175 ---
180 Cooling device power API
184 "power" API in their `cooling_device_ops`.  It consists on three ops:
189 			    struct thermal_zone_device *tz, u32 *power);
196 @power:
197 	pointer in which to store the calculated power
199 `get_requested_power()` calculates the power requested by the device
200 in milliwatts and stores it in @power .  It should return 0 on
201 success, -E* on failure.  This is currently used by the power
202 allocator governor to calculate how much power to give to each cooling
209 			u32 *power);
217 @power:
218 	pointer in which to store the equivalent power
220 Convert cooling device state @state into power consumption in
221 milliwatts and store it in @power.  It should return 0 on success, -E*
222 on failure.  This is currently used by thermal core to calculate the
223 maximum power that an actor can consume.
227 	int power2state(struct thermal_cooling_device *cdev, u32 power,
232 @power:
233 	power in milliwatts
238 most @power mW and store it in @state.  It should return 0 on success,
239 -E* on failure.  This is currently used by the thermal core to convert
240 a given power set by the power allocator governor to a state that the
242 depend on external factors that may change so this function should the
246 ----------------------
249 devices.  They express the relative power efficiency of different
250 cooling devices.  Higher weight can be used to express higher power
261 as the `contribution` property of each map in the `cooling-maps` node.
263 Limitations of the power allocator governor
266 The power allocator governor's PID controller works best if there is a
271 governor, step-wise will also misbehave if you call its throttle()
278 Another important thing is the consistent scale of the power values
280 thermal zone should have power values reported either in milli-Watts