Documentation/driver-api/thermal/power_allocator.rst

   1 =================================
   2 Power allocator governor tunables
   3 =================================
   4
   5 Trip points
   6 -----------
   7
   8 The governor works optimally with the following two passive trip points:
   9
  10 1.  "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
  14 2.  "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
  19 PID Controller
  20 --------------
  21
  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:
  25
  26     P_max = k_p * e + k_i * err_integral + k_d * diff_err + sustainable_power
  27
  28 where
  29    -  e = desired_temperature - current_temperature
  30    -  err_integral is the sum of previous errors
  31    -  diff_err = e - previous_error
  32
  33 It 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
  60 Sustainable power
  61 -----------------
  62
  63 An estimate of the sustainable dissipatable power (in mW) should be
  64 provided while registering the thermal zone.  This estimates the
  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
  69 variations such as environmental conditions, and some factors related
  70 to the speed-grade of the silicon.  `sustainable_power` is therefore
  71 simply an estimate, and may be tuned to affect the aggressiveness of
  72 the thermal ramp. For reference, the sustainable power of a 4" phone
  73 is typically 2000mW, while on a 10" tablet is around 4500mW (may vary
  74 depending on screen size).
  75
  76 If you are using device tree, do add it as a property of the
  77 thermal-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
  86 Instead, 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
  89 will suffice::
  90
  91         static const struct thermal_zone_params tz_params = {
  92                 .sustainable_power = 3500,
  93         };
  94
  95 and then pass `tz_params` as the 5th parameter to
  96 `thermal_zone_device_register()`
  97
  98 k_po and k_pu
  99 -------------
 100
 101 The implementation of the PID controller in the power allocator
 102 thermal governor allows the configuration of two proportional term
 103 constants: `k_po` and `k_pu`.  `k_po` is the proportional term
 104 constant during temperature overshoot periods (current temperature is
 105 above "desired temperature" trip point).  Conversely, `k_pu` is the
 106 proportional term constant during temperature undershoot periods
 107 (current temperature below "desired temperature" trip point).
 108
 109 These controls are intended as the primary mechanism for configuring
 110 the permitted thermal "ramp" of the system.  For instance, a lower
 111 `k_pu` value will provide a slower ramp, at the cost of capping
 112 available capacity at a low temperature.  On the other hand, a high
 113 value of `k_pu` will result in the governor granting very high power
 114 while temperature is low, and may lead to temperature overshooting.
 115
 116 The default value for `k_pu` is::
 117
 118     2 * sustainable_power / (desired_temperature - switch_on_temp)
 119
 120 This means that at `switch_on_temp` the output of the controller's
 121 proportional term will be 2 * `sustainable_power`.  The default value
 122 for `k_po` is::
 123
 124     sustainable_power / (desired_temperature - switch_on_temp)
 125
 126 Focusing on the proportional and feed forward values of the PID
 127 controller equation we have::
 128
 129     P_max = k_p * e + sustainable_power
 130
 131 The proportional term is proportional to the difference between the
 132 desired temperature and the current one.  When the current temperature
 133 is the desired one, then the proportional component is zero and
 134 `P_max` = `sustainable_power`.  That is, the system should operate in
 135 thermal equilibrium under constant load.  `sustainable_power` is only
 136 an estimate, which is the reason for closed-loop control such as this.
 137
 138 Expanding `k_pu` we get::
 139
 140     P_max = 2 * sustainable_power * (T_set - T) / (T_set - T_on) +
 141         sustainable_power
 142
 143 where:
 144
 145     - T_set is the desired temperature
 146     - T is the current temperature
 147     - T_on is the switch on temperature
 148
 149 When the current temperature is the switch_on temperature, the above
 150 formula 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
 156 Therefore, the proportional term alone linearly decreases power from
 157 3 * `sustainable_power` to `sustainable_power` as the temperature
 158 rises from the switch on temperature to the desired temperature.
 159
 160 k_i and integral_cutoff
 161 -----------------------
 162
 163 `k_i` configures the PID loop's integral term constant.  This term
 164 allows the PID controller to compensate for long term drift and for
 165 the quantized nature of the output control: cooling devices can't set
 166 the exact power that the governor requests.  When the temperature
 167 error is below `integral_cutoff`, errors are accumulated in the
 168 integral term.  This term is then multiplied by `k_i` and the result
 169 added to the output of the controller.  Typically `k_i` is set low (1
 170 or 2) and `integral_cutoff` is 0.
 171
 172 k_d
 173 ---
 174
 175 `k_d` configures the PID loop's derivative term constant.  It's
 176 recommended to leave it as the default: 0.
 177
 178 Cooling device power API
 179 ========================
 180
 181 Cooling devices controlled by this governor must supply the additional
 182 "power" API in their `cooling_device_ops`.  It consists on three ops:
 183
 184 1. ::
 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
 198 in milliwatts and stores it in @power .  It should return 0 on
 199 success, -E* on failure.  This is currently used by the power
 200 allocator governor to calculate how much power to give to each cooling
 201 device.
 202
 203 2. ::
 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
 218 Convert cooling device state @state into power consumption in
 219 milliwatts and store it in @power.  It should return 0 on success, -E*
 220 on failure.  This is currently used by thermal core to calculate the
 221 maximum power that an actor can consume.
 222
 223 3. ::
 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
 235 Calculate a cooling device state that would make the device consume at
 236 most @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
 238 a given power set by the power allocator governor to a state that the
 239 cooling device can set.  It is a function because this conversion may
 240 depend on external factors that may change so this function should the
 241 best conversion given "current circumstances".
 242
 243 Cooling device weights
 244 ----------------------
 245
 246 Weights are a mechanism to bias the allocation among cooling
 247 devices.  They express the relative power efficiency of different
 248 cooling devices.  Higher weight can be used to express higher power
 249 efficiency.  Weighting is relative such that if each cooling device
 250 has a weight of one they are considered equal.  This is particularly
 251 useful in heterogeneous systems where two cooling devices may perform
 252 the same kind of compute, but with different efficiency.  For example,
 253 a system with two different types of processors.
 254
 255 If the thermal zone is registered using
 256 `thermal_zone_device_register()` (i.e., platform code), then weights
 257 are passed as part of the thermal zone's `thermal_bind_parameters`.
 258 If the platform is registered using device tree, then they are passed
 259 as the `contribution` property of each map in the `cooling-maps` node.
 260
 261 Limitations of the power allocator governor
 262 ===========================================
 263
 264 The power allocator governor's PID controller works best if there is a
 265 periodic tick.  If you have a driver that calls
 266 `thermal_zone_device_update()` (or anything that ends up calling the
 267 governor's `throttle()` function) repetitively, the governor response
 268 won't be very good.  Note that this is not particular to this
 269 governor, step-wise will also misbehave if you call its throttle()
 270 faster than the normal thermal framework tick (due to interrupts for
 271 example) as it will overreact.