Documentation: Add documentation for drivers/intel/dptf chip driver

Signed-off-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Change-Id: I8915ead08a89dcf95fd92983eca5f85b82916dfd
Reviewed-on: https://review.coreboot.org/c/coreboot/+/43533
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Caveh Jalali <caveh@chromium.org>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>

1 files changed, 313 insertions, 0 deletions

diff --git a/Documentation/drivers/dptf.md b/Documentation/drivers/dptf.md
new file mode 100644
index 0000000000..327d6865b2
--- /dev/null
+++ b/Documentation/drivers/dptf.md
@@ -0,0 +1,313 @@
+# Intel DPTF implementations in coreboot
+
+## Introduction
+
+Intel Dynamic Platform and Thermal Framework is a framework that can be used to
+help regulate the thermal properties (i.e., temperature) of an Intel-based
+computer. It does this by allowing the system designer to specify the different
+components that can generate heat, and/or dissipate heat. Under DPTF, the
+different components are referred to as `participants`. The different types of
+functionality available in DPTF are specified in terms of different `policies`.
+
+## Components ("Participants")
+
+The participants that can be involved in the current implementation are:
+- CPU (monolithic from a DPTF point-of-view)
+  - Note that the CPU's internal temperature sensor is used here
+- 1 fan
+- Up to 4 temperature sensors (TSRs)
+- Battery charger
+
+## Policies
+
+In the current implementation, there are 3 different policies available:
+
+### Passive Policy
+
+The purpose of this policy is to monitor participant temperatures and is capable
+of controlling performance and throttling available on platform devices in order
+to regulate the temperatures of each participant. The temperature threshold
+points are defined by a `_PSV` ACPI object within each participant.
+
+### Critical Policy
+
+The Critical Policy is used for gracefully suspending or powering off the system
+when the temperature of participants exceeds critical threshold
+temperatures. Suspend is effected by specifying temperatures in a `_CRT` object
+for a participant, and poweroff is effected by specifying a temperature
+threshold in a `_HOT` ACPI object.
+
+### Active Policy
+
+This policy monitors the temperature of participants and controls fans to spin
+at varying speeds. These speeds are defined by the platform, and will be enabled
+depending on the various temperatures reported by participants.
+
+# Note about units
+
+ACPI uses unusual units for specifying various physical measurements. For
+example, temperatures are specified in 10ths of a degree K, and time is measured
+in tenths of a second. Those oddities are abstracted away in the DPTF library,
+by using degrees C for temperature, milliseconds for time, mW for power, and mA
+for current.
+
+## Differences from the static ASL files (soc/intel/common/acpi/dptf/*.asl)
+
+1) TCPU had many redundant methods. The many references to \_SB.CP00._* are not
+created anymore in recent SoCs and the ACPI spec says these are optional objects
+anyway. The defaults that were returned by these methods were redundant (all
+data was a 0). The following Methods were removed:
+
+* _TSS
+* _TPC
+* _PTC
+* _TSD
+* _TDL
+* _PSS
+* _PDL
+
+2) There is no more implicit inclusion of _ACn methods for TCPU (these must be
+   specified in the devicetree entries or by calling the DPTF acpigen API).
+
+# ACPI Tables
+
+DPTF relies on an assortment of ACPI tables to provide parameters to the DPTF
+application. We will discuss the more important ones here.
+
+1) _TRT - Thermal Relationship Table
+
+This table is used when the Passive Policy is enabled, and is used to represent
+the thermal relationships in the system that can be controlled passively (i.e.,
+by throttling participants). A passive policy is defined by a Source (which
+generates heat), a Target (typically a temperature sensor), a Sampling Period
+(how often to check the temperature), an activation temperature threshold (for
+when to begin throttling), and a relative priority.
+
+2) _ART - Active Relationship Table
+
+This table is used when the Active Policy is enabled, and is used to represent
+active cooling relationships (i.e., which TSRs the fan can cool). An active
+policy contains a Target (the device the fan can cool), a Weight to control
+which participant needs more attention than others, and a list of temperature /
+fan percentage pairs. The list of pairs defines the fan control percentage that
+should be applied when the TSR reaches each successive threshold (_AC0 is the
+highest threshold, and represents the highest fan control percentage).
+
+3) PPCC - Participant Power Control Capabilities
+
+This table is used to describe parameters for controlling the SoC's Running
+Average Power Limits (RAPL, see below).
+
+4) _FPS - Fan Performance States
+
+This table describes the various fan speeds available for DPTF to use, along with
+various informational properties.
+
+5) PPSS - Participant Performance Supported States
+
+This table describes performance states supported by a participant (typically
+the battery charger).
+
+# ACPI Methods
+
+The Active and Passive policies also provide for short Methods to define
+different kinds of temperature thresholds.
+
+1) _AC0, _AC1, _AC2, _AC3, ..., _AC9
+
+These Methods can provide up to 10 temperature thresholds. What these do is set
+temperatures which act as the thresholds to active rows (fan speeds) in the
+ART. _AC0 is intended to be the highest temperature thresholds, and the lowest
+one can be any of them; leave the rest defined as 0 and they will be omitted
+from the output.
+
+These are optional and are enabled by selecting the Active Policy.
+
+2) _PSV
+
+_PSV is a temperature threshold that is used to indicate to DPTF that it should
+begin taking passive measures (i.e., throttling of the Source) in order to
+reduce the temperature of the Target in question. It will check on the
+temperature according to the given sampling period.
+
+This is optional and is enabled by selecting the Passive Policy.
+
+3) _CRT and _HOT
+
+When the temperature of the Source reaches the threshold specified in _CRT, then
+the system is supposed to execute a "graceful suspend". Similarly, when the Source
+reaches the temperature specified in _HOT, then the system is supposed to execute
+a "graceful shutdown".
+
+These are optional, and are enabled by selecting the Critical Policy.
+
+# How to use the devicetree entries
+
+The `drivers/intel/dptf` chip driver is organized into several sections:
+- Policies
+- Controls
+- Options
+
+The Policies section (`policies.active`, `policies.passive`, and
+`policies.critical`) is where the components of each policy are defined.
+
+## Active Policy
+
+Each Active Policy is defined in terms of 4 parts:
+1) A Source (this is implicitly defined as TFN1, the system fan)
+2) A Target (this is the device that can be affected by the policy, i.e.,
+   this is a device that can be cooled by the fan)
+3) A 'Weight', which is defined as the Source's contribution to the Target's
+   cooling capability (as a percentage, 0-100, often just left at 100).
+4) A list of temperature-fan percentage pairs, which define temperature
+   thresholds that, when the Target reaches, the fan is defined to spin
+   at the corresponding percentage of full duty cycle.
+
+An example definition in the devicetree:
+```C
+register "policies.active[0]" = "{
+    .target=DPTF_CPU,
+    .weight=100,
+    .thresholds={TEMP_PCT(85, 90),
+                 TEMP_PCT(80, 69),
+                 TEMP_PCT(75, 56),
+                 TEMP_PCT(70, 46),
+                 TEMP_PCT(65, 36),}}"
+```
+
+This example sets up a policy wherein the CPU temperature sensor can be cooled
+by the fan. The 'weight' of this policy is 100% (this policy contributes 100% of
+the CPU's active cooling capability). When the CPU temperature first crosses
+65C, the fan is defined to spin at 36% of its duty cycle, and so forth up the
+rest of the table (note that it *must* be defined from highest temperature/
+percentage on down to the lowest).
+
+## Passive Policy
+
+Each Passive Policy is defined in terms of 5 parts:
+1) Source - The device that can be throttled
+2) Target - The device that controls the amount of throttling
+3) Period - How often to check the temperature of the Target
+4) Trip point - What temperature threshold to start throttling
+5) Priority - A number indicating the relative priority between different
+   Policies
+
+An example definition in the devicetree:
+```C
+register "policies.passive[0]" = "DPTF_PASSIVE(CHARGER, TEMP_SENSOR_1, 65, 60000)"
+```
+
+This example sets up a policy to begin throttling the charger performance when
+temperature sensor 1 reaches 65C. The sampling period here is 60000 ms (60 s).
+The Priority is defaulted to 100 in this case.
+
+## Critical Policy
+
+Each Critical Policy is defined in terms of 3 parts:
+1) Source - A device that can trigger a critical event
+2) Type - What type of critical event to trigger (S4-entry or shutdown)
+3) Temperature - The temperature threshold that will cause the entry into S4 or
+   to shutdown the system.
+
+An example definition in the devicetree:
+
+```C
+register "policies.critical[1]" = "DPTF_CRITICAL(CPU, 75, SHUTDOWN)"
+```
+
+This example sets up a policy wherein ACPI will cause the system to shutdown
+(in a "graceful" manner) when the CPU temperature reaches 75C.
+
+## Power Limits
+
+Control over the SoC's Running Average Power Limits (RAPL) is one of the tools
+that DPTF uses to enact Passive policies. DPTF can control both PL1 and PL2, if
+the PPCC table is provided for the TCPU object. Each power limit is given the
+following options:
+1) Minimum power (in mW)
+2) Maximum power (in mW)
+3) Minimum time window (in ms)
+4) Maximum time window (in ms)
+5) Granularity, or minimum step size to control limits (in mW)
+
+An example:
+```C
+register "controls.power_limits.pl1" = "{
+        .min_power = 3000,
+        .max_power = 15000,
+        .time_window_min = 28 * MSECS_PER_SEC,
+        .time_window_max = 32 * MSECS_PER_SEC,
+        .granularity = 200,}"
+```
+
+This example allow DPTF to control the SoC's PL1 level to between 3W and 15W,
+over a time interval ranging from 28 to 32 seconds, and it can move PL1 in
+increments of 200 mW.
+
+## Charger Performance
+
+The battery charger can be a large contributor of unwanted heat in a system that
+has one. Controlling the rate of charging is another tool that DPTF uses to enact
+Passive Policies. Each entry in the PPSS table consists of:
+1) A 'Control' value - an opaque value that the platform firmware uses
+   to initiate a transition to the specified performance state. DPTF will call an
+   ACPI method called `TCHG.SPPC` (Set Participant Performance Capability) if
+   applicable, and will pass this opaque control value as its argument.
+2) The intended charging rate (in mA).
+
+Example:
+```C
+register "controls.charger_perf[0]" = "{ 255, 1700 }"
+register "controls.charger_perf[1]" = "{  24, 1500 }"
+register "controls.charger_perf[2]" = "{  16, 1000 }"
+register "controls.charger_perf[3]" = "{   8,  500 }"
+```
+
+In this example, when DPTF decides to throttle the charger, it has four different
+performance states to choose from.
+
+## Fan Performance
+
+When using DPTF, the system fan (`TFN1`) is the device responsible for actively
+cooling the other temperature sensors on the mainboard. A fan speed table can be
+provided to DPTF to assist with fan control. Each entry holds the following:
+1) Percentage of full duty to spin the fan at
+2) Speed - Speed of the fan at that percentage; informational only, but given in
+   RPM
+3) Noise - Amount of noise created by the fan at that percentage; informational
+   only, but given in tenths of a decibel (centibel).
+4) Power - Amount of power consumed by the fan at that percentage; informational
+   only, but given in mA.
+
+Example:
+```C
+register "controls.fan_perf[0]" = "{  90, 6700, 220, 2200, }"
+register "controls.fan_perf[1]" = "{  80, 5800, 180, 1800, }"
+register "controls.fan_perf[2]" = "{  70, 5000, 145, 1450, }"
+register "controls.fan_perf[3]" = "{  60, 4900, 115, 1150, }"
+register "controls.fan_perf[4]" = "{  50, 3838,  90,  900, }"
+register "controls.fan_perf[5]" = "{  40, 2904,  55,  550, }"
+register "controls.fan_perf[6]" = "{  30, 2337,  30,  300, }"
+register "controls.fan_perf[7]" = "{  20, 1608,  15,  150, }"
+register "controls.fan_perf[8]" = "{  10,  800,  10,  100, }"
+register "controls.fan_perf[9]" = "{   0,    0,   0,   50, }"
+```
+
+In this example, the fan has 10 different performance states, each in an even
+increment of 10 percentage points. This is common when specifying fine-grained
+control of the fan, wherein DPTF will interpolate between the percentages in the
+table for a given temperature threshold.
+
+## Options
+
+### Fan
+1) Fine-grained control - a boolean (see Fan Performance section above)
+2) Step-size - Recommended minimum step size (in percentage points) to adjust
+   the fan speed when using fine-grained control (ranges from 1 - 9).
+3) Low-speed notify - If true, the platform will issue a `Notify (0x80)` to the
+   fan device if a low fan speed is detected.
+
+### Temperature sensors
+1) Hysteresis - The amount of hysteresis implemented in either circuitry or
+   the firmware that reads the temperature sensor (in degrees C).
+2) Name - This name is applied to the _STR property of the sensor