282 lines · plain
1=================================2Power allocator governor tunables3=================================4 5Trip points6-----------7 8The governor works optimally with the following two passive trip points:9 101. "switch on" trip point: temperature above which the governor11 control loop starts operating. This is the first passive trip12 point of the thermal zone.13 142. "desired temperature" trip point: it should be higher than the15 "switch on" trip point. This the target temperature the governor16 is controlling for. This is the last passive trip point of the17 thermal zone.18 19PID Controller20--------------21 22The power allocator governor implements a23Proportional-Integral-Derivative controller (PID controller) with24temperature 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_power27 28where29 - e = desired_temperature - current_temperature30 - err_integral is the sum of previous errors31 - diff_err = e - previous_error32 33It is similar to the one depicted below::34 35 k_d36 |37 current_temp |38 | v39 | +----------+ +---+40 | +----->| diff_err |-->| X |------+41 | | +----------+ +---+ |42 | | | tdp actor43 | | k_i | | get_requested_power()44 | | | | | | |45 | | | | | | | ...46 v | v v v v v47 +---+ | +-------+ +---+ +---+ +---+ +----------+48 | S |-----+----->| sum e |----->| X |--->| S |-->| S |-->|power |49 +---+ | +-------+ +---+ +---+ +---+ |allocation|50 ^ | ^ +----------+51 | | | | |52 | | +---+ | | |53 | +------->| X |-------------------+ v v54 | +---+ granted performance55 desired_temperature ^56 |57 |58 k_po/k_pu59 60Sustainable power61-----------------62 63An estimate of the sustainable dissipatable power (in mW) should be64provided while registering the thermal zone. This estimates the65sustained power that can be dissipated at the desired control66temperature. This is the maximum sustained power for allocation at67the desired maximum temperature. The actual sustained power can vary68for a number of reasons. The closed loop controller will take care of69variations such as environmental conditions, and some factors related70to the speed-grade of the silicon. `sustainable_power` is therefore71simply an estimate, and may be tuned to affect the aggressiveness of72the thermal ramp. For reference, the sustainable power of a 4" phone73is typically 2000mW, while on a 10" tablet is around 4500mW (may vary74depending on screen size). It is possible to have the power value75expressed in an abstract scale. The sustained power should be aligned76to the scale used by the related cooling devices.77 78If you are using device tree, do add it as a property of the79thermal-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 a89`thermal_zone_params` that has a `sustainable_power`. If no90`thermal_zone_params` were being passed, then something like below91will 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 to98`thermal_zone_device_register()`99 100k_po and k_pu101-------------102 103The implementation of the PID controller in the power allocator104thermal governor allows the configuration of two proportional term105constants: `k_po` and `k_pu`. `k_po` is the proportional term106constant during temperature overshoot periods (current temperature is107above "desired temperature" trip point). Conversely, `k_pu` is the108proportional term constant during temperature undershoot periods109(current temperature below "desired temperature" trip point).110 111These controls are intended as the primary mechanism for configuring112the permitted thermal "ramp" of the system. For instance, a lower113`k_pu` value will provide a slower ramp, at the cost of capping114available capacity at a low temperature. On the other hand, a high115value of `k_pu` will result in the governor granting very high power116while 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's123proportional term will be 2 * `sustainable_power`. The default value124for `k_po` is::125 126 sustainable_power / (desired_temperature - switch_on_temp)127 128Focusing on the proportional and feed forward values of the PID129controller equation we have::130 131 P_max = k_p * e + sustainable_power132 133The proportional term is proportional to the difference between the134desired temperature and the current one. When the current temperature135is the desired one, then the proportional component is zero and136`P_max` = `sustainable_power`. That is, the system should operate in137thermal equilibrium under constant load. `sustainable_power` is only138an 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_power144 145where:146 147 - T_set is the desired temperature148 - T is the current temperature149 - T_on is the switch on temperature150 151When the current temperature is the switch_on temperature, the above152formula 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_power157 158Therefore, the proportional term alone linearly decreases power from1593 * `sustainable_power` to `sustainable_power` as the temperature160rises from the switch on temperature to the desired temperature.161 162k_i and integral_cutoff163-----------------------164 165`k_i` configures the PID loop's integral term constant. This term166allows the PID controller to compensate for long term drift and for167the quantized nature of the output control: cooling devices can't set168the exact power that the governor requests. When the temperature169error is below `integral_cutoff`, errors are accumulated in the170integral term. This term is then multiplied by `k_i` and the result171added to the output of the controller. Typically `k_i` is set low (1172or 2) and `integral_cutoff` is 0.173 174k_d175---176 177`k_d` configures the PID loop's derivative term constant. It's178recommended to leave it as the default: 0.179 180Cooling device power API181========================182 183Cooling devices controlled by this governor must supply the additional184"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` pointer194@tz:195 thermal zone in which we are currently operating196@power:197 pointer in which to store the calculated power198 199`get_requested_power()` calculates the power requested by the device200in milliwatts and stores it in @power . It should return 0 on201success, -E* on failure. This is currently used by the power202allocator governor to calculate how much power to give to each cooling203device.204 2052. ::206 207 int state2power(struct thermal_cooling_device *cdev, struct208 thermal_zone_device *tz, unsigned long state,209 u32 *power);210 211@cdev:212 The `struct thermal_cooling_device` pointer213@tz:214 thermal zone in which we are currently operating215@state:216 A cooling device state217@power:218 pointer in which to store the equivalent power219 220Convert cooling device state @state into power consumption in221milliwatts and store it in @power. It should return 0 on success, -E*222on failure. This is currently used by thermal core to calculate the223maximum 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` pointer232@power:233 power in milliwatts234@state:235 pointer in which to store the resulting state236 237Calculate a cooling device state that would make the device consume at238most @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 convert240a given power set by the power allocator governor to a state that the241cooling device can set. It is a function because this conversion may242depend on external factors that may change so this function should the243best conversion given "current circumstances".244 245Cooling device weights246----------------------247 248Weights are a mechanism to bias the allocation among cooling249devices. They express the relative power efficiency of different250cooling devices. Higher weight can be used to express higher power251efficiency. Weighting is relative such that if each cooling device252has a weight of one they are considered equal. This is particularly253useful in heterogeneous systems where two cooling devices may perform254the 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 using258`thermal_zone_device_register()` (i.e., platform code), then weights259are passed as part of the thermal zone's `thermal_bind_parameters`.260If the platform is registered using device tree, then they are passed261as the `contribution` property of each map in the `cooling-maps` node.262 263Limitations of the power allocator governor264===========================================265 266The power allocator governor's PID controller works best if there is a267periodic tick. If you have a driver that calls268`thermal_zone_device_update()` (or anything that ends up calling the269governor's `throttle()` function) repetitively, the governor response270won't be very good. Note that this is not particular to this271governor, step-wise will also misbehave if you call its throttle()272faster than the normal thermal framework tick (due to interrupts for273example) as it will overreact.274 275Energy Model requirements276=========================277 278Another important thing is the consistent scale of the power values279provided by the cooling devices. All of the cooling devices in a single280thermal zone should have power values reported either in milli-Watts281or scaled to the same 'abstract scale'.282