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