Watchdog

• Overview

  • Available APIs

• Usage Guidelines

  • How to Use
  • Opening a Watchdog
  • Obtaining the Watchdog Status
  • Setting the Timeout Duration
  • Obtaining the Timeout Duration
  • Starting a Watchdog
  • Feeding a Watchdog
  • Stopping a Watchdog
  • Closing a Watchdog

• Usage Example

Overview

A watchdog, also called a watchdog timer, is a hardware timing device. If an error occurs in the main program of the system and fails to reset the watchdog timer, the watchdog timer sends a reset signal to restore the system to a normal state.

Available APIs

Table 1 Watchdog APIs

NOTE: All watchdog functions provided in this document can be called only in kernel mode.

Usage Guidelines

How to Use

Figure 1 illustrates the process of using a watchdog.

Figure 1 Process of using a watchdog

Opening a Watchdog

Use WatchdogOpen to open a watchdog. A system may have multiple watchdogs. You can open the specified watchdog by using the ID.

int32_t WatchdogOpen(int16_t wdtId);

Table 2 Description of WatchdogOpen

DevHandle handle = NULL;
handle = WatchdogOpen(0); /* Open watchdog 0.*/
if (handle == NULL) {
    HDF_LOGE("WatchdogOpen: failed, ret %d\n", ret);
    return;
}

Obtaining the Watchdog Status

int32_t WatchdogGetStatus(DevHandle handle, int32_t *status);

Table 3 Description of WatchdogGetStatus

int32_t ret;
int32_t status;
/* Obtain the watchdog status. */
ret = WatchdogGetStatus(handle, &status);
if (ret != 0) {
    HDF_LOGE("WatchdogGetStatus: failed, ret %d\n", ret);
    return;
}

Setting the Timeout Duration

int32_t WatchdogSetTimeout(PalHandle *handle, uint32_t seconds);

Table 4 Description of WatchdogSetTimeout

int32_t ret;
uint32_t timeOut = 60;
/* Set the timeout duration, in seconds. */
ret = WatchdogSetTimeout(handle, timeOut);
if (ret != 0) {
    HDF_LOGE("WatchdogSetTimeout: failed, ret %d\n", ret);
    return;
}

Obtaining the Timeout Duration

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

Table 5 Description of WatchdogGetTimeout

int32_t ret;
uint32_t timeOut;
/* Obtain the timeout duration, in seconds. */
ret = WatchdogGetTimeout(handle, &timeOut);
if (ret != 0) {
    HDF_LOGE("WatchdogGetTimeout: failed, ret %d\n", ret);
    return;
}

Starting a Watchdog

int32_t WatchdogStart(DevHandle handle);

Table 6 Description of WatchdogStart

int32_t ret;
/* Start the watchdog. */
ret = WatchdogStart(handle);
if (ret != 0) {
    HDF_LOGE("WatchdogStart: failed, ret %d\n", ret);
    return;
}

Feeding a Watchdog

int32_t WatchdogFeed(DevHandle handle);

Table 7 Description of WatchdogFeed

int32_t ret;
/* Feed the watchdog. */
ret = WatchdogFeed(handle);
if (ret != 0) {
    HDF_LOGE("WatchdogFeed: failed, ret %d\n", ret);
    return;
}

Stopping a Watchdog

int32_t WatchdogStop(DevHandle handle);

Table 8 Description of WatchdogStop

int32_t ret;
/* Stop the watchdog. */
ret = WatchdogStop(handle);
if (ret != 0) {
    HDF_LOGE("WatchdogStop: failed, ret %d\n", ret);
    return;
}

Closing a Watchdog

If the watchdog is no longer required, call WatchdogClose to close the watchdog handle.

void WatchdogClose(DevHandle handle);

Table 9 Description of WatchdogClose

/* Close the watchdog. */
ret = WatchdogClose(handle);

Usage Example

This example provides a complete process for using a watchdog.

In this example, open a watchdog, set the timeout duration, and start the watchdog.

• Feed the watchdog periodically to ensure that the system is not reset due to timer expiry.
• Stop feeding the watchdog and check whether the system is reset after the timer expires.

Example:

#include "watchdog_if.h"
#include "hdf_log.h"
#include "osal_irq.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;
    uint32_t timeout;
    DevHandle handle = NULL;

    /* Open watchdog 0. */
    handle = WatchdogOpen(0);
    if (handle == NULL) {
        HDF_LOGE("Open watchdog fail!");
        return -1;
    }

    /* Set the timeout duration. */
    ret = WatchdogSetTimeout(handle, WATCHDOG_TEST_TIMEOUT);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: set timeout fail! ret:%d\n", __func__, ret);
        WatchdogClose(handle);
        return ret;
    }

    /* Obtain the configured timeout duration. */
    ret = WatchdogGetTimeout(handle, &timeout);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: get timeout fail! ret:%d\n", __func__, ret);
        WatchdogClose(handle);
        return ret;
    }
    HDF_LOGI("%s: read timeout back:%u\n", __func__, timeout);

    /* Start the watchdog. The timer starts. */
    ret = WatchdogStart(handle);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: satrt fail! ret:%d\n", __func__, ret);
        WatchdogClose(handle);
        return ret;
    }

    /* Feed the watchdog every 1s. */
    for (i = 0; i < WATCHDOG_TEST_FEED_TIME; i++) {
        HDF_LOGE("%s: feeding watchdog %d times... \n", __func__, i);
        ret = WatchdogFeed(handle);
        if (ret != HDF_SUCCESS) {
            HDF_LOGE("%s: feed dog fail! ret:%d\n", __func__, ret);
            WatchdogClose(handle);
            return ret;
        }
        OsalSleep(1);
    }
    /* Because the interval for feeding the watchdog is shorter than the timeout duration, the system does not reset, and logs can be printed normally. */
    HDF_LOGE("%s: no reset ... feeding test OK!!!\n", __func__);

    /* Enable the timer to expire by stopping feeding the watchdog. */
    for (i = 0; i < WATCHDOG_TEST_FEED_TIME; i++) {
        HDF_LOGE("%s: watiting dog buck %d times... \n", __func__, i);
        OsalSleep(1);
    }

    /* The system resets when the timer expires. If the code is correct, the log below is not displayed. */
    HDF_LOGE("%s: dog has't buck!!! \n", __func__, i);
    WatchdogClose(handle);
    return -1;
}