Watchdog

概述

功能简介

看门狗(Watchdog),又称看门狗计时器(Watchdog timer),是一种硬件计时设备。一般有一个输入、一个输出,输入叫做喂狗,输出连接到系统的复位端。当系统主程序发生错误导致未及时清除看门狗计时器的计时值时,看门狗计时器就会对系统发出复位信号,使系统从悬停状态恢复到正常运作状态。

Watchdog接口定义了看门狗操作的通用方法集合,包括:

  • 打开/关闭看门狗设备

  • 启动/停止看门狗设备

  • 设置/获取看门狗设备超时时间

  • 获取看门狗设备状态

  • 喂狗

基本概念

系统正常工作的时候,每隔一段时间输出一个信号到喂狗端,给看门狗清零,这个操作就叫做喂狗。如果超过规定的时间不喂狗,看门狗定时超时,就会给出一个复位信号到系统,使系统复位。

运作机制

在HDF框架中,Watchdog模块接口适配模式采用独立服务模式,如图1所示。在这种模式下,每一个设备对象会独立发布一个设备服务来处理外部访问,设备管理器收到API的访问请求之后,通过提取该请求的参数,达到调用实际设备对象的相应内部方法的目的。独立服务模式可以直接借助HDF设备管理器的服务管理能力,但需要为每个设备单独配置设备节点,增加内存占用。

独立服务模式下,核心层不会统一发布一个服务供上层使用,因此这种模式下驱动要为每个控制器发布一个服务,具体表现为:

  • 驱动适配者需要实现HdfDriverEntry的Bind钩子函数以绑定服务。

  • device_info.hcs文件中deviceNode的policy字段为1或2,不能为0。

Watchdog模块各分层作用:

  • 接口层提供打开看门狗设备、获取看门狗设备状态、启动看门狗设备、设置看门狗设备超时时间、获取看门狗设备超时时间、喂狗、停止看门狗设备超时时间、关闭看门狗设备的接口。

  • 核心层主要提供看门狗控制器的添加、移除以及管理的能力,通过钩子函数与适配层交互。

  • 适配层主要是将钩子函数的功能实例化,实现具体的功能。

图 1 Watchdog独立服务模式结构图

Watchdog独立服务模式结构图

使用指导

场景介绍

对于无法直接观测到的软件异常,我们可以使用看门狗进行自动检测,并在异常产生时及时重置。

接口说明

Watchdog模块提供的主要接口如表1所示,具体API详见//drivers/hdf_core/framework/include/platform/watchdog_if.h。

表 1 看门狗API接口功能介绍

接口名 描述
int32_t WatchdogOpen(int16_t wdtId, DevHandle *handle) 打开看门狗
void WatchdogClose(DevHandle handle) 关闭看门狗
int32_t WatchdogStart(DevHandle handle) 启动看门狗
int32_t WatchdogStop(DevHandle handle) 停止看门狗
int32_t WatchdogSetTimeout(DevHandle handle, uint32_t seconds) 设置看门狗超时时间
int32_t WatchdogGetTimeout(DevHandle handle, uint32_t *seconds) 获取看门狗超时时间
int32_t WatchdogGetStatus(DevHandle handle, int32_t *status) 获取看门狗状态
int32_t WatchdogFeed(DevHandle handle) 清除看门狗定时器(喂狗)

icon-note.gif 说明:
本文涉及的看门狗的所有接口,支持内核态及用户态使用。

开发步骤

使用看门狗的一般流程如下图所示。

图 2 看门狗使用流程图

看门狗使用流程图

打开看门狗设备

在操作看门狗之前,需要调用WatchdogOpen打开看门狗设备,一个系统可能有多个看门狗,通过看门狗ID号来打开指定的看门狗设备:

DevHandle WatchdogOpen(int16_t wdtId, DevHandle *handle);

表 2 WatchdogOpen参数和返回值描述

参数 参数描述
wdtId int16_t类型,看门狗设备号
handle DevHandle类型,看门狗设备句柄
返回值 返回值描述
HDF_SUCCESS 打开看门狗设备成功
负数 打开看门狗设备失败
int16_t wdtId = 0;
int32_t ret;
DevHandle *handle = NULL;

ret = WatchdogOpen(wdtId, handle);    // 打开0号看门狗设备
if (ret != HDF_SUCCESS) {
    HDF_LOGE("WatchdogOpen: open watchdog_%hd failed, ret:%d\n", wdtId, ret);
    return ret;
}

获取看门狗状态

int32_t WatchdogGetStatus(DevHandle handle, int32_t *status); 

表 3 WatchdogGetStatus参数和返回值描述

参数 参数描述
handle DevHandle类型,看门狗设备句柄
status int32_t类型指针,获取到的看门狗状态
返回值 返回值描述
HDF_SUCCESS 获取看门狗状态成功
负数 获取看门狗状态失败
int32_t ret;
int32_t status;

ret = WatchdogGetStatus(handle, &status);    // 获取Watchdog状态
if (ret != HDF_SUCCESS) {
    HDF_LOGE("WatchdogGetStatus: watchdog get status failed, ret:%d\n", ret);
    return ret;
}

设置超时时间

int32_t WatchdogSetTimeout(DevHandle *handle, uint32_t seconds); 

表 4 WatchdogSetTimeout参数和返回值描述

参数 参数描述
handle DevHandle类型,看门狗设备句柄
seconds uint32_t类型,超时时间,单位为秒
返回值 返回值描述
HDF_SUCCESS 设置成功
负数 设置失败
int32_t ret;

ret = WatchdogSetTimeout(handle, 2);    // 设置超时时间2秒
if (ret != HDF_SUCCESS) {
    HDF_LOGE("WatchdogSetTimeout: watchdog set timeOut failed, ret:%d\n", ret);
    return ret;
}

获取超时时间

int32_t WatchdogGetTimeout(DevHandle *handle, uint32_t *seconds);

表 5 WatchdogGetTimeout参数和返回值描述

参数 参数描述
handle DevHandle类型,看门狗设备句柄
seconds uint32_t类型指针,获取的看门狗超时时间
返回值 返回值描述
HDF_SUCCESS 获取看门狗超时时间成功
负数 获取看门狗超时时间失败
 int32_t ret;
 uint32_t timeOut;

 ret = WatchdogGetTimeout(handle, &timeOut);     // 获取超时时间
 if (ret != HDF_SUCCESS) {
     HDF_LOGE("WatchdogGetTimeout: watchdog get timeOut failed, ret:%d\n", ret);
     return ret;
 }

启动看门狗

int32_t WatchdogStart(DevHandle handle);

表 6 WatchdogStart参数和返回值描述

参数 参数描述
handle DevHandle类型,看门狗设备句柄
返回值 返回值描述
HDF_SUCCESS 启动看门狗成功
负数 启动看门狗失败
int32_t ret;

ret = WatchdogStart(handle);    // 启动看门狗
if (ret != HDF_SUCCESS) {
    HDF_LOGE("WatchdogStart: start watchdog failed, ret:%d\n", ret);
    return ret;
}

喂狗

int32_t WatchdogFeed(DevHandle handle);

表 7 WatchdogFeed参数和返回值描述

参数 参数描述
handle DevHandle类型,看门狗设备句柄
返回值 返回值描述
HDF_SUCCESS 喂狗成功
负数 喂狗失败
int32_t ret;

ret = WatchdogFeed(handle);    // 喂狗
if (ret != HDF_SUCCESS) {
    HDF_LOGE("WatchdogFeed: feed watchdog failed, ret:%d\n", ret);
    return ret;
}

停止看门狗

int32_t WatchdogStop(DevHandle handle);

表 8 WatchdogStop参数和返回值描述

参数 参数描述
handle DevHandle类型,看门狗设备句柄
返回值 返回值描述
HDF_SUCCESS 停止看门狗成功
负数 停止看门狗失败
int32_t ret;

ret = WatchdogStop(handle);    // 停止看门狗
if (ret != HDF_SUCCESS) {
    HDF_LOGE("WatchdogStop: stop watchdog failed, ret:%d\n", ret);
    return ret;
}

关闭看门狗设备

当所有操作完毕后,调用WatchdogClose关闭打开的看门狗设备:

void WatchdogClose(DevHandle handle);

表 9 WatchdogClose参数和返回值描述

参数 参数描述
handle DevHandle类型,看门狗设备句柄
WatchdogClose(handle);    // 关闭看门狗

使用实例

下面将基于Hi3516DV300开发板展示使用Watchdog完整操作,步骤主要如下:

  1. 传入看门狗ID号,及空的描述句柄,打开看门狗设备并获得看门狗设备句柄。

  2. 通过看门狗设备句柄及超时时间,设置看门狗设备超时时间。

  3. 通过看门狗设备句柄及待获取超时时间,获取看门狗设备超时时间。

  4. 通过看门狗设备句柄启动看门狗设备。

  5. 通过看门狗设备句柄喂狗。

  6. 通过看门狗设备句柄停止看门狗设备。

  7. 通过看门狗设备句柄关闭看门狗设备。

#include "watchdog_if.h"              // watchdog标准接口头文件
#include "hdf_log.h"                  // 标准日志打印头文件
#include "osal_time.h"                // 标准延迟&睡眠接口头文件

#define WATCHDOG_TEST_TIMEOUT     2
#define WATCHDOG_TEST_FEED_TIME   6

static int32_t TestCaseWatchdog(void)
{
    int32_t i;
    int32_t ret;
    int16_t wdtId = 0;
    int32_t status;
    uint32_t timeout;
    DevHandle *handle = NULL;

    // 打开0号看门狗设备
    ret = WatchdogOpen(wdtId, handle);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("TestCaseWatchdog: open watchdog_%hd failed, ret:%d\n", wdtId, ret);
        return ret;
    }

    // 设置超时时间
    ret = WatchdogSetTimeout(handle, WATCHDOG_TEST_TIMEOUT);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("TestCaseWatchdog: set timeout fail! ret:%d\n", ret);
        WatchdogClose(handle);
        return ret;
    }

    // 获取超时时间
    ret = WatchdogGetTimeout(handle, &timeout);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("TestCaseWatchdog: get timeout fail! ret:%d\n", ret);
        WatchdogClose(handle);
        return ret;
    }
    // 比较设置与获取的超时时间是否一致
    if (timeout != WATCHDOG_TEST_TIMEOUT) {
        HDF_LOGE("TestCaseWatchdog: set:%u, but get:%u", WATCHDOG_TEST_TIMEOUT, timeout);
        WatchdogClose(handle);
        return HDF_FAILURE;
    }
    HDF_LOGI("TestCaseWatchdog: read timeout back:%u\n", timeout);

    // 启动看门狗,开始计时
    ret = WatchdogStart(handle);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("TestCaseWatchdog: start fail! ret:%d\n", ret);
        WatchdogClose(handle);
        return ret;
    }
    // 获取看门狗状态,是否启动
    status = WATCHDOG_STOP;
    ret = WatchdogGetStatus(handle, &status);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("TestCaseWatchdog: get status fail! ret:%d", ret);
        WatchdogClose(handle);
        return ret;
    }
    if (status != WATCHDOG_START) {
        HDF_LOGE("TestCaseWatchdog: status is:%d after start", status);
        WatchdogClose(handle);
        return HDF_FAILURE;
    }

    // 每隔1S喂狗一次
    for (i = 0; i < WATCHDOG_TEST_FEED_TIME; i++) {
        HDF_LOGI("TestCaseWatchdog: feeding watchdog %d times... \n", i);
        ret = WatchdogFeed(handle);
        if (ret != HDF_SUCCESS) {
            HDF_LOGE("TestCaseWatchdog: feed dog fail! ret:%d\n", ret);
            WatchdogClose(handle);
            return ret;
        }
        OsalSleep(1);
    }
    // 由于喂狗间隔小于超时时间,系统不会发生复位,此日志可以正常打印
    HDF_LOGI("TestCaseWatchdog: no reset ... feeding test OK!!!\n");

    ret = WatchdogStop(handle);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("TestCaseWatchdog: stop fail! ret:%d", ret);
        WatchdogClose(handle);
        return ret;
    }
    // 获取看门狗状态,是否停止
    status = WATCHDOG_START;
    ret = WatchdogGetStatus(handle, &status);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("TestCaseWatchdog: get status fail! ret:%d", ret);
        WatchdogClose(handle);
        return ret;
    }
    if (status != WATCHDOG_STOP) {
        HDF_LOGE("TestCaseWatchdog: status is:%d after stop", status);
        WatchdogClose(handle);
        return HDF_FAILURE;
    }
    WatchdogClose(handle);
    HDF_LOGD("TestCaseWatchdog: function tests end.");
    return HDF_SUCCESS;
}