Overview

Informative

What the watchdog driver is, its boundaries, and where it sits. Non-binding orientation; the normative contract is in Wdg — Requirements. The driver builds on the shared foundation (type system, error model, naming, memory mapping) in General.

In one sentence: the watchdog driver (WdgDrv) provides a thin, portable abstraction over a watchdog — it sets the watchdog mode and the reset timeout so that, if the upper layer stops servicing it within the timeout, the watchdog resets the microcontroller.

What it does

  • Brings the watchdog up (Wdg_Init) in a configured default mode and timeout.

  • Switches the watchdog mode (Wdg_SetMode) — off, normal, or alternative.

  • Sets/refreshes the reset timeout (Wdg_UpdateTimeout) at each control-flow watchpoint, so the reset is delayed only while software keeps proving it is alive.

  • Supports two implementation strategies — direct (write the timeout to the watchdog counter) and logical (a timer periodically triggers the hardware via Wdg_FeedHw) — and drives either an internal watchdog (directly) or an external one (through a bus driver such as SPI or I2C).

What it does not do

  • No periodic timer of its own — for the logical strategy, the upper layer owns the timer and calls Wdg_FeedHw; the WdgDrv does not set up timer hardware.

  • No de-init — once armed, a watchdog is not meant to be switched off arbitrarily; there is no de-initialization service (use WDG_MODE_OFF where the hardware allows).

  • No request-conflict arbitration — where Wdg_SetMode and Wdg_FeedHw may race (e.g. an external watchdog over SPI with no queue), resolving the conflict is the implementation’s concern.

  • No system-resource setup — the watchdog’s operation clock (and, for an external watchdog, the bus driver) are prerequisites another module configures before Wdg_Init.

Where it sits

        flowchart TB
   UL["Upper layer"]
   DRV["Chiisai Watchdog Driver"]
   INT["Internal watchdog HW"]
   BUS["Bus driver (SPI / I2C)"]
   EXT["External watchdog HW"]

   UL -->|"Wdg_Init, Wdg_SetMode,<br/>Wdg_UpdateTimeout, Wdg_FeedHw"| DRV
   DRV -->|"internal watchdog"| INT
   DRV -->|"external watchdog"| BUS
   BUS --> EXT

   classDef driver fill:#FEDCD2,stroke:#c66,stroke-width:2px;
   class DRV driver;

An internal watchdog is driven directly; an external one is driven through another bus driver. The WdgDrv is typically brought up early in boot and serviced throughout the application’s life.

Dependencies

Depends on

For

System resources (operation clock)

The watchdog hardware’s operation clock and, for the logical strategy, a timer resource the upper layer owns. These must be set up by another module before Wdg_Init.

Bus interface driver (external watchdog only)

Driving an external watchdog through a bus such as SPI or I2C.

Expected integration interfaces

The services the driver calls back into (LogM_Report for errors, and optional critical-section services). See API Reference → Expected interfaces.

The shared foundation

The common type system, compiler abstraction, error model, naming scheme, and memory mapping defined in General.

References

No.

Document

[1]

The Chiisai HAL General part — the shared contract this module builds on.