Concepts

Informative

The model behind the watchdog driver: the driver state, the watchdog modes, the two timeout implementation strategies, the monitoring/timeout model, and internal vs external watchdogs. Non-binding; the normative rules live in Wdg — Requirements.

Driver state

The WdgDrv is simply uninitialised until Wdg_Init runs, after which its service APIs are accepted. There is no de-initialization.

        stateDiagram-v2
   [*] --> WDG_UNINIT : Reset
   WDG_UNINIT --> WDG_INIT : Wdg_Init()
    

State	Meaning	API calls accepted
WDG_UNINIT	Not initialized (state after reset/startup)	Only Wdg_Init()
WDG_INIT	Initialized; service APIs are accepted	All

Calling a service API before Wdg_Init (or Wdg_Init twice) is a development error (WDG_DEVERR_DRIVER_STATE).

Watchdog modes

The watchdog runs in one of three modes (Wdg_ModeType), each with its own configured settings and default timeout. Wdg_SetMode switches between them and resets the timeout to the new mode’s default.

Mode	Meaning
WDG_MODE_OFF	Watchdog disabled (switched off), where the hardware allows it.
WDG_MODE_NORMAL	Normal mode — typically used while the application runs.
WDG_MODE_ALTERNATIVE	Alternative mode — typically used during a startup or standby sequence (e.g. a longer timeout).

Timeout and monitoring model

The watchdog enforces a reset timeout: if it is not refreshed in time, the hardware resets the MCU. The upper layer refreshes it at watchpoints in its control flow by calling Wdg_UpdateTimeout(timeout) — each call delays the reset until the new timeout elapses. A timeout of 0 requests an (almost) immediate reset. The timeout is expressed in milliseconds and is bounded by the configured maximum_timeout for the current mode.

Implementation strategies

Because watchdog hardware varies, the driver may be implemented in one of two ways; which one is used is vendor-specific (both are described as a down-counter).

Direct timeout management (primary). The timeout value is written straight into the watchdog hardware counter. No timer resource and no periodic triggering are needed — this is recommended for its simplicity, low resource use, and better fault-tolerant time interval (FTTI). It requires hardware whose timeout counter can be rewritten at runtime with millisecond resolution.

Direct timeout management: Wdg_UpdateTimeout writes the counter; the reset fires if it is not refreshed.

Logical timeout management (secondary). Where the hardware is too restrictive for the direct approach (e.g. a write-once counter, or coarse/discontinuous timeout values), the driver keeps the timeout logically in software and a periodic timer triggers the hardware through Wdg_FeedHw. Each Wdg_FeedHw decrements the logical timeout by the call interval and re-triggers the hardware only while the timeout has not expired.

Logical timeout management: a periodic Wdg_FeedHw keeps the hardware alive until the logical timeout expires.

Internal vs external watchdog

A WdgDrv instance controls either an internal watchdog — driving the hardware registers directly — or an external watchdog — driving it through another bus driver such as SPI or I2C. For an external watchdog, Wdg_FeedHw and Wdg_SetMode may issue bus transactions and can therefore conflict; resolving that conflict (blocking, state control, …) is the implementation’s responsibility (see Design Decisions).

Sequence: direct timeout management

The informative view of the direct strategy (CHI-WDG-MUST-01, CHI-WDG-MUST-05, CHI-WDG-MUST-06):

        sequenceDiagram
   participant UPL as Upper layer
   participant DRV as WdgDrv
   participant HW as WDG HW

   UPL->>DRV: Wdg_Init(NULL_PTR)
   activate DRV
   DRV->>HW: set up default mode + timeout
   DRV-->>UPL: return
   deactivate DRV

   Note over UPL,HW: at each control-flow watchpoint
   UPL->>DRV: Wdg_UpdateTimeout(timeout)
   DRV->>HW: write timeout counter (reset delayed)

   opt mode change (e.g. entering sleep)
      UPL->>DRV: Wdg_SetMode(mode)
      DRV->>HW: apply mode + reset timeout to mode default
   end
    

Sequence: logical timeout management

The informative view of the logical strategy — a timer the upper layer owns drives Wdg_FeedHw (CHI-WDG-SHOULD-01, CHI-WDG-SHOULD-02):

        sequenceDiagram
   participant UPL as Upper layer
   participant DRV as WdgDrv
   participant HW as WDG HW
   participant TM as Timer HW

   UPL->>DRV: Wdg_Init(NULL_PTR)
   DRV->>HW: set up default mode
   UPL->>TM: set up periodic timer for the mode's trigger interval

   Note over UPL,TM: runtime
   UPL->>DRV: Wdg_UpdateTimeout(timeout)
   DRV->>DRV: set logical timeout

   TM-->>UPL: timer interrupt
   UPL->>DRV: Wdg_FeedHw()
   activate DRV
   DRV->>DRV: decrement logical timeout by the interval
   alt timeout not expired
      DRV->>HW: trigger the watchdog
   else timeout expired
      Note over DRV,HW: do nothing — the reset will fire
   end
   deactivate DRV
    

Key terms

For watchdog terms — fault-tolerant time interval (FTTI), direct vs logical timeout management, internal vs external watchdog — see the glossary in the appendix and the shared foundation in General.