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>
This commit is contained in:
Tim Wawrzynczak
parent
f524188f48
commit
0115ba8835
|
|
@ -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
|
||||||
Loading…
Reference in New Issue