coreboot-kgpe-d16/Documentation/drivers/dptf.md

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:

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:

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:

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:

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:

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:

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