WDT

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);
    wdt_start();
 
    while (1) {
        xtimer_usleep(time);
        wdt_kick();
    }
    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);
    wdt_start();
 
    while (1) {
        xtimer_usleep(MIN_TIME + time);
        wdt_kick();
    }
    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 CONFIG_WDT_WARNING_PERIOD before the actual reboot. The value of CONFIG_WDT_WARNING_PERIOD may be configurable or a fixed value. If a platform allows this value to be configured, the feature periph_wdt_warning_period is provided. 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);
    wdt_start();
    while (1) {
        xtimer_usleep(time);
        wdt_kick();
    }
    return 0;
}

* |---------------------MAX_TIME-----------------------|
*                      |---CONFIG_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]

arg

optional argument which is passed to the callback

Definition at line 296 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_time	lower bound for WINDOW watchdog in ms, has to be 0 for NORMAL watchdog operation
[in]	max_time	upper 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_time	lower bound for WINDOW watchdog in ms, has to be 0 for NORMAL watchdog.
[in]	max_time	upper bound for WINDOW watchdog in ms, time before reset for NORMAL watchdog.
[in]	wdt_cb	wdt callback, can be NULL
[in]	arg	optional 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.