1Power allocator governor tunables 2================================= 3 4Trip points 5----------- 6 7The governor works optimally with the following two passive trip points: 8 91. "switch on" trip point: temperature above which the governor 10 control loop starts operating. This is the first passive trip 11 point of the thermal zone. 12 132. "desired temperature" trip point: it should be higher than the 14 "switch on" trip point. This the target temperature the governor 15 is controlling for. This is the last passive trip point of the 16 thermal zone. 17 18PID Controller 19-------------- 20 21The power allocator governor implements a 22Proportional-Integral-Derivative controller (PID controller) with 23temperature as the control input and power as the controlled output: 24 25 P_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_power 26 27where 28 e = desired_temperature - current_temperature 29 err_integral is the sum of previous errors 30 diff_err = e - previous_error 31 32It is similar to the one depicted below: 33 34 k_d 35 | 36current_temp | 37 | v 38 | +----------+ +---+ 39 | +----->| diff_err |-->| X |------+ 40 | | +----------+ +---+ | 41 | | | tdp actor 42 | | k_i | | get_requested_power() 43 | | | | | | | 44 | | | | | | | ... 45 v | v v v v v 46 +---+ | +-------+ +---+ +---+ +---+ +----------+ 47 | S |-------+----->| sum e |----->| X |--->| S |-->| S |-->|power | 48 +---+ | +-------+ +---+ +---+ +---+ |allocation| 49 ^ | ^ +----------+ 50 | | | | | 51 | | +---+ | | | 52 | +------->| X |-------------------+ v v 53 | +---+ granted performance 54desired_temperature ^ 55 | 56 | 57 k_po/k_pu 58 59Sustainable power 60----------------- 61 62An estimate of the sustainable dissipatable power (in mW) should be 63provided while registering the thermal zone. This estimates the 64sustained power that can be dissipated at the desired control 65temperature. This is the maximum sustained power for allocation at 66the desired maximum temperature. The actual sustained power can vary 67for a number of reasons. The closed loop controller will take care of 68variations such as environmental conditions, and some factors related 69to the speed-grade of the silicon. `sustainable_power` is therefore 70simply an estimate, and may be tuned to affect the aggressiveness of 71the thermal ramp. For reference, the sustainable power of a 4" phone 72is typically 2000mW, while on a 10" tablet is around 4500mW (may vary 73depending on screen size). 74 75If you are using device tree, do add it as a property of the 76thermal-zone. For example: 77 78 thermal-zones { 79 soc_thermal { 80 polling-delay = <1000>; 81 polling-delay-passive = <100>; 82 sustainable-power = <2500>; 83 ... 84 85Instead, if the thermal zone is registered from the platform code, pass a 86`thermal_zone_params` that has a `sustainable_power`. If no 87`thermal_zone_params` were being passed, then something like below 88will suffice: 89 90 static const struct thermal_zone_params tz_params = { 91 .sustainable_power = 3500, 92 }; 93 94and then pass `tz_params` as the 5th parameter to 95`thermal_zone_device_register()` 96 97k_po and k_pu 98------------- 99 100The implementation of the PID controller in the power allocator 101thermal governor allows the configuration of two proportional term 102constants: `k_po` and `k_pu`. `k_po` is the proportional term 103constant during temperature overshoot periods (current temperature is 104above "desired temperature" trip point). Conversely, `k_pu` is the 105proportional term constant during temperature undershoot periods 106(current temperature below "desired temperature" trip point). 107 108These controls are intended as the primary mechanism for configuring 109the permitted thermal "ramp" of the system. For instance, a lower 110`k_pu` value will provide a slower ramp, at the cost of capping 111available capacity at a low temperature. On the other hand, a high 112value of `k_pu` will result in the governor granting very high power 113whilst temperature is low, and may lead to temperature overshooting. 114 115The default value for `k_pu` is: 116 117 2 * sustainable_power / (desired_temperature - switch_on_temp) 118 119This means that at `switch_on_temp` the output of the controller's 120proportional term will be 2 * `sustainable_power`. The default value 121for `k_po` is: 122 123 sustainable_power / (desired_temperature - switch_on_temp) 124 125Focusing on the proportional and feed forward values of the PID 126controller equation we have: 127 128 P_max = k_p * e + sustainable_power 129 130The proportional term is proportional to the difference between the 131desired temperature and the current one. When the current temperature 132is the desired one, then the proportional component is zero and 133`P_max` = `sustainable_power`. That is, the system should operate in 134thermal equilibrium under constant load. `sustainable_power` is only 135an estimate, which is the reason for closed-loop control such as this. 136 137Expanding `k_pu` we get: 138 P_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) + 139 sustainable_power 140 141where 142 T_set is the desired temperature 143 T is the current temperature 144 T_on is the switch on temperature 145 146When the current temperature is the switch_on temperature, the above 147formula becomes: 148 149 P_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) + 150 sustainable_power = 2 * sustainable_power + sustainable_power = 151 3 * sustainable_power 152 153Therefore, the proportional term alone linearly decreases power from 1543 * `sustainable_power` to `sustainable_power` as the temperature 155rises from the switch on temperature to the desired temperature. 156 157k_i and integral_cutoff 158----------------------- 159 160`k_i` configures the PID loop's integral term constant. This term 161allows the PID controller to compensate for long term drift and for 162the quantized nature of the output control: cooling devices can't set 163the exact power that the governor requests. When the temperature 164error is below `integral_cutoff`, errors are accumulated in the 165integral term. This term is then multiplied by `k_i` and the result 166added to the output of the controller. Typically `k_i` is set low (1 167or 2) and `integral_cutoff` is 0. 168 169k_d 170--- 171 172`k_d` configures the PID loop's derivative term constant. It's 173recommended to leave it as the default: 0. 174 175Cooling device power API 176======================== 177 178Cooling devices controlled by this governor must supply the additional 179"power" API in their `cooling_device_ops`. It consists on three ops: 180 1811. int get_requested_power(struct thermal_cooling_device *cdev, 182 struct thermal_zone_device *tz, u32 *power); 183@cdev: The `struct thermal_cooling_device` pointer 184@tz: thermal zone in which we are currently operating 185@power: pointer in which to store the calculated power 186 187`get_requested_power()` calculates the power requested by the device 188in milliwatts and stores it in @power . It should return 0 on 189success, -E* on failure. This is currently used by the power 190allocator governor to calculate how much power to give to each cooling 191device. 192 1932. int state2power(struct thermal_cooling_device *cdev, struct 194 thermal_zone_device *tz, unsigned long state, u32 *power); 195@cdev: The `struct thermal_cooling_device` pointer 196@tz: thermal zone in which we are currently operating 197@state: A cooling device state 198@power: pointer in which to store the equivalent power 199 200Convert cooling device state @state into power consumption in 201milliwatts and store it in @power. It should return 0 on success, -E* 202on failure. This is currently used by thermal core to calculate the 203maximum power that an actor can consume. 204 2053. int power2state(struct thermal_cooling_device *cdev, u32 power, 206 unsigned long *state); 207@cdev: The `struct thermal_cooling_device` pointer 208@power: power in milliwatts 209@state: pointer in which to store the resulting state 210 211Calculate a cooling device state that would make the device consume at 212most @power mW and store it in @state. It should return 0 on success, 213-E* on failure. This is currently used by the thermal core to convert 214a given power set by the power allocator governor to a state that the 215cooling device can set. It is a function because this conversion may 216depend on external factors that may change so this function should the 217best conversion given "current circumstances". 218 219Cooling device weights 220---------------------- 221 222Weights are a mechanism to bias the allocation among cooling 223devices. They express the relative power efficiency of different 224cooling devices. Higher weight can be used to express higher power 225efficiency. Weighting is relative such that if each cooling device 226has a weight of one they are considered equal. This is particularly 227useful in heterogeneous systems where two cooling devices may perform 228the same kind of compute, but with different efficiency. For example, 229a system with two different types of processors. 230 231If the thermal zone is registered using 232`thermal_zone_device_register()` (i.e., platform code), then weights 233are passed as part of the thermal zone's `thermal_bind_parameters`. 234If the platform is registered using device tree, then they are passed 235as the `contribution` property of each map in the `cooling-maps` node. 236 237Limitations of the power allocator governor 238=========================================== 239 240The power allocator governor's PID controller works best if there is a 241periodic tick. If you have a driver that calls 242`thermal_zone_device_update()` (or anything that ends up calling the 243governor's `throttle()` function) repetitively, the governor response 244won't be very good. Note that this is not particular to this 245governor, step-wise will also misbehave if you call its throttle() 246faster than the normal thermal framework tick (due to interrupts for 247example) as it will overreact. 248