G32S10 WDT API 概述

1. 文档范围

本文档描述 G32S10 WDT 模块当前 SDK 中对外提供的 HAL 层与 LL 层正式接口，包括公开类型、接口行为、参数约束、返回值约定、典型使用方式以及当前实现限制。

构建前提：

• 必须启用 CONFIG_DRIVER_WDT=y。

• 使用中断后复位模式时，应用还需要在 CPU/PLIC 侧注册并使能 HP_WDT 中断。

2. 资源模型与公开类型

2.1 WDT 硬件能力摘要

HAL 层会在配置 WDT 时默认使能 RTC 时钟输入。

2.2 复位模式

typedef enum {
    HAL_WDT_RESET_DIRECT = WDT_RESET_DIRECT,
    HAL_WDT_RESET_IRQ    = WDT_RESET_IRQ,
} hal_wdt_reset_mode_t;

HAL_WDT_RESET_IRQ 仅用于 HP_WDT。LP_WDT 在 HAL 层配置为该模式时返回 IM_ERR_UNSUPPORTED。

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

3.1 超时计算

HAL 层超时计算使用整数向上取整，避免目标超时时间因为截断而提前触发。

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

当计算结果小于 HAL_WDT_FULL_VALUE_MIN 或大于 HAL_WDT_FULL_VALUE_MAX 时，接口返回 IM_ERR_INVALID_PARAM。

3.2 自动分频

自动分频按如下顺序尝试：

1, 4, 16, 64, 256, 1024

选中第一个能容纳目标超时时间的分频。这样可以在满足 FULL 寄存器范围的前提下尽量提高计数精度。

3.3 HAL 与 LL 的使用边界

推荐业务代码优先使用 HAL 层接口。以下场景可以使用 LL 层接口：

• 板级早期启动阶段，需要最小封装直接访问寄存器。

• 调试 WDT 寄存器行为。

如果对芯片底层不够了解的话，同一个 WDT 实例不建议在运行过程中混用 HAL 和 LL 修改关键控制字段，否则 HAL 句柄中保存的软件状态可能与硬件实际状态不一致。

4. 典型用法

4.1 HP_WDT 直接复位模式

#include "common/im_error.h"
#include "drivers/g32s10/wdt/hal_wdt.h"

static hal_wdt_handle_t hwdt;

error_code_t example_hp_wdt_reset_direct(void)
{
    hal_wdt_config_t config;
    error_code_t ret;

    ret = hal_wdt_handle_init(&hwdt, HP_WDT);
    if (ret != IM_OK) {
        return ret;
    }

    ret = hal_wdt_init(&hwdt);
    if (ret != IM_OK) {
        return ret;
    }

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

    config.timeout_ms = 1000U;
    config.clock_hz = 32768U;
    config.auto_prescaler = true;
    config.reset_mode = HAL_WDT_RESET_DIRECT;

    ret = hal_wdt_config(&hwdt, &config);
    if (ret != IM_OK) {
        return ret;
    }

    return hal_wdt_start(&hwdt);
}

4.2 HP_WDT 中断后复位模式

#include "common/im_error.h"
#include "drivers/g32s10/wdt/hal_wdt.h"

static hal_wdt_handle_t hwdt;

static void hp_wdt_timeout_callback(hal_wdt_handle_t *handle,
                                    uint32_t event_mask)
{
    (void)handle;
    (void)event_mask;

    /* Put reset-before-save code here. */
}

error_code_t example_hp_wdt_irq_reset(void)
{
    hal_wdt_config_t config;
    error_code_t ret;

    ret = hal_wdt_handle_init(&hwdt, HP_WDT);
    if (ret != IM_OK) {
        return ret;
    }

    ret = hal_wdt_init(&hwdt);
    if (ret != IM_OK) {
        return ret;
    }

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

    config.timeout_ms = 1000U;
    config.clock_hz = 32768U;
    config.auto_prescaler = true;
    config.reset_mode = HAL_WDT_RESET_IRQ;

    ret = hal_wdt_config(&hwdt, &config);
    if (ret != IM_OK) {
        return ret;
    }

    ret = hal_wdt_callback_register(&hwdt, hp_wdt_timeout_callback, NULL);
    if (ret != IM_OK) {
        return ret;
    }

    return hal_wdt_start_it(&hwdt);
}

4.3 LP_WDT 直接复位模式

#include "common/im_error.h"
#include "drivers/g32s10/wdt/hal_wdt.h"

static hal_wdt_handle_t hwdt;

error_code_t example_lp_wdt_reset_direct(void)
{
    hal_wdt_config_t config;
    error_code_t ret;

    ret = hal_wdt_handle_init(&hwdt, LP_WDT);
    if (ret != IM_OK) {
        return ret;
    }

    ret = hal_wdt_init(&hwdt);
    if (ret != IM_OK) {
        return ret;
    }

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

    config.timeout_ms = 1000U;
    config.clock_hz = 32768U;
    config.auto_prescaler = true;
    config.reset_mode = HAL_WDT_RESET_DIRECT;

    ret = hal_wdt_config(&hwdt, &config);
    if (ret != IM_OK) {
        return ret;
    }

    return hal_wdt_start(&hwdt);
}

5. 推荐关注的错误码

HAL 层接口返回 error_code_t。常见返回值如下。