热敏传感器 THERMAL 驱动

本文档介绍 RK3588 内部温度传感器（TS-ADC）在 Linux 6.1 内核中的 thermal zone / cooling device 框架、设备树配置和温度监控方法。

适用范围： RK3588 Linux 6.1 Debian 12 / Ubuntu 22.04 系统，C-3588LQ V1.0 + SHIMETAPI-M5-R2A V1.0 底板。

1. 概念基础

1.1 Thermal 子系统

RK3588 内部有多个温度传感器（TS-ADC），每个对应一个 thermal zone（温控区域）：

SoC 中央（soc-thermal）
大核 0 / 1（bigcore0/1-thermal），Cortex-A76 集群
小核（littlecore-thermal），Cortex-A55 集群
Center（center-thermal）
GPU（gpu-thermal），Mali-G610
NPU（npu-thermal），6 TOPS NPU

工作流：

TS-ADC 采集 → thermal_zone → trip_point → governor → cooling device
   (温度)     (区域模型)       (温度阈值)    (策略)       (降频/关核)

简单说：温度超过 trip_point 设的阈值后，governor（管理策略）决定怎么响应，让 cooling device（冷却设备）去降频或关核，把温度压回安全范围。

1.2 测量范围 / 精度

项	说明
测量范围	-40 °C ~ 125 °C
精度	±2 °C
读数	sysfs 中以 m°C 计，整数
高温中断	支持

2. 准备工作

2.1 硬件清单

组件	型号/规格	数量	备注
主控板	C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板	1	内置温度传感器
调试串口线	USB 转 TTL（3.3V）	1	波特率 1500000

温度传感器为芯片内置，无需外部引脚，这一章同样不需要额外接线。

3. 软件准备

3.1 内核配置

除了 thermal 框架本身，还要打开与 cpufreq / devfreq 的联动，温度上来才有手段降频：

CONFIG_THERMAL=y
CONFIG_THERMAL_WRITABLE_TRIPS=y
CONFIG_THERMAL_DEFAULT_GOV_STEP_WISE=y
CONFIG_THERMAL_GOV_STEP_WISE=y
CONFIG_THERMAL_GOV_POWER_ALLOCATOR=y
CONFIG_ROCKCHIP_THERMAL=y          /* RK3588 TS-ADC */
CONFIG_CPU_THERMAL=y              /* cpufreq 联动 */
CONFIG_DEVFREQ_THERMAL=y          /* GPU / NPU 联动 */
CONFIG_OF=y

3.2 设备树

tsadc 节点描述传感器本体；下面每个 thermal zone 再声明各自的阈值（trips）和关联的冷却设备：

/* SoC 中央温度 */
tsadc: tsadc@fe720000 {
    compatible = "rockchip,rk3588-tsadc";
    reg = <0x0 0xfe720000 0x0 0x100>;
    interrupts = <GIC_SPI 96 IRQ_TYPE_LEVEL_HIGH>;
    clocks = <&cru CLK_TSADC>, <&cru PCLK_TSADC>;
    clock-names = "tsadc", "apb_pclk";
    resets = <&cru SRST_TSADC>;
    reset-names = "tsadc-apb";
    /* 各 zone 阈值（m°C），可由 governor 改写 */
    rockchip,grf = <&sys_grf>;
    #thermal-sensor-cells = <0>;
    status = "okay";
};

/* CPU thermal zone */
cpu-thermal {
    polling-delay = <1000>;
    thermal-sensors = <&tsadc 4>;
    trips {
        cpu-crit: cpu-crit {
            temperature = <110000>;     /* 110 °C */
            hysteresis = <2000>;         /* 2 °C */
            type = "critical";
        };
        cpu-warm: cpu-warm {
            temperature = <80000>;      /* 80 °C 降频 */
            hysteresis = <2000>;
            type = "passive";
        };
    };
    cooling-devices = <&cpu0_thermal_state 0 ...>;     /* 关联 cpufreq */
};

/* GPU thermal zone */
gpu-thermal {
    polling-delay = <1000>;
    thermal-sensors = <&tsadc 5>;
    /* 类似 trips / cooling */
};

/* NPU thermal zone */
npu-thermal {
    polling-delay = <1000>;
    thermal-sensors = <&tsadc 6>;
};

TS-ADC 通道编号（&tsadc N）：0 = soc-thermal，1/2 = bigcore0/1，3 = littlecore，4 = center，5 = gpu，6 = npu。

4. 设备端温度

以下命令都在板子上执行，先把所有温区的温度读出来，再核对阈值和策略。

4.1 查看全部 thermal zone

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

实机输出：

thermal_zone0 (soc-thermal): 39769
thermal_zone1 (bigcore0-thermal): 39769
thermal_zone2 (bigcore1-thermal): 39769
thermal_zone3 (littlecore-thermal): 40692
thermal_zone4 (center-thermal): 39769
thermal_zone5 (gpu-thermal): 39769
thermal_zone6 (npu-thermal): 39769

本机共 7 个 zone，覆盖 SoC / 大核×2 / 小核 / center / GPU / NPU。读数单位是 m°C：39769 / 1000 = 39.769 °C，40692 / 1000 = 40.692 °C（小核略高）。

4.2 查当前 / 设定 trip_point

# 当前 trip_point（被动降频 / 紧急关机温度）
cat /sys/class/thermal/thermal_zone*/trip_point_0_temp
cat /sys/class/thermal/thermal_zone*/trip_point_0_type

# 冷却设备（如 cpufreq 状态）
ls /sys/class/thermal/cooling_device*

4.3 查 governor

cat /sys/class/thermal/thermal_zone0/policy
# 输出示例：step_wise 或 user_space

输出 step_wise 表示超温后逐级加大冷却力度的策略。

4.4 连续记录温度

# 每秒采样 soc-thermal，写到日志
(while true; do
    echo "$(date +%H:%M:%S) $(cat /sys/class/thermal/thermal_zone0/temp)"
    sleep 1
done) > /tmp/thermal.log

后续可用 gnuplot / matplotlib 画折线图。

5. 用户态工具（可选）

5.1 psensor（图形化，桌面端）

apt install -y psensor
psensor

实时图形化展示 CPU/GPU/NPU 温度。

5.2 lm-sensors

apt install -y lm-sensors
sensors

lm-sensors 主要支持外部传感器，RK3588 内部 TS-ADC 一般不在 sensors 列表中（需 vendor patch）。

6. 设备树调整阈值（PC 端）

如需修改降频或保护温度：

[电脑端] 编辑板级 .dts：

/* 大核降频阈值 */
&cpu_big0_thermal {
    trips {
        cpu-big0-warm {
            temperature = <75000>;    /* 75 °C */
            hysteresis = <5000>;
            type = "passive";
        };
    };
};

/* 临界温度（强制关机） */
&cpu_big0_thermal {
    trips {
        cpu-big0-crit {
            temperature = <105000>;   /* 105 °C */
            hysteresis = <2000>;
            type = "critical";
        };
    };
};

电脑端 重新编译烧录：

./build.sh kernel
./mkfirmware.sh

烧录重启后，用 4.2 的命令核对 trip_point 已换成新阈值。

7. 代码解读

7.1 驱动注册

TS-ADC 驱动同样是 platform driver：

// drivers/thermal/rockchip_thermal.c（简化）

static const struct of_device_id rockchip_thermal_id[] = {
    { .compatible = "rockchip,rk3588-tsadc" },
    { /* sentinel */ }
};

static struct platform_driver rockchip_thermal_driver = {
    .probe  = rockchip_thermal_probe,
    .remove = rockchip_thermal_remove,
    .driver = {
        .name = "rockchip-thermal",
        .of_match_table = rockchip_thermal_id,
    },
};

7.2 thermal_core 调用链

cat 一次温度文件，内核里经过的路径：

用户空间: cat /sys/class/thermal/thermal_zone0/temp
  → read() sysfs
    → thermal_zone_get_temp()             /* thermal core */
      → zone->ops->get_temp()              /* Rockchip driver */
        → rk_tsadc_get_temp()
          → 读 TSADC 寄存器，转换 m°C
          → 返回给 core
            → 用户空间读出

8. 故障排除

8.1 温度不会变化 / 一直是 0 或 -1

dmesg | grep -i tsadc
lsmod | grep -E 'rockchip_thermal|cpufreq_dt'

可能原因：

DTS tsadc 节点未 enable
内核没编译 CONFIG_ROCKCHIP_THERMAL
TS-ADC 时钟异常：cat /sys/kernel/debug/clk/clk_tsadc/clk_rate

8.2 温度异常高

环境温度过高 / 散热不良 / 负载过高。先排查硬件冷却与负载，再考虑降温度阈值。

8.3 自动关机的阈值不生效

检查 governor 是否为 step_wise
检查关联的 cooling-device 是否到位（cpufreq、devfreq）