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:

USEMODULE += periph_wdt_cb

WDT Auto-Start

It is possible to enable the Watchdog in early boot, before application startup:

USEMODULE += periph_wdt_auto_start

The watchdog will automatically be initialized with the parameters CONFIG_PERIPH_WDT_WIN_MIN_MS and CONFIG_PERIPH_WDT_WIN_MAX_MS

It is also possible to automatically kick the watchdog. This is a very non-invasive way of using the watchdog, but it is also very weak as it can only detect situations where low-priority threads are starved from execution and may even trigger wrongly in situations where the system just experiences high load, but would otherwise have recovered on it's own.

If you want to enable it anyway, select this module:

USEMODULE += auto_init_wdt_thread

If you are using an event thread, you can also use the watchdog to ensure that events are processed in time. To do so, add

USEMODULE += auto_init_wdt_event

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.

#define	CONFIG_PERIPH_WDT_WIN_MIN_MS (0)
	If `periph_wdt_auto_start` is used, this will be the lower bound of when the WDT can be kicked.

#define	CONFIG_PERIPH_WDT_WIN_MAX_MS (1024)
	If `periph_wdt_auto_start` is used, this will be the max period after which the WDT must be kicked or else it will reboot the system.

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

Functions
void	wdt_start (void)
	Start watchdog timer.

void	wdt_stop (void)
	Stop watchdog timer.

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.

void	wdt_init (void)
	Initialize WDT module.

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.

Macro Definition Documentation

◆ CONFIG_PERIPH_WDT_WIN_MAX_MS

#define CONFIG_PERIPH_WDT_WIN_MAX_MS (1024)

If periph_wdt_auto_start is used, this will be the max period after which the WDT must be kicked or else it will reboot the system.

Definition at line 280 of file wdt.h.

◆ CONFIG_PERIPH_WDT_WIN_MIN_MS

#define CONFIG_PERIPH_WDT_WIN_MIN_MS (0)

If periph_wdt_auto_start is used, this will be the lower bound of when the WDT can be kicked.

Definition at line 271 of file wdt.h.

◆ NWDT_TIME_LOWER_LIMIT

#define NWDT_TIME_LOWER_LIMIT

Lower limit in ms for wdt operating in NORMAL mode.

Definition at line 222 of file wdt.h.

◆ NWDT_TIME_UPPER_LIMIT

#define NWDT_TIME_UPPER_LIMIT

Upper limit in ms for wdt operating in NORMAL mode.

Definition at line 230 of file wdt.h.

◆ WDT_HAS_INIT

#define WDT_HAS_INIT (0)

Set to 1 if the platform implements wdt_init(), 0 otherwise.

Definition at line 263 of file wdt.h.

◆ WDT_HAS_STOP

#define WDT_HAS_STOP (0)

Set to 1 if the platform supports wdt_stop(), 0 otherwise.

Definition at line 255 of file wdt.h.

◆ WWDT_TIME_LOWER_LIMIT

#define WWDT_TIME_LOWER_LIMIT

Lower limit in ms for wdt operating in WINDOW mode.

Definition at line 238 of file wdt.h.

◆ WWDT_TIME_UPPER_LIMIT

#define WWDT_TIME_UPPER_LIMIT

Upper limit in ms for wdt operating in WINDOW mode.

Definition at line 246 of file wdt.h.

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 346 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.

Detailed Description

NORMAL operation

WINDOW operation

WDT callback

WDT Auto-Start

Modules

Files

Macros

Typedefs

Functions

Macro Definition Documentation

◆ CONFIG_PERIPH_WDT_WIN_MAX_MS

◆ CONFIG_PERIPH_WDT_WIN_MIN_MS

◆ NWDT_TIME_LOWER_LIMIT

◆ NWDT_TIME_UPPER_LIMIT

◆ WDT_HAS_INIT

◆ WDT_HAS_STOP

◆ WWDT_TIME_LOWER_LIMIT

◆ WWDT_TIME_UPPER_LIMIT

Typedef Documentation

◆ wdt_cb_t

Function Documentation

◆ wdt_init()

◆ wdt_setup_reboot()

◆ wdt_setup_reboot_with_callback()

◆ wdt_stop()