Watchdog Driver (Wdg)

O driver de watchdog controla o hardware de watchdog interno ou externo a pedido do Watchdog Manager. Este define apenas uma condição de disparo temporizada por meio do Watchdog Interface. Enquanto ela for válida, o próprio driver dispara o hardware; depois disso, o watchdog expira [SWS_Wdg_00144]. Wdg_Init define o modo padrão e o timeout a partir da configuração, e Wdg_SetMode comuta entre os modos OFF, SLOW e FAST [SWS_Wdg_00160]. Um timeout de 0 aciona um reset quase imediato, e o watchdog só pode ser desativado se a configuração permitir.

mais ›

O driver de watchdog Wdg controla o hardware de watchdog por meio de quatro serviços síncronos: Wdg_Init, Wdg_SetMode, Wdg_SetTriggerCondition e Wdg_GetVersionInfo ([SWS_Wdg_00106], [SWS_Wdg_00107], [SWS_Wdg_00155], [SWS_Wdg_00109]). O EcuM chama Wdg_Init. O Watchdog Manager acessa o driver apenas por meio do Watchdog Interface, que seleciona a instância via DeviceIndex (SWS WdgIf p. 17). Instâncias internas acessam o hardware diretamente, enquanto instâncias externas o fazem via SPI ou DIO ([SWS_Wdg_00161], [SWS_Wdg_00076]). Ambas oferecem a mesma API [SWS_Wdg_00077].

Diagrama de contexto: EcuM inicializa as instâncias de Wdg, WdgM as controla via WdgIf. Instâncias externas acessam o hardware via Spi/Dio. Fontes: [SWS_Wdg_00076], [SWS_Wdg_00161], SWS WdgM p. 86

O núcleo do módulo é a condição de disparo. Ela vale como permissão para atender ao watchdog durante os próximos n milissegundos. Enquanto for válida, o próprio driver realiza o disparo; depois disso, o watchdog expira [SWS_Wdg_00144]. Wdg_SetTriggerCondition reinicia o contador e converte os milissegundos em um valor de contador dependente do modo ([SWS_Wdg_00136], [SWS_Wdg_00139]). A rotina interna de atendimento efetua o disparo e decrementa enquanto o contador for maior que zero. Ao atingir zero, ela não dispara mais ([SWS_Wdg_00134], [SWS_Wdg_00135]). Um timeout de 0 força um reset (quase) imediato, e um contador expirado não pode ser recarregado [SWS_Wdg_00140].

Diagrama de sequência: WdgM apenas recarrega o contador; o disparo é efetuado por uma interrupção de temporizador no driver. Com o contador em 0, o watchdog expira. Fontes: SWS Wdg Fig. 9.2 p. 31, [SWS_Wdg_00134], [SWS_Wdg_00135]

Wdg_Init define o modo padrão e o período de timeout a partir do conjunto de configuração Wdg_ConfigType [SWS_Wdg_00001]. Wdg_SetMode comuta entre WDGIF_OFF_MODE, WDGIF_SLOW_MODE e WDGIF_FAST_MODE e retorna E_OK somente em caso de comutação completa ([SWS_Wdg_00160], [SWS_Wdg_00103]). Não existe desinicialização. A desativação é feita por meio do modo OFF [SWS_Wdg_00031], e isso apenas se WdgDisableAllowed permitir [SWS_Wdg_00025].

Em caso de falha, o Wdg reporta os erros de desenvolvimento WDG_E_DRIVER_STATE, WDG_E_PARAM_MODE, WDG_E_PARAM_CONFIG e WDG_E_PARAM_TIMEOUT [SWS_Wdg_00010]. Somam-se a isso os erros de produção WDG_E_MODE_FAILED e WDG_E_DISABLE_REJECTED ([SWS_Wdg_00016], [SWS_Wdg_00179]). Presume-se que esses erros de produção sejam reportados via Dem_SetEventStatus [SWS_Wdg_00111]. Pergunta Q-f0ec41b842ebbdc9 (aberta)

mais ›

Papel na pilha de watchdog: o driver que assume o próprio disparo

O driver de watchdog Wdg controla o hardware de watchdog por meio de uma API pequena e síncrona com quatro serviços, todos disponíveis via Wdg.h: Wdg_Init (ID de serviço 0x00), Wdg_SetMode (0x01), Wdg_SetTriggerCondition (0x03) e Wdg_GetVersionInfo (0x04). Apenas Wdg_GetVersionInfo é reentrante ([SWS_Wdg_00106], [SWS_Wdg_00107], [SWS_Wdg_00155], [SWS_Wdg_00109]). Deliberadamente não há uma interface para desinicialização. Quando o hardware e o ambiente permitem a desativação, ela ocorre por meio de Wdg_SetMode com o modo OFF [SWS_Wdg_00031].

Os serviços são chamados pelo software básico. O ECU State Manager chama Wdg_Init (SWS EcuM p. 34). O Watchdog Manager necessita de WdgIf_SetMode e WdgIf_SetTriggerCondition (SWS WdgM p. 86). O Watchdog Interface mapeia essas chamadas para o driver e seleciona a instância por meio de um DeviceIndex de base zero do tipo uint8. Se apenas um driver estiver configurado, esse mapeamento não deve causar overhead em tempo de execução, por exemplo por meio de macros (SWS WdgIf p. 17). O disparo temporal fica inteiramente a cargo do driver. O Watchdog Manager define apenas a condição de disparo (SWS WdgM p. 56; [SWS_Wdg_00144]).

Em direção ao hardware, as instâncias diferem entre si. Uma instância para um watchdog interno acessa diretamente o hardware [SWS_Wdg_00161]. Uma instância para um watchdog externo utiliza a API de um handler ou driver, como SPI ou DIO [SWS_Wdg_00076]. Opcionalmente, o Wdg utiliza Det_ReportError para erros de desenvolvimento e Dem_SetEventStatus para status de monitoramento [SWS_Wdg_00111].

Diagrama de contexto: Wdg é inicializado pelo EcuM e controlado pelo WdgM apenas indiretamente via WdgIf. Instâncias internas acessam o hardware diretamente, externas via Spi/Dio. Fontes: [SWS_Wdg_00076], [SWS_Wdg_00161], [SWS_Wdg_00111], SWS WdgM p. 86

Da inicialização do sistema à operação monitorada

Wdg_Init recebe um ponteiro para um conjunto de configuração do tipo Wdg_ConfigType. Essa estrutura é dependente de hardware ([SWS_Wdg_00106], [SWS_Wdg_00171]). A função inicializa o driver e o hardware e define o modo padrão e o período de timeout a partir desse conjunto [SWS_Wdg_00001]. Além disso, inicializa todas as variáveis globais [SWS_Wdg_00100]. Ela escreve apenas nos registradores de controlador que não afetam outros módulos de hardware nem dependem deles. Os registradores compartilhados são inicializados por um módulo de sistema abrangente [SWS_Wdg_00101]. Com a detecção de erros de desenvolvimento ativada, o estado interno muda de WDG_UNINIT para WDG_IDLE após uma inicialização bem-sucedida [SWS_Wdg_00019].

A Figura 9.1 da especificação mostra a divisão de tarefas: o EcuM inicializa o Wdg diretamente, após o que o WdgM controla a condição de disparo e o modo via WdgIf (SWS Wdg Fig. 9.1 p. 34). Importante para os integradores: a partir de Wdg_Init, aplicam-se o modo padrão configurado e o período de timeout inicial [SWS_Wdg_00001]. Se esse modo não for OFF, a entidade de controle deve renovar a condição de disparo dentro da janela de tempo; caso contrário, o watchdog expira [SWS_Wdg_00144].

Diagrama de sequência: À inicialização pelo EcuM seguem-se a definição da condição de disparo e a alternância de modo pelo WdgM via WdgIf. Fontes: SWS Wdg Fig. 9.1 p. 34, [SWS_Wdg_00001], [SWS_Wdg_00019], [SWS_Wdg_00139], SWS WdgIf p. 18

Condição de disparo: permissão temporária para atendimento

O hardware não é atendido por chamadas de disparo individuais a partir do exterior. Em vez disso, aplica-se uma condição de disparo: enquanto ela for válida, o próprio driver atende o hardware. Caso se torne inválida, ele interrompe os disparos e o watchdog expira [SWS_Wdg_00144]. A especificação descreve a condição como «permissão para atender o watchdog durante os próximos n milissegundos». A entidade de controle deve renová-la dentro dessa janela [SWS_Wdg_00144].

Wdg_SetTriggerCondition(uint16 timeout) reinicia o contador de timeout de acordo com o valor passado ([SWS_Wdg_00155], [SWS_Wdg_00136]). O valor é interpretado como milissegundos. O driver converte-o internamente em um valor de contagem [SWS_Wdg_00138], levando em consideração o modo atual [SWS_Wdg_00139]. O valor 0 é permitido: ele encerra o disparo (quase) imediatamente, disparando assim um reset do watchdog (quase) imediato. Se o contador armazenado já estiver em 0, a função ignora qualquer novo valor [SWS_Wdg_00140]. Portanto, um contador expirado não pode mais ser recarregado.

O disparo propriamente dito é realizado por uma rotina de atendimento interna do driver. Se o contador de disparo for maior que zero, ela o decrementa e dispara o hardware [SWS_Wdg_00134]. Se tiver atingido zero, ela nada faz e o watchdog expira [SWS_Wdg_00135]. Se o atendimento for implementado como rotina de interrupção, os quadros de interrupção pertencem a Wdg_Irq.c [SWS_Wdg_00079]. A Figura 9.2 mostra, para isso, uma interrupção por temporizador que dispara o atendimento de forma temporalmente independente da chamada via WdgIf (SWS Wdg Fig. 9.2 p. 31).

Diagrama de sequência: O WdgM apenas recarrega o contador de disparo; o disparo em si é acionado por uma interrupção por temporizador no driver. Com o valor de contagem 0, o disparo não ocorre e o watchdog expira. Fontes: SWS Wdg Fig. 9.2 p. 31, [SWS_Wdg_00134], [SWS_Wdg_00135], [SWS_Wdg_00136], [SWS_Wdg_00093]

Diagrama de atividades: Wdg_SetTriggerCondition descarta timeouts excessivamente grandes, ignora novos valores se o contador já tiver expirado e, caso contrário, converte para um valor de contagem dependente do modo. Interpretação: A especificação não define a ordem das duas verificações. Fontes: [SWS_Wdg_00146], [SWS_Wdg_00140], [SWS_Wdg_00138], [SWS_Wdg_00139], SWS Wdg p. 29

Modos de operação OFF, SLOW e FAST

Wdg_SetMode comuta o driver e o hardware do modo atual para WDGIF_OFF_MODE, WDGIF_SLOW_MODE ou WDGIF_FAST_MODE. Cada modo corresponde a uma configuração estaticamente definida, como watchdog do tipo toggle ou window com diferentes períodos de timeout [SWS_Wdg_00160]. Os parâmetros específicos de hardware para cada modo encontram-se no conjunto de configuração passado para Wdg_Init [SWS_Wdg_00051]. O Wdg importa o tipo WdgIf_ModeType de WdgIf.h [SWS_Wdg_00105]. Um modelo de configuração mais antigo mostra, para isso, os contêineres WdgSettingsFast, WdgSettingsSlow e WdgSettingsOff, bem como WdgDefaultMode (ECUC-Parameter Fig. 5.21 p. 377).

Wdg_SetMode retorna E_OK somente se a transição tiver sido totalmente executada e todos os parâmetros do driver e do hardware tiverem os novos valores [SWS_Wdg_00103]. O WdgIf repassa esse valor de retorno inalterado (SWS WdgIf p. 18). O parâmetro pré-compilação WdgDisableAllowed determina se o watchdog pode ser desativado. Se estiver configurado como OFF, uma inicialização com modo padrão de desativação é rejeitada [SWS_Wdg_00025]. Segundo sua descrição, o erro WDG_E_DISABLE_REJECTED também cobre uma respectiva mudança de modo [SWS_Wdg_00179].

Diagrama de estados: Wdg_Init define o modo padrão configurado; depois, Wdg_SetMode alterna entre os três modos. O modo OFF só é acessível se WdgDisableAllowed o permitir. Fontes: [SWS_Wdg_00160], [SWS_Wdg_00001], [SWS_Wdg_00025], [SWS_Wdg_00179], [SWS_Wdg_00031]

Estados internos, áreas exclusivas e códigos de ativação

Com a detecção de erros de desenvolvimento ativada, o Wdg mantém um estado interno: WDG_UNINIT até a inicialização bem-sucedida, depois WDG_IDLE [SWS_Wdg_00019]. Durante sua execução, Wdg_SetMode e a rotina de atendimento definem WDG_BUSY. Como última operação antes do retorno, definem novamente WDG_IDLE ([SWS_Wdg_00018], [SWS_Wdg_00052]). Ambos verificam previamente se o estado é WDG_IDLE. Caso contrário, a mudança de modo ou o disparo não é executado e WDG_E_DRIVER_STATE é reportado ([SWS_Wdg_00017], [SWS_Wdg_00035]). Dessa forma, identificam-se chamadas antes da inicialização, bem como sobreposições entre mudança de modo e disparo.

Se for necessário desabilitar interrupções para garantir a consistência dos dados, por exemplo, durante a mudança de modo ou na rotina de disparo, isso deve ocorrer preferencialmente por meio de uma área exclusiva do escalonador do BSW. Como módulo MCAL, o driver interno também pode desabilitar interrupções diretamente [SWS_Wdg_00040]. O guia de distribuição do BSW explica o contexto: nos drivers MCAL, a Main Function, a API de serviço e a ISR podem acessar registradores de periféricos compartilhados em contextos de execução próprios (BSW Distribution Guide p. 36).

Alguns hardwares exigem um código de ativação configurável ou variável. Nesses casos, o Wdg gerencia o código internamente e passa sempre o valor correto. O hardware atualiza então a variável interna com o próximo código esperado [SWS_Wdg_00093]. O ciclo de disparo deve ser selecionado de modo a garantir que essa atualização possa ocorrer [SWS_Wdg_00094]. Um código inicial configurável pertence ao conjunto de configuração. Se o código for pré-definido fixamente pelo hardware, esse requisito não se aplica [SWS_Wdg_00095].

Diagrama de estados: Com a detecção de erros de desenvolvimento ativada, aplicam-se os estados WDG_UNINIT, WDG_IDLE e WDG_BUSY. Chamadas fora de WDG_IDLE são rejeitadas com WDG_E_DRIVER_STATE. Fontes: [SWS_Wdg_00019], [SWS_Wdg_00017], [SWS_Wdg_00018], [SWS_Wdg_00035], [SWS_Wdg_00052]

Watchdogs internos e externos: instâncias, arquivos, configuração

Uma ECU pode ter várias instâncias do Wdg, por exemplo, uma para um watchdog interno e outra para um externo. Nesse caso, os nomes de API e os nomes de tipos específicos da instância [SWS_Wdg_00172], assim como os nomes de arquivos de código e de cabeçalho, são estendidos conforme o SRS_BSW_00347 ([SWS_Wdg_00169], [SWS_Wdg_00170]). A Figura 1 mostra a estrutura de arquivos com marcadores como Wdg<xxx>.h e Wdg_<xxx>PBcfg.c (SWS Wdg Fig. 1 p. 11). Um Wdg externo deve oferecer o mesmo escopo funcional com uma API semanticamente idêntica à de um interno [SWS_Wdg_00077]. Seu código-fonte deve ser independente da plataforma de microcontrolador [SWS_Wdg_00055]. Um exemplo da área de segurança funcional é um watchdog de janela externo conectado via SPI (EXP SafetyUseCase Fig. 4.1 p. 20).

A estrutura de arquivos de código não é totalmente pré-definida. Se necessário, ela inclui Wdg_Lcfg.c para parâmetros de link-time e Wdg_PBcfg.c para parâmetros de post-build [SWS_Wdg_00079]. O Wdg valida a configuração estaticamente, no mais tardar em tempo de compilação [SWS_Wdg_00086]. Uma configuração estática determina se o código é executado a partir de ROM ou RAM [SWS_Wdg_00168]. Para hardware externo, o Wdg inclui os parâmetros de acesso, tais como canal SPI ou porta DIO, em seus parâmetros publicados e em seus parâmetros de configuração [SWS_Wdg_00078]. Versões mais recentes modelam isso como uma referência de seleção WdgExternalContainerRef para um grupo de canais DIO, uma sequência SPI ou uma sequência I2C. O I2C não é explicitamente mencionado no R20-11 (SWS Wdg p. 40). Wdg_SetTriggerCondition verifica contra o valor máximo WdgMaxTimeout [SWS_Wdg_00146]. O modelo de informações publicadas contém ainda WdgMinTimeout e WdgResolution (ECUC-Parameter Fig. 5.22 p. 380).

Comportamento em caso de erro

O Wdg diferencia erros de desenvolvimento, que em sua maioria só são verificados com a detecção de erros de desenvolvimento ativada, de erros de produção estendidos. Os códigos de erro estão definidos [SWS_Wdg_00010]:

• WDG_E_DRIVER_STATE (0x10)
• WDG_E_PARAM_MODE (0x11)
• WDG_E_PARAM_CONFIG (0x12)
• WDG_E_PARAM_TIMEOUT (0x13)
• WDG_E_PARAM_POINTER (0x14)
• WDG_E_INIT_FAILED (0x15, seleção inválida do conjunto de configuração)

Para erros de desenvolvimento, o Wdg solicita opcionalmente Det_ReportError [SWS_Wdg_00111]. Os casos de erro dos serviços individuais:

• Inicialização: Se o conjunto de configuração estiver fora dos limites permitidos, a inicialização não é realizada, retornando WDG_E_PARAM_CONFIG [SWS_Wdg_00090]. Se o modo padrão desativasse o watchdog embora WdgDisableAllowed==OFF se aplique, a inicialização não é realizada, retornando WDG_E_DISABLE_REJECTED [SWS_Wdg_00025].
• Mudança de modo: Um estado incorreto leva a WDG_E_DRIVER_STATE [SWS_Wdg_00017]. Um modo fora do intervalo ou configurações de hardware inválidas levam a WDG_E_PARAM_MODE ([SWS_Wdg_00091], [SWS_Wdg_00092]). Em todos os três casos, nenhuma alteração ocorre e a função retorna E_NOT_OK. Se a própria mudança falhar, por exemplo devido a configurações inconsistentes ou violação de temporizações, ela retorna E_NOT_OK e reporta WDG_E_MODE_FAILED [SWS_Wdg_00016].
• Condição de disparo: Se o timeout exceder WdgMaxTimeout, o contador não é recarregado e WDG_E_PARAM_TIMEOUT é reportado [SWS_Wdg_00146].
• Consulta de versão: Um ponteiro inválido enquadra-se em WDG_E_PARAM_POINTER [SWS_Wdg_00010]. A verificação de ponteiro nulo para Wdg_GetVersionInfo é descrita em uma seção do documento em versões mais recentes (SWS Wdg p. 30).

Os erros de produção WDG_E_MODE_FAILED e WDG_E_DISABLE_REJECTED dizem respeito à inicialização e à mudança de modo. Sua frequência de monitoramento depende da camada superior ([SWS_Wdg_00178], [SWS_Wdg_00179]). Eles são reportados com FAILED quando a definição ou desativação do modo falha, e com PASSED quando é bem-sucedida ([SWS_Wdg_00180], [SWS_Wdg_00181], [SWS_Wdg_00182], [SWS_Wdg_00183]). Essas notificações provavelmente trafegam pelo Dem_SetEventStatus opcionalmente solicitado [SWS_Wdg_00111]. Pergunta (aberta) O caso mais grave deliberadamente não aparece como valor de retorno: se a condição de disparo for omitida ou definida como 0, o watchdog expira e a ECU é reinicializada ([SWS_Wdg_00135], [SWS_Wdg_00140]).

Diagrama de atividades: Wdg_SetMode verifica estado, modo e limites de hardware, comuta e reporta o resultado por meio do valor de retorno e de WDG_E_MODE_FAILED. Interpretação: A ordem das verificações não é definida de forma normativa. Fontes: [SWS_Wdg_00017], [SWS_Wdg_00091], [SWS_Wdg_00092], [SWS_Wdg_00016], [SWS_Wdg_00103], [SWS_Wdg_00018], [SWS_Wdg_00180], [SWS_Wdg_00181]

Evidências mais detalhadas

• [SWS_Wdg_00144]: Princípio básico da condição de disparo e da divisão de tarefas entre a entidade de controle e o driver.
• [SWS_Wdg_00134], [SWS_Wdg_00135], [SWS_Wdg_00136], [SWS_Wdg_00140]: Lógica de contagem da rotina de atendimento e caso especial de timeout 0.
• [SWS_Wdg_00160], [SWS_Wdg_00103], [SWS_Wdg_00031]: Modos, condição de sucesso e desativação em vez de desinicialização.
• [SWS_Wdg_00076], [SWS_Wdg_00077], [SWS_Wdg_00161], [SWS_Wdg_00172]: Instâncias internas e externas e extensão de nomes (SWS Wdg p. 24).
• Diagramas divergentes: A Figura 2 do driver, bem como os diagramas de fluxo do Watchdog Manager, mostram WdgIf_Trigger e Wdg_Trigger, respectivamente (SWS Wdg Fig. 2 p. 30, SWS WdgM Fig. 13 p. 75, SWS WdgM Fig. 17 p. 78). Essa função não faz parte da API R20-11. O mecanismo determinante lá é aquele via Wdg_SetTriggerCondition ([SWS_Wdg_00155]).
• A Figura 9.2 sobre o disparo desacoplado no tempo provém do R21-11 e de versões posteriores. Sua afirmação coincide com [SWS_Wdg_00134] e [SWS_Wdg_00093] (SWS Wdg Fig. 9.2 p. 31).