G32S10 WDT HAL 接口

1. 分层关系

WDT SDK 分为寄存器定义、LL 层和 HAL 层。

HAL 层基于 LL 层实现，面向业务侧使用；LL 层面向寄存器级控制和底层调试使用。

1.1 IR_CLR IC 限制

G32S10 WDT 的 IR_CLR 不能作为启动、初始化或停止阶段的预清寄存器使用。只能在对应 IR 状态位已置位后写入清除。

• DIRECT 模式不需要清 WDT 中断状态。

• IRQ 后复位模式下，FULL 到期后由 IRQ handler 先执行用户回调，再清 IR[25]；该清除是硬件进入后续复位阶段的应答。

• 应用不得在 hal_wdt_start_it() 前后直接写 IR_CLR，也不得在回调中提前清除 FULL。

2. 资源模型与公开类型

2.1 模块基地址与实例

WDT 模块当前公开两个实例。

当前SDK中 HP_WDT_IOBASE 和 LP_WDT_IOBASE 定义在 base.h，wdt_regs.h 中提供如下实例宏：

#define HP_WDT        ((wdt_regs_t *)(uintptr_t)HP_WDT_IOBASE)
#define LP_WDT        ((wdt_regs_t *)(uintptr_t)LP_WDT_IOBASE)

说明：

• 实例宏使用 (uintptr_t) 做整数地址到指针的中间转换，避免部分编译器对整数直接转指针产生告警。

• 驱动接口通过 wdt_regs_t * 或 hal_wdt_handle_t.instance 传递外设基地址。

2.2 HAL 公开宏

2.3 HAL 运行状态

typedef enum {
    HAL_WDT_STATE_RESET = 0U,
    HAL_WDT_STATE_READY,
    HAL_WDT_STATE_BUSY,
} hal_wdt_state_t;

典型状态流转如下。

2.4 分频编码

typedef enum {
    HAL_WDT_PRESCALER_1    = WDT_PRESCALER_DIV_1,
    HAL_WDT_PRESCALER_4    = WDT_PRESCALER_DIV_4,
    HAL_WDT_PRESCALER_16   = WDT_PRESCALER_DIV_16,
    HAL_WDT_PRESCALER_64   = WDT_PRESCALER_DIV_64,
    HAL_WDT_PRESCALER_256  = WDT_PRESCALER_DIV_256,
    HAL_WDT_PRESCALER_1024 = WDT_PRESCALER_DIV_1024,
} hal_wdt_prescaler_t;

2.5 HAL 配置结构

typedef struct {
    uint32_t timeout_ms;
    uint32_t clock_hz;
    uint8_t prescaler;
    bool auto_prescaler;
    uint8_t reset_mode;
} hal_wdt_config_t;

timeout_ms 不支持配置为 0。HAL 层不提供直接配置原始 FULL 值的配置字段；如果需要寄存器级控制，可以使用 LL 层接口。

2.6 HAL 回调与句柄

typedef void (*hal_wdt_callback_t)(hal_wdt_handle_t *hwdt,
                                   uint32_t event_mask);

struct hal_wdt_handle {
    wdt_regs_t *instance;
    hal_wdt_state_t state;
    hal_wdt_config_t init;
    bool configured;
    void *user_data;
    hal_wdt_callback_t timeout_callback;
    volatile bool irq_ack_pending;
    volatile bool irq_callback_active;
};

回调仅用于 HP_WDT 中断后复位模式。回调运行在 IRQ 上下文中，应避免执行阻塞操作。

3. HAL 接口规范

3.1 HAL 层实现边界

HAL 层负责：

• 检查实例、句柄、指针和参数合法性。

• 维护 RESET、READY、BUSY 状态。

• 根据 timeout_ms、clock_hz 和分频配置计算 FULL 装载值。

• 提供直接复位模式启动接口和中断后复位模式启动接口。

• 为 HP_WDT 提供中断状态读取、清除、回调注册和 IRQ 处理。

HAL 层不负责：

• 注册或使能 CPU 侧中断控制器。

• 在中断回调内做业务保存动作。

3.2 默认配置、初始化和反初始化

3.2.1 hal_wdt_config_default

error_code_t hal_wdt_config_default(hal_wdt_config_t *config);

功能：填充一份 HAL 默认配置。

默认配置如下。

3.2.2 hal_wdt_handle_init

error_code_t hal_wdt_handle_init(hal_wdt_handle_t *hwdt,
                                 wdt_regs_t *instance);

功能：初始化 HAL 句柄并绑定 WDT 实例。

补充说明：

• 该接口只初始化软件句柄，不配置硬件寄存器。

• 调用成功后状态为 HAL_WDT_STATE_RESET。

3.2.3 hal_wdt_init

error_code_t hal_wdt_init(hal_wdt_handle_t *hwdt);

功能：初始化 WDT 硬件到可配置状态。

补充说明：

• 调用该接口前需要先调用 hal_wdt_handle_init()。

• 该接口会关闭 WDT 计数器并屏蔽 WDT 中断。LL 层只有在 IR[25] 已经置位时才会清除 FULL 状态，不会无条件预写 IR_CLR。

• 调用成功后状态为 HAL_WDT_STATE_READY。

• 调用成功后 configured 为 false，需要继续调用 hal_wdt_config() 后才能启动。

3.2.4 hal_wdt_deinit

error_code_t hal_wdt_deinit(hal_wdt_handle_t *hwdt);

功能：反初始化 WDT HAL 句柄和硬件状态。

补充说明：

• 该接口会关闭计数器并屏蔽中断，但不会清除中断状态或对 WDT 模块执行软复位。

• 该接口会清空 init、configured、user_data 和回调。

• 调用成功后状态为 HAL_WDT_STATE_RESET。

3.3 配置和超时换算

3.3.1 hal_wdt_config

error_code_t hal_wdt_config(hal_wdt_handle_t *hwdt,
                            const hal_wdt_config_t *config);

功能：根据 HAL 配置计算 FULL 值并写入 WDT 寄存器。

配置规则：

• timeout_ms 必须大于等于 HAL_WDT_TIMEOUT_MS_MIN。

• clock_hz 必须非 0。

• reset_mode 必须为 HAL_WDT_RESET_DIRECT 或 HAL_WDT_RESET_IRQ。

• auto_prescaler == true 时，HAL 自动选择可容纳目标超时时间的最小分频。

• auto_prescaler == false 时，HAL 使用 config->prescaler 指定的分频。

• 配置成功后，HAL 会默认使能 RTC 时钟输入。

• 配置成功后，hwdt->configured 置为 true。

3.3.2 hal_wdt_timeout_calc

error_code_t hal_wdt_timeout_calc(uint32_t timeout_ms,
                                  uint32_t clock_hz,
                                  uint8_t prescaler,
                                  uint32_t *full_value_out);

功能：在指定分频条件下，根据目标超时时间计算 FULL 装载值。

换算方式：

full_value = ceil(timeout_ms * clock_hz / (1000 * divider))

其中 divider 由 prescaler 对应到 1 / 4 / 16 / 64 / 256 / 1024。

3.3.3 hal_wdt_timeout_auto_calc

error_code_t hal_wdt_timeout_auto_calc(uint32_t timeout_ms,
                                       uint32_t clock_hz,
                                       uint8_t *prescaler_out,
                                       uint32_t *full_value_out);

功能：自动选择分频并计算 FULL 装载值。

补充说明：

• 自动分频从最小分频开始尝试。

• 第一个能让 FULL 值落入合法范围的分频会被选中。

• 该策略优先保证计数精度。

3.3.4 hal_wdt_full_value_get

error_code_t hal_wdt_full_value_get(const hal_wdt_handle_t *hwdt,
                                    uint32_t *full_value_out);

功能：读取当前 FULL 寄存器值。

补充说明：

• HAL 层不提供直接写 FULL 的接口。

• FULL 值由 hal_wdt_config() 根据超时时间和分频写入。

3.4 启动、停止、喂狗和读数

3.4.1 hal_wdt_start

error_code_t hal_wdt_start(hal_wdt_handle_t *hwdt);

功能：以直接复位模式启动 WDT。

启动流程：

1. 检查句柄状态必须为 READY。

2. 检查 configured 必须为 true。

3. 检查当前配置必须为 HAL_WDT_RESET_DIRECT。

4. 使能 WDT 模块时钟。

5. 屏蔽 WDT FULL 中断；不清除 IR_CLR。

6. 清计数器。

7. 使能计数器。

8. 状态切换为 HAL_WDT_STATE_BUSY。

3.4.2 hal_wdt_start_it

error_code_t hal_wdt_start_it(hal_wdt_handle_t *hwdt);

功能：以中断后复位模式启动 HP_WDT。

补充说明：

• 该接口会打开 WDT 模块时钟、使能 FULL 中断、清计数器并启动计数。

• CPU 侧中断控制器、向量表和 IRQ 使能需要由上层系统完成。

3.4.3 hal_wdt_stop

error_code_t hal_wdt_stop(hal_wdt_handle_t *hwdt);

功能：停止 WDT 计数。

补充说明：

• 该接口会关闭计数器和 WDT 中断。

• 调用成功后状态为 HAL_WDT_STATE_READY。

• 已生效配置仍保留，可再次调用启动接口。

3.4.4 hal_wdt_feed

error_code_t hal_wdt_feed(hal_wdt_handle_t *hwdt);

功能：喂狗，即清除当前 WDT 计数器。

3.4.5 hal_wdt_count_get

error_code_t hal_wdt_count_get(const hal_wdt_handle_t *hwdt,
                               uint32_t *count_out);

功能：读取当前 WDT 计数值。

3.5 中断模式和回调

3.5.1 hal_wdt_interrupt_status_get

error_code_t hal_wdt_interrupt_status_get(const hal_wdt_handle_t *hwdt,
                                          uint32_t *status_out);

功能：读取 HP_WDT 中断状态。

补充说明：

• 当前 HAL 只返回 HAL_WDT_INTERRUPT_MASK 范围内的状态位。

• 对 LP_WDT 调用该接口时，status_out 会被置 0，并返回 IM_ERR_UNSUPPORTED。

3.5.2 hal_wdt_interrupt_status_clear

error_code_t hal_wdt_interrupt_status_clear(hal_wdt_handle_t *hwdt);

功能：清除 HP_WDT FULL 中断状态。

补充说明：

• 只能由 HAL IRQ handler 在用户回调返回后调用；其他阶段返回 IM_ERR_NOT_READY，避免触发 IC 缺陷。

• 在中断后复位模式下，清除 FULL 中断标志会让硬件继续进入复位流程。

• 如果需要在复位前执行用户处理，应在清除标志前完成。

3.5.3 hal_wdt_callback_register

error_code_t hal_wdt_callback_register(hal_wdt_handle_t *hwdt,
                                       hal_wdt_callback_t callback,
                                       void *user_data);

功能：注册 HP_WDT FULL 中断回调。

3.5.4 hal_wdt_irq_handler

void hal_wdt_irq_handler(hal_wdt_handle_t *hwdt);

功能：WDT HAL IRQ 处理入口。

处理流程：

1. 检查句柄和 WDT 实例合法性；非法句柄或实例直接返回。

2. 读取 HAL_WDT_INTERRUPT_MASK 范围内的 pending 状态；没有 pending 时返回。

3. 设置 irq_ack_pending 和 irq_callback_active，防止重入。

4. 调用用户 timeout_callback。

5. 回调返回后清除 irq_callback_active。

6. 清除 FULL 中断状态，并清除 irq_ack_pending。

补充说明：

• 该 IRQ 处理入口只用于 HP_WDT 中断后复位模式。LP_WDT 不支持该模式，hal_wdt_start_it() 会返回 IM_ERR_UNSUPPORTED。

• hal_wdt_irq_handler() 当前只校验实例是否属于 HP_WDT/LP_WDT，不会额外拒绝 LP_WDT；应用不应为 LP_WDT 调用该入口。

• 清除 FULL 中断标志后，硬件在中断后复位模式下会继续进入复位流程。

• 因此需要在复位前执行的用户代码应放在 timeout_callback 中。

3.6 软复位

3.6.1 hal_wdt_soft_reset

error_code_t hal_wdt_soft_reset(hal_wdt_handle_t *hwdt);

功能：触发 WDT 模块软复位。

补充说明：

• WDT 模块软复位后，模块寄存器会恢复默认状态。

• HAL 层同步清空当前配置、configured、user_data 和回调。

• 调用成功后状态置为 HAL_WDT_STATE_RESET。

3.6.2 hal_wdt_soft_reset_status_get

error_code_t hal_wdt_soft_reset_status_get(const hal_wdt_handle_t *hwdt,
                                           uint32_t *status_out);

功能：读取 WDT 软复位完成状态。

3.6.3 hal_wdt_soft_reset_status_clear

error_code_t hal_wdt_soft_reset_status_clear(hal_wdt_handle_t *hwdt);

功能：清除 WDT 软复位完成状态。

3.7 调试和状态查询

3.7.1 hal_wdt_regs_dump

error_code_t hal_wdt_regs_dump(const hal_wdt_handle_t *hwdt);

功能：打印 WDT 关键寄存器值。

补充说明：

• 该接口受 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_WDT_ENABLE_DEBUG_HELPERS 控制。

• 调试未开启时接口保留，但返回 IM_ERR_UNSUPPORTED。

3.7.2 hal_wdt_state_get

error_code_t hal_wdt_state_get(const hal_wdt_handle_t *hwdt,
                               hal_wdt_state_t *state_out);

功能：读取 HAL 句柄状态。

4. 当前实现约束与行为说明

4.1 中断后复位

中断后复位模式的关键行为如下。

• FULL 到达后先置中断状态。

• HAL IRQ handler 会先调用用户回调，再清中断状态。

• 清除 FULL 中断状态后，硬件继续进入复位流程。

因此，复位前必须执行的用户代码应放在回调中，而不是放在 hal_wdt_irq_handler() 返回后的路径中。

4.2 软复位后的 HAL 状态

hal_wdt_soft_reset() 会让 WDT 模块寄存器恢复默认状态，因此 HAL 层同步将句柄状态置为 HAL_WDT_STATE_RESET，并清除当前配置和回调相关信息。

软复位后如果需要重新使用 WDT，建议按如下顺序重新执行：

1. hal_wdt_init()

2. hal_wdt_config()

3. hal_wdt_start() 或 hal_wdt_start_it()

5. 典型用法

5.1 喂狗流程

error_code_t example_wdt_feed(hal_wdt_handle_t *hwdt)
{
    return hal_wdt_feed(hwdt);
}

喂狗接口只允许在 HAL_WDT_STATE_BUSY 状态调用。直接复位模式下，业务侧需要确保喂狗周期短于配置的 WDT 超时时间。