1. 从一次温控翻车说起：thermal framework 到底管什么
前阵子帮朋友调一块嵌入式板子，跑压力测试不到三分钟就降频，日志里刷出一堆thermal_zone相关的告警。他第一反应是散热片没贴好，换了硅脂、加了风扇，问题依旧。后来把/sys/class/thermal/下的节点挨个 dump 出来看，才发现是某个 trip point 的温度阈值配错了，导致系统在 60 度就触发了被动降温。这件事让我意识到，很多人对 Linux 功耗子系统里的 thermal framework 只有一个模糊印象——"管温度的"，但真到排查问题时，连它内部有哪几层、数据从哪来到哪去都说不清楚。
这篇就来把 thermal framework 的通用架构从头到尾捋一遍。它不是某个具体驱动，而是内核里一整套温度管理与散热控制的框架，向上对接用户空间，向下管理各类温度传感器和冷却设备。搞嵌入式的、做功耗优化的、调散热策略的，甚至只是想在面试里把这块讲明白的，都值得花时间把它的骨架吃透。我会按"分层结构—核心数据结构—注册流程—触发机制—用户接口"这条线展开，中间穿插实际调试时踩过的坑，尽量让刚接触内核的朋友也能跟上。
需要先说明一点：thermal framework 的代码在drivers/thermal/目录下，核心文件包括thermal_core.c、thermal_zone_device.c（较新内核里拆得更细）、thermal_cooling.c、thermal_sysfs.c等。不同内核版本目录结构会有调整，但整体设计思想是稳定的。下面讲的内容以通用架构为主，具体函数名可能随版本变化，理解思路比记函数名重要。
2. thermal framework 的四层骨架与职责边界
2.1 分层设计的动机：为什么不做成一个大驱动
刚看 thermal 代码的人常有一个疑问：不就是读个温度、超了就降频吗，为什么内核要搞这么复杂的一套框架？答案在于硬件多样性和策略可替换性这两个现实约束。
温度传感器可能是 SoC 内部的 TSADC、外部的 I2C 温度芯片、甚至是通过某种总线间接读取的。冷却手段可能是 CPU 调频、GPU 降频、风扇调速、甚至主动限制某个外设的功率。如果每个平台都写一个"读温度—判断—降频"的大驱动，代码会彻底碎片化，策略也没法复用。thermal framework 的价值就在于把这些变化点抽象出来，用统一的注册接口和事件机制把它们串起来。
我个人的理解是：它本质上是一个生产者—消费者模型。温度传感器是生产者，持续上报温度；冷却设备是消费者，在需要时被调用去散热；而 thermal zone 是把两者绑定在一起的"策略容器"，trip point 则是触发条件。
2.2 四个核心抽象层
从架构上看，thermal framework 可以拆成四层，每层职责清晰：
| 层次 | 代表对象 | 核心职责 |
|---|---|---|
| 传感器层 | thermal sensor driver | 读取原始温度，注册为 thermal zone 的数据源 |
| 框架核心层 | thermal_core | 管理 zone 生命周期、轮询/中断触发、trip 判定 |
| 策略/治理层 | governor | 决定触发 trip 后如何调节冷却设备 |
| 冷却设备层 | cooling device | 实际执行降频、调速等散热动作 |
传感器层负责"感知"，核心层负责"调度"，governor 负责"决策"，冷却设备层负责"执行"。这四层之间通过内核内部的数据结构和回调函数通信，而不是直接互相调用，这样任何一层替换实现都不影响其他层。
2.3 与功耗子系统其他模块的边界
thermal framework 经常和 CPUFreq、devfreq、regulator 这些模块一起出现，容易混淆。要理清边界：thermal 只负责"根据温度决定要不要散热、散多少"，它不直接去改 CPU 频率。真正改频率的是 CPUFreq 的 governor，thermal 只是通过 cooling device 接口去"请求"CPUFreq 降频。同理，风扇转速是 hwmon 或 pwm 驱动在管，thermal 通过 cooling device 去请求它调整。
这个边界很重要。调试时如果发现温度降不下来，要先确认是 thermal 没触发，还是触发了但 cooling device 没响应，还是响应了但散热能力本身不够。这三者的排查路径完全不同。
3. thermal zone 与 trip point：策略的载体
3.1 thermal_zone_device 里到底存了什么
struct thermal_zone_device是整个框架的核心数据结构，理解它基本就理解了 thermal 的工作方式。它里面几个关键字段值得单独拎出来说：
type：zone 的类型字符串，比如cpu-thermal、gpu-thermal，用户空间靠它区分不同 zone。temperature：当前温度，由传感器驱动通过get_temp回调更新。trips：trip point 数组，每个 trip 包含温度阈值、类型（active/passive/hot/critical）和绑定的 cooling device。governor：当前使用的治理策略，决定 trip 触发后怎么调冷却设备。polling_delay/passive_delay：轮询间隔，决定多久读一次温度。
这里有个容易忽略的点：temperature不是传感器主动推上来的，而是框架在轮询或收到中断通知后，调用驱动的get_temp回调去"拉"的。所以如果你的传感器驱动get_temp实现有问题（比如返回缓存值不更新），温度就会一直不变，trip 永远不触发。
3.2 trip point 的四种类型与触发语义
trip point 是 thermal 策略的触发条件，内核里定义了四种类型，语义差别很大：
- passive：被动散热。触发后 governor 会去调 cooling device，通常是降频。这是最常见的类型。
- active：主动散热。触发后启动主动散热设备，典型是风扇。active trip 通常有多个，对应风扇的不同档位。
- hot：温度已经偏高，通知用户空间，但框架本身不一定采取强制动作。
- critical：危险温度。触发后框架会直接调用
thermal_zone_device_critical，默认行为是关机或重启，防止硬件损坏。
实测中踩过的坑：critical trip 的温度一定要留足余量。有次配了个 105 度的 critical，结果 SoC 在 103 度时已经不稳定，还没到 critical 就死机了。后来改成 95 度 critical、85 度 passive，系统反而稳了。critical 不是"硬件极限温度"，而是"你必须在此之前采取最后手段的温度"，这个区别很关键。
3.3 trip point 与 cooling device 的绑定关系
一个 trip 可以绑定多个 cooling device，每个绑定带一个weight权重。governor 在调节时，会按权重分配散热力度。比如一个 passive trip 同时绑了 CPU 和 GPU 两个 cooling device，权重分别是 100 和 50，那降频时会优先动 CPU。
绑定关系在设备树里通过cooling-maps描述，也可以在驱动里用thermal_zone_bind_cooling_device手动绑。设备树方式更常见，但调试时手动绑更灵活。我一般先在设备树里配好，出问题时用 sysfs 临时改权重验证，确认策略对了再回写设备树。
4. governor：从温度到散热动作的决策逻辑
4.1 governor 的注册与选择机制
governor 是 thermal 的"大脑"，内核里内置了几种，常见的有：
step_wise：逐步调节，每次触发只调一档，温和但响应慢。power_allocator：基于功率预算分配，适合复杂 SoC，配置也最复杂。fair_share：按权重公平分配散热力度。bang_bang：开关式，超过阈值就全开，简单粗暴。
governor 通过thermal_register_governor注册，zone 在创建时通过governor_name指定用哪个。如果指定的 governor 还没注册，zone 会先挂起，等 governor 注册后再绑定。这个机制导致一个常见问题：governor 驱动的初始化顺序如果晚于 zone 创建，zone 会短暂处于无 governor 状态，这段时间温度保护是失效的。所以 governor 驱动通常要设成较早初始化。
4.2 step_wise 的工作流程拆解
step_wise 是最常用的 governor，逻辑不复杂但细节不少。它的核心是get_target_state函数，流程大致是：
- 遍历所有 trip point，找出当前温度命中的最高 trip。
- 根据 trip 类型决定动作方向：温度上升时增加散热，下降时减少散热。
- 对每个绑定的 cooling device，根据当前 state 和权重计算目标 state。
- 调用
thermal_cooling_device_update下发新 state。
这里有个"滞后"设计值得注意：step_wise 不会在温度刚好低于 trip 时就立刻降档，而是等温度降到trip - hysteresis才降。hysteresis 是滞后量，防止温度在阈值附近抖动导致 cooling device 频繁开关。这个值配小了会抖，配大了散热不及时，需要根据实际热惯性调。
4.3 power_allocator 的功率预算思路
power_allocator 是给复杂 SoC 用的，思路和 step_wise 完全不同。它不盯着单个 trip，而是维护一个"可持续功率预算"，根据温度动态调整这个预算，再按各 cooling device 的功率模型分配。
它的配置项多，sustainable-power、k_po、k_pu、k_i这些参数需要根据平台热特性调。调不好的典型症状是温度震荡或者散热过度导致性能损失大。我的经验是：先用 step_wise 把基本功能跑通，确认传感器和 cooling device 都正常，再换 power_allocator 慢慢调参数。直接上 power_allocator 调参，出问题很难定位是传感器、绑定还是参数的问题。
5. cooling device 注册与绑定的实操细节
5.1 cooling device 的注册接口
任何能散热的设备，只要实现struct thermal_cooling_device_ops里的回调，就能注册成 cooling device。核心回调有三个：
get_max_state：返回最大冷却档位。get_cur_state：返回当前档位。set_cur_state：设置档位，真正执行散热动作。
CPUFreq 的 cooling device 就是把档位映射成频率限制，档位越高频率压得越低。风扇的 cooling device 就是把档位映射成 PWM 占空比。注册用thermal_cooling_device_register，传入设备名、私有数据和 ops。
有个细节：get_max_state返回的是"最大档位编号"，不是档位数量。如果档位是 0 到 3，应该返回 3 而不是 4。这个 off-by-one 错误我见过不止一次，症状是最高档永远调不到。
5.2 设备树里的 cooling-maps 怎么写
设备树方式绑定 trip 和 cooling device，典型写法是在 thermal zone 节点下加cooling-maps子节点，每个 map 指定trip、cooling-device和contribution（权重）。示例结构大致是：
thermal-zones { cpu_thermal: cpu-thermal { polling-delay-passive = <250>; polling-delay = <1000>; trips { cpu_passive: cpu-passive { temperature = <85000>; hysteresis = <2000>; type = "passive"; }; }; cooling-maps { map0 { trip = <&cpu_passive>; cooling-device = <&cpu0 THERMAL_NO_LIMIT THERMAL_NO_LIMIT>; }; }; }; };THERMAL_NO_LIMIT表示不限制档位范围。如果要限制，可以写成具体的 min/max 档位。polling-delay-passive是进入被动散热后的轮询间隔，通常比正常轮询短，因为这时候需要更快响应。
5.3 绑定失败的常见原因排查
绑定失败时内核会打日志，但日志往往不够具体。我总结了几类常见原因：
- cooling device 还没注册：设备树里引用了但驱动还没 probe，绑定会延迟或失败。检查 probe 顺序。
- trip 索引对不上：设备树里 trip 的顺序和驱动里解析的顺序不一致，导致绑错 trip。
- 权重配置为 0：contribution 为 0 时绑定无效，但不会报错，只是不生效。
- zone 和 cooling device 在不同 thermal 实例：多实例场景下容易搞混。
排查时最直接的办法是看/sys/class/thermal/cooling_device*/和对应 zone 的cdev*链接，确认绑定关系是否建立。
6. 用户空间接口与调试手段
6.1 sysfs 节点的读写语义
thermal 在/sys/class/thermal/下暴露了大量节点，常用的有：
thermal_zone*/temp：当前温度，单位是毫摄氏度。读出来 45000 就是 45 度。thermal_zone*/type：zone 类型名。thermal_zone*/mode：控制模式，enabled或disabled，写disabled可以临时关掉某个 zone 的治理。thermal_zone*/policy：当前 governor 名字，可读写，能动态切换 governor。cooling_device*/cur_state：当前冷却档位，可读写，写进去能手动测试 cooling device。
调试时我习惯先cat thermal_zone*/type确认 zone 都在，再cat thermal_zone*/temp看温度是否合理，然后echo一个值到cooling_device*/cur_state验证 cooling device 能不能动。这三步能快速定位问题出在哪一层。
6.2 用 trace 和 debugfs 看触发链路
sysfs 只能看状态，看不到"为什么触发"。要追触发链路，得用 tracepoint。thermal 提供了thermal_temperature、thermal_zone_trip、cdev_update等 tracepoint，打开后能看到温度变化、trip 命中、cooling device 更新的完整序列。
echo 1 > /sys/kernel/debug/tracing/events/thermal/enable cat /sys/kernel/debug/tracing/trace_pipe实测中这套 trace 帮我定位过一次"温度到了但没降频"的问题：trace 显示 trip 命中了，但cdev_update没出现，说明 governor 判定后没下发到 cooling device。最后查到是权重配置问题，governor 算出来的目标档位和当前档位一样，所以没下发。这种问题光看 sysfs 是看不出来的。
6.3 手动触发 trip 验证策略
不想真的把板子加热到 85 度，可以用thermal_zone*/emul_temp节点模拟温度。写一个值进去，框架会当成真实温度处理，触发对应的 trip。这是验证策略最快的方式，不用真的制造高温。
注意：
emul_temp需要内核编译时打开CONFIG_THERMAL_EMULATION，生产内核通常不开，调试内核才开。用完记得清零，否则会一直用模拟值。
7. 几个容易踩的坑与经验总结
7.1 轮询延迟配错导致响应迟钝
polling-delay默认值往往偏大，有些平台默认 1000ms 甚至更长。如果温度上升很快，1 秒的轮询间隔意味着可能超调很多才触发散热。我的做法是：正常轮询设 500ms 到 1000ms，被动散热触发后的polling-delay-passive设 100ms 到 250ms，保证进入散热状态后响应够快。
但也不能一味调小，轮询太频繁会增加 CPU 开销，尤其传感器读取走慢速总线（如 I2C）时，频繁读会拖慢总线。要在响应速度和开销之间找平衡。
7.2 多 zone 之间的相互干扰
复杂 SoC 上往往有多个 thermal zone，比如 CPU、GPU、DDR 各一个。它们可能共享 cooling device（比如都请求 CPU 降频），也可能互相影响温度。如果两个 zone 都绑了同一个 CPU cooling device，一个要降频一个不要，最终档位取决于 governor 的仲裁逻辑，容易出现"这边降了那边又升"的震荡。
处理办法是明确 cooling device 的归属，尽量让一个 cooling device 只被一个 zone 主导，或者用 power_allocator 统一管理。实在要共享，权重配置要拉开差距，避免势均力敌。
7.3 传感器精度与校准问题
有些传感器的原始值需要校准，比如带偏移量或需要查表转换。如果驱动里校准没做对，读出来的温度整体偏高或偏低，会导致 trip 提前或延后触发。我遇到过一块板子温度读数整体偏高 8 度，导致系统频繁降频，实际芯片温度并不高。后来在驱动里加了偏移校准才正常。
校准数据通常来自芯片手册或产线标定，没有标定数据时，可以用外部温度计对比，手动加个偏移量。这个偏移量最好做成设备树属性，方便不同批次调整。
7.4 内核版本差异带来的接口变化
thermal framework 在 4.x 到 6.x 之间经历了不少重构，比如thermal_zone_device的注册接口从thermal_zone_device_register演进出带更多参数的版本，governor 的注册方式也有调整。跨版本移植代码时，不能照搬函数签名，要先确认目标内核的头文件。
我的习惯是：拿到一个新内核版本，先看include/linux/thermal.h里的结构体定义和函数声明，再对照drivers/thermal/下的实现，确认接口没变再动手。直接抄旧代码，编译报错还是小事，接口语义变了但签名没变才最坑。
8. 把架构装进脑子：一张心智图
捋完这一圈，thermal framework 的通用架构其实可以浓缩成一条链：传感器驱动注册 zone → zone 按 polling 或中断读温度 → 温度命中 trip → governor 根据 trip 和权重算目标档位 → 调用 cooling device 的 set_cur_state → 硬件执行散热。用户空间通过 sysfs 观察和干预这条链的每个环节，trace 则记录链上每个事件。
理解这条链之后，遇到温控问题就有了排查顺序：先确认温度读数对不对（传感器层），再看 trip 有没有命中（核心层），然后看 governor 有没有算出动作（策略层），最后看 cooling device 有没有执行（执行层）。按这个顺序走，基本不会漏。
thermal framework 的代码量不算小，但架构思想是清晰的。真正花时间的不是理解框架，而是理解具体平台的热特性和调参。框架给你的是工具，怎么用好还得靠对硬件的理解。我调过的每个平台，最终稳定的参数都不一样，没有一套放之四海皆准的配置。多 dump 数据、多做对比实验，比死记参数有用得多。
