A watchdog is a device used to protect a system from specific software or hardware failures that may cause the system to stop responding. You can find more information in Hardware reference manuals and the Watchdog Linux BSP section.

Digi adds an API for Linux that allows the management of these watchdog devices. To use this API, include the following header file:

#include <libdigiapix/watchdog.h>

Request a watchdog

You can request a watchdog with the following function:

Function Description 
wd_t *ldx_watchdog_request(
	char const * const wd_dev_file);

Requests a watchdog by its absolute device node path.

It returns a pointer to wd_t on success, NULL on error.
A requested watchdog must be freed once it is not needed anymore. See Free a watchdog.

This function may fail and return NULL for the following reasons:

  • The provided device node path is not available on the system.

  • The API encountered problems allocating memory to initialize the watchdog. Your system may have run out of resources.

Request a watchdog
/* Request a Watchdog */
wd_t *wd = ldx_watchdog_request("/dev/watchdog");

printf("The Watchdog %s was requested\n", wd->node);

Read and set the watchdog timeout

You can read and set the watchdog timer to configure a different timeout:

Function Description 
int ldx_watchdog_get_timeout(wd_t *wd);

Retrieves the value of the watchdog timeout.

If the function encounters an error, it returns -1.

 
int ldx_watchdog_set_timeout(wd_t *wd,
			   int timeout);

Configures a new timeout in seconds for the given watchdog timer.

It returns EXIT_SUCCESS on success, EXIT_FAILURE otherwise.

For more information, see Watchdog in the Linux BSP section.
Read and set a watchdog value
wd_t *wd = ...;
int timeout = 10;
int current_timeout = -1;

/* Read the watchdog timeout value */
current_timeout = ldx_watchdog_get_timeout(wd);

printf("Current watchdog timeout is: %d", current_timeout);

/* Configure a custom timeout */
ldx_watchdog_set_timeout(wd, timeout);

printf("Watchdog timeout set to %d", timeout);

Refresh the watchdog timeout

Once requested, the watchdog timer starts counting so you must refresh the watchdog before the configured timeout expires, to avoid the system from resetting. To do so, use the ldx_watchdog_refresh() function.

int ldx_watchdog_refresh(wd_t *wd);
Refresh the watchdog
wd_t *wd = ...;

/* [...] */

while (true) {

	/* [...] */

	/* Refresh the watchdog to prevent the watchdog reset */
	ldx_watchdog_refresh(wd);
}

Stop the watchdog

If the watchdog can be stopped once enabled (most drivers are no-way-out), you can use the ldx_watchdog_stop() function to stop it.

int ldx_watchdog_stop(wd_t *wd);
Refresh the watchdog
wd_t *wd = ...;

/* [...] */

ldx_watchdog_stop(wd);

Free a watchdog

You must free a requested watchdog when it is no longer required. To do so, use the ldx_watchdog_free() function.

Freeing the watchdog does not stop it. 
int ldx_watchdog_free(wd_t *wd);
Free a requested watchdog
wd_t *wd = ...;

/* [...] */

ldx_watchdog_free(wd);

Watchdog example

This example demonstrates how to enable a watchdog on a ConnectCore board. Once the watchdog is enabled, the application refreshes the watchdog timer until the test time is consumed. After the timeout expires, the device automatically reboots.

To see an example of the watchdog API, import the watchdog example in Eclipse using the Digi Embedded Yocto plugin. For more information, see Create a new DEY sample project. This example is included in Digi Embedded Yocto. Go to GitHub to see the application source code.