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). It is possible to have the power value 75expressed in an abstract scale. The sustained power should be aligned 76to the scale used by the related cooling devices. 77 78If you are using device tree, do add it as a property of the 79thermal-zone. For example:: 80 81 thermal-zones { 82 soc_thermal { 83 polling-delay = <1000>; 84 polling-delay-passive = <100>; 85 sustainable-power = <2500>; 86 ... 87 88Instead, if the thermal zone is registered from the platform code, pass a 89`thermal_zone_params` that has a `sustainable_power`. If no 90`thermal_zone_params` were being passed, then something like below 91will suffice:: 92 93 static const struct thermal_zone_params tz_params = { 94 .sustainable_power = 3500, 95 }; 96 97and then pass `tz_params` as the 5th parameter to 98`thermal_zone_device_register()` 99 100k_po and k_pu 101------------- 102 103The implementation of the PID controller in the power allocator 104thermal governor allows the configuration of two proportional term 105constants: `k_po` and `k_pu`. `k_po` is the proportional term 106constant during temperature overshoot periods (current temperature is 107above "desired temperature" trip point). Conversely, `k_pu` is the 108proportional term constant during temperature undershoot periods 109(current temperature below "desired temperature" trip point). 110 111These controls are intended as the primary mechanism for configuring 112the permitted thermal "ramp" of the system. For instance, a lower 113`k_pu` value will provide a slower ramp, at the cost of capping 114available capacity at a low temperature. On the other hand, a high 115value of `k_pu` will result in the governor granting very high power 116while temperature is low, and may lead to temperature overshooting. 117 118The default value for `k_pu` is:: 119 120 2 * sustainable_power / (desired_temperature - switch_on_temp) 121 122This means that at `switch_on_temp` the output of the controller's 123proportional term will be 2 * `sustainable_power`. The default value 124for `k_po` is:: 125 126 sustainable_power / (desired_temperature - switch_on_temp) 127 128Focusing on the proportional and feed forward values of the PID 129controller equation we have:: 130 131 P_max = k_p * e + sustainable_power 132 133The proportional term is proportional to the difference between the 134desired temperature and the current one. When the current temperature 135is the desired one, then the proportional component is zero and 136`P_max` = `sustainable_power`. That is, the system should operate in 137thermal equilibrium under constant load. `sustainable_power` is only 138an estimate, which is the reason for closed-loop control such as this. 139 140Expanding `k_pu` we get:: 141 142 P_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) + 143 sustainable_power 144 145where: 146 147 - T_set is the desired temperature 148 - T is the current temperature 149 - T_on is the switch on temperature 150 151When the current temperature is the switch_on temperature, the above 152formula becomes:: 153 154 P_max = 2 * sustainable_power * (T_set - T_on) / (T_set - T_on) + 155 sustainable_power = 2 * sustainable_power + sustainable_power = 156 3 * sustainable_power 157 158Therefore, the proportional term alone linearly decreases power from 1593 * `sustainable_power` to `sustainable_power` as the temperature 160rises from the switch on temperature to the desired temperature. 161 162k_i and integral_cutoff 163----------------------- 164 165`k_i` configures the PID loop's integral term constant. This term 166allows the PID controller to compensate for long term drift and for 167the quantized nature of the output control: cooling devices can't set 168the exact power that the governor requests. When the temperature 169error is below `integral_cutoff`, errors are accumulated in the 170integral term. This term is then multiplied by `k_i` and the result 171added to the output of the controller. Typically `k_i` is set low (1 172or 2) and `integral_cutoff` is 0. 173 174k_d 175--- 176 177`k_d` configures the PID loop's derivative term constant. It's 178recommended to leave it as the default: 0. 179 180Cooling device power API 181======================== 182 183Cooling devices controlled by this governor must supply the additional 184"power" API in their `cooling_device_ops`. It consists on three ops: 185 1861. :: 187 188 int get_requested_power(struct thermal_cooling_device *cdev, 189 struct thermal_zone_device *tz, u32 *power); 190 191 192@cdev: 193 The `struct thermal_cooling_device` pointer 194@tz: 195 thermal zone in which we are currently operating 196@power: 197 pointer in which to store the calculated power 198 199`get_requested_power()` calculates the power requested by the device 200in milliwatts and stores it in @power . It should return 0 on 201success, -E* on failure. This is currently used by the power 202allocator governor to calculate how much power to give to each cooling 203device. 204 2052. :: 206 207 int state2power(struct thermal_cooling_device *cdev, struct 208 thermal_zone_device *tz, unsigned long state, 209 u32 *power); 210 211@cdev: 212 The `struct thermal_cooling_device` pointer 213@tz: 214 thermal zone in which we are currently operating 215@state: 216 A cooling device state 217@power: 218 pointer in which to store the equivalent power 219 220Convert cooling device state @state into power consumption in 221milliwatts and store it in @power. It should return 0 on success, -E* 222on failure. This is currently used by thermal core to calculate the 223maximum power that an actor can consume. 224 2253. :: 226 227 int power2state(struct thermal_cooling_device *cdev, u32 power, 228 unsigned long *state); 229 230@cdev: 231 The `struct thermal_cooling_device` pointer 232@power: 233 power in milliwatts 234@state: 235 pointer in which to store the resulting state 236 237Calculate a cooling device state that would make the device consume at 238most @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 240a given power set by the power allocator governor to a state that the 241cooling device can set. It is a function because this conversion may 242depend on external factors that may change so this function should the 243best conversion given "current circumstances". 244 245Cooling device weights 246---------------------- 247 248Weights are a mechanism to bias the allocation among cooling 249devices. They express the relative power efficiency of different 250cooling devices. Higher weight can be used to express higher power 251efficiency. Weighting is relative such that if each cooling device 252has a weight of one they are considered equal. This is particularly 253useful in heterogeneous systems where two cooling devices may perform 254the same kind of compute, but with different efficiency. For example, 255a system with two different types of processors. 256 257If the thermal zone is registered using 258`thermal_zone_device_register()` (i.e., platform code), then weights 259are passed as part of the thermal zone's `thermal_bind_parameters`. 260If the platform is registered using device tree, then they are passed 261as the `contribution` property of each map in the `cooling-maps` node. 262 263Limitations of the power allocator governor 264=========================================== 265 266The power allocator governor's PID controller works best if there is a 267periodic tick. If you have a driver that calls 268`thermal_zone_device_update()` (or anything that ends up calling the 269governor's `throttle()` function) repetitively, the governor response 270won't be very good. Note that this is not particular to this 271governor, step-wise will also misbehave if you call its throttle() 272faster than the normal thermal framework tick (due to interrupts for 273example) as it will overreact. 274 275Energy Model requirements 276========================= 277 278Another important thing is the consistent scale of the power values 279provided by the cooling devices. All of the cooling devices in a single 280thermal zone should have power values reported either in milli-Watts 281or scaled to the same 'abstract scale'. 282