Watchdog

Introduction

The Watchdog Timer (WDG) is a hardware timer primarily used to detect and recover from system anomalies caused by software faults. It contains an auto-decrementing counter that requires periodic “feeding” (resetting the counter). If the counter reaches zero, a system reset will be triggered. WDG can be divided into Independent Watchdog (IWDG) and System Watchdog (SWDG), where the System Watchdog is further categorized into secure and non-secure types. The WDG architecture diagram is as follows:

RTL8721Dx:

Features

  • Common Features

    • Once enabled, cannot be disabled.

    • Optional early interrupt function that generates an interrupt at a programmable time before watchdog timeout.

    • Each watchdog timer has independent boot reasons.

  • IWDG Specific Features

RTL8721Dx:

  • Powered by the AON domain’s power supply and clock source

  • Configurable operation in sleep mode

  • Can wake system from sleep mode via early interrupt

  • Automatically halted when KM4/KM0 is in debug mode

  • Timeout can only be decreased (not increased) after enabled

  • System Watchdog Specific Features

RTL8721Dx:

  • WDG0 halted when KM0 is in debug mode; WDG1 and WDG2 halted when KM4 is in debug mode

  • Halted in sleep mode with settings remaining unchanged

  • Window protection function and timeout become unmodifiable once enabled

Note

Both IWDG and System Watchdog support window function. However, since the AON 100kHz clock is uncalibrated, it is not recommended to enable the window function for IWDG.

Hardware Default Enable

RTL8721Dx:

Independent Watchdog (IWDG) is enabled by default in Efuse configuration, activated during every system startup with a 64-second timeout duration, and a software-implemented RTOS timer executes the watchdog refresh task every 500 ms.

Low-Power Modes

  • All watchdogs are disabled in deepsleep mode.

  • In sleep mode, the System Watchdog stops working while the Independent Watchdog (IWDG) can be configured to either continue operating or halt in sleep mode.

  • When the IWDG is configured to continue operating in sleep mode, it is recommended to enable the early interrupt to wake the system and execute the interrupt handler for watchdog refresh.

Reset Domains

RTL8721Dx:

All watchdog trigger global reset when counter reaches zero

Application Examples

The SDK provides two types of functional examples to help developers understand and use WDG:

  • mbed Examples

    • Path: {SDK}\example\peripheral\mbed\Watchdog\mbed_watchdog

    • Demonstrates watchdog control in the mbed environment.

  • raw Examples

    • Path: {SDK}\example\peripheral\raw\Watchdog\raw_watchdog

    • Demonstrates direct watchdog control without abstraction layers.

Brief description of raw example functionality:

  • raw_watchdog demonstrates watchdog configuration and control.

Note

Refer to the README.md file in the example directory for supported chips.

Raw API

WDG Exported Types

struct WDG_InitTypeDef

WDG Init Structure Definition.

Public Members

u16 Window

WDG parameter specifies window protection of WDG, the value cannot be changed when WDG is Enabled This parameter must be set to a value in the 0-65535 range

u16 Timeout

WDG parameter specifies WDG timeout count in units of ms This parameter must be set to a value in the 1-65535 range

u16 EICNT

WDG parameter specifies WDG early interrupt trigger threshold This parameter must be set to a value in the 1-65535 range

u16 EIMOD

WDG parameter, Specifies WDG early interrupt enable or not This parameter must be set to a value of 0 or 1

WDG Exported Constants

WDG Magic Key

/* Magic key to enable register access. */
#define WDG_ACCESS_EN 0x00006969

/* Magic key to enable WDG function. */
#define WDG_FUNC_EN 0x00003C3C

/* Magic key to reload WDG counter. */
#define WDG_REFRESH 0x00005A5A

WDG Peripheral Definitions

/* Check if IWDG peripheral is valid. */
#define IS_IWDG_PERIPH ((PERIPH) == IWDG_DEV)
RTL8721Dx: 
/* Check if system WDG peripheral is valid. */
#define IS_SYETEM_WDG_PERIPH (((PERIPH) == KM0_WDG_DEV) || ((PERIPH) == KM4_S_WDG_DEV) \
    || ((PERIPH) == KM4_NS_WDG_DEV))

/* Check if WDG peripheral is valid. */
#define IS_WDG_ALL_PERIPH (IS_IWDG_PERIPH(PERIPH) || IS_SYETEM_WDG_PERIPH(PERIPH))

WDG Exported Functions

void IWDG_LP_Enable(WDG_TypeDef *WDG, u32 NewState)

Enable or disable IWDG low power function.

Parameters:

  • WDG – WDG can only be IWDG_DEV.

  • NewState – Specifies the state of the low power function. This parameter can be: ENABLE or DISABLE.

void WDG_ClearINT(WDG_TypeDef *WDG, u32 INTrBit)

Clear WDG interrupt.

Parameters:

  • WDG – The watchdog peripheral. Refer to WDG Peripheral Definitions for valid devices.

  • INTrBit – Specifies the interrupt sources to be cleared.

void WDG_Enable(WDG_TypeDef *WDG)

Enable WDG.

Parameters:

Note

Once enabled, the WDG can’t Disabled by software.

void WDG_INTConfig(WDG_TypeDef *WDG, u32 WDG_IT, u32 NewState)

Early interrupt enable or not by New State.

Parameters:

  • WDG – The watchdog peripheral. Refer to WDG Peripheral Definitions for valid devices.

  • WDG_IT – Specifies the interrupt source to be enabled or disabled.

  • NewState – Specifies the state of the interrupt.

Note

This function only used in interrupt mode.

void WDG_Init(WDG_TypeDef *WDG, WDG_InitTypeDef *WDG_InitStruct)

Initialize the WDG registers according to the specified parameters.

Parameters:

  • WDG – The watchdog peripheral. Refer to WDG Peripheral Definitions for valid devices.

  • WDG_InitStruct – Pointer to a WDG_InitTypeDef structure that contains the configuration information for the WDG peripheral.

void WDG_Refresh(WDG_TypeDef *WDG)

Refresh WDG timer.

Parameters:

Note

If call this function to refresh WDG before timeout period, then MCU reset or WDG interrupt won’t generate.

void WDG_StructInit(WDG_InitTypeDef *WDG_InitStruct)

Fill each WDG_InitStruct member with its default value.

Parameters:

  • WDG_InitStruct – Pointer to a WDG_InitTypeDef structure which will be initialized.

void WDG_Timeout(WDG_TypeDef *WDG, u32 Timeout)

Update WDG reload value.

Parameters:

  • WDG – The watchdog peripheral. Refer to WDG Peripheral Definitions for valid devices.

  • Timeout – Specify the target timeout period in ms.

Note

WDG won’t use the new timeout until a WDG refresh,Be careful if window protection enabled.

void WDG_Wait_Busy(WDG_TypeDef *WDG)

Before writing to the watchdog register, SW needs to check watch status to ensure no conflict and disorder issues.

Parameters:

Mbed API

MBED_WDG Exported Types

Structure Type

typedef u32 (*wdt_irq_handler)(void *id)

Typedef function pointer for WDG IRQ callback handler.

MBED_WDG Exported Functions

void watchdog_init(uint32_t timeout_ms)

Initialize the watchdog, including time and early interrupt settings.

Parameters:

  • timeout_ms – Timeout value of watchdog timer in units of ms.

Note

By default, watchdog will reset the whole system once timeout occurs.

void watchdog_irq_init(wdt_irq_handler handler, uint32_t id)

Enable early interrupt and register a watchdog timer timeout interrupt handler. The interrupt handler will be called at a programmable time prior to watchdog timeout, for users to prepare for reset.

Parameters:

  • handler – WDT timeout interrupt callback function.

  • id – WDT timeout interrupt callback parameter.

void watchdog_refresh(void)

Refresh count of the watchdog in avoidance of WDT timeout.

void watchdog_start(void)

Enable the watchdog and it starts to count.

void watchdog_stop(void)

Disable the watchdog and it stops counting.

Note

Once watchdog is enabled, it cannot be disabled by software.