class ara::diag::DTCInformation

Die Methode Clear der Klasse ara::diag::DTCInformation ([SWS_DM_00671]) dient dem Löschen eines einzelnen DTCs oder einer DTC-Gruppe im Fehlerspeicher (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.6 „Service 0x14 – ClearDiagnosticInformation“). Als Parameter nimmt sie über dtcGroup die Kennung der zu löschenden Gruppe bzw. des DTCs entgegen und liefert das Ergebnis asynchron als ara::core::Future<void> zurück ([SWS_DM_00671]). Die Berechtigung zum Löschen einzelner DTCs oder Gruppen unterliegt dabei Konfigurationsparametern wie clearDtcLimitation ([SWS_DM_00160]).

Fehlerbehandlung und Semantik

Die Funktion ist als noexcept deklariert und meldet Fehler asynchron über das Future mit Rollback-Semantik ([SWS_DM_00671]). Mögliche Fehlercodes aus DiagErrc sind:

• DiagErrc::kBusy: Die Schnittstelle ist bereits mit einer Verarbeitung belegt.
• DiagErrc::kFailed: Bei der Ausführung ist ein allgemeiner Verarbeitungsfehler aufgetreten.
• DiagErrc::kMemoryError: Während der Bearbeitung trat ein Speicherfehler auf.
• DiagErrc::kWrongDtc: Es wurde eine ungültige DTC-Nummer übergeben.
• DiagErrc::kServiceNotAvailable: Essenzielle Funktionen des Diagnostic Managers stehen derzeit nicht zur Verfügung.

Nebenläufigkeit und Abgrenzung

Die Methode ist ausnahmesicher (exception safe), jedoch ausdrücklich als not thread-safe eingestuft ([SWS_DM_00671]). Parallele Aufrufe auf derselben Instanz müssen daher durch den Aufrufer synchronisiert werden, andernfalls droht DiagErrc::kBusy. Interpretation: Das zurückgegebene ara::core::Future dürfte erst dann erfüllt werden, wenn der physische Fehlerspeicher vollständig bereinigt wurde, analog zur Quittierung des UDS-Dienstes 0x14 ([SWS_DM_00162]). Frage Q-b97545b6864b24aa (offen)

Funktional ist die Operation von gleichnamigen SOVD-Methoden abzugrenzen: Während ara::diag::DiagnosticSovdContentElementDataView::Clear ([SWS_DM_02233]) Datencontainer synchron und thread-safe leert, steuert diese Methode Diagnoseabläufe im Diagnostic Management.

Verwendung

Die Methode ara::diag::DTCInformation::EnableControlDtc ([SWS_DM_00674]) dient einer Überwachungsanwendung dazu, die Erfassung und Speicherung von Diagnose-Fehlercodes (DTCs) im Diagnostic Server wieder freizugeben. Der Aufruf erfolgt parameterlos und synchron über eine Instanz der Klasse ara::diag::DTCInformation aus dem Header ara/diag/dtc_information.h. Als Rückgabewert liefert die Funktion ara::core::Result<void> zurück.

Zusammenspiel und Semantik

Wurde das DTC-Setting zuvor, etwa über den UDS-Dienst ControlDTCSetting (0x85) mit Subfunktion 0x02 (OFF), deaktiviert ([SWS_DM_00910]), veranlasst der Aufruf von EnableControlDtc den Diagnostic Server gemäß [SWS_DM_00811] zu folgenden Schritten:

• Wiederfreigabe der Aktualisierung des UDS-DTC-Statusbytes,
• Freigabe der Fehlerspeicherung im primären sowie in betroffenen anwenderspezifischen Ereignisspeichern,
• Aktualisierung von ara::diag::ControlDtcStatusType auf kDTCSettingOn.

Interpretation: Das Setzen des Status auf aktiviert erfolgt unter Umständen erst nach der Rückkehr des Methodenaufrufs (AP SWS Diagnostics §8.48.2.2.3.2 „EnableControlDtc“), weshalb Aufrufer nicht von einer zwingend unmittelbaren Statusänderung während der Ausführung ausgehen dürfen. Frage Q-8bfa0436f6ab98b9 (offen)

Fehlerbehandlung und Nebenläufigkeit

Die Schnittstelle ist als noexcept deklariert, gilt als ausnahmesicher (exception safe) und definiert keine spezifischen standardisierten Fehlercodes ([SWS_DM_00674]). Hinsichtlich der Nebenläufigkeit ist die Funktion als nicht threadsicher (not thread-safe) spezifiziert. Parallele Zugriffe auf dieselbe Instanz müssen daher durch die aufrufende Anwendung synchronisiert werden.

Verwendung und Aufrufkontext

Die Methode SetControlDtcStatusNotifier gehört zur Klasse ara::diag::DTCInformation und wird über den Header ara/diag/dtc_information.h eingebunden [SWS_DM_00673]. Sie dient der Registrierung einer anwendungsseitigen Callback-Funktion vom Typ ControlDtcStatusTypeNotifier [SWS_DM_00673]. Dieser Notifier wird aufgerufen, wenn sich der ControlDTCStatus für die betreffende Diagnosespeicher-Instanz ändert, welcher mit dem UDS-Dienst 0x85 (ControlDTCSetting) in Verbindung steht [SWS_DM_00673]. Ein wiederholter Aufruf der Methode führt dazu, dass ein zuvor registrierter Notifier überschrieben wird [SWS_DM_00673].

Fehlerbehandlung und Rückgabewerte

Als Rückgabetyp dient ara::core::Result<void> [SWS_DM_00673]. Im Erfolgsfall liefert die Funktion keinen Wert zurück, während im Fehlerfall ein Fehlercode bereitgestellt wird [SWS_DM_00673]. Als möglicher Fehler ist der Code DiagErrc::kInvalidArgument spezifiziert [SWS_DM_00673]. Die Funktion ist als noexcept deklariert und als exception safe eingestuft, weshalb Aufrufer keine C++-Ausnahmen behandeln müssen [SWS_DM_00673].

Nebenläufigkeit und Spezifikationsstatus

Die Schnittstelle ist explizit als not thread-safe ausgewiesen [SWS_DM_00673]. Daher müssen parallele Zugriffe auf dieselbe Instanz von ara::diag::DTCInformation durch den Aufrufer synchronisiert werden. Gemäß Dokumentation SWS Diagnostics §8.48.2.2.3.7 „SetControlDtcStatusNotifier“ besitzt die API-Definition im Release R25-11 zudem den Status DRAFT.

Mit der Funktion ara::diag::DTCInformation::SetDTCStatusChangedNotifier registriert eine Adaptive Application (AA) eine Callback-Funktion, die bei jeder Änderung des UDS-DTC-Status aufgerufen wird ([SWS_DM_00667]). Sobald sich der Status eines dem jeweiligen Fehlerspeicher zugeordneten DTCs ändert, löst das Diagnostic Management (DM) diesen Notifier für den betroffenen DTC aus ([SWS_DM_01031], SWS Diagnostics §7.3.4.4.2.2 „UDS DTC Status change notifications“).

Die Schnittstelle besitzt folgende Eigenschaften und Parameter (SWS Diagnostics §8.48.2.2.3.8 „SetDTCStatusChangedNotifier“):

• Parameter: notifier nimmt das aufzurufende Funktionsobjekt vom Typ DtcStatusChangedNotifier entgegen ([SWS_DM_00667]).
• Rückgabewert: Die Funktion liefert ara::core::Result<void> zurück und ist als noexcept deklariert ([SWS_DM_00667]).
• Fehlerbehandlung: Es sind keine standardisierten Fehlercodes definiert; die Funktion ist als ausnahmesicher (exception safe) spezifiziert ([SWS_DM_00667]).
• Nebenläufigkeit: Die Methode ist nicht threadsicher (not thread-safe) ([SWS_DM_00667]). Parallele Aufrufe auf derselben Instanz müssen aufruferseitig synchronisiert werden.

Wird SetDTCStatusChangedNotifier auf derselben Instanz von ara::diag::DTCInformation wiederholt aufgerufen, überschreibt das DM den zuvor registrierten Notifier vollständig ([SWS_DM_01350]). Im Gesamtsystem ergänzt der Notifier die synchrone Statusabfrage mittels GetCurrentStatus um eine ereignisbasierte Benachrichtigung über Statuswechsel im Fehlerspeicher (SWS Diagnostics §7.3.4.4.2.2 „UDS DTC Status change notifications“).

Die Funktion SetEventMemoryOverflowNotifier der Klasse ara::diag::DTCInformation (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.9 „SetEventMemoryOverflowNotifier“) dient der Registrierung einer Callback-Funktion (notifier), die bei einer Änderung des Überlaufstatus des zugeordneten Ereignisspeichers aufgerufen wird [SWS_DM_00918].

Verwendung und Semantik: Der Aufruf erfolgt über eine Instanz von ara::diag::DTCInformation unter Einbindung der Header-Datei ara/diag/dtc_information.h. Der Parameter notifier nimmt ein Funktionsobjekt vom Typ EventMemory OverflowSetNotifier entgegen. Bei erfolgreicher Registrierung liefert die Methode ein leeres ara::core::Result<void> zurück [SWS_DM_00918].

Zusammenspiel und Auslösung: Ein Überlauf entsteht, wenn in einem Ereignisspeicher bereits die maximal konfigurierte Anzahl an Einträgen (DiagnosticMemoryDestination.maxNumberOfEventEntries) hinterlegt ist und ein weiterer Eintrag gespeichert werden soll (AUTOSAR_AP_SWS_Diagnostics §7.3.4.4.9 „Event memory overflow“, [SWS_DM_00923]). Wurde ein Überlauf registriert, ruft das Diagnostic-Management-Modul den Notifier nach dem nächsten Ausführen des Löschvorgangs aller DTCs (clear all DTCs) für den jeweiligen Ereignisspeicher mit dem Parameterwert false auf [SWS_DM_00926].

Nebenläufigkeit und Einschränkungen: Die Funktion ist als noexcept deklariert und gilt als ausnahmesicher (exception safe), ist jedoch nicht threadsicher (not thread-safe) [SWS_DM_00918]. Parallele Aufrufe an derselben Instanz müssen daher extern synchronisiert werden. Wird SetEventMemoryOverflowNotifier mehrfach aufgerufen, überschreibt der neue Aufruf den zuvor registrierten Notifier vollständig [SWS_DM_01354].

Fehlerbehandlung: Schlägt die Operation fehl, wird der Fehlercode DiagErrc::kInvalidArgument im ara::core::Result zurückgegeben [SWS_DM_00918].

Die Methode SetNumberOfStoredEntriesNotifier der Klasse ara::diag::DTCInformation (deklariert in ara/diag/dtc_information.h) dient der Registrierung einer Callback-Funktion vom Typ NumberOfStoredEntriesNotifier ([SWS_DM_00670]). Diese Funktion wird benachrichtigt, sobald sich die Anzahl der im Fehlerspeicher der betreffenden Ereignisspeicher-Instanz hinterlegten Einträge ändert (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.10 „SetNumberOfStoredEntriesNotifier“).

Für die Verwendung und das Laufzeitverhalten gelten die folgenden Spezifikationen:

• Überschreibende Registrierung: Pro Instanz kann jeweils nur eine Callback-Funktion aktiv sein. Ein erneuter Aufruf der Methode überschreibt den zuvor registrierten Notifier vollständig ([SWS_DM_00670]).
• Nebenläufigkeit und Sicherheit: Die Methode ist mit noexcept versehen und als ausnahmesicher (exception safe) spezifiziert ([SWS_DM_00670]). Da sie jedoch als nicht threadsicher (not thread-safe) eingestuft ist, müssen parallele Zugriffe auf dieselbe Instanz anwendungsseitig synchronisiert werden.
• Fehlerbehandlung: Die Funktion gibt ein ara::core::Result<void> zurück ([SWS_DM_00670]). Schlägt die Registrierung fehl, wird der Fehlercode DiagErrc::kInvalidArgument zurückgemeldet ([SWS_DM_00670]); dies dürfte insbesondere dann der Fall sein, wenn ein ungültiger Notifier übergeben wird. Frage Q-27e5e89452a7dfbb (offen)

Verwendung und Ablauf

Die Methode ara::diag::DTCInformation::SetSnapshotRecordUpdatedNotifier dient der Registrierung einer Callback-Funktion vom Typ SnapshotRecordUpdatedTypeNotifier, die aufgerufen wird, sobald sich ein Snapshot-Record ändert ([SWS_DM_00668], AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.11 „SetSnapshotRecordUpdatedNotifier“). Nachfolgende Aufrufe dieser Methode sind zulässig und überschreiben einen zuvor registrierten Notifier vollständig ([SWS_DM_00668]).

Fehlerbehandlung und Signatur

Die Funktion ist als noexcept deklariert und gewährleistet Ausnahme-Sicherheit (exception safe) ([SWS_DM_00668]). Als Rückgabetyp dient ara::core::Result<void>, über den Fehler synchron zurückgegeben werden. Im Fehlerfall kann der Fehlercode DiagErrc::kInvalidArgument zurückgeliefert werden ([SWS_DM_00668]). Interpretation: Die Spezifikationsnotiz „rollback_semantics e.g. kPreFailed with internal debouncing“ dürfte darauf hindeuten, dass dieser Fehler bei ungültigen Zuständen während interner Entprellungen und Rollbacks gemeldet wird. Frage Q-481ee254b8395fef (offen)

Nebenläufigkeit und Einschränkungen

Die Methode ist explizit als nicht threadsicher (not thread-safe) spezifiziert ([SWS_DM_00668]). Aufrufende Komponenten müssen sicherstellen, dass nebenläufige Zugriffe auf dasselbe ara::diag::DTCInformation-Objekt extern synchronisiert werden.