Watchdog Driver (Wdg)

The watchdog driver controls the internal or external watchdog hardware on behalf of the Watchdog Manager. The latter sets only a temporary trigger condition via the Watchdog Interface. As long as it applies, the driver triggers the hardware itself; thereafter, the watchdog expires [SWS_Wdg_00144]. Wdg_Init sets default mode and timeout from the configuration, and Wdg_SetMode switches between OFF, SLOW, and FAST modes [SWS_Wdg_00160]. A timeout of 0 triggers a nearly immediate reset, and the watchdog can only be switched off if the configuration permits it.

more ›

The watchdog driver Wdg controls the watchdog hardware via four synchronous services: Wdg_Init, Wdg_SetMode, Wdg_SetTriggerCondition, and Wdg_GetVersionInfo ([SWS_Wdg_00106], [SWS_Wdg_00107], [SWS_Wdg_00155], [SWS_Wdg_00109]). EcuM calls Wdg_Init. The Watchdog Manager reaches the driver only via the Watchdog Interface, which selects the instance via DeviceIndex (SWS WdgIf p. 17). Internal instances access the hardware directly, external ones via SPI or DIO ([SWS_Wdg_00161], [SWS_Wdg_00076]). Both provide the same API [SWS_Wdg_00077].

Context diagram: EcuM initializes the Wdg instances, WdgM controls them via WdgIf. External instances reach the hardware via Spi/Dio. Sources: [SWS_Wdg_00076], [SWS_Wdg_00161], SWS WdgM p. 86

The core of the module is the trigger condition. It is considered permission to service the watchdog for the next n milliseconds. As long as it is valid, the driver triggers itself; thereafter, the watchdog expires [SWS_Wdg_00144]. Wdg_SetTriggerCondition resets the counter and converts the milliseconds mode-dependently into a counter value ([SWS_Wdg_00136], [SWS_Wdg_00139]). The internal servicing routine triggers and decrements as long as the counter is greater than zero. At zero, it no longer triggers ([SWS_Wdg_00134], [SWS_Wdg_00135]). A timeout of 0 forces a (nearly) immediate reset, and an expired counter cannot be reloaded [SWS_Wdg_00140].

Sequence diagram: WdgM only reloads the counter; triggering is initiated by a timer interrupt in the driver. When the counter value reaches 0, the watchdog expires. Sources: SWS Wdg Fig. 9.2 p. 31, [SWS_Wdg_00134], [SWS_Wdg_00135]

Wdg_Init sets the default mode and timeout period from the configuration set Wdg_ConfigType [SWS_Wdg_00001]. Wdg_SetMode switches between WDGIF_OFF_MODE, WDGIF_SLOW_MODE, and WDGIF_FAST_MODE and returns E_OK only upon complete switching ([SWS_Wdg_00160], [SWS_Wdg_00103]). De-initialization does not exist. Switching off is performed via the OFF mode [SWS_Wdg_00031], and only if WdgDisableAllowed permits it [SWS_Wdg_00025].

In the event of an error, Wdg reports the development errors WDG_E_DRIVER_STATE, WDG_E_PARAM_MODE, WDG_E_PARAM_CONFIG, and WDG_E_PARAM_TIMEOUT [SWS_Wdg_00010]. In addition, there are the production errors WDG_E_MODE_FAILED and WDG_E_DISABLE_REJECTED ([SWS_Wdg_00016], [SWS_Wdg_00179]). These production errors are likely reported via Dem_SetEventStatus [SWS_Wdg_00111]. Question Q-f0ec41b842ebbdc9 (open)

more ›

Role in the watchdog stack: the driver that handles triggering itself

The watchdog driver Wdg controls the watchdog hardware via a small, synchronous API with four services, all of which are available via Wdg.h: Wdg_Init (Service ID 0x00), Wdg_SetMode (0x01), Wdg_SetTriggerCondition (0x03), and Wdg_GetVersionInfo (0x04). Only Wdg_GetVersionInfo is reentrant ([SWS_Wdg_00106], [SWS_Wdg_00107], [SWS_Wdg_00155], [SWS_Wdg_00109]). An interface for de-initialization deliberately does not exist. If the hardware and environment permit switching off, it is done via Wdg_SetMode with the OFF mode [SWS_Wdg_00031].

The services are called by the basic software. The ECU State Manager calls Wdg_Init (SWS EcuM p. 34). The Watchdog Manager requires WdgIf_SetMode and WdgIf_SetTriggerCondition (SWS WdgM p. 86). The Watchdog Interface maps these calls to the driver and selects the instance via a zero-based DeviceIndex of type uint8. If only one driver is configured, this mapping must not cause any runtime overhead, for example through macros (SWS WdgIf p. 17). The timing of the triggering resides completely within the driver. The Watchdog Manager sets only the trigger condition (SWS WdgM p. 56; [SWS_Wdg_00144]).

Toward the hardware, the instances differ. An instance for an internal watchdog accesses the hardware directly [SWS_Wdg_00161]. An instance for an external watchdog uses the API of a handler or driver, such as SPI or DIO [SWS_Wdg_00076]. Optionally, Wdg uses Det_ReportError for development errors and Dem_SetEventStatus for monitor status [SWS_Wdg_00111].

Context diagram: Wdg is initialized by EcuM and controlled by WdgM only indirectly via WdgIf. Internal instances access the hardware directly, external ones via Spi/Dio. Sources: [SWS_Wdg_00076], [SWS_Wdg_00161], [SWS_Wdg_00111], SWS WdgM p. 86

From system startup to supervised operation

Wdg_Init receives a pointer to a configuration set of type Wdg_ConfigType. This structure is hardware-dependent ([SWS_Wdg_00106], [SWS_Wdg_00171]). The function initializes driver and hardware and sets the default mode and the timeout period from this set [SWS_Wdg_00001]. In addition, it initializes all global variables [SWS_Wdg_00100]. It writes only to those controller registers that neither influence nor depend on other hardware modules. Shared registers are initialized by an overarching system module [SWS_Wdg_00101]. When development error detection is enabled, the internal state transitions from WDG_UNINIT to WDG_IDLE after successful initialization [SWS_Wdg_00019].

Figure 9.1 of the specification shows the division of work: EcuM initializes Wdg directly, after which WdgM controls trigger condition and mode via WdgIf (SWS Wdg Fig. 9.1 p. 34). For integrators, it is important: starting from Wdg_Init, the configured default mode and initial timeout period apply [SWS_Wdg_00001]. If this mode is not OFF, the controlling entity must refresh the trigger condition within the time window; otherwise, the watchdog expires [SWS_Wdg_00144].

Sequence diagram: Initialization by EcuM is followed by setting the trigger condition and switching the mode by WdgM via WdgIf. Sources: SWS Wdg Fig. 9.1 p. 34, [SWS_Wdg_00001], [SWS_Wdg_00019], [SWS_Wdg_00139], SWS WdgIf p. 18

Trigger condition: temporary permission for servicing

The hardware is not serviced by individual external trigger calls. Instead, a trigger condition applies: as long as it is valid, the driver services the hardware itself. If it becomes invalid, it stops triggering, and the watchdog expires [SWS_Wdg_00144]. The specification describes the condition as "permission to service the watchdog for the next n milliseconds". The controlling entity must refresh it within this window [SWS_Wdg_00144].

Wdg_SetTriggerCondition(uint16 timeout) resets the timeout counter according to the passed value ([SWS_Wdg_00155], [SWS_Wdg_00136]). The value is interpreted as milliseconds. The driver converts it internally into a counter value [SWS_Wdg_00138], taking into account the current mode [SWS_Wdg_00139]. The value 0 is permitted: it terminates triggering (almost) immediately and thus triggers a (nearly) immediate watchdog reset. If the stored counter is already at 0, the function ignores any new value [SWS_Wdg_00140]. Thus, an expired counter can no longer be reloaded.

The actual triggering is performed by a driver-internal servicing routine. If the trigger counter is greater than zero, it decrements it and triggers the hardware [SWS_Wdg_00134]. When it has reached zero, it does nothing, and the watchdog expires [SWS_Wdg_00135]. If the servicing is implemented as an interrupt routine, the interrupt frames belong in Wdg_Irq.c [SWS_Wdg_00079]. Figure 9.2 shows a timer interrupt for this purpose, which triggers the servicing independently in time from the call via WdgIf (SWS Wdg Fig. 9.2 p. 31).

Sequence diagram: WdgM only reloads the trigger counter; the triggering itself is initiated by a timer interrupt in the driver. At counter value 0, triggering is omitted and the watchdog expires. Sources: SWS Wdg Fig. 9.2 p. 31, [SWS_Wdg_00134], [SWS_Wdg_00135], [SWS_Wdg_00136], [SWS_Wdg_00093]

Activity diagram: Wdg_SetTriggerCondition discards timeouts that are too large, ignores new values if the counter has already expired, and otherwise converts into a counter value depending on the mode. Interpretation: The specification does not define the order of the two checks. Sources: [SWS_Wdg_00146], [SWS_Wdg_00140], [SWS_Wdg_00138], [SWS_Wdg_00139], SWS Wdg p. 29

Operating modes OFF, SLOW, and FAST

Wdg_SetMode switches driver and hardware from the current mode to WDGIF_OFF_MODE, WDGIF_SLOW_MODE, or WDGIF_FAST_MODE. Each mode corresponds to a statically configured setting, such as toggle or window watchdog with different timeout periods [SWS_Wdg_00160]. The hardware-specific parameters for each mode are located in the configuration set passed to Wdg_Init [SWS_Wdg_00051]. Wdg imports type WdgIf_ModeType from WdgIf.h [SWS_Wdg_00105]. An older configuration model shows the containers WdgSettingsFast, WdgSettingsSlow, and WdgSettingsOff as well as WdgDefaultMode for this purpose (ECUC-Parameter Fig. 5.21 p. 377).

Wdg_SetMode returns E_OK only if the switch has been completely executed and all parameters of driver and hardware have the new values [SWS_Wdg_00103]. WdgIf passes this return value through unchanged (SWS WdgIf p. 18). Whether the watchdog is permitted to be switched off is determined by the pre-compile parameter WdgDisableAllowed. If set to OFF, an initialization with a switching-off default mode is rejected [SWS_Wdg_00025]. According to its description, error WDG_E_DISABLE_REJECTED also covers a corresponding mode switch [SWS_Wdg_00179].

State diagram: Wdg_Init sets the configured default mode, after which Wdg_SetMode switches between the three modes. The OFF mode can only be reached if WdgDisableAllowed permits it. Sources: [SWS_Wdg_00160], [SWS_Wdg_00001], [SWS_Wdg_00025], [SWS_Wdg_00179], [SWS_Wdg_00031]

Internal states, exclusive areas, and activation codes

When development error detection is enabled, Wdg maintains an internal state: WDG_UNINIT until successful initialization, thereafter WDG_IDLE [SWS_Wdg_00019]. Wdg_SetMode and the servicing routine set WDG_BUSY during their execution. As their last operation before returning, they set WDG_IDLE again ([SWS_Wdg_00018], [SWS_Wdg_00052]). Both verify beforehand whether the state is WDG_IDLE. Otherwise, the mode switch or triggering does not take place, and WDG_E_DRIVER_STATE is reported ([SWS_Wdg_00017], [SWS_Wdg_00035]). In this way, calls prior to initialization are detected, as are overlaps between mode switch and triggering.

If interrupts must be disabled for data consistency, for example during a mode switch or in the trigger routine, this should preferably be done via an exclusive area of the BSW scheduler. As an MCAL module, the internal driver is also permitted to disable interrupts directly [SWS_Wdg_00040]. The guide to BSW distribution explains the background: in MCAL drivers, main function, service API, and ISR can access shared peripheral registers in their own execution contexts (BSW Distribution Guide p. 36).

Some hardware requires a configurable or variable activation code. In that case, Wdg manages the code internally and passes the correct value in each case. The hardware then updates the internal variable with the next expected code [SWS_Wdg_00093]. The trigger cycle must be selected such that this update is guaranteed to take place [SWS_Wdg_00094]. A configurable initial code belongs in the configuration set. For hardware-fixed code, this requirement does not apply [SWS_Wdg_00095].

State diagram: When development error detection is enabled, states WDG_UNINIT, WDG_IDLE, and WDG_BUSY apply. Calls outside of WDG_IDLE are rejected with WDG_E_DRIVER_STATE. Sources: [SWS_Wdg_00019], [SWS_Wdg_00017], [SWS_Wdg_00018], [SWS_Wdg_00035], [SWS_Wdg_00052]

Internal and external watchdogs: instances, files, configuration

An ECU can have multiple Wdg instances, such as one for an internal watchdog and one for an external watchdog. In this case, API names and instance-specific type names [SWS_Wdg_00172] as well as code and header file names are extended according to SRS_BSW_00347 ([SWS_Wdg_00169], [SWS_Wdg_00170]). Figure 1 shows the file structure with placeholders such as Wdg<xxx>.h and Wdg_<xxx>PBcfg.c (SWS Wdg Fig. 1 p. 11). An external Wdg must provide the same functional scope with a semantically identical API as an internal one [SWS_Wdg_00077]. Its source code must be independent of the microcontroller platform [SWS_Wdg_00055]. An example from the safety domain is an external window watchdog connected via SPI (EXP SafetyUseCase Fig. 4.1 p. 20).

The code file structure is not fully prescribed. If needed, it includes Wdg_Lcfg.c for link-time parameters and Wdg_PBcfg.c for post-build parameters [SWS_Wdg_00079]. Wdg checks the configuration statically at compile time at the latest [SWS_Wdg_00086]. A static configuration specifies whether the code runs from ROM or RAM [SWS_Wdg_00168]. For external hardware, Wdg includes the access parameters, such as SPI channel or DIO port, in its published parameters and configuration parameters [SWS_Wdg_00078]. More recent releases model this as a choice reference WdgExternalContainerRef to a DIO channel group, an SPI sequence, or an I2C sequence. I2C is not explicitly mentioned in R20-11 (SWS Wdg p. 40). Wdg_SetTriggerCondition checks against the maximum value WdgMaxTimeout [SWS_Wdg_00146]. In addition, the published information model contains WdgMinTimeout and WdgResolution (ECUC-Parameter Fig. 5.22 p. 380).

Behavior in the event of an error

Wdg distinguishes development errors, which are mostly checked only when development error detection is enabled, from extended production errors. The error codes are defined [SWS_Wdg_00010]:

• WDG_E_DRIVER_STATE (0x10)
• WDG_E_PARAM_MODE (0x11)
• WDG_E_PARAM_CONFIG (0x12)
• WDG_E_PARAM_TIMEOUT (0x13)
• WDG_E_PARAM_POINTER (0x14)
• WDG_E_INIT_FAILED (0x15, invalid selection of configuration set)

For development errors, Wdg optionally requests Det_ReportError [SWS_Wdg_00111]. The error cases of the individual services:

• Initialization: If the configuration set is outside the permissible limits, initialization is skipped with WDG_E_PARAM_CONFIG [SWS_Wdg_00090]. If the default mode would switch off the watchdog even though WdgDisableAllowed==OFF applies, it is skipped with WDG_E_DISABLE_REJECTED [SWS_Wdg_00025].
• Mode switch: An incorrect state leads to WDG_E_DRIVER_STATE [SWS_Wdg_00017]. A mode out of range or invalid hardware settings lead to WDG_E_PARAM_MODE ([SWS_Wdg_00091], [SWS_Wdg_00092]). In all three cases, no switch takes place, and the function returns E_NOT_OK. If the switch itself fails, for instance due to inconsistent settings or violated timing conditions, it returns E_NOT_OK and reports WDG_E_MODE_FAILED [SWS_Wdg_00016].
• Trigger condition: If the timeout exceeds WdgMaxTimeout, the counter is not reloaded, and WDG_E_PARAM_TIMEOUT is reported [SWS_Wdg_00146].
• Version query: An invalid pointer falls under WDG_E_PARAM_POINTER [SWS_Wdg_00010]. A document passage from more recent releases describes the null pointer check for Wdg_GetVersionInfo (SWS Wdg p. 30).

The production errors WDG_E_MODE_FAILED and WDG_E_DISABLE_REJECTED affect initialization and mode switches. Their monitoring frequency depends on the upper layer ([SWS_Wdg_00178], [SWS_Wdg_00179]). They are reported with FAILED if setting or switching off the mode fails, and with PASSED if it succeeds ([SWS_Wdg_00180], [SWS_Wdg_00181], [SWS_Wdg_00182], [SWS_Wdg_00183]). These reports likely run via the optionally requested Dem_SetEventStatus [SWS_Wdg_00111]. Question (open) The most severe case deliberately does not appear as a return value: If the trigger condition is omitted or set to 0, the watchdog expires, and the ECU is reset ([SWS_Wdg_00135], [SWS_Wdg_00140]).

Activity diagram: Wdg_SetMode checks state, mode, and hardware limits, switches over, and reports the result via return value and WDG_E_MODE_FAILED. Interpretation: The order of checks is not normatively specified. Sources: [SWS_Wdg_00017], [SWS_Wdg_00091], [SWS_Wdg_00092], [SWS_Wdg_00016], [SWS_Wdg_00103], [SWS_Wdg_00018], [SWS_Wdg_00180], [SWS_Wdg_00181]

Further detailed evidence

• [SWS_Wdg_00144]: Basic principle of the trigger condition and the division of tasks between controlling instance and driver.
• [SWS_Wdg_00134], [SWS_Wdg_00135], [SWS_Wdg_00136], [SWS_Wdg_00140]: Counter logic of the servicing routine and special case of timeout 0.
• [SWS_Wdg_00160], [SWS_Wdg_00103], [SWS_Wdg_00031]: Modes, success condition, and switching off instead of de-initialization.
• [SWS_Wdg_00076], [SWS_Wdg_00077], [SWS_Wdg_00161], [SWS_Wdg_00172]: Internal and external instances and name extension (SWS Wdg p. 24).
• Differing diagrams: Figure 2 of the driver as well as the sequence diagrams of the Watchdog Manager show WdgIf_Trigger and Wdg_Trigger, respectively (SWS Wdg Fig. 2 p. 30, SWS WdgM Fig. 13 p. 75, SWS WdgM Fig. 17 p. 78). This function is not part of the R20-11 API. Authoritative there is the mechanism via Wdg_SetTriggerCondition ([SWS_Wdg_00155]).
• Figure 9.2 on time-decoupled triggering originates from R21-11 and later releases. Its statement coincides with [SWS_Wdg_00134] and [SWS_Wdg_00093] (SWS Wdg Fig. 9.2 p. 31).