G32S10 WDT Middleware 接口

1. 构建配置与文件组织

1.1 文件职责

2. 资源模型与公开类型

2.1 实例

两种实例均支持直接复位模式。当前只有 HP_WDT 支持中断后复位模式。

2.2 公开枚举

2.2.1 im_wdt_instance_t

typedef enum {
    IM_WDT_INSTANCE_HP = 0,
    IM_WDT_INSTANCE_LP,
} im_wdt_instance_t;

2.2.2 im_wdt_reset_mode_t

typedef enum {
    IM_WDT_RESET_DIRECT = 0,
    IM_WDT_RESET_IRQ,
} im_wdt_reset_mode_t;

IM_WDT_RESET_IRQ 与 IM_WDT_INSTANCE_LP 组合时，im_wdt_init() 返回 IM_ERR_UNSUPPORTED。

2.2.3 im_wdt_prescaler_t

typedef enum {
    IM_WDT_PRESCALER_1 = 0,
    IM_WDT_PRESCALER_4,
    IM_WDT_PRESCALER_16,
    IM_WDT_PRESCALER_64,
    IM_WDT_PRESCALER_256,
    IM_WDT_PRESCALER_1024,
} im_wdt_prescaler_t;

这些枚举值与 HAL 分频字段编码一致。除特别说明外，应优先使用 auto_prescaler = true，由 HAL 根据目标超时和实际 RTCLK 自动选择分频。

2.3 单例和生命周期

im_wdt_* 接口管理模块内的一个静态单例，没有公开设备句柄。一个系统只能同时使用一个 WDT 实例和一个配置。

MID 内部主要状态如下：

error_code_t im_wdt_config_default(im_wdt_config_t *config);

error_code_t im_wdt_init(const im_wdt_config_t *config);

error_code_t im_wdt_start(void);

error_code_t im_wdt_feed(void);

error_code_t im_wdt_stop(void);

error_code_t im_wdt_restart(void);

typedef void (*im_wdt_timeout_callback_t)(void *user_data);

4. 行为约束与资源管理

4.1 HP/LP 模式约束

4.2 IRQ 资源

• HP_WDT IRQ 模式使用调用方指定的 irq_id，典型值为 IRQ_TCU_WDT。

• MID 在 im_wdt_start() 中注册并使能 IRQ，在停止、重新初始化和重启前释放。

• irq_id 必须大于 IRQ_PLIC_START 且小于 IRQ_NUMS。

• CONFIG_IRQ_SIMPLE_DISPATCH=y 时，普通 PLIC 注册接口可能返回 IM_ERR_UNSUPPORTED，此时只能使用 DIRECT 模式。

• 其它模块已经注册同一个 IRQ 时，MID 返回 IM_ERR_ALREADY_REGISTERED，不会抢占该 IRQ。

4.3 并发和线程约束

• MID 使用内部互斥锁保护初始化、启动、停止和重启流程。

• im_wdt_feed() 可以在任务中调用，不能在 WDT 回调内部调用。

• 多个任务不应无协调地重复启动或停止 WDT。

• WDT 回调在 IRQ 上下文执行，不能调用 MID 控制 API。

4.4 重新配置和时钟变化

• WDT 运行时调用 im_wdt_init() 返回 IM_ERR_BUSY。需要先停止 WDT。

• im_wdt_start() 使用已保存的配置，不重新查询 CPM。

• 如果 CPM RTCLK 在初始化后发生变化，应停止 WDT、重新调用 im_wdt_init()，再启动；或直接使用 im_wdt_restart()。

5. 典型用法

5.1 HP_WDT 直接复位看门狗

#include "im_error.h"
#include "im_time.h"
#include "im_wdt.h"

error_code_t wdt_keepalive_init(void)
{
    im_wdt_config_t config;
    error_code_t ret;

    ret = im_wdt_config_default(&config);
    if (ret != IM_OK) {
        return ret;
    }

    config.instance = IM_WDT_INSTANCE_HP;
    config.timeout_ms = 5000U;
    config.auto_prescaler = true;
    config.reset_mode = IM_WDT_RESET_DIRECT;

    ret = im_wdt_init(&config);
    if (ret != IM_OK) {
        return ret;
    }

    return im_wdt_start();
}

error_code_t wdt_keepalive_feed(void)
{
    return im_wdt_feed();
}

应用应以明显短于 5000 ms 的周期调用 wdt_keepalive_feed()。示例程序使用 1000 ms 周期。

5.2 LP_WDT 直接复位看门狗

im_wdt_config_t config;
error_code_t ret;

ret = im_wdt_config_default(&config);
if (ret != IM_OK) {
    return ret;
}

config.instance = IM_WDT_INSTANCE_LP;
config.timeout_ms = 5000U;
config.auto_prescaler = true;
config.reset_mode = IM_WDT_RESET_DIRECT;

ret = im_wdt_init(&config);
if (ret == IM_OK) {
    ret = im_wdt_start();
}

LP_WDT 不能配置为 IM_WDT_RESET_IRQ，超时后直接进入复位流程。

5.3 HP_WDT 中断后复位

static void wdt_timeout_callback(void *user_data)
{
    (void)user_data;
    /* 只执行 ISR 安全且必须在复位前完成的最小动作。 */
}

error_code_t wdt_irq_mode_init(void)
{
    im_wdt_config_t config;
    error_code_t ret;

    ret = im_wdt_config_default(&config);
    if (ret != IM_OK) {
        return ret;
    }

    config.instance = IM_WDT_INSTANCE_HP;
    config.timeout_ms = 3000U;
    config.auto_prescaler = true;
    config.reset_mode = IM_WDT_RESET_IRQ;
    config.irq_id = (uint32_t)IRQ_TCU_WDT;
    config.irq_name = "app_wdt";
    config.timeout_callback = wdt_timeout_callback;
    config.user_data = NULL;

    ret = im_wdt_init(&config);
    if (ret != IM_OK) {
        return ret;
    }

    return im_wdt_start();
}

应用必须在启动 WDT 前完成 IRQ 框架初始化。回调返回后，硬件进入复位流程。

5.4 主动请求复位

error_code_t ret;

ret = im_wdt_restart();
if (ret == IM_OK) {
    /* WDT 已启动最短合法 DIRECT 复位，等待硬件复位。 */
}

成功返回后不要再调用 im_wdt_feed() 或 im_wdt_stop() 尝试取消复位，这些接口会返回 IM_ERR_BUSY。