Design Decisions

Informative

The rationale behind the watchdog driver contract. This helps implementers get the behavior right; it is not itself a requirement. Each entry points to the requirement it explains.

Why two implementation strategies (direct vs logical)?

Governs CHI-WDG-MUST-01, CHI-WDG-SHOULD-01, CHI-WDG-SHOULD-02.

Watchdog hardware differs widely. Some counters can be rewritten freely with fine resolution — for those, writing the timeout straight into the counter (direct) needs no timer, no periodic service, and gives the best fault-tolerant time interval, so it is the primary strategy. Other watchdogs are write-once after reset, or offer only coarse power-of-two timeouts — there, the driver keeps the timeout in software and a periodic timer re-triggers the hardware (logical). Offering both, selected by the vendor, lets one API serve both hardware classes without compromising the common case.

Implication for implementers: prefer direct management; fall back to logical only when the hardware forces it, and then rely on the upper layer’s timer to call Wdg_FeedHw.

Why doesn’t the driver own the feed timer?

Relates to CHI-WDG-SHOULD-02.

The trigger interval and the timer resource are system-integration concerns — the same timer is often shared, and the safe periodicity depends on the whole schedule, not just the watchdog. Making the upper layer own the timer and simply call Wdg_FeedHw keeps the driver free of timer-hardware dependencies and portable, and puts the safety-critical timing decision where the system knowledge is.

Implication for implementers: do not configure timer hardware inside the driver; document the required call interval per mode and let the integrator drive Wdg_FeedHw.

Why must the implementation resolve Wdg_SetMode / Wdg_FeedHw conflicts?

Governs CHI-WDG-MUST-03.

For an external watchdog reached over a bus (e.g. SPI with no request queue), a mode change and a periodic feed can collide on the shared transport. Rather than mandate one arbitration mechanism, the specification requires the implementation to prevent the conflict (blocking, a state machine, or another scheme) — because the right mechanism depends on the bus driver and the system’s timing.

Implication for implementers: serialise bus access from Wdg_SetMode and Wdg_FeedHw for an external watchdog; choose the mechanism that fits the bus driver.

Why is there no de-init, and why does timeout = 0 reset?

Relates to CHI-WDG-MUST-04, CHI-WDG-MUST-06.

A watchdog exists to catch a hung system; letting software freely tear it down would defeat that, so there is no de-initialization (use WDG_MODE_OFF where the hardware genuinely supports disabling). For the opposite need — forcing a reset deliberately — Wdg_UpdateTimeout(0) gives a defined, minimal-timeout path rather than requiring a separate “reset now” API.

Implication for implementers: keep the watchdog armed for its lifetime; treat timeout = 0 as a request for an immediate reset (subject to hardware timing).

Why does Wdg_Init take only NULL_PTR?

Relates to CHI-WDG-MUST-04.

Configuration variants are selected at build time, not passed at runtime. Requiring configPtr == NULL_PTR keeps the interface stable and avoids implying a runtime variant-selection mechanism the driver does not provide.

Implication for implementers: bind the active configuration at build time; reject a non-null configPtr as a development error.