看门狗（Watchdog）

概述

看门狗定时器（Watchdog Timer, WDG）是一种硬件定时器，主要用于检测和恢复由软件故障引起的系统异常。它是一个自动递减的计数器，期间需要系统周期性地“喂狗”（复位计数器），否则计数器归零后会触发复位。

看门狗可以细分为以下类型：

  • 独立看门狗（Independent WDG，IWDG）

  • 系统看门狗（System WDG，SWDG）

    • 安全看门狗

    • 非安全看门狗

看门狗的架构图如下所示：

RTL8721Dx:

功能特性

  • 共同特性：

    • 一旦使能后，不能除能

    • 可选的提前中断功能，可在看门狗超时前的可编程时间生成中断

    • 每个看门狗定时器都有独立的启动原因

  • 独立看门狗特有特性：

独立看门狗:
RTL8721Dx:

  • 由 AON 区域的电源和时钟源供电。

  • 可以配置在休眠模式下是否工作。

  • 可以通过提前中断从休眠模式唤醒系统。

  • 当 KM4 或 KM0 处于调试模式时会自动暂停。

  • 使能后，超时时间只能减小，不能增大。

备注

独立看门狗和系统看门狗都有窗口功能，但是由于 AON 的 100k 时钟是未校准的时钟，所以不建议使能独立看门狗的窗口功能。

硬件默认使能

RTL8721Dx:

独立看门狗在 Efuse 中默认使能，系统每次启动时 IWDG 都是使能的，IWDG 的超时时间是 64 秒， 同时软件中会创建 rtos 定时器，每 500 毫秒执行一次喂狗任务。

低功耗模式

  • 在深度睡眠状态下，所有看门狗都不能工作。

  • 在睡眠状态下，系统看门狗不能工作，独立看门狗可以配置在睡眠状态下继续工作或者暂停工作。

  • 独立看门狗可以在睡眠状态下继续工作的情形，推荐使能提前中断用于唤醒系统，执行提前中断函数进行喂狗。

复位域

RTL8721Dx:

在看门狗计数到 0 时，会触发全局复位。

应用示例

SDK 提供了两类功能示例，帮助开发者了解和使用看门狗功能：

  • mbed 示例

    • 路径：{SDK}\example\peripheral\mbed\Watchdog\mbed_watchdog

    • 展示如何在 mbed 环境中实现看门狗控制。

  • raw 示例

    • 路径：{SDK}\example\peripheral\raw\Watchdog\raw_watchdog

    • 展示如何在无抽象层的情况下直接控制看门狗。

以下是对 raw 示例功能的简要说明：

备注

要了解示例支持的芯片，请查看示例路径下的 README.md 文件。

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.

参数:

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

参数:

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

参数:

备注

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.

参数:

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

备注

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.

参数:

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

参数:

备注

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.

参数:

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

void WDG_Timeout(WDG_TypeDef *WDG, u32 Timeout)

Update WDG reload value.

参数:

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

  • Timeout -- Specify the target timeout period in ms.

备注

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.

参数:

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.

参数:

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

备注

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.

参数:

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

备注

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