| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
| |
| <book id="thermal-api"> |
| <bookinfo> |
| <title>Linux Kernel Thermal Framework API</title> |
| |
| <authorgroup> |
| <author> |
| <firstname>Eduardo</firstname> |
| <surname>Valentin</surname> |
| <affiliation> |
| <address> |
| <email>evalenti@kernel.org</email> |
| </address> |
| </affiliation> |
| </author> |
| </authorgroup> |
| |
| <copyright> |
| <year>2008-2014</year> |
| <holder>Eduardo Valentin</holder> |
| <holder>Sujith Thomas</holder> |
| <holder>Zhang Rui</holder> |
| </copyright> |
| <legalnotice> |
| <para> |
| This documentation is free software; you can redistribute |
| it and/or modify it under the terms of the GNU General Public |
| License version 2 as published by the Free Software Foundation. |
| </para> |
| |
| <para> |
| This program is distributed in the hope that it will be |
| useful, but WITHOUT ANY WARRANTY; without even the implied |
| warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| See the GNU General Public License for more details. |
| </para> |
| |
| <para> |
| For more details see the file COPYING in the source |
| distribution of Linux. |
| </para> |
| </legalnotice> |
| </bookinfo> |
| |
| <toc></toc> |
| |
| <chapter id="introduction"> |
| <title>Introduction</title> |
| <para>Thermal management is any method or technique implied to |
| mitigate emergencies caused by operating devices outside of |
| supported temperatures. The challenge consists of designing a |
| product keeping the junction temperature of the IC components. |
| The operating temperature of IC components used on products must |
| operate within their design limits. Besides, temperature towards |
| device enclosure must be in a comfort level for the user. |
| Therefore, thermal management, by the time of this writing, |
| starts in very early device design phase. Managing thermal may |
| involve different disciplines, at different stages, such as |
| temperature monitoring, floorplanning, microarchitectural |
| techniques, compiler techniques, OS techniques, liquid cooling, |
| and thermal reliability or security. This document covers what |
| the Linux Kernel Thermal Framework provides as abstraction to |
| users with respect to thermal management. |
| </para> |
| <para>One of the first proposals to provide a solution to cover |
| the thermal problem appears in the Advanced Configuration and |
| Power Interface (ACPI) specification. ACPI provides an open |
| standard for device configuration and power management by the |
| operating system. However, several computing devices which may |
| have thermal issues in the market disregard the ACPI standard. |
| Therefore, the Linux Kernel Thermal Framework has been designed |
| to serve as abstraction for ACPI and non-ACPI systems. The core |
| concepts applies in both types of systems. |
| </para> |
| <para>The Linux Kernel Thermal Framework has a design which |
| represents the different thermal constraints found in |
| end-products. The thermal constraints exist to serve different |
| purposes. There are two major types of thermal constraints. The |
| first is related to components junction temperature. The second |
| is related to the level of comfort while end users are handling |
| devices. |
| </para> |
| |
| <sect1 id="glossary"> |
| <title>Glossary</title> |
| <para>The Linux Kernel Thermal Framework uses a |
| specific terminology to represent the entities involved |
| in thermal constrained environments. This section |
| summarizes the terminology as dictionary. These terms |
| are in use within the present document and in the source |
| code of the Linux Kernel Thermal Framework. |
| </para> |
| <glossary> |
| <glossentry> |
| <glossterm>Thermal Zone</glossterm> |
| <glossdef> |
| <para>Thermal zones represent |
| what is the current status of a |
| thermal constrained zone in the |
| hardware. The zone usually is a |
| device or component. The status |
| of a thermal zone is mainly with |
| respect to temperature. |
| Currently, the Linux Kernel |
| Thermal Framework represents |
| temperature in miliCelsius. The |
| current abstraction covers for |
| non-negative temperatures and |
| constraints. |
| </para> |
| </glossdef> |
| </glossentry> |
| <glossentry> |
| <glossterm>Thermal Sensors</glossterm> |
| <glossdef> |
| <para>Thermal sensors provide |
| temperature sensing capabilities |
| on thermal zones. Typical |
| devices are I2C ADC converters |
| and bandgaps. These are nodes |
| providing temperature data to |
| thermal zones. Thermal sensor |
| devices may control one or more |
| internal sensors. |
| </para> |
| </glossdef> |
| </glossentry> |
| <glossentry> |
| <glossterm>Trip Points</glossterm> |
| <glossdef> |
| <para>The trip node describes a |
| point in the temperature domain |
| in which the system takes an |
| action. This item describes just |
| the point, not the action. Trip |
| points are represented as |
| temperature in miliCelsius. The |
| current abstraction covers for |
| non-negative temperatures. |
| </para> |
| </glossdef> |
| </glossentry> |
| <glossentry> |
| <glossterm>Thermal Governor</glossterm> |
| <glossdef> |
| <para>Thermal Governors |
| represent a policy to manage the |
| thermal zone device temperature. |
| The governor targets to keep |
| temperature in an acceptable |
| range which correlates to the |
| power budget, while maximizing |
| the performance. Governors can |
| be implemented in Kernel Space |
| or in User Space. |
| </para> |
| </glossdef> |
| </glossentry> |
| <glossentry> |
| <glossterm>Thermal Cooling Device</glossterm> |
| <glossdef> |
| <para>Cooling devices provide |
| control on power dissipation. |
| There are essentially two ways |
| to provide control on power |
| dissipation. First is by means |
| of regulating device |
| performance, which is known as |
| passive cooling. A typical |
| passive cooling is a CPU that |
| has dynamic voltage and |
| frequency scaling (DVFS), and |
| uses lower frequencies as |
| cooling states. Second is by |
| means of activating devices in |
| order to remove the dissipated |
| heat, which is known as active |
| cooling, e.g. regulating fan |
| speeds. In both cases, cooling |
| devices shall have a way to |
| determine the state of cooling |
| in which the device is. |
| </para> |
| </glossdef> |
| </glossentry> |
| <glossentry> |
| <glossterm>Cooling State</glossterm> |
| <glossdef> |
| <para>Any cooling device has a |
| range of cooling states (i.e. |
| different levels of heat |
| dissipation). For example a |
| fan's cooling states correspond |
| to the different fan speeds |
| possible. Cooling states are |
| referred to by single unsigned |
| integers, where larger numbers |
| mean greater heat dissipation. |
| The precise set of cooling |
| states associated with a device |
| (as referred to be the |
| cooling-min-state and |
| cooling-max-state properties) |
| should be defined in a |
| particular device's binding. |
| </para> |
| </glossdef> |
| </glossentry> |
| </glossary> |
| </sect1> |
| </chapter> |
| <chapter id="api"> |
| <title>Thermal Device Driver Writer API reference</title> |
| <para> This Chapter contains an API reference for Thermal driver writers. |
| </para> |
| !Iinclude/linux/thermal.h |
| !Edrivers/thermal/thermal_core.c |
| !Edrivers/thermal/cpu_cooling.c |
| !Edrivers/thermal/of-thermal.c |
| </chapter> |
| </book> |
