classe ara::diag::DTCInformation

La méthode Clear de la classe ara::diag::DTCInformation ([SWS_DM_00671]) sert à effacer un DTC individuel ou un groupe de DTC dans la mémoire des défauts (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.6 « Service 0x14 – ClearDiagnosticInformation »). En tant que paramètre, elle reçoit via dtcGroup l'identifiant du groupe ou du DTC à effacer et renvoie le résultat de manière asynchrone sous la forme d'un ara::core::Future<void> ([SWS_DM_00671]). L'autorisation d'effacer des DTC individuels ou des groupes est ici soumise à des paramètres de configuration tels que clearDtcLimitation ([SWS_DM_00160]).

Traitement des erreurs et sémantique

La fonction est déclarée comme noexcept et signale les erreurs de manière asynchrone via le Future avec une sémantique de retour arrière ([SWS_DM_00671]). Les codes d'erreur possibles issus de DiagErrc sont :

• DiagErrc::kBusy : l'interface est déjà occupée par un traitement.
• DiagErrc::kFailed : une erreur générale de traitement est survenue lors de l'exécution.
• DiagErrc::kMemoryError : une erreur de mémoire est survenue pendant le traitement.
• DiagErrc::kWrongDtc : un numéro de DTC non valide a été transmis.
• DiagErrc::kServiceNotAvailable : des fonctions essentielles du Diagnostic Manager ne sont actuellement pas disponibles.

Concurrence et délimitation

La méthode est sûre vis-à-vis des exceptions (exception safe), mais expressément classifiée comme not thread-safe ([SWS_DM_00671]). Les appels parallèles sur la même instance doivent donc être synchronisés par l'appelant, faute de quoi DiagErrc::kBusy menace. Interprétation : le ara::core::Future renvoyé ne devrait être tenu que lorsque la mémoire physique des défauts aura été entièrement purgée, de manière analogue à l'acquittement du service UDS 0x14 ([SWS_DM_00162]). Question Q-b97545b6864b24aa (ouverte)

Sur le plan fonctionnel, l'opération doit être distinguée de méthodes SOVD homonymes : tandis que ara::diag::DiagnosticSovdContentElementDataView::Clear ([SWS_DM_02233]) vide des conteneurs de données de manière synchrone et thread-safe, cette méthode contrôle des séquences de diagnostic dans le Diagnostic Management.

Utilisation

La méthode ara::diag::DTCInformation::EnableControlDtc ([SWS_DM_00674]) sert à une application de surveillance à réactiver l'acquisition et l'enregistrement des codes de défaut de diagnostic (DTC) dans le serveur de diagnostic. L'appel s'effectue sans paramètre et de manière synchrone via une instance de la classe ara::diag::DTCInformation issue de l'en-tête ara/diag/dtc_information.h. Comme valeur de retour, la fonction renvoie ara::core::Result<void>.

Interaction et sémantique

Si le réglage DTC a été préalablement désactivé ([SWS_DM_00910]), par exemple via le service UDS ControlDTCSetting (0x85) avec la sous-fonction 0x02 (OFF), l'appel de EnableControlDtc amène le serveur de diagnostic à effectuer les étapes suivantes conformément à [SWS_DM_00811] :

• réactivation de la mise à jour de l'octet d'état du DTC UDS,
• autorisation de l'enregistrement des défauts dans la mémoire d'événements primaire ainsi que dans les mémoires d'événements spécifiques à l'utilisateur concernées,
• mise à jour de ara::diag::ControlDtcStatusType vers kDTCSettingOn.

Interprétation : le passage de l'état à activé n'intervient le cas échéant qu'après le retour de l'appel de méthode (AP SWS Diagnostics §8.48.2.2.3.2 « EnableControlDtc »), raison pour laquelle les appelants ne doivent pas présumer d'un changement d'état obligatoirement immédiat pendant l'exécution. Question Q-8bfa0436f6ab98b9 (ouverte)

Gestion des erreurs et concurrence

L'interface est déclarée comme noexcept, est considérée comme sûre du point de vue des exceptions (exception safe) et ne définit pas de codes d'erreur standardisés spécifiques ([SWS_DM_00674]). En ce qui concerne la concurrence, la fonction est spécifiée comme non sûre pour les threads (not thread-safe). Les accès parallèles à la même instance doivent donc être synchronisés par l'application appelante.

Utilisation et contexte d'appel

La méthode SetControlDtcStatusNotifier appartient à la classe ara::diag::DTCInformation et est incluse via l'en-tête ara/diag/dtc_information.h [SWS_DM_00673]. Elle sert à enregistrer une fonction de rappel côté application de type ControlDtcStatusTypeNotifier [SWS_DM_00673]. Ce notificateur est appelé lorsque le ControlDTCStatus change pour l'instance de mémoire de diagnostic concernée, lequel est associé au service UDS 0x85 (ControlDTCSetting) [SWS_DM_00673]. Un appel répété de la méthode a pour effet d'écraser un notificateur précédemment enregistré [SWS_DM_00673].

Gestion des erreurs et valeurs de retour

Le type de retour utilisé est ara::core::Result<void> [SWS_DM_00673]. En cas de succès, la fonction ne renvoie aucune valeur, tandis qu'en cas d'erreur, un code d'erreur est fourni [SWS_DM_00673]. Le code DiagErrc::kInvalidArgument est spécifié comme erreur possible [SWS_DM_00673]. La fonction est déclarée comme noexcept et classée comme exception safe, c'est pourquoi les appelants n'ont pas à gérer d'exceptions C++ [SWS_DM_00673].

Concurrence et statut de la spécification

L'interface est explicitement désignée comme not thread-safe [SWS_DM_00673]. Par conséquent, les accès concurrents à la même instance de ara::diag::DTCInformation doivent être synchronisés par l'appelant. Selon la documentation SWS Diagnostics §8.48.2.2.3.7 « SetControlDtcStatusNotifier », la définition de l'API possède en outre le statut DRAFT dans la version R25-11.

Avec la fonction ara::diag::DTCInformation::SetDTCStatusChangedNotifier, une Adaptive Application (AA) enregistre une fonction de rappel appelée à chaque changement d'état du DTC UDS ([SWS_DM_00667]). Dès que l'état d'un DTC associé à la mémoire de défauts respective change, le Diagnostic Management (DM) déclenche ce notificateur pour le DTC concerné ([SWS_DM_01031], SWS Diagnostics §7.3.4.4.2.2 « UDS DTC Status change notifications »).

L'interface possède les propriétés et paramètres suivants (SWS Diagnostics §8.48.2.2.3.8 « SetDTCStatusChangedNotifier ») :

• Paramètres : notifier reçoit l'objet fonctionnel à appeler de type DtcStatusChangedNotifier ([SWS_DM_00667]).
• Valeur de retour : la fonction renvoie ara::core::Result<void> et est déclarée comme noexcept ([SWS_DM_00667]).
• Gestion des erreurs : aucun code d'erreur standardisé n'est défini ; la fonction est spécifiée comme sûre face aux exceptions (exception safe) ([SWS_DM_00667]).
• Concurrence : la méthode n'est pas sûre du point de vue des threads (not thread-safe) ([SWS_DM_00667]). Les appels parallèles sur la même instance doivent être synchronisés côté appelant.

Si SetDTCStatusChangedNotifier est appelée à plusieurs reprises sur la même instance de ara::diag::DTCInformation, le DM écrase entièrement le notificateur précédemment enregistré ([SWS_DM_01350]). Dans le système global, le notificateur complète l'interrogation synchrone de l'état au moyen de GetCurrentStatus par une notification basée sur les événements concernant les changements d'état dans la mémoire de défauts (SWS Diagnostics §7.3.4.4.2.2 « UDS DTC Status change notifications »).

La fonction SetEventMemoryOverflowNotifier de la classe ara::diag::DTCInformation (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.9 « SetEventMemoryOverflowNotifier ») sert à enregistrer une fonction de rappel (notifier) appelée lors d'un changement de l'état de dépassement de capacité de la mémoire d'événements associée [SWS_DM_00918].

Utilisation et sémantique : l'appel s'effectue via une instance de ara::diag::DTCInformation en incluant le fichier d'en-tête ara/diag/dtc_information.h. Le paramètre notifier prend un objet fonction de type EventMemory OverflowSetNotifier. En cas d'enregistrement réussi, la méthode renvoie un ara::core::Result<void> vide [SWS_DM_00918].

Interaction et déclenchement : un dépassement de capacité se produit lorsque le nombre maximal d'entrées configuré (DiagnosticMemoryDestination.maxNumberOfEventEntries) est déjà stocké dans une mémoire d'événements et qu'une entrée supplémentaire doit être enregistrée (AUTOSAR_AP_SWS_Diagnostics §7.3.4.4.9 « Event memory overflow », [SWS_DM_00923]). Si un dépassement de capacité a été enregistré, le module Diagnostic Management appelle le notificateur avec la valeur de paramètre false après la prochaine exécution de l'opération d'effacement de tous les DTC (clear all DTCs) pour la mémoire d'événements concernée [SWS_DM_00926].

Concurrence et restrictions : la fonction est déclarée comme noexcept et est considérée comme sûre face aux exceptions (exception safe), mais n'est pas sûre vis-à-vis des threads (not thread-safe) [SWS_DM_00918]. Les appels parallèles sur la même instance doivent donc être synchronisés de manière externe. Si SetEventMemoryOverflowNotifier est appelée plusieurs fois, le nouvel appel écrase complètement le notificateur précédemment enregistré [SWS_DM_01354].

Gestion des erreurs : si l'opération échoue, le code d'erreur DiagErrc::kInvalidArgument est renvoyé dans le ara::core::Result [SWS_DM_00918].

La méthode SetNumberOfStoredEntriesNotifier de la classe ara::diag::DTCInformation (déclarée dans ara/diag/dtc_information.h) sert à enregistrer une fonction de rappel de type NumberOfStoredEntriesNotifier ([SWS_DM_00670]). Cette fonction est notifiée dès que le nombre d'entrées consignées dans la mémoire de défauts de l'instance de mémoire d'événements concernée change (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.10 « SetNumberOfStoredEntriesNotifier »).

Les spécifications suivantes s'appliquent à l'utilisation et au comportement à l'exécution :

• Enregistrement par écrasement : une seule fonction de rappel peut être active à la fois par instance. Un nouvel appel de la méthode écrase entièrement le notificateur précédemment enregistré ([SWS_DM_00670]).
• Concurrence et sécurité : la méthode est dotée de noexcept et spécifiée comme sûre face aux exceptions (exception safe) ([SWS_DM_00670]). Cependant, étant classée comme non sûre du point de vue des threads (not thread-safe), les accès parallèles à la même instance doivent être synchronisés côté application.
• Gestion des erreurs : La fonction renvoie un ara::core::Result<void> ([SWS_DM_00670]). Si l'enregistrement échoue, le code d'erreur DiagErrc::kInvalidArgument est renvoyé ([SWS_DM_00670]) ; cela devrait notamment être le cas lorsqu'un notificateur non valide est transmis. Question Q-27e5e89452a7dfbb (ouverte)

Utilisation et déroulement

La méthode ara::diag::DTCInformation::SetSnapshotRecordUpdatedNotifier sert à enregistrer une fonction de rappel de type SnapshotRecordUpdatedTypeNotifier qui est appelée dès qu'un enregistrement snapshot est modifié ([SWS_DM_00668], AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.11 « SetSnapshotRecordUpdatedNotifier »). Des appels ultérieurs de cette méthode sont autorisés et écrasent entièrement un notificateur précédemment enregistré ([SWS_DM_00668]).

Gestion des erreurs et signature

La fonction est déclarée comme noexcept et garantit la sécurité face aux exceptions (exception safe) ([SWS_DM_00668]). Le type de retour utilisé est ara::core::Result<void>, par l'intermédiaire duquel les erreurs sont renvoyées de manière synchrone. En cas d'erreur, le code d'erreur DiagErrc::kInvalidArgument peut être renvoyé ([SWS_DM_00668]). Interprétation : la note de spécification « rollback_semantics e.g. kPreFailed with internal debouncing » devrait indiquer que cette erreur est signalée lors d'états non valides pendant les filtrages antirebond internes et les rollbacks. Question Q-481ee254b8395fef (ouverte)

Concurrence et restrictions

La méthode est explicitement spécifiée comme non sûre du point de vue des threads (not thread-safe) ([SWS_DM_00668]). Les composants appelants doivent s'assurer que les accès concurrents au même objet ara::diag::DTCInformation sont synchronisés de manière externe.