PWM Driver (Pwm)

A função síncrona Pwm_Init serve como serviço central para a inicialização de todo o driver PWM ([SWS_Pwm_00095]). É disponibilizada através do ficheiro de cabeçalho Pwm.h e possui o ID de serviço hexadecimal 0x00 ([SWS_Pwm_00095]). Como único parâmetro de entrada, é passado ConfigPtr, que atua como ponteiro para o conjunto de configurações específico do driver do tipo Pwm_ConfigType ([SWS_Pwm_00095]). A interface não possui valor de retorno e não utiliza parâmetros de saída nem parâmetros de entrada/saída ([SWS_Pwm_00095]).

Em relação ao comportamento de tempo de execução, Pwm_Init é síncrona e especificada como não reentrante (Non Reentrant) ([SWS_Pwm_00095]). Uma chamada simultânea ou de interrupção a esta função a partir de múltiplas threads, tarefas ou rotinas de interrupção é, portanto, estritamente inadmissível. A execução deverá ocorrer tipicamente uma única vez durante o arranque do sistema, na fase de inicialização da ECU, antes de qualquer utilização posterior dos canais PWM. Pergunta Q-ff3f1cf769dfed70 (aberta)

Para garantir a ordem de chamada admissível, o módulo monitoriza o seu estado: se o serviço Pwm_Init for chamado quando o driver PWM já se encontra inicializado, o módulo reporta o erro de desenvolvimento PWM_E_ALREADY_INITIALIZED com o identificador 0x14 ([SWS_Pwm_50002]). Uma inicialização repetida é, assim, considerada um erro.

Uso e assinatura

A função Pwm_DeInit serve como serviço para a desinicialização do driver PWM ([SWS_Pwm_00096]). Ela é disponibilizada por meio do arquivo de cabeçalho Pwm.h e possui o ID de serviço 0x01 ([SWS_Pwm_00096]). A interface tem a assinatura void Pwm_DeInit(void), não recebe parâmetros de entrada nem de saída e não fornece valor de retorno ao chamador ([SWS_Pwm_00096]).

A chamada de Pwm_DeInit é executada de forma síncrona ([SWS_Pwm_00096]). O fluxo de controle chamador permanece, portanto, na função até que as etapas de desinicialização do módulo PWM sejam concluídas.

Simultaneidade e restrições

Para a execução, aplicam-se as seguintes condições de contorno relativas à concorrência:

• Não reentrante: o serviço é especificado como não reentrante ([SWS_Pwm_00096]). Uma chamada simultânea ou de interrupção a partir de múltiplas threads, tasks ou ISRs é inadmissível.
• Contexto de chamada: devido à semântica síncrona e à ausência de reentrância, a chamada tipicamente deve ocorrer no âmbito de uma fase controlada de shutdown no nível de task. Pergunta Q-f1afc58637cba5cf (aberta)

Tratamento de erros

Na especificação de Pwm_DeInit, não estão definidos valores de retorno nem códigos de erro específicos ([SWS_Pwm_00096]). Eventuais erros de tempo de execução ou de estado provavelmente devem ser registrados ou interceptados por meio de mecanismos internos de monitoramento do módulo, como a interface de desenvolvimento (DET), uma vez que não está previsto um feedback direto de erro através da interface da função. Pergunta (aberta)

A função Pwm_DisableNotification serve para desativar a notificação de borda (Signal Edge Notification) de um determinado canal PWM [SWS_Pwm_91003]. A declaração da função e as definições de tipo correspondentes são disponibilizadas através do arquivo de cabeçalho Pwm.h [SWS_Pwm_91003].

Parâmetros e valor de retorno

A interface possui o ID de serviço 0x06 e apresenta as seguintes características de assinatura [SWS_Pwm_91003]:

• ChannelNumber (in): identificador numérico do canal PWM a ser configurado, do tipo Pwm_ChannelType [SWS_Pwm_91003].

Não existem parâmetros de entrada/saída (inout) nem parâmetros puramente de saída (out) [SWS_Pwm_91003]. A função não fornece valor de retorno (void) ao chamador [SWS_Pwm_91003].

Comportamento de sincronização e concorrência

A chamada de Pwm_DisableNotification opera de forma assíncrona [SWS_Pwm_91003]. Em relação ao comportamento multithreading, o serviço é reentrante desde que números de canais diferentes sejam acessados [SWS_Pwm_91003].

Interpretação: como a reentrância é explicitamente limitada a canais diferentes, a função presumivelmente não é reentrante para o mesmo canal PWM [SWS_Pwm_91003]. Pergunta Q-005e97fd25679da7 (aberta) Chamadas simultâneas para o canal idêntico provavelmente precisam, portanto, ser sincronizadas no lado do chamador.

usar

A função Pwm_EnableNotification serve para a ativação de notificações de borda de sinal para um determinado canal PWM de acordo com o parâmetro de notificação passado [SWS_Pwm_91004]. O serviço é disponibilizado por meio do arquivo de cabeçalho Pwm.h, possui o Service-ID 0x07 e não retorna nenhum valor de retorno (void) ao chamador [SWS_Pwm_91004].

Ao chamar a interface, devem ser passados dois parâmetros de entrada obrigatórios [SWS_Pwm_91004]:

• ChannelNumber (do tipo Pwm_ChannelType): identificador numérico do canal PWM a ser acessado [SWS_Pwm_91004].
• Notification (do tipo Pwm_EdgeNotificationType): define o tipo da notificação de borda com os valores permitidos PWM_RISING_EDGE, PWM_FALLING_EDGE ou PWM_BOTH_EDGES [SWS_Pwm_91004].

Semântica e concorrência

A execução do serviço é especificada como assíncrona [SWS_Pwm_91004]. Em relação à concorrência, Pwm_EnableNotification é projetada como reentrante para números de canais diferentes [SWS_Pwm_91004]. No caso de um acesso simultâneo ou interruptivo ao mesmo canal PWM, o serviço presumivelmente não é reentrante; tal chamada deve, portanto, ser protegida pelo chamador. Pergunta Q-73309ed8589161a3 (aberta)

Tratamento de erros e condições de contorno

O excerto da especificação não define para esta função nem valores de retorno específicos nem mensagens de erro para o Development Error Tracer (DET) ou o Diagnostic Event Manager (DEM) [SWS_Pwm_91004]. Da mesma forma, faltam especificações sobre contextos de chamada permitidos ou ordens relacionadas a tarefas. Como nenhuma pré-condição é mencionada, presume-se que a chamada da função seja permitida apenas após uma inicialização bem-sucedida do driver PWM. Pergunta Q-7f428f59a20175c2 (aberta)

A função síncrona Pwm_SetPowerState coloca o módulo PWM em um estado previamente preparado a partir de uma seleção pré-configurada de power-states [SWS_Pwm_00166]. A declaração está disponível por meio do cabeçalho Pwm.h [SWS_Pwm_00166].

Uso e valores de retorno

A função não recebe parâmetros de entrada e passa o resultado detalhado por meio do parâmetro de ponteiro Result do tipo Pwm_PowerStateRequestResultType* [SWS_Pwm_00166]:

• Se o modo pôde ser alterado com sucesso, a função retorna E_OK e define Result como PWM_SERVICE_ACCEPTED [SWS_Pwm_00166].
• Se a solicitação for rejeitada, a chamada retorna E_NOT_OK [SWS_Pwm_00166].

Tratamento de erros

Em caso de erro (valor de retorno E_NOT_OK), Result especifica a causa da falha [SWS_Pwm_00166]:

• PWM_NOT_INIT: o módulo PWM não está inicializado [SWS_Pwm_00166].
• PWM_SEQUENCE_ERROR: há uma sequência inválida de chamadas de API [SWS_Pwm_00166].
• PWM_HW_FAILURE: um erro no módulo de hardware impede a entrada no power-state solicitado [SWS_Pwm_00166].

Simultaneidade e condições marginais

Pwm_SetPowerState não é reentrante (Non Reentrant) e exige, para evitar um erro de sequência, que o estado de destino tenha sido preparado antes da chamada [SWS_Pwm_00166].

usar

A função síncrona Pwm_PreparePowerState inicia o processo de preparação necessário para que o módulo de hardware PWM possa transitar para um estado de energia solicitado [SWS_Pwm_00183]. O estado de destino desejado é passado por meio do parâmetro PowerState, enquanto o resultado detalhado é disponibilizado por meio do ponteiro de saída Result [SWS_Pwm_00183]. Se a preparação foi iniciada com sucesso, a função retorna E_OK e define Result como PWM_SERVICE_ACCEPTED [SWS_Pwm_00183].

Tratamento de erros

Se o serviço for rejeitado, a função retorna E_NOT_OK e reporta a causa específica por meio de Result [SWS_Pwm_00183]:

• PWM_NOT_INIT: o módulo PWM não está inicializado [SWS_Pwm_00183].
• PWM_SEQUENCE_ERROR: sequência de chamadas inválida, pois o estado de energia atual já corresponde ao estado de destino [SWS_Pwm_00183].
• PWM_POWER_STATE_NOT_SUPP: o módulo não suporta o estado de energia solicitado [SWS_Pwm_00183].
• PWM_TRANS_NOT_POSSIBLE: Uma transição direta não é possível ou o periférico de hardware ainda está ocupado [SWS_Pwm_00183].

Concorrência e interação

A função não é reentrante (Non Reentrant) e, portanto, não deve ser chamada concorrentemente para o mesmo módulo [SWS_Pwm_00183]. Após a preparação bem-sucedida por Pwm_PreparePowerState, devem ser executadas ações subsequentes, não imediatamente efetivas, para concluir finalmente a transição do estado de energia [SWS_Pwm_00190].

A interface Pwm_Main_PowerTransitionManager serve para o monitoramento cíclico de transições de estado de energia (Power State Transitions) do driver PWM de acordo com [SWS_Pwm_00189]. Ela possui o Service-ID 0x0d, não recebe parâmetros de passagem e não fornece valor de retorno (assinatura void Pwm_Main_PowerTransitionManager(void)).

No âmbito de sua execução cíclica, a função verifica a prontidão operacional do módulo para o respectivo estado de energia. Assim que a prontidão estiver presente, ela dispara os callbacks de notificação IoHwAb_Pwm_NotifyReadyForPowerState<Mode>, que são referenciados pelo parâmetro de configuração PwmPowerStateReadyCbkRef [SWS_Pwm_00189].

A função é prevista para um contexto de chamada cíclico e é disponibilizada por meio do arquivo de cabeçalho SchM_Pwm.h. Em consequência, a chamada periódica presumivelmente deve ocorrer no contexto do escalonador de BSW (Schedule Manager) [SWS_Pwm_00189]. Códigos de erro específicos, mecanismos para tratamento de erros via DET ou DEM, bem como condições especiais de reentrância não são definidos na especificação do módulo para este serviço. Pergunta Q-b9b0431e7ccbca88 (aberta)

A função de notificação relativa ao canal Pwm_Notification_<#Channel> é chamada sincronamente pelo módulo PWM assim que ocorre o evento de borda configurado para o respectivo canal [SWS_Pwm_00105]. A função possui a assinatura void Pwm_Notification_<#Channel>(void), não recebe parâmetros de passagem e não fornece valor de retorno [SWS_Pwm_00105]. Ela é declarada no arquivo Pwm_Externals.h e deve ser fornecida pelo usuário [SWS_Pwm_00105].

A chamada ocorre em função da última chamada de Pwm_EnableNotification para o canal em questão [SWS_Pwm_00105]. Os eventos disparadores orientam-se pelos valores de Pwm_EdgeNotificationType, que distingue bordas de sinal de subida (PWM_RISING_EDGE), de descida (PWM_FALLING_EDGE) ou ambas (PWM_BOTH_EDGES) [SWS_Pwm_00109]. Antes da geração de sinais e da notificação de eventos, o módulo PWM deve ter sido inicializado por meio de Pwm_Init com uma estrutura Pwm_ConfigType dependente de hardware [SWS_Pwm_00095], [SWS_Pwm_00111].

Em relação à concorrência, a reentrância da função de callback é explicitamente definida como dependente do usuário (PWM user implementation dependant) [SWS_Pwm_00105]. O contexto de execução exato (por exemplo, se a chamada ocorre diretamente em uma rotina de serviço de interrupção ou no contexto de task) deve depender da implementação subjacente do driver (interpretação). Pergunta Q-327872e0e8fecb37 (aberta) Não existem códigos de erro específicos, valores de retorno ou mensagens padronizadas de DET ou DEM para esta interface de notificação [SWS_Pwm_00105].

A função IoHwAb_Pwm_NotifyReadyForPower (declarada na sintaxe como IoHwAb_Pwm_NotifyReadyForPowerState<#Mode>) é disponibilizada através do cabeçalho IoHwAb_Pwm.h e serve como interface de callback no gerenciamento de energia AUTOSAR [SWS_Pwm_00198].

Em relação ao uso, às propriedades da interface e à interação com o sistema, aplicam-se as seguintes diretrizes obrigatórias:

• Uso e contexto de chamada: A interface possui o ID de serviço 0x60 e é executada de forma síncrona [SWS_Pwm_00198]. Ela deve obrigatoriamente ser chamada pelo driver PWM assim que a preparação no nível do dispositivo para um estado de energia (Power State) solicitado de um modo tiver sido concluída com sucesso [SWS_Pwm_00198].
• Parâmetros e valores de retorno: A assinatura da função não define parâmetros de entrada, de entrada/saída ou de saída e não possui valor de retorno (void) [SWS_Pwm_00198]. Interpretação: a associação ao respectivo modo de energia provavelmente decorre diretamente do nome da função específico do modo no código-fonte. Pergunta Q-ab761160ed91de78 (aberta)
• Concorrência e restrições: A função é especificada como não reentrante (Non Reentrant) [SWS_Pwm_00198]. As chamadas não devem, portanto, ocorrer em paralelo ou aninhadas dentro do mesmo contexto de driver.
• Interação: No fluxo entre módulos, a chamada sinaliza à abstração de hardware de E/S de nível superior que o estágio do driver está pronto para a mudança para o estado de operação desejado [SWS_Pwm_00198].

Nas fontes da especificação, não estão previstos códigos de erro específicos nem mensagens para DET ou DEM para esta função [SWS_Pwm_00198].

O tipo de enumeração Pwm_OutputStateType define o estado de saída de um canal PWM dentro do driver Classic AUTOSAR Pwm [SWS_Pwm_00108]. A definição do tipo é disponibilizada por meio do arquivo de cabeçalho Pwm.h para unidades de software chamadoras e aplicações de driver [SWS_Pwm_00108].

A faixa de valores desta enumeração distingue dois estados claramente definidos do canal [SWS_Pwm_00108]:

• PWM_HIGH (valor numérico 0x00): indica que o respectivo canal PWM se encontra no estado High [SWS_Pwm_00108].
• PWM_LOW (valor numérico 0x01): indica que o respectivo canal PWM se encontra no estado Low [SWS_Pwm_00108].

Em relação ao contexto de chamada e à finalidade de uso, o elemento em si, como tipo, não define funções de interface [SWS_Pwm_00108]. Interpretação: os valores tipicamente devem servir como parâmetros ou valores de retorno em funções de API do módulo para sinalizar o estado de nível lógico atual ou desejado de um canal. Pergunta Q-9c142d658ab7fcfd (aberta)

Por se tratar de uma definição de tipo elementar, não existem tratamentos de erro específicos relativos a DET ou DEM, tampouco requisitos de reentrância ou de execução síncrona no escopo da especificação [SWS_Pwm_00108].

O tipo de enumeração Pwm_PowerStateRequestResultType fornece o resultado de solicitações para mudança de estado do modo de gerenciamento de energia (Power State Transitions) no driver PWM, de acordo com [SWS_Pwm_00165]. A definição do tipo está disponível por meio do cabeçalho Pwm.h [SWS_Pwm_00165].

O tipo representa tanto a transição bem-sucedida quanto condições de erro específicas [SWS_Pwm_00165]:

• PWM_SERVICE_ACCEPTED (0x00): a mudança solicitada do estado de energia (Power-State) foi executada com sucesso [SWS_Pwm_00165].
• PWM_NOT_INIT (0x01): o módulo PWM ainda não está inicializado [SWS_Pwm_00165].
• PWM_SEQUENCE_ERROR (0x02): a sequência de chamada da API é inadmissível [SWS_Pwm_00165].
• PWM_HW_FAILURE (0x03): um erro de hardware impede que o estado de energia exigido seja assumido [SWS_Pwm_00165].
• PWM_POWER_STATE_NOT_SUPP (0x04): o estado solicitado não é suportado pelo módulo [SWS_Pwm_00165].
• PWM_TRANS_NOT_POSSIBLE (0x05): uma transição direta de estado não é possível ou o periférico de hardware ainda está ocupado [SWS_Pwm_00165].

Os chamadores devem avaliar o resultado para determinar se uma mudança de estado se tornou efetiva imediatamente. Interpretação: o tipo tipicamente deve atuar como valor de retorno ou parâmetro de saída de funções correspondentes de gerenciamento de energia para informar módulos superiores sobre conflitos de transição ou bloqueios de hardware. Pergunta Q-fd06829e5c030906 (aberta)

O tipo enumerado Pwm_PowerStateType serve no módulo PWM para a descrição de estados de energia [SWS_Pwm_00197]. Ele representa ou o estado operacional atualmente ativo ou um novo estado de potência definido como destino do driver [SWS_Pwm_00197]. Esse tipo de dados é disponibilizado por meio do arquivo de cabeçalho Pwm.h [SWS_Pwm_00197].

A especificação define para a enumeração os seguintes valores e faixas de valores [SWS_Pwm_00197]:

• PWM_FULL_POWER (valor 0x00): caracteriza o estado de potência máxima («Full Power») [SWS_Pwm_00197].
• Faixa de valores 1..255: define modos de potência graduados com consumo de energia decrescente passo a passo («power modes with decreasing power consumptions») [SWS_Pwm_00197].

Em relação ao contexto de uso, presume-se que o tipo funcione como parâmetro de passagem na solicitação de um modo de economia de energia, bem como valor de retorno em consultas de status, já que o tipo mapeia tanto estados ativos quanto de destino [SWS_Pwm_00197]. Pergunta Q-f0423f8b958d7e91 (aberta) Funções de API concretas, tratamentos de erro (DET/DEM) e restrições de concorrência não estão presentes para este tipo de dados no excerto de especificação fornecido e, portanto, foram omitidos [SWS_Pwm_00197].