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