diff options
Diffstat (limited to 'Documentation/drivers')
| -rw-r--r-- | Documentation/drivers/dptf.md | 313 |
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 |