driver-api/thermal/power_allocator.rst

2 Power allocator governor tunables
6 -----------
19 PID Controller
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
68 for a number of reasons.  The closed loop controller will take care of
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
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
115 value of `k_pu` will result in the governor granting very high power
120     2 * sustainable_power / (desired_temperature - switch_on_temp)
122 This means that at `switch_on_temp` the output of the controller's
126     sustainable_power / (desired_temperature - switch_on_temp)
129 controller equation we have::
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
163 -----------------------
166 allows the PID controller to compensate for long term drift and for
168 the exact power that the governor requests.  When the temperature
171 added to the output of the controller.  Typically `k_i` is set low (1
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*
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
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