class ara::diag::DTCInformation

The method Clear of class ara::diag::DTCInformation ([SWS_DM_00671]) serves to clear an individual DTC or a DTC group in the fault memory (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.6 “Service 0x14 – ClearDiagnosticInformation”). As a parameter, it accepts the identifier of the group or DTC to be cleared via dtcGroup and returns the result asynchronously as ara::core::Future<void> ([SWS_DM_00671]). The permission to clear individual DTCs or groups is subject to configuration parameters such as clearDtcLimitation ([SWS_DM_00160]).

Error Handling and Semantics

The function is declared as noexcept and reports errors asynchronously via the Future with rollback semantics ([SWS_DM_00671]). Possible error codes from DiagErrc are:

• DiagErrc::kBusy: The interface is already busy with processing.
• DiagErrc::kFailed: A general processing error occurred during execution.
• DiagErrc::kMemoryError: A memory error occurred during processing.
• DiagErrc::kWrongDtc: An invalid DTC number was passed.
• DiagErrc::kServiceNotAvailable: Essential functions of the Diagnostic Manager are currently not available.

Concurrency and Distinction

The method is exception safe (exception safe), but explicitly classified as not thread-safe ([SWS_DM_00671]). Parallel calls on the same instance must therefore be synchronized by the caller; otherwise, DiagErrc::kBusy threatens. Interpretation: The returned ara::core::Future is likely to be fulfilled only when the physical fault memory has been completely cleared, analogously to the acknowledgment of UDS service 0x14 ([SWS_DM_00162]). Question Q-b97545b6864b24aa (open)

Functionally, the operation is to be distinguished from SOVD methods of the same name: While ara::diag::DiagnosticSovdContentElementDataView::Clear ([SWS_DM_02233]) clears data containers synchronously and thread-safe, this method controls diagnostic sequences in Diagnostic Management.

use

Method ara::diag::DTCInformation::EnableControlDtc ([SWS_DM_00674]) serves a monitoring application to re-enable the recording and storage of diagnostic trouble codes (DTCs) in the Diagnostic Server. The call is parameterless and synchronous via an instance of class ara::diag::DTCInformation from header ara/diag/dtc_information.h. The function returns ara::core::Result<void> as its return value.

Interaction and Semantics

If DTC setting was previously disabled ([SWS_DM_00910]), for example via the UDS service ControlDTCSetting (0x85) with subfunction 0x02 (OFF), calling EnableControlDtc causes the Diagnostic Server according to [SWS_DM_00811] to perform the following steps:

• Re-enabling updating of the UDS DTC status byte,
• Enabling error storage in the primary as well as in affected user-defined event memories,
• Updating ara::diag::ControlDtcStatusType to kDTCSettingOn.

Interpretation: Setting the status to enabled may under certain circumstances take place only after the method call has returned (AP SWS Diagnostics §8.48.2.2.3.2 “EnableControlDtc”), which is why callers must not assume a necessarily immediate status change during execution. Question Q-8bfa0436f6ab98b9 (open)

Error Handling and Concurrency

The interface is declared as noexcept, is considered exception-safe (exception safe), and defines no specific standardized error codes ([SWS_DM_00674]). Regarding concurrency, the function is specified as not thread-safe (not thread-safe). Concurrent accesses to the same instance must therefore be synchronized by the calling application.

Usage and Call Context

The method SetControlDtcStatusNotifier belongs to class ara::diag::DTCInformation and is included via header ara/diag/dtc_information.h [SWS_DM_00673]. It serves to register an application-side callback function of type ControlDtcStatusTypeNotifier [SWS_DM_00673]. This notifier is called when the ControlDTCStatus changes for the respective diagnostic memory instance, which is associated with UDS service 0x85 (ControlDTCSetting) [SWS_DM_00673]. Calling the method repeatedly results in a previously registered notifier being overwritten [SWS_DM_00673].

Error Handling and Return Values

The return type used is ara::core::Result<void> [SWS_DM_00673]. In the event of success, the function returns no value, while in the event of an error, an error code is provided [SWS_DM_00673]. Code DiagErrc::kInvalidArgument is specified as a possible error [SWS_DM_00673]. The function is declared as noexcept and classified as exception safe, which is why callers do not need to handle any C++ exceptions [SWS_DM_00673].

Concurrency and specification status

The interface is explicitly designated as not thread-safe [SWS_DM_00673]. Therefore, parallel accesses to the same instance of ara::diag::DTCInformation must be synchronized by the caller. According to the documentation SWS Diagnostics §8.48.2.2.3.7 “SetControlDtcStatusNotifier”, the API definition in release R25-11 also has the status DRAFT.

With the function ara::diag::DTCInformation::SetDTCStatusChangedNotifier, an Adaptive Application (AA) registers a callback function that is called upon every change in the UDS DTC status ([SWS_DM_00667]). As soon as the status of a DTC assigned to the respective event memory changes, Diagnostic Management (DM) triggers this notifier for the affected DTC ([SWS_DM_01031], SWS Diagnostics §7.3.4.4.2.2 “UDS DTC Status change notifications”).

The interface has the following properties and parameters (SWS Diagnostics §8.48.2.2.3.8 “SetDTCStatusChangedNotifier”):

• Parameter: notifier accepts the function object of type DtcStatusChangedNotifier to be called ([SWS_DM_00667]).
• Return value: The function returns ara::core::Result<void> and is declared as noexcept ([SWS_DM_00667]).
• Error handling: No standardized error codes are defined; the function is specified as exception-safe (exception safe) ([SWS_DM_00667]).
• Concurrency: The method is not thread-safe (not thread-safe) ([SWS_DM_00667]). Parallel calls on the same instance must be synchronized on the caller side.

If SetDTCStatusChangedNotifier is called repeatedly on the same instance of ara::diag::DTCInformation, DM completely overwrites the previously registered notifier ([SWS_DM_01350]). In the overall system, the notifier complements the synchronous status query via GetCurrentStatus with event-based notification of status changes in the event memory (SWS Diagnostics §7.3.4.4.2.2 “UDS DTC Status change notifications”).

Function SetEventMemoryOverflowNotifier of class ara::diag::DTCInformation (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.9 “SetEventMemoryOverflowNotifier”) serves to register a callback function (notifier) that is called upon a change in the overflow status of the associated event memory [SWS_DM_00918].

Usage and semantics: The call is made via an instance of ara::diag::DTCInformation including header file ara/diag/dtc_information.h. Parameter notifier accepts a function object of type EventMemory OverflowSetNotifier. Upon successful registration, the method returns an empty ara::core::Result<void> [SWS_DM_00918].

Interaction and triggering: An overflow occurs when the maximum configured number of entries (DiagnosticMemoryDestination.maxNumberOfEventEntries) is already stored in an event memory and an additional entry is to be stored (AUTOSAR_AP_SWS_Diagnostics §7.3.4.4.9 “Event memory overflow”, [SWS_DM_00923]). If an overflow was registered, the Diagnostic Management module calls the notifier after the next execution of clearing all DTCs (clear all DTCs) for the respective event memory with the parameter value false [SWS_DM_00926].

Concurrency and limitations: The function is declared as noexcept and considered exception safe (exception safe), but is not thread-safe (not thread-safe) [SWS_DM_00918]. Parallel calls on the same instance must therefore be synchronized externally. If SetEventMemoryOverflowNotifier is called multiple times, the new call completely overwrites the previously registered notifier [SWS_DM_01354].

Error handling: If the operation fails, the error code DiagErrc::kInvalidArgument is returned in ara::core::Result [SWS_DM_00918].

The method SetNumberOfStoredEntriesNotifier of class ara::diag::DTCInformation (declared in ara/diag/dtc_information.h) serves to register a callback function of type NumberOfStoredEntriesNotifier ([SWS_DM_00670]). This function is notified as soon as the number of entries stored in the event memory of the respective event memory instance changes (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.10 “SetNumberOfStoredEntriesNotifier”).

The following specifications apply to usage and runtime behavior:

• Overwriting registration: Only one callback function can be active per instance at a time. A new call to the method completely overwrites the previously registered notifier ([SWS_DM_00670]).
• Concurrency and safety: The method is provided with noexcept and specified as exception-safe (exception safe) ([SWS_DM_00670]). However, since it is classified as not thread-safe (not thread-safe), parallel accesses to the same instance must be synchronized on the application side.
• Error handling: The function returns a ara::core::Result<void> ([SWS_DM_00670]). If registration fails, error code DiagErrc::kInvalidArgument is reported back ([SWS_DM_00670]); this is likely the case in particular when an invalid notifier is passed. Question Q-27e5e89452a7dfbb (open)

Usage and Flow

The method ara::diag::DTCInformation::SetSnapshotRecordUpdatedNotifier serves to register a callback function of type SnapshotRecordUpdatedTypeNotifier, which is called as soon as a snapshot record changes ([SWS_DM_00668], AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.11 “SetSnapshotRecordUpdatedNotifier”). Subsequent calls to this method are permitted and completely overwrite a previously registered notifier ([SWS_DM_00668]).

Error handling and signature

The function is declared as noexcept and guarantees exception safety (exception safe) ([SWS_DM_00668]). The return type used is ara::core::Result<void>, via which errors are returned synchronously. In the event of an error, error code DiagErrc::kInvalidArgument can be returned ([SWS_DM_00668]). Interpretation: The specification note "rollback_semantics e.g. kPreFailed with internal debouncing" is likely to indicate that this error is reported for invalid states during internal debouncing and rollbacks. Question Q-481ee254b8395fef (open)

Concurrency and Limitations

The method is explicitly specified as not thread-safe (not thread-safe) ([SWS_DM_00668]). Calling components must ensure that concurrent accesses to the same ara::diag::DTCInformation object are externally synchronized.