Loading...
Searching...
No Matches

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;
}
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_start(void)
Start watchdog timer.
static void xtimer_usleep(uint32_t microseconds)
Pause the execution of a thread for some microseconds.
stdio wrapper to extend the C libs stdio
watchdog peripheral interface definitions
xtimer interface definitions

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 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);
while (1) {
}
return 0;
}
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.
* |---------------------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]argoptional 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_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.