Documentation: thermal docbook: introduce governor chapter
In this patch we add a chapter in the thermal docbook to
describe the existing governors. The chapter contains
one section per governor.
Each governor description includes the respective code documentation.
Each governor section contains a description of the governor
logic.
Signed-off-by: Eduardo Valentin <edubezval@gmail.com>
diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
index 47e6413..d96cd20c 100644
--- a/Documentation/DocBook/thermal.tmpl
+++ b/Documentation/DocBook/thermal.tmpl
@@ -212,6 +212,73 @@
</glossary>
</sect1>
</chapter>
+
+ <chapter id="governors">
+ <title>Thermal Governors</title>
+ <para>
+ </para>
+
+ <sect1 id="step_wise">
+ <title>step_wise Thermal Governor</title>
+ <para>Step Wise uses the trend of the thermal zone to
+ throttle. If the thermal zone is 'heating up' this
+ throttles all the cooling devices associated with the
+ zone and its particular trip point, by one step. If the
+ zone is 'cooling down' it brings back the performance
+ of the devices by one step.
+ </para>
+!Idrivers/thermal/step_wise.c
+!Pdrivers/thermal/step_wise.c Algorithm
+ </sect1>
+ <sect1 id="fair_share">
+ <title>fair_share Thermal Governor</title>
+ <para>Fair Share Governor uses three parameters to
+ calculate the new throttle state of the cooling devices
+ associated with the given zone. Parameters used for
+ Throttling:
+ </para>
+ <itemizedlist mark='opencircle'>
+ <listitem>P1. max_state: Maximum throttle state
+ exposed by the cooling device.</listitem>
+ <listitem>P2. weight[i]/100:</listitem>
+ <listitem>How 'effective' the 'i'th device is,
+ in cooling the given zone.</listitem>
+ <listitem>P3.
+ cur_trip_level/max_no_of_trips:</listitem>
+ </itemizedlist>
+ <para>This describes the extent to which the devices
+ should be throttled. We do not want to throttle too
+ much when we trip a lower temperature, whereas the
+ throttling is at full swing if we trip critical levels.
+ Heavily assumes the trip points are in ascending order
+ new_state of cooling device = P3 * P2 * P1.
+ </para>
+!Idrivers/thermal/fair_share.c
+ </sect1>
+ <sect1 id="bang_bang">
+ <title>bang_bang Thermal Governor</title>
+ <para>The Bang Bang Governor has a two point regulation
+ logic, deliver cooling state depending on the previous
+ state shown in this diagram: </para>
+ <para>If the fan is not running and temperature exceeds
+ trip_temp, the fan gets turned on. In case the fan is
+ running, temperature must fall below (trip_temp - hyst)
+ so that the fan gets turned off again.
+ </para>
+!Idrivers/thermal/gov_bang_bang.c
+ </sect1>
+ <sect1 id="user_space">
+ <title>user_space Thermal Governor</title>
+ <para> The User Space governor is outside the Kernel.
+ The Thermal Framework hands off the entire control to
+ userland if the User Space governor is assigned to a
+ thermal zone. A KOBJ_CHANGE UEvent notification is sent
+ to userland whenever a governor needs to take an
+ action.
+ </para>
+!Idrivers/thermal/user_space.c
+ </sect1>
+ </chapter>
<chapter id="api">
<title>Thermal Device Driver Writer API reference</title>
<para> This Chapter contains an API reference for Thermal driver writers.
