clase ara::diag::DTCInformation

El método Clear de la clase ara::diag::DTCInformation ([SWS_DM_00671]) sirve para borrar un DTC individual o un grupo de DTC de la memoria de errores (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.6 «Service 0x14 – ClearDiagnosticInformation»). Como parámetro recibe a través de dtcGroup el identificador del grupo o del DTC que se va a borrar y devuelve el resultado de forma asíncrona como ara::core::Future<void> ([SWS_DM_00671]). La autorización para borrar DTC individuales o grupos está sujeta a parámetros de configuración como clearDtcLimitation ([SWS_DM_00160]).

Tratamiento de errores y semántica

La función está declarada como noexcept y notifica los errores de forma asíncrona a través del Future con semántica de reversión ([SWS_DM_00671]). Los posibles códigos de error de DiagErrc son:

• DiagErrc::kBusy: La interfaz ya está ocupada con un procesamiento.
• DiagErrc::kFailed: Durante la ejecución se ha producido un error general de procesamiento.
• DiagErrc::kMemoryError: Durante el procesamiento se produjo un error de memoria.
• DiagErrc::kWrongDtc: Se ha pasado un número de DTC no válido.
• DiagErrc::kServiceNotAvailable: Las funciones esenciales del Diagnostic Manager no están disponibles actualmente.

Concurrencia y delimitación

El método es seguro frente a excepciones (exception safe), pero está clasificado expresamente como not thread-safe ([SWS_DM_00671]). Por lo tanto, el llamador debe sincronizar las llamadas paralelas en la misma instancia; de lo contrario, existe el riesgo de DiagErrc::kBusy. Interpretación: Es probable que el ara::core::Future devuelto solo se complete una vez que la memoria física de errores se haya limpiado por completo, de forma análoga a la confirmación del servicio UDS 0x14 ([SWS_DM_00162]). Pregunta Q-b97545b6864b24aa (abierta)

Desde el punto de vista funcional, la operación debe distinguirse de los métodos SOVD homónimos: mientras que ara::diag::DiagnosticSovdContentElementDataView::Clear ([SWS_DM_02233]) vacía contenedores de datos de forma síncrona y con seguridad frente a subprocesos, este método controla flujos de diagnóstico en el Diagnostic Management.

usar

El método ara::diag::DTCInformation::EnableControlDtc ([SWS_DM_00674]) sirve para que una aplicación de monitorización vuelva a habilitar el registro y almacenamiento de códigos de error de diagnóstico (DTC) en el Diagnostic Server. La llamada se realiza sin parámetros y de forma síncrona a través de una instancia de la clase ara::diag::DTCInformation del encabezado ara/diag/dtc_information.h. Como valor de retorno, la función devuelve ara::core::Result<void>.

Interacción y semántica

Si el DTC-Setting se desactivó previamente ([SWS_DM_00910]), por ejemplo mediante el servicio UDS ControlDTCSetting (0x85) con la subfunción 0x02 (OFF), la llamada a EnableControlDtc hace que el Diagnostic Server realice los siguientes pasos según [SWS_DM_00811]:

• nueva habilitación de la actualización del byte de estado del UDS-DTC,
• habilitación del almacenamiento de errores tanto en la memoria de eventos primaria como en las memorias de eventos específicas del usuario afectadas,
• actualización de ara::diag::ControlDtcStatusType a kDTCSettingOn.

Interpretación: el establecimiento del estado como activado podría tener lugar solo tras el retorno de la llamada al método (AP SWS Diagnostics §8.48.2.2.3.2 «EnableControlDtc»), por lo que los emisores de llamadas no deben asumir un cambio de estado obligatoriamente inmediato durante la ejecución. Pregunta Q-8bfa0436f6ab98b9 (abierta)

Tratamiento de errores y concurrencia

La interfaz está declarada como noexcept, se considera segura frente a excepciones (exception safe) y no define códigos de error estandarizados específicos ([SWS_DM_00674]). En cuanto a la concurrencia, la función está especificada como no segura para subprocesos (not thread-safe). Por tanto, los accesos paralelos a la misma instancia deben ser sincronizados por la aplicación emisora de la llamada.

Uso y contexto de llamada

El método SetControlDtcStatusNotifier pertenece a la clase ara::diag::DTCInformation y se incluye a través de la cabecera ara/diag/dtc_information.h [SWS_DM_00673]. Sirve para registrar una función de retrollamada del lado de la aplicación del tipo ControlDtcStatusTypeNotifier [SWS_DM_00673]. Se llama a este notificador cuando cambia el ControlDTCStatus para la instancia de memoria de diagnóstico correspondiente, el cual está relacionado con el servicio UDS 0x85 (ControlDTCSetting) [SWS_DM_00673]. Una llamada repetida al método hace que se sobrescriba un notificador registrado previamente [SWS_DM_00673].

Tratamiento de errores y valores de retorno

Como tipo de retorno se utiliza ara::core::Result<void> [SWS_DM_00673]. En caso de éxito, la función no devuelve ningún valor, mientras que en caso de error se proporciona un código de error [SWS_DM_00673]. Como posible error está especificado el código DiagErrc::kInvalidArgument [SWS_DM_00673]. La función está declarada como noexcept y clasificada como exception safe, por lo que los llamadores no necesitan tratar excepciones de C++ [SWS_DM_00673].

Concurrencia y estado de la especificación

La interfaz está designada explícitamente como not thread-safe [SWS_DM_00673]. Por tanto, el llamador debe sincronizar los accesos paralelos a la misma instancia de ara::diag::DTCInformation. Según la documentación SWS Diagnostics §8.48.2.2.3.7 «SetControlDtcStatusNotifier», la definición de la API en el release R25-11 posee además el estado DRAFT.

Mediante la función ara::diag::DTCInformation::SetDTCStatusChangedNotifier, una Adaptive Application (AA) registra una función de devolución de llamada (callback) a la que se invoca ante cada cambio del estado de DTC de UDS ([SWS_DM_00667]). Tan pronto como cambia el estado de un DTC asignado a la memoria de averías correspondiente, Diagnostic Management (DM) activa este notificador para el DTC afectado ([SWS_DM_01031], SWS Diagnostics §7.3.4.4.2.2 «UDS DTC Status change notifications»).

La interfaz posee las siguientes propiedades y parámetros (SWS Diagnostics §8.48.2.2.3.8 «SetDTCStatusChangedNotifier»):

• Parámetro: notifier acepta el objeto de función que se invocará, de tipo DtcStatusChangedNotifier ([SWS_DM_00667]).
• Valor de retorno: La función devuelve ara::core::Result<void> y está declarada como noexcept ([SWS_DM_00667]).
• Tratamiento de errores: No hay códigos de error estandarizados definidos; la función está especificada como segura frente a excepciones (exception safe) ([SWS_DM_00667]).
• Concurrencia: El método no es seguro para subprocesos (not thread-safe) ([SWS_DM_00667]). Las llamadas paralelas sobre la misma instancia deben sincronizarse en el lado del llamador.

Si se invoca SetDTCStatusChangedNotifier repetidamente en la misma instancia de ara::diag::DTCInformation, el DM sobrescribe por completo el notificador registrado previamente ([SWS_DM_01350]). En el sistema global, el notificador complementa la consulta síncrona de estado mediante GetCurrentStatus con una notificación basada en eventos sobre transiciones de estado en la memoria de averías (SWS Diagnostics §7.3.4.4.2.2 «UDS DTC Status change notifications»).

La función SetEventMemoryOverflowNotifier de la clase ara::diag::DTCInformation (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.9 «SetEventMemoryOverflowNotifier») sirve para registrar una función de retrollamada (notifier) a la que se llama cuando se produce un cambio en el estado de desbordamiento de la memoria de eventos asignada [SWS_DM_00918].

Uso y semántica: La llamada se efectúa a través de una instancia de ara::diag::DTCInformation incluyendo el archivo de cabecera ara/diag/dtc_information.h. El parámetro notifier recibe un objeto de función del tipo EventMemory OverflowSetNotifier. En caso de registro correcto, el método devuelve un ara::core::Result<void> vacío [SWS_DM_00918].

Interacción y activación: Se produce un desbordamiento cuando en una memoria de eventos ya está almacenada la cantidad máxima configurada de entradas (DiagnosticMemoryDestination.maxNumberOfEventEntries) y se debe guardar otra entrada (AUTOSAR_AP_SWS_Diagnostics §7.3.4.4.9 «Event memory overflow», [SWS_DM_00923]). Si se ha registrado un desbordamiento, el módulo Diagnostic Management llama al notificador con el valor de parámetro false tras la siguiente ejecución del proceso de borrado de todos los DTC (clear all DTCs) para la memoria de eventos respectiva [SWS_DM_00926].

Concurrencia y restricciones: La función está declarada como noexcept y se considera segura frente a excepciones (exception safe), pero no es segura frente a hilos (not thread-safe) [SWS_DM_00918]. Por lo tanto, las llamadas paralelas en la misma instancia deben sincronizarse externamente. Si se llama a SetEventMemoryOverflowNotifier varias veces, la nueva llamada sobrescribe completamente el notificador registrado previamente [SWS_DM_01354].

Tratamiento de errores: Si la operación falla, se devuelve el código de error DiagErrc::kInvalidArgument en ara::core::Result [SWS_DM_00918].

El método SetNumberOfStoredEntriesNotifier de la clase ara::diag::DTCInformation (declarado en ara/diag/dtc_information.h) sirve para registrar una función de retrollamada del tipo NumberOfStoredEntriesNotifier ([SWS_DM_00670]). Esta función recibe una notificación tan pronto como cambia el número de entradas guardadas en la memoria de fallos de la instancia de memoria de eventos correspondiente (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.10 «SetNumberOfStoredEntriesNotifier»).

Para el uso y el comportamiento en tiempo de ejecución se aplican las siguientes especificaciones:

• Registro con sobrescritura: Por cada instancia solo puede estar activa una función de retrollamada a la vez. Una nueva llamada al método sobrescribe por completo el notificador registrado previamente ([SWS_DM_00670]).
• Concurrencia y seguridad: El método está provisto de noexcept y especificado como seguro frente a excepciones (exception safe) ([SWS_DM_00670]). Sin embargo, dado que está clasificado como no seguro para hilos (not thread-safe), los accesos paralelos a la misma instancia deben sincronizarse en el lado de la aplicación.
• Tratamiento de errores: La función devuelve un ara::core::Result<void> ([SWS_DM_00670]). Si el registro falla, se devuelve el código de error DiagErrc::kInvalidArgument ([SWS_DM_00670]); es probable que este sea el caso, en particular, si se pasa un notificador no válido. Pregunta Q-27e5e89452a7dfbb (abierta)

Uso y secuencia

El método ara::diag::DTCInformation::SetSnapshotRecordUpdatedNotifier sirve para registrar una función de retrollamada del tipo SnapshotRecordUpdatedTypeNotifier, a la que se llama tan pronto como cambia un snapshot record ([SWS_DM_00668], AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.11 «SetSnapshotRecordUpdatedNotifier»). Las llamadas posteriores a este método están permitidas y sobrescriben por completo un notificador registrado previamente ([SWS_DM_00668]).

Tratamiento de errores y firma

La función está declarada como noexcept y garantiza seguridad frente a excepciones (exception safe) ([SWS_DM_00668]). Como tipo de retorno se utiliza ara::core::Result<void>, a través del cual los errores se devuelven de forma síncrona. En caso de error, se puede devolver el código de error DiagErrc::kInvalidArgument ([SWS_DM_00668]). Interpretación: La nota de la especificación «rollback_semantics e.g. kPreFailed with internal debouncing» probablemente apunta a que este error se notifica en caso de estados no válidos durante los antirrebotes internos y los rollbacks. Pregunta Q-481ee254b8395fef (abierta)

Concurrencia y restricciones

El método está especificado explícitamente como no seguro para hilos (not thread-safe) ([SWS_DM_00668]). Los componentes llamadores deben asegurarse de que los accesos concurrentes al mismo objeto ara::diag::DTCInformation se sincronicen externamente.