A watchdog is a device used to protect a system from specific software or hardware failures that may cause the system to stop responding.
The ConnectCore platforms have several watchdog devices. You can find more information in Hardware reference manuals and the MCA 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_device_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 */
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) |
Configure a new timeout in seconds for the given watchdog timer. It returns EXIT_SUCCESS on success, EXIT_FAILURE otherwise. For more information, see MCA watchdog in the Linux BSP section. |
[...]
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)[...]
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)[...]
wd_t *wd = ...;
[...]
/* Stop the watchdog once it is not needed */
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)[...]
wd_t *wd = ...;
[...]
/* Free watchdog once it is not required */
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.
