Wdg — Requirements

Normative

Defines what a conformant watchdog driver MUST do. Keywords per Requirement Keywords; conformance per Conformance. Requirements do not carry individual status — the set-level status applies to all of them. Signatures, error codes, and configuration properties are in the API Reference, Errors, and Configuration Reference pages. Cross-module rules (types, error model, naming, memory mapping) are in General.

Mandatory (MUST) - 9 Requirements

The conformance contract — an implementation MUST satisfy every requirement here.

Implementation model

CHI-WDG-MUST-01 — Direct timeout management

The driver MUST support direct timeout management as its primary implementation: the timeout is written directly into the watchdog hardware counter, using no timer resource and no periodic triggering. (This requires hardware whose timeout counter can be rewritten at runtime with millisecond resolution.)

CHI-WDG-MUST-02 — Internal watchdog control

Where a WdgDrv instance controls an internal watchdog, it MUST drive the watchdog hardware directly.

CHI-WDG-MUST-03 — External watchdog control

Where a WdgDrv instance controls an external watchdog, it MUST drive the hardware through another software component (e.g. an SPI or I2C driver). The implementation MUST resolve any request conflict between Wdg_SetMode and Wdg_FeedHw on that shared component.

Initialization

CHI-WDG-MUST-04 — Initialization

Wdg_Init MUST initialize the driver and the watchdog hardware, applying the configured default mode and initial timeout. configPtr MUST be NULL_PTR.

Mode and timeout

CHI-WDG-MUST-05 — Mode switching

Wdg_SetMode MUST transition the watchdog to the requested mode, update the hardware settings accordingly, and reset the timeout to that mode’s default. It MUST return E_NOT_OK if a development error is detected.

CHI-WDG-MUST-06 — Timeout update

Wdg_UpdateTimeout MUST delay the watchdog reset until the given timeout (milliseconds) elapses. A timeout of 0 MUST cause an (almost) immediate reset.

Errors, types, and configuration

CHI-WDG-MUST-07 — Development error detection

When development error reporting is enabled, each API MUST detect the conditions listed in Errors and report them via LogM_Report (CHI-GEN-MUST-10).

CHI-WDG-MUST-08 — Public types and error identifiers

The driver MUST provide Wdg_ConfigType, Wdg_ModeType (WDG_MODE_OFF / WDG_MODE_NORMAL / WDG_MODE_ALTERNATIVE), and the development error identifiers as defined in API Reference and Errors, and MUST use the shared type system from General (CHI-GEN-MUST-09).

CHI-WDG-MUST-09 — Configuration model

The driver MUST support the configuration model in Configuration Reference — a General section and a ConfigSet with the default mode, initial and maximum timeouts, and per-mode settings — following the common model in General (CHI-GEN-MUST-12).

Recommended (SHOULD) - 3 Requirements

Logical timeout management

CHI-WDG-SHOULD-01 — Logical timeout management

Where the hardware is too restrictive for direct timeout management (e.g. a write-once counter, or coarse/discontinuous timeout values), the driver SHOULD support logical timeout management — keeping the timeout in software and using a periodic timer to trigger the hardware via Wdg_FeedHw.

CHI-WDG-SHOULD-02 — Watchdog feed

For logical timeout management, Wdg_FeedHw SHOULD trigger the watchdog hardware, decrementing the timeout by the (configured, per-mode) call interval and MUST NOT trigger the hardware once the timeout has expired. The periodic call of Wdg_FeedHw is the upper layer’s responsibility — the driver does not set up timer hardware.

Previous-timeout evaluation

CHI-WDG-SHOULD-03 — Previous-timeout evaluation

For logical timeout management, Wdg_SetMode and Wdg_UpdateTimeout SHOULD evaluate the previous timeout before acting: if it has already expired, the mode / timeout MUST NOT be updated (the timeout value is treated as 0).