Watchdog timer peripheral driver. More...

Detailed Description

Watchdog timer peripheral driver.

A watchdog timer (WDT) is an electronic or software timer that is used to detect and recover from unusual or suspect behaviour as well as software malfunctions. During NORMAL operation the application will reset wdt_kick() the timer counter preventing it from hitting 0. If due to software or hardware error the WDT counter isn't reset, it will trigger corrective actions, i.e. a system reboot or callback (not supported by all platforms).

This interface defines two operation modes NORMAL and WINDOW. In NORMAL operation if the WDT counter isn't reset before max_time then a reboot/callback is triggered. In WINDOW operation if a reset isn't triggered or if it's triggered outside of the time window = [min_time, max_time] a reboot is triggered.

NORMAL operation

In the code snippet and diagram time is an arbitrary value such that time < MAX_TIME.

* 0(ms)                                            MAX_TIME(ms)
* |----------------------------------------------------|
*
*                          time(ms)
* |--------------------------| - - - - - - - - - - - - |
*
*                            ^
*                            |
*                        wdt_kick()
* 
#include <stdio.h>
#include "periph/wdt.h"
#include "xtimer.h"
int main(void)
{
wdt_setup_reboot(0, MAX_TIME);
while (1) {
}
return 0;
}

WINDOW operation

In the code snippet and diagram time is an arbitrary value such that time < (MAX_TIME - MIN_TIME).

* 0(ms)                 MIN_TIME(ms)                MAX_TIME(ms)
*  |-------------------------|-----------WINDOW----------|
*
*                                  time(ms)
*                            |--------| - - - - - - - - -|
*                                     ^
*                                     |
*                                wdt_kick()
* 
#include <stdio.h>
#include "periph/wdt.h"
#include "xtimer.h"
int main(void)
{
wdt_setup_reboot(MIN_TIME, MAX_TIME);
while (1) {
xtimer_usleep(MIN_TIME + time);
}
return 0;
}

WDT callback

Before reboot WDT can trigger Early Wakeup Interrupt and execute a callback to perform specific safety operations of data logging before the actual reboot. This function is highly platform dependent so check the platform documentation for details on its constraints.

The callback will be executed WDT_WARNING_PERIOD before the actual reboot. The value of WDT_WARNING_PERIOD may be configurable or a fixed value. But is in any case defined at compile time. Specific platform implementation should assert improper values.

In the code snippet and diagram time is an arbitrary value such that time < MAX_TIME.

#include <stdio.h>
#include "periph/wdt.h"
#include "xtimer.h"
static void wdt_cb(void *arg)
{
(void) arg;
puts("wdt cb called, doing something now...");
}
int main(void)
{
wdt_setup_reboot_with_callback(0, MAX_TIME, wdt_cb, arg);
while (1) {
}
return 0;
}
* |---------------------MAX_TIME-----------------------|
*                             |---WDT_WARNING_PERIOD---|
*                             ^                        ^
*                             |                        |
*                        wdt_cb()                   reboot
* 

To include this feature, (If your platform supports it) in your application Makefile add:

MODULE += periph_wdt_cb

Modules

 WDT compile configurations
 

Files

file  wdt.h
 watchdog peripheral interface definitions
 

Macros

#define NWDT_TIME_LOWER_LIMIT
 Lower limit in ms for wdt operating in NORMAL mode.
 
#define NWDT_TIME_UPPER_LIMIT
 Upper limit in ms for wdt operating in NORMAL mode.
 
#define WWDT_TIME_LOWER_LIMIT
 Lower limit in ms for wdt operating in WINDOW mode.
 
#define WWDT_TIME_UPPER_LIMIT
 Upper limit in ms for wdt operating in WINDOW mode.
 
#define WDT_HAS_STOP   (0)
 Set to 1 if the platform supports wdt_stop(), 0 otherwise.
 
#define WDT_HAS_INIT   (0)
 Set to 1 if the platform implements wdt_init(), 0 otherwise.
 

Typedefs

typedef void(* wdt_cb_t) (void *arg)
 Signature for the watchdog early warning callback. More...
 

Functions

void wdt_start (void)
 Start watchdog timer.
 
void wdt_stop (void)
 Stop watchdog timer. More...
 
void wdt_kick (void)
 Reset the watchdog timer counter, delay system reset.
 
void wdt_setup_reboot (uint32_t min_time, uint32_t max_time)
 Set up the wdt timer. More...
 
void wdt_init (void)
 Initialize WDT module. More...
 
void wdt_setup_reboot_with_callback (uint32_t min_time, uint32_t max_time, wdt_cb_t wdt_cb, void *arg)
 Set up the wdt timer with callback. More...
 

Typedef Documentation

◆ wdt_cb_t

typedef void(* wdt_cb_t) (void *arg)

Signature for the watchdog early warning callback.

Parameters
[in]argoptional argument which is passed to the callback

Definition at line 294 of file wdt.h.

Function Documentation

◆ wdt_init()

void wdt_init ( void  )

Initialize WDT module.

Note
Only implemented and called for platforms with WDT_HAS_INIT = 1.

◆ wdt_setup_reboot()

void wdt_setup_reboot ( uint32_t  min_time,
uint32_t  max_time 
)

Set up the wdt timer.

Note
If NORMAL watchdog only use max_time (min_time=0).
If WINDOW watchdog set min_time and max_time.
Parameters
[in]min_timelower bound for WINDOW watchdog in ms, has to be 0 for NORMAL watchdog operation
[in]max_timeupper bound for WINDOW watchdog in ms, time before reset for NORMAL watchdog

◆ wdt_setup_reboot_with_callback()

void wdt_setup_reboot_with_callback ( uint32_t  min_time,
uint32_t  max_time,
wdt_cb_t  wdt_cb,
void *  arg 
)

Set up the wdt timer with callback.

Note
If NORMAL watchdog only use max_time (min_time=0).
If WINDOW watchdog set min_time and max_time.
Parameters
[in]min_timelower bound for WINDOW watchdog in ms, has to be 0 for NORMAL watchdog.
[in]max_timeupper bound for WINDOW watchdog in ms, time before reset for NORMAL watchdog.
[in]wdt_cbwdt callback, can be NULL
[in]argoptional argument which is passed to the callback, can be NULL

◆ wdt_stop()

void wdt_stop ( void  )

Stop watchdog timer.

Note
Not all platforms support stopping the WDT. if WDT_HAS_STOP = 0 once the wdt timer is enabled it can't be stopped.