Rockchip TSADC 驱动实现

1. 数据结构

rockchip_tsadc_chip 描述 SoC差异：

• channel ids/count；
• conversion table；
• conversion time/trim；
• TSHUT默认；
• initialize/control/irq_ack；
• get_temp/set_alarm/set_tshut/mode。

rockchip_thermal_data 保存 MMIO、clocks、reset、GRF和 sensors。

2. RK3588数据

1
2
3
4
5

channels: 0..6
count: 7
table mode: ADC_INCREMENT
data mask: 9-bit TSADCV4 mask
default chip TSHUT: 95°C, GPIO/OTP active-low

但 DTS显式覆盖为 120°C、mode 0 CRU、active-low，因此实际公共 DTS配置不是 chip默认95°C GPIO。

3. 转换表

RK3588 calibration points：

1
2
3
4

code 215 -> -40°C
code 285 -> 25°C
code 350 -> 85°C
code 395 -> 125°C

驱动在相邻点间整数线性插值，并校验范围。它不是简单固定斜率。

4. Probe

1
2
3
4
5
6
7
8
9
10
11
12

match compatible
 -> allocate data
 -> map MMIO/get IRQ
 -> clocks/reset/GRF/pinctrl
 -> parse TSHUT properties
 -> reset and initialize TSADC
 -> OTP/trim configuration
 -> register 7 OF thermal sensors
 -> request threaded IRQ
 -> program TSHUT
 -> enable channels/controller
 -> panic notifier

5. get_temp

zone callback：

1
2
3
4
5

read channel data register
 -> mask
 -> code_to_temp table/interpolation
 -> subtract sensor trim temperature
 -> milli-Celsius

无效 code返回错误，不能当0°C。

6. set_trips

Thermal Core给 low/high window；driver忽略 low，将 high + trim_temp 转换为 alarm code并写 comparator。超范围时按实现禁用/设置边界，IRQ用于及时 update。

7. IRQ

threaded handler：

• ack pending；
• 对各 sensor调用 thermal_zone_device_update()；
• Core重算 trips/governor；
  -重新编程 alarm。

8. TSHUT

每 channel写 shutdown comparator，并配置 route：

• CRU：硬件复位；
• GPIO/OTP：输出到 PMIC。

这条链不依赖 Linux调度，是 critical软件保护失效后的最后防线。

9. Trim

驱动读取 OTP/NVMEM相关 trim配置并换算为温度修正。读取温度时减去 trim_temp；写 alarm和 TSHUT硬件阈值时则把 trim加回，保持对外温度语义一致。缺失/非法 trim应回退而非随机修正。

10. PM

suspend关闭 sensors/controller/clocks；resume reset、重新 initialize、恢复 TSHUT/alarm并启用。panic notifier打印各 channel温度用于故障分析。

RK3588 七通道温区与冷却拓扑

1. Channel映射

名称来自本树 DTS与 driver注释。

2. Soc zone

1
2
3
4
5

75°C passive threshold, hyst 2°C
85°C passive target, hyst 2°C
115°C critical
polling 1s / passive 20ms
sustainable power 2100mW

3. Cooling map

85°C target绑定：

1
2
3
4

cpu_l0   little cluster
cpu_b0   big cluster 0
cpu_b2   big cluster 1
gpu      devfreq

每项 contribution 1024，上下限均 NO_LIMIT。

4. Local zones

其它六个 zone每个只有115°C critical，没有普通 passive cooling map。其主要作用是发现局部 hotspot并触发安全关机。

5. NPU

npu-thermal 监测 NPU热点，但公共 cooling map不引用 NPU。NPU可能由其它系统监控/devfreq策略管理；不能根据有 thermal zone就断言 Thermal Core会直接降 NPU频率。

6. TSADC节点

1
2
3
4
5
6
7
8

base 0xfec00000
IRQ 397
clock 2MHz
reset tsadc/apb
7 sensor cells
hw TSHUT 120°C
CRU reset
active low

SoC基础节点 disabled，板级 DTS需启用。

7. 软件与硬件阈值

1
2
3

85°C: 开始主要 cooling control
115°C: 软件 critical shutdown
120°C: 硬件 TSHUT/CRU reset

5°C margin是否足够要结合过热斜率、关机耗时和传感器误差验证。

8. Power allocator

控制基于 channel0 soc temp和2100mW sustainable power。局部 big/GPU/NPU温度在到115°C前不参与该 zone PID输入，因此高局部热点场景必须实测。

9. 风扇

公共 soc-thermal map未绑定 pwm-fan。部分板的厂商 pwm-fan通过 rockchip,temp-trips和 system monitor notifier独立控制，形成与 Thermal Core并行路径。

10. 观测

1
2
3
4
5
6

for z in /sys/class/thermal/thermal_zone*; do
  printf '%s ' "$(cat "$z/type")"; cat "$z/temp"
done
for c in /sys/class/thermal/cooling_device*; do
  echo "$(cat "$c/type") $(cat "$c/cur_state")/$(cat "$c/max_state")"
done

Trip、中断、轮询与临界关机

1. Polling

Core delayed work按：

• normal polling delay；
• passive delay；
• disabled/no polling；

安排下一次 update。RK3588 soc zone正常1秒、passive时20ms。

2. Window interrupt

有 set_trips() 的 sensor可把下一高/低边界下发硬件。温度穿越 comparator后 IRQ触发 update，减少纯轮询延迟。

3. Hysteresis

trip进入与退出阈值不同，避免 cooling state在边界快速抖动。它不能替代 governor的动态稳定性设计。

4. Passive

Passive trip不直接等于某一固定频率：

1
2
3
4
5

trip crossed
 -> governor
 -> instance target/power budget
 -> cooling state
 -> cpufreq/devfreq limit

5. Hot

HOT表示平台需要强动作，可通知/调用 hot handler，但通常不如 CRITICAL具备强制关机语义。

6. Critical

Core检测 critical/hot trip并触发相应处理。critical通常调用 orderly_poweroff(true)；若配置了非零 emergency delay，失败后可执行硬关机。

本树 Kconfig emergency delay默认0，主 defconfig未显式改，因此不能假设 software emergency poweroff timer已启用。

7. RK3588 TSHUT

TSADC hardware comparator独立于 Core：

1
2
3

temp reaches 120°C
 -> TSHUT source
 -> CRU reset (DTS mode 0)

即使内核 deadlock或 IRQ丢失仍有机会保护芯片。

8. GPIO模式

mode 1把 TSHUT输出到 pin/PMIC，要求 pinctrl、polarity和板级 PMIC连接正确。当前公共 DTS选择 CRU模式，不走 GPIO。

9. IRQ失效

即便 comparator IRQ异常，1秒 polling仍可能发现升温，但快速 runaway可能来不及。硬件 TSHUT是必要后备。

10. 验证

不要在无安全台架上直接加热到 critical。优先：

• writable trip降低测试阈值；
• thermal emulation（测试内核）；
  -限制负载；
  -观测 event/cdev；
  -独立温度仪校准；
  -最后按硬件认证流程测试 TSHUT。

并发、锁、生命周期与电源管理

1. 并发来源

• polling delayed work；
• sensor IRQ；
• sysfs读写；
• netlink；
• governor切换；
• cdev注册/注销；
• cpufreq/devfreq notification；
• suspend/resume；
• driver remove。

2. Zone锁

zone lock保护温度、mode、governor和 instances。update和 policy切换不能并发破坏 target。sensor get_temp可能睡眠，driver需遵循调用上下文。

3. Cdev锁

同一 cooling device可收到多个 zone target。cdev update锁保护 target聚合和当前 state，避免重复/交错 set_cur_state。

4. 全局列表

zone/cdev/governor全局注册列表受 Core锁保护。新 cdev注册时需尝试绑定已有 zones，反之亦然。

5. Poll work

unregister必须 cancel_delayed_work_sync，防止 zone释放后 polling继续。IRQ driver则先禁止硬件和 synchronize IRQ。

6. Sensor remove

1
2
3
4
5
6

disable TSADC IRQ/channels
 -> unregister zones/devm cleanup
 -> cancel Core work
 -> unregister panic notifier
 -> clock off/reset
 -> free data

实际 devm action顺序必须与 probe逆序依赖一致。

7. Suspend

Rockchip driver：

-关闭 TSADC channels；
-切 pinctrl；
-disable clocks；
-resume reset/initialize；
-恢复 TSHUT、alarm、controller；
-重新读取/update。

8. Cooling PM

CPU/GPU cooling device在 suspend时可能被 cpufreq/devfreq core停用。resume后 zone update应重新施加必要限制，避免短暂无 cap。

9. 错误温度

get_temp失败时 Core不应将其当低温解除 cooling。driver需返回 errno；监控 daemon也应把“无数据”视为故障，而不是0°C。

10. Deadlock

避免在 zone锁内同步触发会回调同一 thermal path的 cpufreq/devfreq notifier。Core和 cooling drivers使用延后更新/既定锁顺序；厂商扩展应保持相同规则。

虚拟温区、通用 ADC 与其它 Thermal 驱动

1. rk_virtual_thermal

Rockchip厂商虚拟温区用于组合/转换多个温度来源或提供平台逻辑。主 defconfig未显式启用 RK_VIRTUAL_THERMAL，不能默认认为 RK3588运行时存在。

2. Generic ADC thermal

thermal-generic-adc.c：

1
2
3
4

IIO channel
 -> read processed/raw
 -> lookup/interpolate temperature table
 -> OF thermal sensor

适合 NTC/外部模拟 sensor。精度依赖电阻、电压基准和转换表。

3. Thermal MMIO

读取单个 MMIO/shared memory温度值并按 DT scale暴露，适合 firmware共享寄存器。必须验证 endian、单位和更新原子性。

4. SCMI

固件提供的 temperature sensors通常通过 SCMI sensor/thermal相关层接入。采样率和 trip编程受 firmware能力限制。

5. PMIC alarm

部分 PMIC thermal driver只提供离散 warning/critical alarm，不一定有连续精确温度；zone语义依设备能力。

6. SoC driver分类

• bandgap/TSADC直接 MMIO；
• firmware/mailbox；
• ACPI；
• PMIC；
• ADC；
• virtual/composite。

它们共享 Thermal Core但寄存器与 calibration完全不同。

7. HWMON传感器

某些外部温度 hwmon driver设置 HWMON_C_REGISTER_TZ，由 hwmon core按 OF引用注册 thermal sensor。无需再写第二个 thermal driver。

8. Composite策略

聚合 max/weighted温度可能隐藏局部热点或增加噪声。若硬件有多个独立 critical sensors，应保留每个局部 critical zone，不只依赖平均值。

9. 选择

1
2
3
4
5

RK3588 die sensor       -> rockchip TSADC
NTC + SARADC            -> generic ADC thermal
外部数字温度芯片        -> hwmon + thermal bridge
firmware managed sensor -> SCMI
虚拟最大值/模型         -> virtual/composite

10. 构建

本目录约132个文件，大部分是其它 SoC。判断实际启用必须同时看 Kconfig、compatible、最终 DT和 probe日志。

RK3588 热设计调优、调试与安全

1. 枚举

1
2
3
4
5
6
7

for z in /sys/class/thermal/thermal_zone*; do
  echo "[$z] $(cat "$z/type")"
  cat "$z/temp"
done
for c in /sys/class/thermal/cooling_device*; do
  echo "[$c] $(cat "$c/type") $(cat "$c/cur_state")/$(cat "$c/max_state")"
done

编号不稳定，按 type识别。

2. 验证配置

1
2
3

zcat /proc/config.gz | grep -E 'THERMAL|ENERGY_MODEL|ROCKCHIP'
dmesg | grep -Ei 'thermal|tsadc|cooling'
cat /sys/class/thermal/thermal_zone*/policy

3. 压力测试

分别和组合加载：

• CPU little/big；
• GPU；
• NPU；
• VPU/ISP；
• memory；
  -存储/网络。

记录温度、频率、cooling state、thermal pressure、功耗和吞吐。

4. 2100mW

sustainable-power=2100 是 power allocator模型输入。调优必须基于整机散热器、风道、环境温度和机壳实测，不可照搬 EVB。

5. Polling

20ms passive polling响应快但增加开销。若 TSADC set_trips IRQ可靠，仍需 Core周期用于 policy。调整前测 CPU开销与温度过冲。

6. 温度校验

片上 sensor测 die热点，红外/热电偶测封装/散热器，两者不可直接要求一致。关注：

• 稳态偏差；
• 动态滞后；
• sensor channel相对关系；
• trim；
  -环境温度。

7. 风扇

确认控制权：

• generic thermal cooling map；
• Rockchip system monitor notifier；
• userspace daemon。

只保留一个主 controller，避免 duty振荡。

8. 常见故障

1
2
3
4
5
6
7

无 zone -> tsadc status/config/probe
固定温度 -> clock/controller/channel
异常负温/高温 -> code/trim/MMIO
不降频 -> cooling map/cdev/policy/EM
频率振荡 -> PID/sustainable power/polling
到 critical不关机 -> trip/mode/poweroff path
重启过早 -> TSHUT阈值/转换/噪声

9. 安全

• trip/policy/emulation root-only；
  -量产禁用 emul_temp；
  -保留 hardware TSHUT；
• critical与 TSHUT留足 margin；
  -不要用脚本持续写低温或 state 0；
  -监控 sensor read error；
  -bootloader也应配置早期热保护；
  -验证 suspend/resume后 TSHUT恢复。

10. 建议基线

1. 保持115°C software critical和120°C TSHUT作为起点；
2. 按产品认证调整，不以提高阈值解决降频；
3. 优先改善散热/风扇/OPP模型；
4. 高环境温度做持续满载；
5. 模拟风扇停转、散热器异常；
6. 验证 orderly shutdown和硬件 reset两级保护。

Thermal 分析文档

原单篇文档已扩展为专题文档集，请从 README.md 开始。

• Thermal子系统架构与源码总览.md
• 源码目录与模块索引.md
• 06-Rockchip-TSADC驱动实现.md
• 07-RK3588七通道温区与冷却拓扑.md

Linux 6.1 Thermal 子系统文档索引

源码：rk3588/kernel-6.1/drivers/thermal/
平台：RK3588 / Rockchip Linux 6.1 厂商树

1
2
3
4

for z in /sys/class/thermal/thermal_zone*; do
  echo "$(cat "$z/type"): $(cat "$z/temp")"
done
cat /sys/class/thermal/cooling_device*/type

Thermal 子系统架构与源码总览

1. 模型

1
2
3
4
5
6
7
8
9
10
11

temperature sensor
        |
 thermal_zone_device
        |
 trips + governor
        |
 thermal_instance
        |
 thermal_cooling_device
        |
 CPUFreq / Devfreq / fan / power actor

2. 对象

• thermal_zone_device：温区、温度、trips、policy；
• thermal_trip：temperature、hysteresis、type；
• thermal_cooling_device：可调 cooling state；
• thermal_instance：某 zone/trip与 cdev的绑定、上下限、weight、target；
• thermal_governor：计算 target；
• sensor ops：get_temp/set_trips等。

3. 更新链

1
2
3
4
5
6
7
8
9

poll/IRQ/driver event
 -> thermal_zone_device_update()
 -> thermal_zone_get_temp()
 -> update trend
 -> handle each trip
 -> governor->throttle()
 -> instance target
 -> thermal_cdev_update()
 -> cdev->set_cur_state()

4. Trip

• active：主动散热；
• passive：降频/功率限制；
• hot：平台定义热状态；
• critical：关机。

hysteresis避免阈值附近抖动。

5. Governors

• step_wise；
• fair_share；
• bang_bang；
• user_space；
• power_allocator。

本树 RK3588主配置默认选择 power_allocator，不是常见默认 step_wise。

6. Interfaces

• sysfs：zone/cdev状态和 policy；
• generic netlink：查询与事件；
• hwmon bridge：温度只读展示；
• tracepoints；
• OF thermal zones；
• uevent。

7. RK3588

RK3588使用 rockchip_thermal.c：

• 7个 TSADC channels；
• code-table插值；
  -高温 IRQ；
  -硬件 TSHUT；
• CRU/GPIO模式；
• suspend/resume；
• panic dump。

DTS定义 soc、bigcore0、bigcore1、littlecore、center、GPU、NPU七个 zone。

8. 冷却拓扑

公共 DTS只有 soc-thermal 的 85°C target绑定：

• little CPU；
• big CPU cluster 0；
• big CPU cluster 1；
• GPU。

其它六个 zone只定义115°C critical trip，不直接绑定 cooling map。

9. 双重保护

• 软件 critical trip：115°C，orderly poweroff；
• TSADC hardware TSHUT：DTS 120°C，CRU reset模式。

硬件阈值高于软件 critical，形成最后防线。

10. 边界

Thermal负责控制策略；hwmon负责观测和 sensor阈值；devfreq/cpufreq实现执行动作；regulator只提供电源资源。不能把这些 sysfs接口混作同一控制平面。

drivers/thermal/ 源码目录与模块索引

1. Core

2. Governors

1
2
3
4
5

gov_step_wise.c
gov_fair_share.c
gov_bang_bang.c
gov_user_space.c
gov_power_allocator.c

3. Cooling

• cpufreq_cooling.c；
• devfreq_cooling.c；
• cpuidle_cooling.c；
• fan cooling由相应 fan driver注册。

4. Generic sensors

• thermal-generic-adc.c；
• thermal_mmio.c；
• SCMI thermal位于 firmware协议相关目录；
• hwmon sensor可反向注册 thermal zone。

5. RK

6. 其它平台

Intel、QCOM TSENS、Tegra soctherm、Samsung TMU、TI bandgap、i.MX、MediaTek、Amlogic、Allwinner等。源码存在不代表 RK3588构建。

7. RK3588主配置

1
2
3
4
5
6
7
8
9
10
11

THERMAL=y
THERMAL_WRITABLE_TRIPS=y
THERMAL_DEFAULT_GOV_POWER_ALLOCATOR=y
THERMAL_GOV_FAIR_SHARE=y
THERMAL_GOV_STEP_WISE=y
THERMAL_GOV_USER_SPACE=y
THERMAL_GOV_POWER_ALLOCATOR=y
CPU_THERMAL=y
DEVFREQ_THERMAL=y
ROCKCHIP_THERMAL=y
ENERGY_MODEL=y

CPU_FREQ_THERMAL 由 CPU_THERMAL 下的 default y间接启用，仍以最终 .config 为准。

8. DTS

rk3588s.dtsi：

• thermal-zones；
• tsadc@fec00000；
• 7 channels；
• 2MHz clock；
• IRQ397；
• TSHUT 120°C/CRU/active low；
• base节点默认 disabled，板级通常 &tsadc { status = "okay"; }。

9. API headers

• include/linux/thermal.h
• include/uapi/linux/thermal.h
• include/trace/events/thermal.h
• DT bindings under Documentation/devicetree/bindings/thermal/