看门狗 WDT 驱动

本文档介绍 RK3588 内置看门狗控制器在 Linux 6.1 内核中的驱动配置、设备树绑定和用户态用法。

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

1. 概念基础

1.1 WDT 是什么

看门狗（Watchdog Timer）是一个硬件定时器：程序必须在计数归零前定期「喂狗」（把计数重置），一旦长时间没人喂，硬件就认定系统挂死，自动复位。这是嵌入式设备无人值守时的最后一道保险。

RK3588 内置多通道 WDT：

特性	说明
计数模式	递减
超时动作	系统复位 / 中断
时钟源	24 MHz（外部 APB 预分频）
超时范围	数十毫秒 ~ 数十秒
预超时	支持 prv / irq

1.2 应用场景

系统死锁自动复位
远程设备心跳监控
安全启动的超时防护
工业控制 / 物联网

2. 准备工作

2.1 硬件清单

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

看门狗为内置模块，无外部引脚，复位信号通过内部总线送达系统复位控制器，所以这一章不需要额外接线。

3. 软件准备

3.1 内核配置

RK3588 的看门狗用的是 DesignWare 的 IP 核，内核配置只需要这几项：

CONFIG_WATCHDOG=y
CONFIG_WATCHDOG_CORE=y
CONFIG_DW_WATCHDOG=y                /* DesignWare 看门狗 */
CONFIG_OF=y

CONFIG_DW_WATCHDOG 是 Synopsys DesignWare WDT，RK3588 使用该 IP 核。

3.2 设备树

wdt: watchdog@fd8d0000 {
    compatible = "snps,dw-wdt";
    reg = <0x0 0xfd8d0000 0x0 0x100>;
    interrupts = <GIC_SPI 117 IRQ_TYPE_LEVEL_HIGH>;
    clocks = <&cru TCLK_WDT>, <&cru PCLK_WDT>;
    clock-names = "tclk", "pclk";
    status = "okay";   /* 默认 disabled，需在板级 dts enable */
};

RK3588 WDT 基地址：WDT@fd8d0000。

4. 设备端 WDT

先在板子上确认现状，再决定要不要改内核或设备树。

4.1 当前是否暴露 watchdog 设备

ls /dev/watchdog*
ls /sys/class/watchdog/

实机输出：

ls: 无法访问 '/dev/watchdog*': 没有那个文件或目录
（ls /sys/class/watchdog/ 为空）

本机未暴露 /dev/watchdog* 节点，原因是本机默认 kernel config 未编译 DW WDT 驱动，或设备树未 enable &wdt。

4.2 内核是否编译 WDT

grep -E '^CONFIG_(WATCHDOG|DW_WATCHDOG)' /boot/config-$(uname -r) 2>&1

如 CONFIG_DW_WATCHDOG=m，可手动 modprobe dw_wdt 加载。

5. 用户态使用（假设已加载）

5.1 启动看门狗

# 激活（启动后内核立即按默认超时计时）
echo V > /dev/watchdog

5.2 喂狗（守护进程模式）

手动喂狗不现实，实际都交给 watchdog 守护进程：它周期性喂狗，一旦系统卡死喂不动了，就由硬件复位：

apt install -y watchdog

cat > /etc/watchdog.conf << 'EOF'
watchdog-device = /dev/watchdog
watchdog-timeout = 15     # 15 秒超时
realtime = yes
priority = 1
EOF

systemctl enable watchdog
systemctl start watchdog

watchdog 守护进程会周期性「喂狗」，系统卡死超 15 秒后自动复位。

5.3 查看状态

# 是否激活
cat /sys/class/watchdog/watchdog0/state        # active / inactive

# 超时（秒）
cat /sys/class/watchdog/watchdog0/timeout

# 预设预超时（GOV）
cat /sys/class/watchdog/watchdog0/pretimeout

5.4 手动复位测试（谨慎！）

这个实验会故意停掉喂狗、让设备自动重启，只在受控环境做：

# ⚠️ 此操作会强制重启设备，仅在受控环境测试
echo V > /dev/watchdog
# 故意停掉 watchdog 守护进程，等超时重启
systemctl stop watchdog

观察串口：内核将在 timeout 秒后打印 Watchdog detected hard LOCKUP，自动重启。

6. 设备树配置（PC 端）

[电脑端] 如出厂 DTS 未 enable WDT：

&wdt {
    status = "okay";
};

电脑端 重新编译烧录：

./build.sh kernel
./mkfirmware.sh

烧录重启后回到 4.1，/dev/watchdog0 出现即配置生效。

6.1 嵌入式启动配置

如需 uboot 阶段也启用 watchdog：

# uboot 中
setenv watchdog_timeout=15
setenv bootcmd "run watchdog_init; ..."

U-Boot 阶段 watchdog 时序与内核需统一，否则会误复位。

7. 代码解读

7.1 内核驱动注册

看门狗驱动同样是 platform driver，按 compatible 匹配设备树：

// drivers/watchdog/dw_wdt.c（简化）

static const struct of_device_id dw_wdt_of_match[] = {
    { .compatible = "snps,dw-wdt" },
    { /* sentinel */ }
};

static struct platform_driver dw_wdt_driver = {
    .probe  = dw_wdt_probe,
    .remove = dw_wdt_remove,
    .driver = {
        .name = "dw-wdt",
        .of_match_table = dw_wdt_of_match,
    },
};

7.2 sysfs 调用链

从写入 /dev/watchdog 到系统复位，中间发生的事：

用户空间: echo V > /dev/watchdog
  → write()                                  /* VFS */
    → watchdog_write()
      → dw_wdt_pet()                         /* 喂狗 */
        → regmap_update_bits(WDT_TORR)       /* 重置计数器 */

用户空间停止喂狗
  → 计数器归零 → 触发中断
    → 系统复位（触发 PMU）→ 自动重启

8. 故障排除

8.1 没有 /dev/watchdog

按顺序检查三处：

内核配置：grep CONFIG_DW_WATCHDOG /boot/config-$(uname -r)，需 =y 或 =m 且已加载。
DTS：cat /proc/device-tree/soc/watchdog@fd8d0000/status 须 "okay"。
加载模块：modprobe dw_wdt。

8.2 频繁意外复位

dmesg | grep -i watchdog
journalctl -b | grep -i watchdog

可能原因：

watchdog-timeout 太短
喂狗线程被优先级更高的进程阻塞
系统实时负载过高（load average）

调整 / 优化喂狗线程，或延长超时。

8.3 看门狗不复位

DTS status = "disabled"
时钟被关闭：检查 cat /sys/kernel/debug/clk/clk_wdt/clk_rate
平台硬件是否阻止复位（特殊电路）