Watchdog Driver (Wdg)

Der Watchdog-Treiber steuert die interne oder externe Watchdog-Hardware im Auftrag des Watchdog Managers. Dieser setzt über das Watchdog Interface nur eine befristete Triggerbedingung. Solange sie gilt, triggert der Treiber die Hardware selbst; danach läuft der Watchdog ab [SWS_Wdg_00144]. Wdg_Init setzt Standardmodus und Timeout aus der Konfiguration, und Wdg_SetMode wechselt zwischen OFF-, SLOW- und FAST-Modus [SWS_Wdg_00160]. Ein Timeout von 0 löst einen nahezu sofortigen Reset aus, und abschalten lässt sich der Watchdog nur, wenn die Konfiguration es erlaubt.

mehr ›

Der Watchdog-Treiber Wdg steuert die Watchdog-Hardware über vier synchrone Dienste: Wdg_Init, Wdg_SetMode, Wdg_SetTriggerCondition und Wdg_GetVersionInfo ([SWS_Wdg_00106], [SWS_Wdg_00107], [SWS_Wdg_00155], [SWS_Wdg_00109]). EcuM ruft Wdg_Init auf. Der Watchdog Manager erreicht den Treiber nur über das Watchdog Interface, das die Instanz per DeviceIndex wählt (SWS WdgIf S. 17). Interne Instanzen greifen direkt auf die Hardware zu, externe über SPI oder DIO ([SWS_Wdg_00161], [SWS_Wdg_00076]). Beide bieten dieselbe API [SWS_Wdg_00077].

Kontextdiagramm: EcuM initialisiert die Wdg-Instanzen, WdgM steuert sie über WdgIf. Externe Instanzen erreichen die Hardware über Spi/Dio. Quellen: [SWS_Wdg_00076], [SWS_Wdg_00161], SWS WdgM S. 86

Kern des Moduls ist die Triggerbedingung. Sie gilt als Erlaubnis, den Watchdog für die nächsten n Millisekunden zu bedienen. Solange sie gültig ist, triggert der Treiber selbst; danach läuft der Watchdog ab [SWS_Wdg_00144]. Wdg_SetTriggerCondition setzt den Zähler zurück und rechnet die Millisekunden modusabhängig in einen Zählerwert um ([SWS_Wdg_00136], [SWS_Wdg_00139]). Die interne Bedienroutine triggert und dekrementiert, solange der Zähler größer als null ist. Bei null triggert sie nicht mehr ([SWS_Wdg_00134], [SWS_Wdg_00135]). Ein Timeout von 0 erzwingt einen (nahezu) sofortigen Reset, und ein abgelaufener Zähler lässt sich nicht neu laden [SWS_Wdg_00140].

Sequenzdiagramm: WdgM lädt nur den Zähler nach, das Triggern löst ein Timer-Interrupt im Treiber aus. Bei Zählerstand 0 läuft der Watchdog ab. Quellen: SWS Wdg Abb. 9.2 S. 31, [SWS_Wdg_00134], [SWS_Wdg_00135]

Wdg_Init setzt Standardmodus und Timeout-Periode aus dem Konfigurationssatz Wdg_ConfigType [SWS_Wdg_00001]. Wdg_SetMode wechselt zwischen WDGIF_OFF_MODE, WDGIF_SLOW_MODE und WDGIF_FAST_MODE und liefert E_OK nur bei vollständigem Wechsel ([SWS_Wdg_00160], [SWS_Wdg_00103]). Eine De-Initialisierung gibt es nicht. Abgeschaltet wird über den OFF-Modus [SWS_Wdg_00031], und das nur, wenn WdgDisableAllowed es erlaubt [SWS_Wdg_00025].

Im Fehlerfall meldet Wdg die Entwicklungsfehler WDG_E_DRIVER_STATE, WDG_E_PARAM_MODE, WDG_E_PARAM_CONFIG und WDG_E_PARAM_TIMEOUT [SWS_Wdg_00010]. Hinzu kommen die Produktionsfehler WDG_E_MODE_FAILED und WDG_E_DISABLE_REJECTED ([SWS_Wdg_00016], [SWS_Wdg_00179]). Diese Produktionsfehler dürften über Dem_SetEventStatus gemeldet werden [SWS_Wdg_00111]. Frage Q-f0ec41b842ebbdc9 (offen)

mehr ›

Rolle im Watchdog-Stack: der Treiber, der das Triggern selbst übernimmt

Der Watchdog-Treiber Wdg steuert die Watchdog-Hardware über eine kleine, synchrone API mit vier Diensten, die alle über Wdg.h verfügbar sind: Wdg_Init (Service-ID 0x00), Wdg_SetMode (0x01), Wdg_SetTriggerCondition (0x03) und Wdg_GetVersionInfo (0x04). Nur Wdg_GetVersionInfo ist reentrant ([SWS_Wdg_00106], [SWS_Wdg_00107], [SWS_Wdg_00155], [SWS_Wdg_00109]). Eine Schnittstelle zur De-Initialisierung gibt es bewusst nicht. Wenn Hardware und Umgebung ein Abschalten zulassen, geschieht es über Wdg_SetMode mit dem OFF-Modus [SWS_Wdg_00031].

Die Dienste werden von der Basissoftware aufgerufen. Der ECU State Manager ruft Wdg_Init auf (SWS EcuM S. 34). Der Watchdog Manager benötigt WdgIf_SetMode und WdgIf_SetTriggerCondition (SWS WdgM S. 86). Das Watchdog Interface bildet diese Aufrufe auf den Treiber ab und wählt die Instanz über einen nullbasierten DeviceIndex vom Typ uint8. Ist nur ein Treiber konfiguriert, darf diese Abbildung keinen Laufzeit-Overhead verursachen, etwa durch Makros (SWS WdgIf S. 17). Das zeitliche Triggern liegt vollständig im Treiber. Der Watchdog Manager setzt nur die Triggerbedingung (SWS WdgM S. 56; [SWS_Wdg_00144]).

Zur Hardware hin unterscheiden sich die Instanzen. Eine Instanz für einen internen Watchdog greift direkt auf die Hardware zu [SWS_Wdg_00161]. Eine Instanz für einen externen Watchdog nutzt die API eines Handlers oder Treibers, etwa SPI oder DIO [SWS_Wdg_00076]. Optional verwendet Wdg Det_ReportError für Entwicklungsfehler und Dem_SetEventStatus für Monitorstatus [SWS_Wdg_00111].

Kontextdiagramm: Wdg wird von EcuM initialisiert und vom WdgM nur indirekt über WdgIf gesteuert. Interne Instanzen greifen direkt auf die Hardware zu, externe über Spi/Dio. Quellen: [SWS_Wdg_00076], [SWS_Wdg_00161], [SWS_Wdg_00111], SWS WdgM S. 86

Vom Systemstart zum überwachten Betrieb

Wdg_Init erhält einen Zeiger auf einen Konfigurationssatz vom Typ Wdg_ConfigType. Diese Struktur ist hardwareabhängig ([SWS_Wdg_00106], [SWS_Wdg_00171]). Die Funktion initialisiert Treiber und Hardware und setzt den Standardmodus und die Timeout-Periode aus diesem Satz [SWS_Wdg_00001]. Außerdem initialisiert sie alle globalen Variablen [SWS_Wdg_00100]. Sie beschreibt nur die Controllerregister, die andere Hardwaremodule weder beeinflussen noch von ihnen abhängen. Gemeinsam genutzte Register initialisiert ein übergreifendes Systemmodul [SWS_Wdg_00101]. Bei aktivierter Entwicklungsfehlererkennung wechselt der interne Zustand nach erfolgreicher Initialisierung von WDG_UNINIT nach WDG_IDLE [SWS_Wdg_00019].

Abbildung 9.1 der Spezifikation zeigt die Arbeitsteilung: EcuM initialisiert Wdg direkt, danach steuert WdgM über WdgIf Triggerbedingung und Modus (SWS Wdg Abb. 9.1 S. 34). Für Integratoren ist wichtig: Ab Wdg_Init gelten der konfigurierte Standardmodus und die initiale Timeout-Periode [SWS_Wdg_00001]. Ist dieser Modus nicht OFF, muss die steuernde Instanz die Triggerbedingung innerhalb des Zeitfensters erneuern, sonst läuft der Watchdog ab [SWS_Wdg_00144].

Sequenzdiagramm: Auf die Initialisierung durch EcuM folgen das Setzen der Triggerbedingung und das Umschalten des Modus durch WdgM über WdgIf. Quellen: SWS Wdg Abb. 9.1 S. 34, [SWS_Wdg_00001], [SWS_Wdg_00019], [SWS_Wdg_00139], SWS WdgIf S. 18

Triggerbedingung: befristete Erlaubnis zum Bedienen

Die Hardware wird nicht durch einzelne Triggeraufrufe von außen bedient. Stattdessen gilt eine Triggerbedingung: Solange sie gültig ist, bedient der Treiber die Hardware selbst. Wird sie ungültig, stellt er das Triggern ein, und der Watchdog läuft ab [SWS_Wdg_00144]. Die Spezifikation beschreibt die Bedingung als „Erlaubnis, den Watchdog für die nächsten n Millisekunden zu bedienen“. Die steuernde Instanz muss sie innerhalb dieses Fensters erneuern [SWS_Wdg_00144].

Wdg_SetTriggerCondition(uint16 timeout) setzt den Timeout-Zähler entsprechend dem übergebenen Wert zurück ([SWS_Wdg_00155], [SWS_Wdg_00136]). Der Wert wird als Millisekunden interpretiert. Der Treiber rechnet ihn intern in einen Zählerwert um [SWS_Wdg_00138] und berücksichtigt dabei den aktuellen Modus [SWS_Wdg_00139]. Der Wert 0 ist zulässig: Er beendet das Triggern (nahezu) sofort und löst damit einen (nahezu) sofortigen Watchdog-Reset aus. Steht der gespeicherte Zähler bereits auf 0, ignoriert die Funktion jeden neuen Wert [SWS_Wdg_00140]. Ein abgelaufener Zähler lässt sich also nicht mehr neu laden.

Das eigentliche Triggern erledigt eine treiberinterne Bedienroutine. Ist der Triggerzähler größer als null, dekrementiert sie ihn und triggert die Hardware [SWS_Wdg_00134]. Hat er null erreicht, tut sie nichts, und der Watchdog läuft ab [SWS_Wdg_00135]. Wird die Bedienung als Interruptroutine umgesetzt, gehören die Interrupt-Rahmen in Wdg_Irq.c [SWS_Wdg_00079]. Abbildung 9.2 zeigt dafür einen Timer-Interrupt, der das Triggern zeitlich unabhängig vom Aufruf über WdgIf auslöst (SWS Wdg Abb. 9.2 S. 31).

Sequenzdiagramm: WdgM lädt den Triggerzähler nur nach, das Triggern selbst löst ein Timer-Interrupt im Treiber aus. Bei Zählerstand 0 unterbleibt das Triggern, und der Watchdog läuft ab. Quellen: SWS Wdg Abb. 9.2 S. 31, [SWS_Wdg_00134], [SWS_Wdg_00135], [SWS_Wdg_00136], [SWS_Wdg_00093]

Aktivitätsdiagramm: Wdg_SetTriggerCondition verwirft zu große Timeouts, ignoriert neue Werte bei bereits abgelaufenem Zähler und rechnet sonst modusabhängig in einen Zählerwert um. Interpretation: Die Reihenfolge der beiden Prüfungen legt die Spezifikation nicht fest. Quellen: [SWS_Wdg_00146], [SWS_Wdg_00140], [SWS_Wdg_00138], [SWS_Wdg_00139], SWS Wdg S. 29

Betriebsmodi OFF, SLOW und FAST

Wdg_SetMode schaltet Treiber und Hardware vom aktuellen Modus in WDGIF_OFF_MODE, WDGIF_SLOW_MODE oder WDGIF_FAST_MODE. Jeder Modus entspricht einer statisch konfigurierten Einstellung, etwa Toggle- oder Window-Watchdog mit unterschiedlichen Timeout-Perioden [SWS_Wdg_00160]. Die hardwarespezifischen Parameter je Modus stehen im Konfigurationssatz, der an Wdg_Init übergeben wird [SWS_Wdg_00051]. Den Typ WdgIf_ModeType importiert Wdg aus WdgIf.h [SWS_Wdg_00105]. Ein älteres Konfigurationsmodell zeigt dazu die Container WdgSettingsFast, WdgSettingsSlow und WdgSettingsOff sowie WdgDefaultMode (ECUC-Parameter Abb. 5.21 S. 377).

Wdg_SetMode liefert E_OK nur, wenn der Wechsel vollständig ausgeführt ist und alle Parameter von Treiber und Hardware die neuen Werte haben [SWS_Wdg_00103]. WdgIf reicht diesen Rückgabewert unverändert weiter (SWS WdgIf S. 18). Ob der Watchdog abgeschaltet werden darf, bestimmt der Pre-Compile-Parameter WdgDisableAllowed. Steht er auf OFF, wird eine Initialisierung mit abschaltendem Standardmodus abgelehnt [SWS_Wdg_00025]. Der Fehler WDG_E_DISABLE_REJECTED deckt laut seiner Beschreibung auch einen entsprechenden Moduswechsel ab [SWS_Wdg_00179].

Zustandsdiagramm: Wdg_Init setzt den konfigurierten Standardmodus, danach wechselt Wdg_SetMode zwischen den drei Modi. Der OFF-Modus ist nur erreichbar, wenn WdgDisableAllowed es zulässt. Quellen: [SWS_Wdg_00160], [SWS_Wdg_00001], [SWS_Wdg_00025], [SWS_Wdg_00179], [SWS_Wdg_00031]

Interne Zustände, exklusive Bereiche und Aktivierungscodes

Bei aktivierter Entwicklungsfehlererkennung führt Wdg einen internen Zustand: WDG_UNINIT bis zur erfolgreichen Initialisierung, danach WDG_IDLE [SWS_Wdg_00019]. Wdg_SetMode und die Bedienroutine setzen während ihrer Ausführung WDG_BUSY. Als letzte Operation vor der Rückkehr setzen sie wieder WDG_IDLE ([SWS_Wdg_00018], [SWS_Wdg_00052]). Beide prüfen vorher, ob der Zustand WDG_IDLE ist. Andernfalls unterbleibt der Moduswechsel bzw. das Triggern, und WDG_E_DRIVER_STATE wird gemeldet ([SWS_Wdg_00017], [SWS_Wdg_00035]). So werden Aufrufe vor der Initialisierung erkannt, ebenso Überschneidungen von Moduswechsel und Triggern.

Müssen für Datenkonsistenz Interrupts gesperrt werden, etwa beim Moduswechsel oder in der Triggerroutine, soll dies möglichst über einen exklusiven Bereich des BSW-Schedulers geschehen. Der interne Treiber darf als MCAL-Modul Interrupts auch direkt sperren [SWS_Wdg_00040]. Der Leitfaden zur BSW-Verteilung erklärt den Hintergrund: In MCAL-Treibern können Main Function, Service-API und ISR in eigenen Ausführungskontexten auf gemeinsame Peripherieregister zugreifen (BSW Distribution Guide S. 36).

Manche Hardware verlangt einen konfigurierbaren oder veränderlichen Aktivierungscode. Dann verwaltet Wdg den Code intern und übergibt jeweils den korrekten Wert. Die Hardware aktualisiert daraufhin die interne Variable mit dem nächsten erwarteten Code [SWS_Wdg_00093]. Der Triggerzyklus muss so gewählt sein, dass diese Aktualisierung garantiert stattfinden kann [SWS_Wdg_00094]. Ein konfigurierbarer Anfangscode gehört in den Konfigurationssatz. Bei hardwarefest vorgegebenem Code entfällt diese Anforderung [SWS_Wdg_00095].

Zustandsdiagramm: Bei aktivierter Entwicklungsfehlererkennung gelten die Zustände WDG_UNINIT, WDG_IDLE und WDG_BUSY. Aufrufe außerhalb von WDG_IDLE werden mit WDG_E_DRIVER_STATE abgewiesen. Quellen: [SWS_Wdg_00019], [SWS_Wdg_00017], [SWS_Wdg_00018], [SWS_Wdg_00035], [SWS_Wdg_00052]

Interne und externe Watchdogs: Instanzen, Dateien, Konfiguration

Ein Steuergerät kann mehrere Wdg-Instanzen haben, etwa eine für einen internen und eine für einen externen Watchdog. Dann werden API-Namen und instanzspezifische Typnamen [SWS_Wdg_00172] sowie Code- und Header-Dateinamen nach SRS_BSW_00347 erweitert ([SWS_Wdg_00169], [SWS_Wdg_00170]). Abbildung 1 zeigt die Dateistruktur mit Platzhaltern wie Wdg<xxx>.h und Wdg_<xxx>PBcfg.c (SWS Wdg Abb. 1 S. 11). Ein externer Wdg muss denselben Funktionsumfang mit semantisch identischer API bieten wie ein interner [SWS_Wdg_00077]. Sein Quellcode muss unabhängig von der Mikrocontrollerplattform sein [SWS_Wdg_00055]. Ein Beispiel aus dem Safety-Umfeld ist ein externer Window-Watchdog, der per SPI angebunden ist (EXP SafetyUseCase Abb. 4.1 S. 20).

Die Codedateistruktur ist nicht vollständig vorgegeben. Bei Bedarf umfasst sie Wdg_Lcfg.c für Link-Time-Parameter und Wdg_PBcfg.c für Post-Build-Parameter [SWS_Wdg_00079]. Wdg prüft die Konfiguration spätestens zur Compile-Zeit statisch [SWS_Wdg_00086]. Ob der Code aus ROM oder RAM läuft, legt eine statische Konfiguration fest [SWS_Wdg_00168]. Für externe Hardware nimmt Wdg die Zugriffsparameter, etwa SPI-Kanal oder DIO-Port, in seine veröffentlichten Parameter und seine Konfigurationsparameter auf [SWS_Wdg_00078]. Jüngere Releases modellieren das als Auswahlreferenz WdgExternalContainerRef auf eine DIO-Kanalgruppe, eine SPI-Sequenz oder eine I2C-Sequenz. I2C wird in R20-11 nicht ausdrücklich genannt (SWS Wdg S. 40). Gegen den Maximalwert WdgMaxTimeout prüft Wdg_SetTriggerCondition [SWS_Wdg_00146]. Das Modell der veröffentlichten Informationen enthält daneben WdgMinTimeout und WdgResolution (ECUC-Parameter Abb. 5.22 S. 380).

Verhalten im Fehlerfall

Wdg unterscheidet Entwicklungsfehler, die überwiegend nur bei aktivierter Entwicklungsfehlererkennung geprüft werden, von erweiterten Produktionsfehlern. Die Fehlercodes sind festgelegt [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, ungültige Auswahl des Konfigurationssatzes)

Für Entwicklungsfehler fordert Wdg optional Det_ReportError an [SWS_Wdg_00111]. Die Fehlerfälle der einzelnen Dienste:

• Initialisierung: Liegt der Konfigurationssatz außerhalb der zulässigen Grenzen, unterbleibt die Initialisierung mit WDG_E_PARAM_CONFIG [SWS_Wdg_00090]. Würde der Standardmodus den Watchdog abschalten, obwohl WdgDisableAllowed==OFF gilt, unterbleibt sie mit WDG_E_DISABLE_REJECTED [SWS_Wdg_00025].
• Moduswechsel: Ein falscher Zustand führt zu WDG_E_DRIVER_STATE [SWS_Wdg_00017]. Ein Modus außerhalb des Bereichs oder unzulässige Hardwareeinstellungen führen zu WDG_E_PARAM_MODE ([SWS_Wdg_00091], [SWS_Wdg_00092]). In allen drei Fällen findet kein Wechsel statt, und die Funktion liefert E_NOT_OK. Scheitert der Wechsel selbst, etwa an inkonsistenten Einstellungen oder verletzten Zeitbedingungen, liefert sie E_NOT_OK und meldet WDG_E_MODE_FAILED [SWS_Wdg_00016].
• Triggerbedingung: Überschreitet der Timeout WdgMaxTimeout, wird der Zähler nicht neu geladen, und WDG_E_PARAM_TIMEOUT wird gemeldet [SWS_Wdg_00146].
• Versionsabfrage: Ein ungültiger Zeiger fällt unter WDG_E_PARAM_POINTER [SWS_Wdg_00010]. Die Nullzeiger-Prüfung für Wdg_GetVersionInfo beschreibt eine Dokumentstelle aus jüngeren Releases (SWS Wdg S. 30).

Die Produktionsfehler WDG_E_MODE_FAILED und WDG_E_DISABLE_REJECTED betreffen Initialisierung und Moduswechsel. Ihre Überwachungsfrequenz hängt von der oberen Schicht ab ([SWS_Wdg_00178], [SWS_Wdg_00179]). Sie werden mit FAILED gemeldet, wenn Setzen bzw. Abschalten des Modus scheitert, und mit PASSED, wenn es gelingt ([SWS_Wdg_00180], [SWS_Wdg_00181], [SWS_Wdg_00182], [SWS_Wdg_00183]). Diese Meldungen dürften über das optional angeforderte Dem_SetEventStatus laufen [SWS_Wdg_00111]. Frage (offen) Der gravierendste Fall erscheint bewusst nicht als Rückgabewert: Bleibt die Triggerbedingung aus oder wird 0 gesetzt, läuft der Watchdog ab, und das Steuergerät wird zurückgesetzt ([SWS_Wdg_00135], [SWS_Wdg_00140]).

Aktivitätsdiagramm: Wdg_SetMode prüft Zustand, Modus und Hardwaregrenzen, schaltet um und meldet das Ergebnis über Rückgabewert und WDG_E_MODE_FAILED. Interpretation: Die Reihenfolge der Prüfungen ist nicht normativ festgelegt. Quellen: [SWS_Wdg_00017], [SWS_Wdg_00091], [SWS_Wdg_00092], [SWS_Wdg_00016], [SWS_Wdg_00103], [SWS_Wdg_00018], [SWS_Wdg_00180], [SWS_Wdg_00181]

Weiterführende Detailbelege

• [SWS_Wdg_00144]: Grundprinzip der Triggerbedingung und der Aufgabenteilung zwischen steuernder Instanz und Treiber.
• [SWS_Wdg_00134], [SWS_Wdg_00135], [SWS_Wdg_00136], [SWS_Wdg_00140]: Zählerlogik der Bedienroutine und Sonderfall Timeout 0.
• [SWS_Wdg_00160], [SWS_Wdg_00103], [SWS_Wdg_00031]: Modi, Erfolgsbedingung und Abschalten statt De-Initialisierung.
• [SWS_Wdg_00076], [SWS_Wdg_00077], [SWS_Wdg_00161], [SWS_Wdg_00172]: interne und externe Instanzen und Namenserweiterung (SWS Wdg S. 24).
• Abweichende Schaubilder: Abbildung 2 des Treibers sowie die Ablaufbilder des Watchdog Managers zeigen WdgIf_Trigger bzw. Wdg_Trigger (SWS Wdg Abb. 2 S. 30, SWS WdgM Abb. 13 S. 75, SWS WdgM Abb. 17 S. 78). Diese Funktion gehört nicht zur R20-11-API. Maßgeblich ist dort der Mechanismus über Wdg_SetTriggerCondition ([SWS_Wdg_00155]).
• Abbildung 9.2 zum zeitlich entkoppelten Triggern stammt aus R21-11 und späteren Releases. Ihre Aussage deckt sich mit [SWS_Wdg_00134] und [SWS_Wdg_00093] (SWS Wdg Abb. 9.2 S. 31).