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