Watchdog (WDG)

Overview

RTL8721F provides a secure system watchdog reachable from the KM4TZ core. The Rust driver ameba_hal::wdg wraps the PAC register block directly — no raw bit-masking or C FFI is involved.

Features

  • A single secure system watchdog instance, Wdg / CPU0_S_WDG_DEV, reachable from the KM4TZ core

  • Configurable reload timeout in milliseconds via Wdg::init, clamped to the 16-bit WDG_RLR.RELOAD field

  • No feed-window restriction — refresh can be called at any point in the countdown

  • Hardware reset on timeout, with no early-interrupt path exposed

  • No software disable path once enabled — the underlying hardware provides no unlock sequence for this

Note

The independent watchdog IWDG_DEV is not exposed by this driver. It is already owned unconditionally by the NP core’s C firmware at boot, so a KM4TZ-side driver would only race the NP core’s own refresh sequence on the same registers with no corresponding safety benefit.

Operating Modes

WDG follows a single linear flow: initialize the timeout, enable the watchdog, then refresh it periodically before the timeout elapses.

Watchdog Flow

Wdg::init configures the reload timeout and enables the peripheral clock, Wdg::enable arms the watchdog, and Wdg::refresh restarts the countdown from the configured timeout. If refresh is not called before the timeout elapses, the hardware resets the chip.

use ameba_hal::{println, wdg::Wdg};
...
const TIMEOUT_MS: u32 = 5000;
const REFRESH_INTERVAL_MS: u64 = 500;
...
let wdg = unsafe { Wdg::steal() };
wdg.init(TIMEOUT_MS);
wdg.enable();
...
loop {
    Timer::after(Duration::from_millis(REFRESH_INTERVAL_MS)).await;
    wdg.refresh();
}

Full example: examples/wdg/src/main.rs.

Application Examples

The Rust SDK provides one example project under examples/wdg/:

  • wdg

    Initializes and enables the system watchdog with a 5 s timeout, refreshes it every 500 ms, and prints 10 refresh rounds before reporting [PASS]. Refreshing then continues indefinitely to keep the board running — a logic error in the refresh loop resets the board within 5 s, restarting the serial log from [WDG] start without ever reaching [PASS].

    Wiring: none required.

    [WDG] start
    [WDG] system watchdog enabled, timeout=5000ms
    [WDG] refresh #0
    ...
    [WDG] refresh #9
    [PASS] wdg: OK
    

Note

Build any example with cargo xtask build example --name wdg.

API Reference

Quick Usage

use ameba_hal::wdg::Wdg;

let wdg = unsafe { Wdg::steal() };
wdg.init(5000);
wdg.enable();

wdg.refresh();