classe ara::diag::DTCInformation

O método Clear da classe ara::diag::DTCInformation ([SWS_DM_00671]) destina-se à exclusão de um DTC individual ou de um grupo de DTCs na memória de falhas (AUTOSAR_AP_SWS_Diagnostics §7.3.2.8.6 «Service 0x14 – ClearDiagnosticInformation»). Como parâmetro, ele recebe através de dtcGroup a identificação do grupo ou do DTC a ser excluído e retorna o resultado de forma assíncrona como ara::core::Future<void> ([SWS_DM_00671]). A permissão para excluir DTCs individuais ou grupos está sujeita a parâmetros de configuração como clearDtcLimitation ([SWS_DM_00160]).

Tratamento de erros e semântica

A função é declarada como noexcept e reporta erros de forma assíncrona através do Future com semântica de reversão ([SWS_DM_00671]). Possíveis códigos de erro de DiagErrc são:

• DiagErrc::kBusy: A interface já está ocupada com um processamento.
• DiagErrc::kFailed: Ocorreu um erro geral de processamento durante a execução.
• DiagErrc::kMemoryError: Ocorreu um erro de memória durante o processamento.
• DiagErrc::kWrongDtc: Foi passado um número de DTC inválido.
• DiagErrc::kServiceNotAvailable: Funções essenciais do Diagnostic Manager não estão disponíveis no momento.

Concorrência e delimitação

O método é seguro contra exceções (exception safe), mas expressamente classificado como not thread-safe ([SWS_DM_00671]). Chamadas paralelas na mesma instância devem, portanto, ser sincronizadas pelo chamador; caso contrário, há o risco de DiagErrc::kBusy. Interpretação: o ara::core::Future retornado provavelmente só será cumprido quando a memória física de falhas tiver sido completamente limpa, de forma análoga à confirmação do serviço UDS 0x14 ([SWS_DM_00162]). Pergunta Q-b97545b6864b24aa (aberta)

Funcionalmente, a operação deve ser distinguida de métodos SOVD homônimos: enquanto ara::diag::DiagnosticSovdContentElementDataView::Clear ([SWS_DM_02233]) esvazia contêineres de dados de forma síncrona e thread-safe, este método controla fluxos de diagnóstico no Diagnostic Management.

usar

O método ara::diag::DTCInformation::EnableControlDtc ([SWS_DM_00674]) serve para que uma aplicação de monitoramento volte a liberar o registo e armazenamento de códigos de falha de diagnóstico (DTCs) no Diagnostic Server. A chamada ocorre sem parâmetros e de forma síncrona através de uma instância da classe ara::diag::DTCInformation do cabeçalho ara/diag/dtc_information.h. Como valor de retorno, a função retorna ara::core::Result<void>.

Interação e semântica

Se a configuração de DTC tiver sido desativada anteriormente, por exemplo através do serviço UDS ControlDTCSetting (0x85) com a subfunção 0x02 (OFF) ([SWS_DM_00910]), a chamada de EnableControlDtc instrui o Diagnostic Server, em conformidade com [SWS_DM_00811], a executar os seguintes passos:

• Reliberação da atualização do byte de status do DTC UDS,
• Liberação do armazenamento de erros na memória de eventos primária, bem como nas memórias de eventos afetadas específicas do utilizador,
• Atualização de ara::diag::ControlDtcStatusType para kDTCSettingOn.

Interpretação: A definição do status como ativado poderá ocorrer apenas após o retorno da chamada do método (AP SWS Diagnostics §8.48.2.2.3.2 «EnableControlDtc»), razão pela qual os chamadores não devem assumir uma alteração de status obrigatoriamente imediata durante a execução. Pergunta Q-8bfa0436f6ab98b9 (aberta)

Tratamento de erros e simultaneidade

A interface é declarada como noexcept, considerada segura contra exceções (exception safe) e não define códigos de erro padronizados específicos ([SWS_DM_00674]). Em relação à concorrência, a função é especificada como não segura para threads (not thread-safe). Os acessos paralelos à mesma instância devem, portanto, ser sincronizados pela aplicação chamadora.

Utilização e contexto de chamada

O método SetControlDtcStatusNotifier pertence à classe ara::diag::DTCInformation e é incluído por meio do cabeçalho ara/diag/dtc_information.h [SWS_DM_00673]. Ele serve para registrar uma função de callback do lado da aplicação do tipo ControlDtcStatusTypeNotifier [SWS_DM_00673]. Esse notificador é chamado quando o ControlDTCStatus for alterado para a respectiva instância de memória de diagnóstico, o qual está relacionado ao serviço UDS 0x85 (ControlDTCSetting) [SWS_DM_00673]. Uma chamada repetida do método faz com que um notificador registrado anteriormente seja sobrescrito [SWS_DM_00673].

Tratamento de erros e valores de retorno

Como tipo de retorno serve ara::core::Result<void> [SWS_DM_00673]. Em caso de sucesso, a função não retorna nenhum valor, enquanto em caso de erro é fornecido um código de erro [SWS_DM_00673]. Como erro possível, está especificado o código DiagErrc::kInvalidArgument [SWS_DM_00673]. A função é declarada como noexcept e classificada como exception safe, razão pela qual os chamadores não precisam tratar exceções C++ [SWS_DM_00673].

Concorrência e status da especificação

A interface é indicada explicitamente como not thread-safe [SWS_DM_00673]. Portanto, acessos paralelos à mesma instância de ara::diag::DTCInformation devem ser sincronizados pelo chamador. De acordo com a documentação SWS Diagnostics §8.48.2.2.3.7 «SetControlDtcStatusNotifier», a definição da API no release R25-11 possui também o status DRAFT.

Com a função ara::diag::DTCInformation::SetDTCStatusChangedNotifier, uma Adaptive Application (AA) registra uma função de callback que é chamada a cada alteração do status do DTC do UDS ([SWS_DM_00667]). Assim que o status de um DTC atribuído à respectiva memória de falhas for alterado, o Diagnostic Management (DM) dispara esse notificador para o DTC afetado ([SWS_DM_01031], SWS Diagnostics §7.3.4.4.2.2 «UDS DTC Status change notifications»).

A interface possui as seguintes propriedades e parâmetros (SWS Diagnostics §8.48.2.2.3.8 «SetDTCStatusChangedNotifier»):

• Parâmetro: notifier recebe o objeto de função a ser chamado do tipo DtcStatusChangedNotifier ([SWS_DM_00667]).
• Valor de retorno: A função retorna ara::core::Result<void> e é declarada como noexcept ([SWS_DM_00667]).
• Tratamento de erros: Não estão definidos códigos de erro padronizados; a função é especificada como segura contra exceções (exception safe) ([SWS_DM_00667]).
• Concorrência: O método não é seguro para threads (not thread-safe) ([SWS_DM_00667]). Chamadas paralelas na mesma instância devem ser sincronizadas pelo lado chamador.

Se SetDTCStatusChangedNotifier for chamado repetidamente na mesma instância de ara::diag::DTCInformation, o DM sobrescreve totalmente o notificador registrado anteriormente ([SWS_DM_01350]). No sistema global, o notificador complementa a consulta de status síncrona por meio de GetCurrentStatus com uma notificação baseada em eventos sobre mudanças de status na memória de falhas (SWS Diagnostics §7.3.4.4.2.2 «UDS DTC Status change notifications»).

A função SetEventMemoryOverflowNotifier da classe ara::diag::DTCInformation (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.9 «SetEventMemoryOverflowNotifier») serve para registrar uma função de callback (notifier) que é chamada mediante uma alteração do estado de estouro da memória de eventos atribuída [SWS_DM_00918].

Uso e semântica: A chamada ocorre através de uma instância de ara::diag::DTCInformation com inclusão do arquivo de cabeçalho ara/diag/dtc_information.h. O parâmetro notifier recebe um objeto de função do tipo EventMemory OverflowSetNotifier. Em caso de registro bem-sucedido, o método retorna um ara::core::Result<void> vazio [SWS_DM_00918].

Interação e acionamento: Um estouro ocorre quando o número máximo configurado de entradas (DiagnosticMemoryDestination.maxNumberOfEventEntries) já está armazenado em uma memória de eventos e uma entrada adicional deve ser salva (AUTOSAR_AP_SWS_Diagnostics §7.3.4.4.9 «Event memory overflow», [SWS_DM_00923]). Se um estouro tiver sido registrado, o módulo Diagnostic Management chama o notificador após a próxima execução do procedimento de limpeza de todos os DTCs (clear all DTCs) para a respectiva memória de eventos com o valor de parâmetro false [SWS_DM_00926].

Simultaneidade e restrições: A função é declarada como noexcept e considerada segura para exceções (exception safe), mas não é segura para threads (not thread-safe) [SWS_DM_00918]. Chamadas paralelas na mesma instância devem, portanto, ser sincronizadas externamente. Se SetEventMemoryOverflowNotifier for chamado várias vezes, a nova chamada sobrescreve completamente o notificador registrado anteriormente [SWS_DM_01354].

Tratamento de erros: Se a operação falhar, o código de erro DiagErrc::kInvalidArgument é retornado no ara::core::Result [SWS_DM_00918].

O método SetNumberOfStoredEntriesNotifier da classe ara::diag::DTCInformation (declarado em ara/diag/dtc_information.h) serve para registrar uma função de callback do tipo NumberOfStoredEntriesNotifier ([SWS_DM_00670]). Essa função é notificada assim que a quantidade de entradas armazenadas na memória de falhas da respectiva instância de memória de eventos for alterada (AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.10 «SetNumberOfStoredEntriesNotifier»).

Para o uso e o comportamento em tempo de execução, aplicam-se as seguintes especificações:

• Registro com sobrescrita: Apenas uma função de callback pode estar ativa por instância por vez. Uma nova chamada do método sobrescreve totalmente o notificador registrado anteriormente ([SWS_DM_00670]).
• Concorrência e segurança: O método é provido de noexcept e especificado como seguro contra exceções (exception safe) ([SWS_DM_00670]). No entanto, como é classificado como não seguro para threads (not thread-safe), acessos paralelos à mesma instância devem ser sincronizados pelo lado da aplicação.
• Tratamento de erros: A função retorna um ara::core::Result<void> ([SWS_DM_00670]). Se o registro falhar, o código de erro DiagErrc::kInvalidArgument é retornado ([SWS_DM_00670]); este deve ser o caso especialmente se um notificador inválido for passado. Pergunta Q-27e5e89452a7dfbb (aberta)

Uso e fluxo

O método ara::diag::DTCInformation::SetSnapshotRecordUpdatedNotifier serve para registrar uma função de callback do tipo SnapshotRecordUpdatedTypeNotifier, que é chamada assim que um Snapshot-Record for alterado ([SWS_DM_00668], AUTOSAR_AP_SWS_Diagnostics §8.48.2.2.3.11 «SetSnapshotRecordUpdatedNotifier»). Chamadas subsequentes deste método são permitidas e sobrescrevem totalmente um notificador registrado anteriormente ([SWS_DM_00668]).

Tratamento de erros e assinatura

A função é declarada como noexcept e garante segurança contra exceções (exception safe) ([SWS_DM_00668]). Como tipo de retorno serve ara::core::Result<void>, através do qual os erros são retornados de forma síncrona. Em caso de falha, o código de erro DiagErrc::kInvalidArgument pode ser retornado ([SWS_DM_00668]). Interpretação: A nota de especificação “rollback_semantics e.g. kPreFailed with internal debouncing” deve indicar que esse erro é reportado em caso de estados inválidos durante debouncings internos e rollbacks. Pergunta Q-481ee254b8395fef (aberta)

Simultaneidade e restrições

O método é especificado explicitamente como não seguro para threads (not thread-safe) ([SWS_DM_00668]). Componentes chamadores devem garantir que acessos concorrentes ao mesmo objeto ara::diag::DTCInformation sejam sincronizados externamente.