klasse ara::diag::DTCInformation

De methode Clear van de klasse ara::diag::DTCInformation ([SWS_DM_00671]) dient voor het wissen van een afzonderlijke DTC of een DTC-groep in het foutgeheugen (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.6 “Service 0x14 – ClearDiagnosticInformation”). Als parameter accepteert zij via dtcGroup de identificator van de te wissen groep resp. DTC en levert het resultaat asynchroon terug als ara::core::Future<void> ([SWS_DM_00671]). De bevoegdheid om afzonderlijke DTC's of groepen te wissen is daarbij onderhevig aan configuratieparameters zoals clearDtcLimitation ([SWS_DM_00160]).

Foutafhandeling en semantiek

De functie is gedeclareerd als noexcept en meldt fouten asynchroon via de Future met rollback-semantiek ([SWS_DM_00671]). Mogelijke foutcodes uit DiagErrc zijn:

• DiagErrc::kBusy: De interface is al bezet met een verwerking.
• DiagErrc::kFailed: Bij de uitvoering is een algemene verwerkingsfout opgetreden.
• DiagErrc::kMemoryError: Tijdens de verwerking is een geheugenfout opgetreden.
• DiagErrc::kWrongDtc: Er is een ongeldig DTC-nummer doorgegeven.
• DiagErrc::kServiceNotAvailable: Essentiële functies van de Diagnostic Manager zijn momenteel niet beschikbaar.

Gelijktijdigheid en afbakening

De methode is uitzonderingsveilig (exception safe), maar uitdrukkelijk geclassificeerd als not thread-safe ([SWS_DM_00671]). Parallelle aanroepen op dezelfde instantie moeten daarom door de aanroeper worden gesynchroniseerd, anders dreigt DiagErrc::kBusy. Interpretatie: De geretourneerde ara::core::Future wordt vermoedelijk pas vervuld wanneer het fysieke foutgeheugen volledig is opgeschoond, analoog aan de bevestiging van UDS-dienst 0x14 ([SWS_DM_00162]). Vraag Q-b97545b6864b24aa (open)

Functioneel moet de operatie worden onderscheiden van gelijknamige SOVD-methoden: terwijl ara::diag::DiagnosticSovdContentElementDataView::Clear ([SWS_DM_02233]) datacontainers synchroon en thread-safe leegmaakt, bestuurt deze methode diagnoseprocessen in Diagnostic Management.

Gebruik

De methode ara::diag::DTCInformation::EnableControlDtc ([SWS_DM_00674]) dient ertoe dat een monitoringapplicatie de registratie en opslag van diagnose-foutcodes (DTC's) in de Diagnostic Server weer vrijgeeft. De aanroep vindt parameterloos en synchroon plaats via een instantie van de klasse ara::diag::DTCInformation uit de header ara/diag/dtc_information.h. Als retourwaarde levert de functie ara::core::Result<void> op.

Samenspel en semantiek

Werd de DTC-setting eerder, bijvoorbeeld via de UDS-dienst ControlDTCSetting (0x85) met subfunctie 0x02 (OFF), gedeactiveerd ([SWS_DM_00910]), dan zet de aanroep van EnableControlDtc de Diagnostic Server conform [SWS_DM_00811] aan tot de volgende stappen:

• Opnieuw vrijgeven van het bijwerken van de UDS-DTC-statusbyte,
• Vrijgave van de foutopslag in het primaire evenals in getroffen gebruikersspecifieke gebeurtenisgeheugens,
• Bijwerken van ara::diag::ControlDtcStatusType naar kDTCSettingOn.

Interpretatie: Het instellen van de status op geactiveerd vindt onder bepaalde omstandigheden pas plaats na terugkeer van de methode-aanroep (AP SWS Diagnostics §8.48.2.2.3.2 “EnableControlDtc”), waardoor aanroepers niet mogen uitgaan van een verplicht onmiddellijke statuswijziging tijdens de uitvoering. Vraag Q-8bfa0436f6ab98b9 (open)

Foutafhandeling en gelijktijdigheid

De interface is gedeclareerd als noexcept, geldt als uitzonderingsveilig (exception safe) en definieert geen specifieke gestandaardiseerde foutcodes ([SWS_DM_00674]). Met betrekking tot concurrency is de functie gespecificeerd als niet thread-safe (not thread-safe). Parallelle toegangen tot dezelfde instantie moeten daarom door de aanroepende applicatie worden gesynchroniseerd.

Gebruik en aanroepcontext

De methode SetControlDtcStatusNotifier behoort tot de klasse ara::diag::DTCInformation en wordt via de header ara/diag/dtc_information.h opgenomen [SWS_DM_00673]. Deze dient voor de registratie van een applicatiezijdige callbackfunctie van het type ControlDtcStatusTypeNotifier [SWS_DM_00673]. Deze notifier wordt aangeroepen wanneer de ControlDTCStatus voor de betreffende diagnosegeheugeninstantie wijzigt, die verband houdt met de UDS-dienst 0x85 (ControlDTCSetting) [SWS_DM_00673]. Een herhaalde aanroep van de methode leidt ertoe dat een eerder geregistreerde notifier wordt overschreven [SWS_DM_00673].

Foutafhandeling en retourwaarden

Als retourtype dient ara::core::Result<void> [SWS_DM_00673]. Bij succes retourneert de functie geen waarde, terwijl bij een fout een foutcode ter beschikking wordt gesteld [SWS_DM_00673]. Als mogelijke fout is de code DiagErrc::kInvalidArgument gespecificeerd [SWS_DM_00673]. De functie is gedeclareerd als noexcept en geclassificeerd als exception safe, waardoor aanroepers geen C++-excepties hoeven af te handelen [SWS_DM_00673].

Gelijktijdigheid en specificatiestatus

De interface is expliciet aangeduid als not thread-safe [SWS_DM_00673]. Daarom moeten parallelle toegangen tot dezelfde instantie van ara::diag::DTCInformation door de aanroeper worden gesynchroniseerd. Volgens de documentatie SWS Diagnostics §8.48.2.2.3.7 “SetControlDtcStatusNotifier” heeft de API-definitie in release R25-11 bovendien de status DRAFT.

Met de functie ara::diag::DTCInformation::SetDTCStatusChangedNotifier registreert een Adaptive Application (AA) een callbackfunctie die bij elke wijziging van de UDS-DTC-status wordt aangeroepen ([SWS_DM_00667]). Zodra de status van een aan het betreffende foutgeheugen toegewezen DTC verandert, triggert het Diagnostic Management (DM) deze notifier voor de betreffende DTC ([SWS_DM_01031], SWS Diagnostics §7.3.4.4.2.2 “UDS DTC Status change notifications”).

De interface heeft de volgende eigenschappen en parameters (SWS Diagnostics §8.48.2.2.3.8 “SetDTCStatusChangedNotifier”):

• Parameter: notifier neemt het aan te roepen functie-object van het type DtcStatusChangedNotifier aan ([SWS_DM_00667]).
• Retourwaarde: De functie retourneert ara::core::Result<void> en is gedeclareerd als noexcept ([SWS_DM_00667]).
• Foutafhandeling: Er zijn geen gestandaardiseerde foutcodes gedefinieerd; de functie is gespecificeerd als exception-safe (exception safe) ([SWS_DM_00667]).
• Gelijktijdigheid: De methode is niet thread-safe (not thread-safe) ([SWS_DM_00667]). Parallelle aanroepen op dezelfde instantie moeten aan de aanroeperszijde worden gesynchroniseerd.

Als SetDTCStatusChangedNotifier op dezelfde instantie van ara::diag::DTCInformation herhaaldelijk wordt aangeroepen, overschrijft het DM de eerder geregistreerde notifier volledig ([SWS_DM_01350]). In het totale systeem vult de notifier de synchrone statusopvraag via GetCurrentStatus aan met een gebeurtenisgebaseerde melding over statuswisselingen in het foutgeheugen (SWS Diagnostics §7.3.4.4.2.2 “UDS DTC Status change notifications”).

De functie SetEventMemoryOverflowNotifier van de klasse ara::diag::DTCInformation (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.9 “SetEventMemoryOverflowNotifier”) dient voor de registratie van een callback-functie (notifier), die wordt aangeroepen bij een wijziging van de overloopstatus van het toegewezen geheugen voor gebeurtenissen [SWS_DM_00918].

Gebruik en semantiek: De aanroep geschiedt via een instantie van ara::diag::DTCInformation met opname van het headerbestand ara/diag/dtc_information.h. De parameter notifier accepteert een functie-object van het type EventMemory OverflowSetNotifier. Bij succesvolle registratie levert de methode een lege ara::core::Result<void> terug [SWS_DM_00918].

Samenspel en activering: Een overloop ontstaat wanneer in een geheugen voor gebeurtenissen reeds het maximaal geconfigureerde aantal vermeldingen (DiagnosticMemoryDestination.maxNumberOfEventEntries) is opgeslagen en er nog een vermelding moet worden opgeslagen (AUTOSAR_AP_SWS_Diagnostics §7.3.4.4.9 “Event memory overflow”, [SWS_DM_00923]). Wanneer een overloop is geregistreerd, roept de Diagnostic-Management-module de notifier aan na de volgende uitvoering van het wisproces van alle DTC's (clear all DTCs) voor het betreffende geheugen voor gebeurtenissen met de parameterwaarde false [SWS_DM_00926].

Gelijktijdigheid en beperkingen: De functie is gedeclareerd als noexcept en geldt als uitzonderingsveilig (exception safe), maar is niet thread-safe (not thread-safe) [SWS_DM_00918]. Parallelle aanroepen op dezelfde instantie moeten daarom extern worden gesynchroniseerd. Als SetEventMemoryOverflowNotifier meermalen wordt aangeroepen, overschrijft de nieuwe aanroep de eerder geregistreerde notifier volledig [SWS_DM_01354].

Foutafhandeling: Faalt de operatie, dan wordt de foutcode DiagErrc::kInvalidArgument in ara::core::Result geretourneerd [SWS_DM_00918].

De methode SetNumberOfStoredEntriesNotifier van de klasse ara::diag::DTCInformation (gedeclareerd in ara/diag/dtc_information.h) dient voor de registratie van een callbackfunctie van het type NumberOfStoredEntriesNotifier ([SWS_DM_00670]). Deze functie wordt genotificeerd zodra het aantal in het foutgeheugen van de desbetreffende gebeurtenisgeheugeninstantie opgeslagen items wijzigt (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.10 “SetNumberOfStoredEntriesNotifier”).

Voor het gebruik en het runtimegedrag gelden de volgende specificaties:

• Overschrijvende registratie: Per instantie kan steeds slechts één callbackfunctie actief zijn. Een hernieuwde aanroep van de methode overschrijft de eerder geregistreerde notifier volledig ([SWS_DM_00670]).
• Gelijktijdigheid en veiligheid: De methode is voorzien van noexcept en gespecificeerd als exception-safe (exception safe) ([SWS_DM_00670]). Aangezien deze echter als niet thread-safe (not thread-safe) is ingedeeld, moeten parallelle toegangen tot dezelfde instantie applicatiezijdig worden gesynchroniseerd.
• Foutafhandeling: De functie retourneert een ara::core::Result<void> ([SWS_DM_00670]). Mislukt de registratie, dan wordt de foutcode DiagErrc::kInvalidArgument teruggemeld ([SWS_DM_00670]); dit is vermoedelijk met name het geval wanneer een ongeldige notifier wordt doorgegeven. Vraag Q-27e5e89452a7dfbb (open)

Gebruik en verloop

De methode ara::diag::DTCInformation::SetSnapshotRecordUpdatedNotifier dient voor de registratie van een callbackfunctie van het type SnapshotRecordUpdatedTypeNotifier die wordt aangeroepen zodra een snapshotrecord wijzigt ([SWS_DM_00668], AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.11 “SetSnapshotRecordUpdatedNotifier”). Daaropvolgende aanroepen van deze methode zijn toegestaan en overschrijven een eerder geregistreerde notifier volledig ([SWS_DM_00668]).

Foutafhandeling en signatuur

De functie is gedeclareerd als noexcept en waarborgt exceptieveiligheid (exception safe) ([SWS_DM_00668]). Als retourtype dient ara::core::Result<void>, waarmee fouten synchroon worden geretourneerd. In geval van een fout kan de foutcode DiagErrc::kInvalidArgument worden geretourneerd ([SWS_DM_00668]). Interpretatie: de specificatienotitie "rollback_semantics e.g. kPreFailed with internal debouncing" duidt er vermoedelijk op dat deze fout wordt gemeld bij ongeldige statussen tijdens interne ontdenderingen en rollbacks. Vraag Q-481ee254b8395fef (open)

Gelijktijdigheid en beperkingen

De methode is expliciet gespecificeerd als niet-thread-safe (not thread-safe) ([SWS_DM_00668]). Aanroepende componenten moeten ervoor zorgen dat gelijktijdige toegangen tot hetzelfde ara::diag::DTCInformation-object extern worden gesynchroniseerd.