Thermal Framework Device Tree descriptor（待续）
- Thermal Framework Device Tree descriptor
此文件描述了一种通用绑定，为了提供使用设备树定义硬件thermal结构的方法。thermal结构包括thermal zones及其组件，例如trip points，polling intervals，sensors 和 cooling devices绑定描述符。
设备树thermal描述符的目标仅用于描述硬件thermal 方面。 thermal设备树绑定与系统必须如何控制或必须采用哪种算法或策略无关。
描述thermal 绑定涉及五种类型的节点：
- thermal sensors：可用于 测量温度的装置。
- cooling devices：可用于散热的装置。
- trip points：描述建议冷却的关键温度。应根据硬件限制选择一组点。
- cooling maps：用于描述trip points和cooling devices之间的链接;
- thermal zones：用于描述硬件内的thermal 数据;
以下是每种节点类型的描述。
- Thermal sensor 设备
Thermal zones中的thermal sensor是提供温度感测功能的节点。 典型器件是I2C ADC转换器。 这些是向thermal sensor提供温度数据的节点。Thermal sensor设备可以控制一个或多个内部传感器。
所需属性：
- #thermal-sensor-cells：用于提供传感器设备特定信息
类型：unsigned。 热传感器通常为0
大小：一个单元节点只有一个传感器，节点上大于一个则有几个内部传感器，按顺序
唯一地标识其中的传感器实例。 有关详细信息，关于消费者如何参考传感器设备请参阅 thermal zone绑定。
Required property: - #thermal-sensor-cells: Used to provide sensor device specific information
Type: unsigned while referring to it. Typically 0 on thermal sensor
Size: one cell nodes with only one sensor, and at least 1 on nodes
with several internal sensors, in order
to identify uniquely the sensor instances within
the IC. See thermal zone binding for more details
on how consumers refer to sensor devices.
- Cooling device nodes
Cooling devices are nodes providing 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.
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
should be defined in a particular device’s binding.
For more examples of cooling devices, refer to the example sections below.
Required properties:
- #cooling-cells: Used to provide cooling device specific information
Type: unsigned while referring to it. Must be at least 2, in order
Size: one cell to specify minimum and maximum cooling state used
in the reference. The first cell is the minimum
cooling state requested and the second cell is
the maximum cooling state requested in the reference.
See Cooling device maps section below for more details
on how consumers refer to cooling devices.
- Trip points
The trip node is a node to describe a point in the temperature domain
in which the system takes an action. This node describes just the point,
not the action.
Required properties:
-
temperature: An integer indicating the trip temperature level,
Type: signed in millicelsius.
Size: one cell -
hysteresis: A low hysteresis value on temperature property (above).
Type: unsigned This is a relative value, in millicelsius.
Size: one cell -
type: a string containing the trip type. Expected values are:
“active”: A trip point to enable active cooling
“passive”: A trip point to enable passive cooling
“hot”: A trip point to notify emergency
“critical”: Hardware not reliable.
Type: string
- Cooling device maps
The cooling device maps node is a node to describe how cooling devices
get assigned to trip points of the zone. The cooling devices are expected
to be loaded in the target system.
Required properties:
- cooling-device: A list of phandles of cooling devices with their specifiers,
Type: phandle + referring to which cooling devices are used in this
cooling specifier binding. In the cooling specifier, the first cell
is the minimum cooling state and the second cell
is the maximum cooling state used in this map. - trip: A phandle of a trip point node within the same thermal
Type: phandle of zone.
trip point node
Optional property:
- contribution: The cooling contribution to the thermal zone of the
Type: unsigned referred cooling device at the referred trip point.
Size: one cell The contribution is a ratio of the sum
of all cooling contributions within a thermal zone.
Note: Using the THERMAL_NO_LIMIT (-1UL) constant in the cooling-device phandle
limit specifier means:
(i) - minimum state allowed for minimum cooling state used in the reference.
(ii) - maximum state allowed for maximum cooling state used in the reference.
Refer to include/dt-bindings/thermal/thermal.h for definition of this constant.
- Thermal zone nodes
The thermal zone node is the node containing all the required info
for describing a thermal zone, including its cooling device bindings. The
thermal zone node must contain, apart from its own properties, one sub-node
containing trip nodes and one sub-node containing all the zone cooling maps.
Required properties:
-
polling-delay: The maximum number of milliseconds to wait between polls
Type: unsigned when checking this thermal zone.
Size: one cell -
polling-delay-passive: The maximum number of milliseconds to wait
Type: unsigned between polls when performing passive cooling.
Size: one cell -
thermal-sensors: A list of thermal sensor phandles and sensor specifier
Type: list of used while monitoring the thermal zone.
phandles + sensor
specifier -
trips: A sub-node which is a container of only trip point nodes
Type: sub-node required to describe the thermal zone. -
cooling-maps: A sub-node which is a container of only cooling device
Type: sub-node map nodes, used to describe the relation between trips
and cooling devices.
Optional property:
-
coefficients: An array of integers (one signed cell) containing
Type: array coefficients to compose a linear relation between
Elem size: one cell the sensors listed in the thermal-sensors property.
Elem type: signed Coefficients defaults to 1, in case this property
is not specified. A simple linear polynomial is used:
Z = c0 * x0 + c1 * x1 + … + c(n-1) * x(n-1) + cn.The coefficients are ordered and they match with sensors by means of sensor ID. Additional coefficients are interpreted as constant offset. -
sustainable-power: An estimate of the sustainable power (in mW) that the
Type: unsigned thermal zone can dissipate at the desired
Size: one cell control temperature. For reference, the
sustainable power of a 4’’ phone is typically
2000mW, while on a 10’’ tablet is around
4500mW.
Note: The delay properties are bound to the maximum dT/dt (temperature
derivative over time) in two situations for a thermal zone:
(i) - when passive cooling is activated (polling-delay-passive); and
(ii) - when the zone just needs to be monitored (polling-delay) or
when active cooling is activated.
The maximum dT/dt is highly bound to hardware power consumption and dissipation
capability. The delays should be chosen to account for said max dT/dt,
such that a device does not cross several trip boundaries unexpectedly
between polls. Choosing the right polling delays shall avoid having the
device in temperature ranges that may damage the silicon structures and
reduce silicon lifetime.
- The thermal-zones node
The “thermal-zones” node is a container for all thermal zone nodes. It shall
contain only sub-nodes describing thermal zones as in the section
“Thermal zone nodes”. The “thermal-zones” node appears under “/”.
- Examples
Below are several examples on how to use thermal data descriptors
using device tree bindings:
(a) - CPU thermal zone
The CPU thermal zone example below describes how to setup one thermal zone
using one single sensor as temperature source and many cooling devices and
power dissipation control sources.
#include
cpus {
/*
* Here is an example of describing a cooling device for a DVFS
* capable CPU. The CPU node describes its four OPPs.
* The cooling states possible are 0..3, and they are
* used as OPP indexes. The minimum cooling state is 0, which means
* all four OPPs can be available to the system. The maximum
* cooling state is 3, which means only the lowest OPPs ([email protected])
* can be available in the system.
*/
cpu0: cpu@0 {
...
operating-points = <
/* kHz uV */
970000 1200000
792000 1100000
396000 950000
198000 850000
>;
#cooling-cells = <2>; /* min followed by max */
};
...
};
&i2c1 {
...
/*
* A simple fan controller which supports 10 speeds of operation
* (represented as 0-9).
*/
fan0: fan@48 {
...
#cooling-cells = <2>; /* min followed by max */
};
};
ocp {
...
/*
* A simple IC with a single bandgap temperature sensor.
*/
bandgap0: bandgap@0000ed00 {
...
#thermal-sensor-cells = <0>;
};
};
thermal-zones {
cpu_thermal: cpu-thermal {
polling-delay-passive = <250>; /* milliseconds */
polling-delay = <1000>; /* milliseconds */
thermal-sensors = <&bandgap0>;
trips {
cpu_alert0: cpu-alert0 {
temperature = <90000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "active";
};
cpu_alert1: cpu-alert1 {
temperature = <100000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "passive";
};
cpu_crit: cpu-crit {
temperature = <125000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "critical";
};
};
cooling-maps {
map0 {
trip = <&cpu_alert0>;
cooling-device = <&fan0 THERMAL_NO_LIMIT 4>;
};
map1 {
trip = <&cpu_alert1>;
cooling-device = <&fan0 5 THERMAL_NO_LIMIT>, <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
};
};
};
};
In the example above, the ADC sensor (bandgap0) at address 0x0000ED00 is
used to monitor the zone ‘cpu-thermal’ using its sole sensor. A fan
device (fan0) is controlled via I2C bus 1, at address 0x48, and has ten
different cooling states 0-9. It is used to remove the heat out of
the thermal zone ‘cpu-thermal’ using its cooling states
from its minimum to 4, when it reaches trip point ‘cpu_alert0’
at 90C, as an example of active cooling. The same cooling device is used at
‘cpu_alert1’, but from 5 to its maximum state. The cpu@0 device is also
linked to the same thermal zone, ‘cpu-thermal’, as a passive cooling device,
using all its cooling states at trip point ‘cpu_alert1’,
which is a trip point at 100C. On the thermal zone ‘cpu-thermal’, at the
temperature of 125C, represented by the trip point ‘cpu_crit’, the silicon
is not reliable anymore.
(b) - IC with several internal sensors
The example below describes how to deploy several thermal zones based off a
single sensor IC, assuming it has several internal sensors. This is a common
case on SoC designs with several internal IPs that may need different thermal
requirements, and thus may have their own sensor to monitor or detect internal
hotspots in their silicon.
#include
ocp {
...
/*
* A simple IC with several bandgap temperature sensors.
*/
bandgap0: bandgap@0000ed00 {
...
#thermal-sensor-cells = <1>;
};
};
thermal-zones {
cpu_thermal: cpu-thermal {
polling-delay-passive = <250>; /* milliseconds */
polling-delay = <1000>; /* milliseconds */
/* sensor ID */
thermal-sensors = <&bandgap0 0>;
trips {
/* each zone within the SoC may have its own trips */
cpu_alert: cpu-alert {
temperature = <100000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "passive";
};
cpu_crit: cpu-crit {
temperature = <125000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "critical";
};
};
cooling-maps {
/* each zone within the SoC may have its own cooling */
...
};
};
gpu_thermal: gpu-thermal {
polling-delay-passive = <120>; /* milliseconds */
polling-delay = <1000>; /* milliseconds */
/* sensor ID */
thermal-sensors = <&bandgap0 1>;
trips {
/* each zone within the SoC may have its own trips */
gpu_alert: gpu-alert {
temperature = <90000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "passive";
};
gpu_crit: gpu-crit {
temperature = <105000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "critical";
};
};
cooling-maps {
/* each zone within the SoC may have its own cooling */
...
};
};
dsp_thermal: dsp-thermal {
polling-delay-passive = <50>; /* milliseconds */
polling-delay = <1000>; /* milliseconds */
/* sensor ID */
thermal-sensors = <&bandgap0 2>;
trips {
/* each zone within the SoC may have its own trips */
dsp_alert: dsp-alert {
temperature = <90000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "passive";
};
dsp_crit: gpu-crit {
temperature = <135000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "critical";
};
};
cooling-maps {
/* each zone within the SoC may have its own cooling */
...
};
};
};
In the example above, there is one bandgap IC which has the capability to
monitor three sensors. The hardware has been designed so that sensors are
placed on different places in the DIE to monitor different temperature
hotspots: one for CPU thermal zone, one for GPU thermal zone and the
other to monitor a DSP thermal zone.
Thus, there is a need to assign each sensor provided by the bandgap IC
to different thermal zones. This is achieved by means of using the
#thermal-sensor-cells property and using the first cell of the sensor
specifier as sensor ID. In the example, then,
monitor CPU thermal zone,
zone and
may be uncorrelated, having its own dT/dt requirements, trips
and cooling maps.
© - Several sensors within one single thermal zone
The example below illustrates how to use more than one sensor within
one thermal zone.
#include
&i2c1 {
…
/*
* A simple IC with a single temperature sensor.
*/
adc: sensor@49 {
…
#thermal-sensor-cells = <0>;
};
};
ocp {
…
/*
* A simple IC with a single bandgap temperature sensor.
*/
bandgap0: bandgap@0000ed00 {
…
#thermal-sensor-cells = <0>;
};
};
thermal-zones {
cpu_thermal: cpu-thermal {
polling-delay-passive = <250>; /* milliseconds /
polling-delay = <1000>; / milliseconds */
thermal-sensors = <&bandgap0>, /* cpu */
<&adc>; /* pcb north */
/* hotspot = 100 * bandgap - 120 * adc + 484 */
coefficients = <100 -120 484>;
trips {
...
};
cooling-maps {
...
};
};
};
In some cases, there is a need to use more than one sensor to extrapolate
a thermal hotspot in the silicon. The above example illustrates this situation.
For instance, it may be the case that a sensor external to CPU IP may be placed
close to CPU hotspot and together with internal CPU sensor, it is used
to determine the hotspot. Assuming this is the case for the above example,
the hypothetical extrapolation rule would be:
hotspot = 100 * bandgap - 120 * adc + 484
In other context, the same idea can be used to add fixed offset. For instance,
consider the hotspot extrapolation rule below:
hotspot = 1 * adc + 6000
In the above equation, the hotspot is always 6C higher than what is read
from the ADC sensor. The binding would be then:
thermal-sensors = <&adc>;
/* hotspot = 1 * adc + 6000 */
coefficients = <1 6000>;
(d) Board thermal
下面的电路板热量示例说明了如何使用多个传感器和许多cooling devices设置一个thermal zone。
#include
&i2c1 {
...
/*
* An IC with several temperature sensor.
*/
adc_dummy: sensor@50 {
...
#thermal-sensor-cells = <1>; /* sensor internal ID */
};
};
thermal-zones {
batt-thermal {
polling-delay-passive = <500>; /* milliseconds */
polling-delay = <2500>; /* milliseconds */
/* sensor ID */
thermal-sensors = <&adc_dummy 4>;
trips {
...
};
cooling-maps {
...
};
};
board_thermal: board-thermal {
polling-delay-passive = <1000>; /* milliseconds */
polling-delay = <2500>; /* milliseconds */
/* sensor ID */
thermal-sensors = <&adc_dummy 0>, /* pcb top edge */
<&adc_dummy 1>, /* lcd */
<&adc_dummy 2>; /* back cover */
/*
* An array of coefficients describing the sensor
* linear relation. E.g.:
* z = c1*x1 + c2*x2 + c3*x3
*/
coefficients = <1200 -345 890>;
sustainable-power = <2500>;
trips {
/* Trips are based on resulting linear equation */
cpu_trip: cpu-trip {
temperature = <60000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "passive";
};
gpu_trip: gpu-trip {
temperature = <55000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "passive";
}
lcd_trip: lcp-trip {
temperature = <53000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "passive";
};
crit_trip: crit-trip {
temperature = <68000>; /* millicelsius */
hysteresis = <2000>; /* millicelsius */
type = "critical";
};
};
cooling-maps {
map0 {
trip = <&cpu_trip>;
cooling-device = <&cpu0 0 2>;
contribution = <55>;
};
map1 {
trip = <&gpu_trip>;
cooling-device = <&gpu0 0 2>;
contribution = <20>;
};
map2 {
trip = <&lcd_trip>;
cooling-device = <&lcd0 5 10>;
contribution = <15>;
};
};
};
};
上面的例子是前面例子的混合，传感器IP有几个用于监控不同区域的内部传感器，其中一个由几个传感器和不同的冷却设备组成。