一、概述

       Thermal，中文意思是热的、保暖的。在 Linux 内核中，Thermal 特指一套关于温控机制的驱动框架，其目的是为了防止 SoC 等硬件芯片因过热而造成系统不稳定，甚至缩减芯片寿命。

       Thermal 框架是在软件层面上对自然界散热系统的抽象。试想一下空调的工作机制，假设场景是夏天，室内温度 35 度，用户设定目标温度 25 度。对房间降温首先得知道房间里当前温度是多少，这个工作需要温度传感器来完成。当温度传感器探知室内温度并传给空调内部的 MCU（姑且认为空调的控制系统是由一颗内嵌的 MCU 来完成的吧） 后，MCU 得知当前温差是10度，比较大，所以加大功率，让房间迅速降温（我们知道空调内部的降温设备是雪种）。一段时间后，温度降至 28 度，这个时候 MCU 开始减小功率，降温速度开始趋缓，直至稳定在 25 度。当然，空调实际的工作方式不一定和上面描述的一模一样，但是基本原理是这样。我们试图通过空调的例子抽取温控系统的必要组件，然后过渡到 Linux 内核中的 Thermal 框架：

1、既然要控制房间温度，当然要能知道房间当前的温度，这个必要组件就是温度传感器；

2、降温或者升温，需要实际的设备来支撑，这个必要组件就是雪种；

3、温差大，加大功率以便迅速降温，温差小，降低功率省电，这个必要组件就是温控策略，或者叫温控算法；

4、整个温控系统需要有一个类似大脑的设备来统筹管理，这个必要组件就是 MCU。

       类比到 Thermal 框架（我们主要考虑 CPU/GPU 的温控），其必要组件和上面的空调例子十分相似：

1、Thermal sensor driver，SoC 内部 CPU 和 GPU 的旁边通常会有用于获取它们温度的传感器，比如 tsadc（Temperature Sensor ADC）。关于传感器的更多细节我们在 sensor driver 章节再进行深入探讨。

2、Thermal cooling device，降温设备，比如风扇。这里有点特殊的是，CPU 和 GPU 不仅是发热设备（即需要实施温控策略的设备），也可以是降温设备，当我们降低 CPU/GPU 的运行频率的时候，它们就在充当降温设备。降低产热量即是在降温。

3、Thermal governer，温控策略，Linux 内核中的温控策略要比上面的空调控制精细得多，而且也提供了多种策略。

4、Thermal core，组织并管理上面三个组件，并通过 sysfs 和用户空间交互。

       Thermal 的软件框架大致如下：

                 

二、代码路径

       本文源码分析基于瑞芯微 RK3399 Android7.1（kernel 4.4）平台，除了 sensor driver 是平台驱动工程师写的外，其余组件均为 Linux 内核提供。

Thermal sensor driver 代码：
drivers/thermal/rockchip_thermal.c  /* tsadc驱动 */

Thermal cooling device 相关代码：
drivers/thermal/devfreq_cooling.c
drivers/thermal/cpu_cooling.c

Thermal governor 相关代码：
drivers/thermal/power_allocator.c    /* power allocator 温控策略 */
drivers/thermal/step_wise.c              /* step wise 温控策略 */
drivers/thermal/fair_share.c              /* fair share 温控策略 */
drivers/thermal/user_space.c            /* userspace 温控策略 */

Thermal core 相关代码：
drivers/thermal/thermal_core.c
drivers/thermal/of_thermal.c

三、重要结构体

       这些重要结构体，这里先只做一个简要的介绍，混个脸熟，到后面各个组件的源码分析时再来进行详细的成员解析。

1、sensor driver相关

/**
 * struct rockchip_thermal_sensor - hold the information of thermal sensor
 * @thermal: pointer to the platform/configuration data
 * @tzd: pointer to a thermal zone
 * @id: identifier of the thermal sensor
 */
struct rockchip_thermal_sensor {
	struct rockchip_thermal_data *thermal;
	struct thermal_zone_device *tzd;
	int id;
};

struct rockchip_thermal_sensor：RK 平台上该结构体代表了一个 tsadc；

       struct rockchip_thermal_data：见下面的介绍；

       struct thermal_zone_device：一个 tsadc 会和一个 thermal zone 绑定；

       int id：该 tsadc 的编号，一般来说 RK 的 SoC 内部有两个 tsadc；

/**
 * struct rockchip_thermal_data - hold the private data of thermal driver
 * @chip: pointer to the platform/configuration data
 * @pdev: platform device of thermal
 * @reset: the reset controller of tsadc
 * @sensors[SOC_MAX_SENSORS]: the thermal sensor
 * @clk: the controller clock is divided by the exteral 24MHz
 * @pclk: the advanced peripherals bus clock
 * @grf: the general register file will be used to do static set by software
 * @regs: the base address of tsadc controller
 * @tshut_temp: the hardware-controlled shutdown temperature value
 * @tshut_mode: the hardware-controlled shutdown mode (0:CRU 1:GPIO)
 * @tshut_polarity: the hardware-controlled active polarity (0:LOW 1:HIGH)
 */
struct rockchip_thermal_data {
	const struct rockchip_tsadc_chip *chip;
	struct platform_device *pdev;
	struct reset_control *reset;

	struct rockchip_thermal_sensor sensors[SOC_MAX_SENSORS];

	struct clk *clk;
	struct clk *pclk;

	struct regmap *grf;
	void __iomem *regs;

	int tshut_temp;
	enum tshut_mode tshut_mode;
	enum tshut_polarity tshut_polarity;
};

struct rockchip_thermal_data：sensor driver 的私有数据，详见注释。

/**
 * struct rockchip_tsadc_chip - hold the private data of tsadc chip
 * @chn_id[SOC_MAX_SENSORS]: the sensor id of chip correspond to the channel
 * @chn_num: the channel number of tsadc chip
 * @tshut_temp: the hardware-controlled shutdown temperature value
 * @tshut_mode: the hardware-controlled shutdown mode (0:CRU 1:GPIO)
 * @tshut_polarity: the hardware-controlled active polarity (0:LOW 1:HIGH)
 * @initialize: SoC special initialize tsadc controller method
 * @irq_ack: clear the interrupt
 * @get_temp: get the temperature
 * @set_alarm_temp: set the high temperature interrupt
 * @set_tshut_temp: set the hardware-controlled shutdown temperature
 * @set_tshut_mode: set the hardware-controlled shutdown mode
 * @table: the chip-specific conversion table
 */
struct rockchip_tsadc_chip {
	/* The sensor id of chip correspond to the ADC channel */
	int chn_id[SOC_MAX_SENSORS];
	int chn_num;

	/* The hardware-controlled tshut property */
	int tshut_temp;
	enum tshut_mode tshut_mode;
	enum tshut_polarity tshut_polarity;

	/* Chip-wide methods */
	void (*initialize)(struct regmap *grf,
			   void __iomem *reg, enum tshut_polarity p);
	void (*irq_ack)(void __iomem *reg);
	void (*control)(void __iomem *reg, bool on);

	/* Per-sensor methods */
	int (*get_temp)(struct chip_tsadc_table table,
			int chn, void __iomem *reg, int *temp);
	void (*set_alarm_temp)(struct chip_tsadc_table table,
			       int chn, void __iomem *reg, int temp);
	void (*set_tshut_temp)(struct chip_tsadc_table table,
			       int chn, void __iomem *reg, int temp);
	void (*set_tshut_mode)(int chn, void __iomem *reg, enum tshut_mode m);

	/* Per-table methods */
	struct chip_tsadc_table table;
};

struct rockchip_tsadc_chip：详见注释。

RK 的 sensor driver 为了兼容他们家很多 SoC 的 tsadc，把差异性的东西抽出来。比如那些函数指针，由于寄存器地址的不一样函数体的具体内容也会不一样，如 RK3399 和 PX30 之间。再比如由于 SoC 制程不一样，默认的关机温度也可能不一样。

2、governor相关

/**
 * struct thermal_governor - structure that holds thermal governor information
 * @name: name of the governor
 * @bind_to_tz: callback called when binding to a thermal zone.  If it
 *		returns 0, the governor is bound to the thermal zone,
 *		otherwise it fails.
 * @unbind_from_tz: callback called when a governor is unbound from a thermal zone.
 * @throttle: callback called for every trip point even if temperature is
 *		below the trip point temperature
 * @governor_list: node in thermal_governor_list (in thermal_core.c)
 */
struct thermal_governor {
	char name[THERMAL_NAME_LENGTH];
	int (*bind_to_tz) (struct thermal_zone_device *tz);
	void (*unbind_from_tz) (struct thermal_zone_device *tz);
	int (*throttle) (struct thermal_zone_device *tz, int trip);
	struct list_head governor_list;
};

struct thermal_governor：用来描述一个 governor（即温控策略） 信息。

内核目前有五种 governor：

1、power_allocator：引⼊ PID（⽐例-积分-微分）控制，根据当前温度，动态给各 cooling device 分配 power，并将 power 转换为频率，从而达到根据温度限制频率的效果。

2、step_wise：根据当前温度，cooling device 逐级降频。

3、fair share：频率档位⽐较多的 cooling device 优先降频。

4、bang bang：两点温度调节，可用于 cooling device 有风扇的场景。

5、userspace：用户空间控制。

RK 平台统一使用 power_allocator 策略。

3、cooling device相关

struct thermal_cooling_device {
	int id;
	char type[THERMAL_NAME_LENGTH];
	struct device device;
	struct device_node *np;
	void *devdata;
	const struct thermal_cooling_device_ops *ops;
	bool updated; /* true if the cooling device does not need update */
	struct mutex lock; /* protect thermal_instances list */
	struct list_head thermal_instances;
	struct list_head node;
};


struct thermal_cooling_device_ops {
	int (*get_max_state) (struct thermal_cooling_device *, unsigned long *);
	int (*get_cur_state) (struct thermal_cooling_device *, unsigned long *);
	int (*set_cur_state) (struct thermal_cooling_device *, unsigned long);
	int (*get_requested_power) (struct thermal_cooling_device *,
				   struct thermal_zone_device *, u32 *);
	int (*state2power) (struct thermal_cooling_device *,
			   struct thermal_zone_device *, unsigned long, u32 *);
	int (*power2state) (struct thermal_cooling_device *,
			   struct thermal_zone_device *, u32, unsigned long *);
};

struct thermal_cooling_device：用来描述一个 cooling device（即降温设备） 信息，并将函数操作集抽取出来。

4、thermal zone

/**
 * struct thermal_zone_device - structure for a thermal zone
 * @id:		unique id number for each thermal zone
 * @type:	the thermal zone device type
 * @device:	&struct device for this thermal zone
 * @trip_temp_attrs:	attributes for trip points for sysfs: trip temperature
 * @trip_type_attrs:	attributes for trip points for sysfs: trip type
 * @trip_hyst_attrs:	attributes for trip points for sysfs: trip hysteresis
 * @devdata:	private pointer for device private data
 * @trips:	number of trip points the thermal zone supports
 * @trips_disabled;	bitmap for disabled trips
 * @passive_delay:	number of milliseconds to wait between polls when
 *			performing passive cooling.
 * @polling_delay:	number of milliseconds to wait between polls when
 *			checking whether trip points have been crossed (0 for
 *			interrupt driven systems)
 * @temperature:	current temperature.  This is only for core code,
 *			drivers should use thermal_zone_get_temp() to get the
 *			current temperature
 * @last_temperature:	previous temperature read
 * @emul_temperature:	emulated temperature when using CONFIG_THERMAL_EMULATION
 * @passive:		1 if you've crossed a passive trip point, 0 otherwise.
 * @forced_passive:	If > 0, temperature at which to switch on all ACPI
 *			processor cooling devices.  Currently only used by the
 *			step-wise governor.
 * @need_update:	if equals 1, thermal_zone_device_update needs to be invoked.
 * @ops:	operations this &thermal_zone_device supports
 * @tzp:	thermal zone parameters
 * @governor:	pointer to the governor for this thermal zone
 * @governor_data:	private pointer for governor data
 * @thermal_instances:	list of &struct thermal_instance of this thermal zone
 * @idr:	&struct idr to generate unique id for this zone's cooling
 *		devices
 * @lock:	lock to protect thermal_instances list
 * @node:	node in thermal_tz_list (in thermal_core.c)
 * @poll_queue:	delayed work for polling
 */
struct thermal_zone_device {
	int id;
	char type[THERMAL_NAME_LENGTH];
	struct device device;
	struct thermal_attr *trip_temp_attrs;
	struct thermal_attr *trip_type_attrs;
	struct thermal_attr *trip_hyst_attrs;
	void *devdata;
	int trips;
	unsigned long trips_disabled;	/* bitmap for disabled trips */
	int passive_delay;
	int polling_delay;
	int temperature;
	int last_temperature;
	int emul_temperature;
	int passive;
	unsigned int forced_passive;
	atomic_t need_update;
	struct thermal_zone_device_ops *ops;
	struct thermal_zone_params *tzp;
	struct thermal_governor *governor;
	void *governor_data;
	struct list_head thermal_instances;
	struct idr idr;
	struct mutex lock;
	struct list_head node;
	struct delayed_work poll_queue;
};


struct thermal_zone_device_ops {
	int (*bind) (struct thermal_zone_device *,
		     struct thermal_cooling_device *);
	int (*unbind) (struct thermal_zone_device *,
		       struct thermal_cooling_device *);
	int (*get_temp) (struct thermal_zone_device *, int *);
	int (*get_mode) (struct thermal_zone_device *,
			 enum thermal_device_mode *);
	int (*set_mode) (struct thermal_zone_device *,
		enum thermal_device_mode);
	int (*get_trip_type) (struct thermal_zone_device *, int,
		enum thermal_trip_type *);
	int (*get_trip_temp) (struct thermal_zone_device *, int, int *);
	int (*set_trip_temp) (struct thermal_zone_device *, int, int);
	int (*get_trip_hyst) (struct thermal_zone_device *, int, int *);
	int (*set_trip_hyst) (struct thermal_zone_device *, int, int);
	int (*get_crit_temp) (struct thermal_zone_device *, int *);
	int (*set_emul_temp) (struct thermal_zone_device *, int);
	int (*get_trend) (struct thermal_zone_device *, int,
			  enum thermal_trend *);
	int (*notify) (struct thermal_zone_device *, int,
		       enum thermal_trip_type);
};

struct thermal_zone_device：一个 thermal zone 是根据 dts 里的配置一步步解析并构建的，包含了很多信息，比如服务于该 thermal zone 的 tsadc，服务于该 thermal zone 的降温设备，该 thermal zone 所用的 governor，以及 thermal 机制工作时所需的一些参数，等等。更多细节在源码分析部分再来说明。

       通常，RK 平台上 thermal zone 的 dts 配置格式如下。其它平台应该和这个大同小异，因为都要基于 thermal core 来配置。

thermal_zones: thermal-zones {
	/* 一个节点对应一个thermal zone，并包含温控策略相关参数 */
	soc_thermal: soc-thermal {
		/* 温度高于trip-point-0指定的值，每隔20ms获取一次温度 */
		polling-delay-passive = <20>; /* milliseconds */
		/* 温度低于trip-point-0指定的值，每隔1000ms获取一次温度 */
		polling-delay = <1000>; /* milliseconds */
		/* 温度等于trip-point-1指定的值时，系统分配给cooling device的能量 */
		sustainable-power = <1000>; /* milliwatts */
		/* 当前thermal zone通过tsadc0获取温度 */
		thermal-sensors = <&tsadc 0>;

		/* trips包含不同温度阈值，不同的温控策略，配置不一定相同 */
		trips {
			/*
			 * 温控阈值，超过该值温控策略开始工作作，但不一定马上限制频率，
			 * power小到一定程度才开始限制频率
			 */
			threshold: trip-point-0 {
				/* 超过70摄氏度，温控策略开始工作，并且70度也是tsadc触发中断的一个阈值 */
				temperature = <70000>; /* millicelsius */
				/* 温度低于temperature-hysteresis时触发中断，当前未实现，但框架要求必须填 */
				hysteresis = <2000>; /* millicelsius */
				type = "passive"; /* 表示超过该温度值时，使用polling-delay-passive */
			};

			/* 温控目标温度，期望通过降频使得芯片不超过该值 */
			target: trip-point-1 {
				/* 期望通过降频使得芯片不超过85摄氏度，并且85度也是tsadc触发中断的一个阈值 */
				temperature = <85000>; /* millicelsius */
				/* 温度低于temperature-hysteresis时触发中断，当前未实现，但框架要求必须填 */
				hysteresis = <2000>; /* millicelsius */
				type = "passive"; /* 表示超过该温度值时，使用polling-delay-passive */
			};

			/* 过温保护阈值，如果降频后温度仍然上升，那么超过该值后，让系统重启 */
			soc_crit: soc-crit {
				/* 超过115摄氏度重启，并且115度也是tsadc触发中断的一个阈值 */
				temperature = <115000>; /* millicelsius */
				/* 温度低于temperature-hysteresis时触发中断，当前未实现，但框架要求必须填 */
				hysteresis = <2000>; /* millicelsius */
				type = "critical"; /* 表示超过该温度值时，重启 */
			};
		};

		/* cooling device配置节点，每个子节点代表一个cooling device */
		cooling-maps {
			map0 {
				/*
				 * 表示在target trip下，该cooling device才起作用，
				 * 对于power allocater策略必须填target
				 */
				trip = <&target>;
				/* A53做为cooloing device， THERMAL_NO_LIMIT不起作用，但必须填 */
				cooling-device = <&cpu_l0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
				/* 计算功耗时乘以4096/1024倍，用于调整降频顺序和尺度 */
				contribution = <4096>;
			};

			map1 {
				/*
				 * 表示在target trip下，该cooling device才起作用，
				 * 对于power allocater策略必须填target
				 */
				trip = <&target>;
				/* A72做为cooloing device， THERMAL_NO_LIMIT不起作用，但必须填 */
				cooling-device = <&cpu_b0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
				/* 计算功耗时乘以1024/1024倍，用于调整降频顺序和尺度 */
				contribution = <1024>;
			};

			map2 {
				/*
				 * 表示在target trip下，该cooling device才起作用，
				 * 对于power allocater策略必须填target
				 */
				trip = <&target>;
				/* GPU做为cooloing device， THERMAL_NO_LIMIT不起作用，但必须填 */
				cooling-device = <&gpu THERMAL_NO_LIMIT THERMAL_NO_LIMIT>;
				/* 计算功耗时乘以4096/1024倍，用于调整降频顺序和尺度 */
				contribution = <4096>;
			};
		};
	};

	/* 一个节点对应一个thermal zone，并包含温控策略相关参数，当前thermal zone只用于获取温度 */
	gpu_thermal: gpu-thermal {
		/* 包含温控策略配置的情况下才起作用，框架要求必须填 */
		polling-delay-passive = <100>; /* milliseconds */
		/* 每隔1000ms获取一次温度 */
		polling-delay = <1000>; /* milliseconds */

		/* 当前thermal zone通过tsadc1获取温度 */
		thermal-sensors = <&tsadc 1>;
	};
};

上面每个子结点和每条属性的注释摘自 RK 平台的开发参考文档，这些注释都可以在源码里找到答案，到具体源码分析时读者应该会有更深刻的理解。