RTOS_WDT使用参考

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	01/31/2024
1.1	Update doc to match the latest driver	07/10/2024

1. 概述¶

Hardware Watchdog 提供超时复位系统的功能，其功能由定时器和复位功能组成，用户可以设定一个超时时间，并在超时时间以内对它进行“喂狗”的操作，重置其内部计数，如果其内部计算达到了设定的超时时间，watchdog 就会对系统进行复位，重启系统。

通常WDT被视作HW Watchdog的缩写。

2. RTOS用法介绍¶

目前 Watchdog 模块只提供 api 调用，需要用户在自己的业务逻辑中对 watchdog 进行管理。

2.1 DRIVER PATH¶

WDT驱动代码位于：<RTK>/proj/sc/driver/sysdriver/watchdog

2.2 CONFIG配置¶

#make menuconfig

BSP Driver Options --->
    [*] Support WatchDog driver

配置WDT的的源文件位于:<RTK>/proj/sc/driver/sysdriver/watchdog<RTK>/proj/sc/driver/sysdriver/watchdog/hal/<platform>/inc/hal_wdt_cfg.h，形如：

#define WDT_CFG_DEFAULT_MARGIN 10
......
struct wdt_cfg wdt_config =
{
    .reg_base = BASE_REG_WDT_PA,
    .irq      = INT_FIQ_WDT,
    .clk_id   = -1,
    .clk_rate = 12000000,
};

其中：

WDT_CFG_DEFAULT_MARGIN：即WDT默认的超时设定，可使用API在运行时重新设定。
wdt_config：包含了WDT的平台相关的硬件设定
- reg_base：用于指定WDT的寄存器基址
- irq：用于指定WDT的硬件中断号
- clk_id：用于指定WDT的时钟编号，如若当前分支未支持CAM_OS_CLK功能或者不希望动态地去获取时钟频率，可指定为'-1'。
- clk_rate：用于指定WDT默认的时钟频率。

2.3 API说明¶

RTK中的WDT驱动API声明位于：<RTK>/proj/sc/driver/sysdriver/watchdog/drv/pub/drv_wdt.h，形如：

2.3.1. drv_wdt_get¶

功能

获取WDT设备凭据
语法
```
void *drv_wdt_get(int wdt_id)
```
返回值

返回值描述

非NULL 该指针是后续使用其他API的凭据（wdt_handle参数）

NULL 失败

2.3.2. drv_wdt_put¶

功能

释放WDT设备
语法
```
void drv_wdt_put(void *wdt_handle)
```
返回值

无

2.3.3. drv_wdt_ping¶

功能

复位WDT计数器，俗称‘喂狗’
语法
```
int drv_wdt_ping(void *wdt_handle)
```
返回值

返回值描述

0 成功

非0 失败

2.3.4. drv_wdt_set_pretimeout¶

功能

设定WDT预超期的时长，它通常配合‘drv_wdt_register_pretimeout_callback’使用

语法

int drv_wdt_set_pretimeout(void *wdt_handle, unsigned int timeout)

返回值

返回值描述

0 成功

非0 失败

2.3.5. drv_wdt_register_pretimeout_callback¶

功能

注册WDT预超期时的回调函数

语法

int drv_wdt_register_pretimeout_callback(void *wdt_handle, drv_wdt_callback callback, void *pdata)

返回值

返回值描述

0 成功

非0 失败

2.3.6. drv_wdt_set_timeout¶

功能

设定WDT超期的时长，如果没有在这个时长内没有周期地使用drv_wdt_ping来‘喂狗’，系统将会复位，俗称‘狗咬’

语法

int drv_wdt_set_timeout(void *wdt_handle, unsigned int timeout)

返回值

返回值描述

0 成功

非0 失败

2.3.7. drv_wdt_start¶

功能

按设定好的或者默认的timeout启动WDT
语法
```
int drv_wdt_start(void *wdt_handle)
```
返回值

返回值描述

0 成功

非0 失败

2.3.8. drv_wdt_stop¶

功能

停止WDT
语法
```
int drv_wdt_stop(void *wdt_handle)
```
返回值

返回值描述

0 成功

非0 失败

2.4 使用示例¶

可参见WDT的测试demo：<RTK>/proj/sc/driver/sysdriver/watchdog/drv/src/drv_wdt_test.c。

常见组合一：不关注预超期的情况

drv_wdt_get
drv_wdt_set_timeout & drv_wdt_start
drv_wdt_ping
drv_wdt_stop & drv_wdt_put

常见组合二：关注预超期的情况

drv_wdt_get
drv_wdt_register_pretimeout_callback & drv_wdt_set_pretimeout
drv_wdt_set_timeout & drv_wdt_start
drv_wdt_ping
drv_wdt_stop & drv_wdt_put

返回值	描述
非NULL	该指针是后续使用其他API的凭据（wdt_handle参数）
NULL	失败