Memory Abstraction Interface (MemIf)

A MemIf encaminha os pedidos de memória do NVRAM Manager para módulos Fee ou Ea e oculta o número destes por detrás de uma API uniforme SWS MemIf p. 7. O parâmetro DeviceIndex seleciona o módulo; se apenas estiver configurado um, este é ignorado e a MemIf é implementada como conjunto de macros SWS MemIf p. 17. Os serviços aceitam pedidos de forma síncrona e transmitem o valor de retorno, enquanto a operação de memória é executada assincronamente por baixo. O estado e o resultado são fornecidos por MemIf_GetStatus e MemIf_GetJobResult. Com a deteção de erros de desenvolvimento ativa, chamadas com erro fornecem E_NOT_OK ou MEMIF_JOB_FAILED.

mais ›

A Memory Abstraction Interface substitui as anteriores camadas de interface de drivers para Flash e EEPROM. Permite ao NVRAM Manager aceder a múltiplos módulos de abstração através de uma API uniforme: a Flash EEPROM Emulation (Fee) e a EEPROM Abstraction (Ea) SRS MemHwAb p. 5. A MemIf oculta o número destes módulos e oferece uma segmentação virtual num espaço de endereçamento linear SWS MemIf p. 7.

Diagrama de contexto: a MemIf efetua a mediação entre o NvM e a Fee/Ea; as notificações de conclusão seguem diretamente da Fee/Ea para o NvM. Fontes: SWS Fee p. 6, [SWS_MemIf_00047]

A MemIf não possui lógica de armazenamento própria. O parâmetro DeviceIndex seleciona o módulo; se apenas estiver configurado um, este é ignorado e a MemIf é implementada como conjunto de macros. No caso de múltiplos módulos, a distribuição ocorre, por exemplo, através de tabelas de ponteiros de funções SWS MemIf p. 17. Na R20-11, DeviceIndex é do tipo uint8 [SWS_MemIf_00039]; versões posteriores utilizam uint16.

Os serviços aceitam pedidos de forma síncrona e transmitem o valor de retorno do módulo [SWS_MemIf_00040]. A operação de memória é executada a seguir de forma assíncrona na função principal da camada inferior. O NvM toma conhecimento da conclusão através de callback da Fee/Ea ou por polling de MemIf_GetJobResult SWS Fee p. 48. MemIf_GetStatus notifica UNINIT, IDLE, BUSY ou BUSY_INTERNAL [SWS_MemIf_00064]. O resultado do job refere-se sempre ao último pedido e distingue, entre outros, blocos cancelados, inconsistentes e inválidos [SWS_MemIf_00065]. MemIf_SetMode atua em todos os módulos em simultâneo [SWS_MemIf_00038].

Diagrama de sequência: aceitação síncrona através da MemIf, execução assíncrona no driver, conclusão por callback ou polling. Fontes: SWS Ea p. 41, [SWS_MemIf_00040]

Em caso de erro, a MemIf notifica índices de dispositivo inválidos e ponteiros NULL como erros de desenvolvimento [SWS_MemIf_00006]. Os serviços fornecem então E_NOT_OK, e MemIf_GetJobResult fornece MEMIF_JOB_FAILED SWS MemIf p. 21. Os erros de tempo de execução da memória são detetados pela Fee ou Ea; o NvM lê-os em modo de polling como MEMIF_JOB_FAILED e é responsável pela sua correção ErrorDescription p. 58.

mais ›

Papel na pilha de memória: distribuidor entre NvM e Fee/Ea

A Memory Abstraction Interface (MemIf) substitui as anteriores camadas de interface de drivers para Flash e EEPROM. Permite ao NVRAM Manager (NvM) aceder a múltiplos módulos de abstração de memória através de uma única API: a Flash EEPROM Emulation (Fee) e a EEPROM Abstraction (Ea) SRS MemHwAb p. 5. Para as camadas superiores, a MemIf oculta quantos módulos Fee e Ea se encontram por baixo. Oferece uma segmentação virtual num espaço de endereçamento linear uniforme SWS MemIf p. 7. A Fee e a Ea fornecem o endereçamento baseado em blocos e um número «virtualmente ilimitado» de ciclos de apagamento e escrita. Por isso, não é necessário alterar o NvM quando os drivers ou o componente mudam SRS MemHwAb p. 5.

A MemIf em si não contém qualquer lógica de armazenamento. A sua API deve ser mapeada na API dos módulos de abstração, e o comportamento funcional é definido pelas especificações destes ou pelas dos drivers de memória SWS MemIf p. 17. Do mesmo modo, a MemIf necessita dos serviços dos módulos de abstração, para a Ea por exemplo Ea_Read, Ea_Cancel, Ea_GetStatus e Ea_GetJobResult [SWS_MemIf_00047]. Opcionalmente, utiliza Det_ReportError [SWS_MemIf_00048]. Os tipos MemIf_StatusType, MemIf_JobResultType e MemIf_ModeType definidos em MemIf.h formam o vocabulário comum da pilha [SWS_MemIf_00064] [SWS_MemIf_00065] [SWS_MemIf_00066]. Deste modo, por exemplo, Fls_GetJobResult fornece diretamente MemIf_JobResultType SWS Fls p. 36.

As ilustrações de releases mais recentes mostram adicionalmente, abaixo de Ea e Fee, os módulos MemAcc e Mem SWS Ea p. 42. Para a R20-11, presume-se que a visão geral mais antiga seja a determinante, na qual a Fee assenta sobre o driver Flash e a Ea sobre o driver EEPROM SWS Fee p. 6. Para a MemIf, a diferença é irrelevante, uma vez que apenas encaminha até ao nível de abstração SWS MemIf p. 17. Pergunta Q-3c74a6029dd0d159 (aberta)

Diagrama de contexto: a MemIf localiza-se entre o NvM e os módulos de abstração Fee/Ea; as notificações de conclusão chegam ao NvM diretamente a partir da Fee/Ea. Fontes: SWS Fee p. 6, SRS MemHwAb p. 5, [SWS_MemIf_00047], [SWS_MemIf_00048].

Seleção de dispositivo através de DeviceIndex: macros ou tabela de distribuição

O parâmetro DeviceIndex seleciona o módulo de abstração e, consequentemente, o componente de memória. Se apenas estiver configurado um módulo, este é ignorado SWS MemIf p. 17. Neste caso, a MemIf deve ser implementada como um conjunto de macros, por exemplo #define MemIf_Write(DeviceIndex, BlockNumber, DataPtr) Fee_Write(BlockNumber, DataPtr). No caso de múltiplos módulos, as chamadas devem ser distribuídas através de mecanismos eficientes; a especificação menciona como uma solução tabelas de ponteiros de funções indexadas através de DeviceIndex SWS MemIf p. 17. Se uma biblioteca específica do fabricante substituir todos os módulos Fee e Ea necessários, a MemIf consiste apenas em macros SRS MemHwAb p. 5.

Na R20-11, DeviceIndex é do tipo uint8 [SWS_MemIf_00039] [SWS_MemIf_00041]. Versões posteriores da especificação indicam-no como uint16 SWS MemIf p. 18. A referência normativa para esta release é uint8.

Diagrama de atividades: o número de módulos de abstração configurados decide entre mapeamento por macro e distribuição por DeviceIndex. Fontes: SWS MemIf p. 17, SRS MemHwAb p. 5

Fluxo de pedidos: aceitação síncrona, execução assíncrona

Todos os serviços da MemIf estão especificados como síncronos. Cada um chama a função homónima do módulo selecionado e retorna o respetivo valor de retorno, como por exemplo Read, Write e InvalidateBlock [SWS_MemIf_00039] [SWS_MemIf_00040] [SWS_MemIf_00044]. A operação de memória propriamente dita decorre depois de forma assíncrona na função principal da camada inferior chamada ciclicamente. Para o efeito, a sequência Ea mostra um ciclo sobre Eep_MainFunction na tarefa BSW SWS Ea p. 41. De acordo com a especificação da Fee, este padrão também se aplica aos restantes serviços assíncronos SWS Fee p. 48.

O NvM toma conhecimento do fim do pedido através de uma de duas vias, consoante a configuração da pilha. Ou o módulo de abstração chama um callback como NvM_JobEndNotification ou NvM_JobErrorNotification, ou o NvM efetua o polling de MemIf_GetJobResult SWS Fee p. 48 EXP ErrorDescription p. 45. A própria MemIf não disponibiliza qualquer função de callback; a sua API é composta pelos seguintes serviços [SWS_MemIf_00038] [SWS_MemIf_00046].

Serviço	ID de serviço	retornar	Efeito
MemIf_SetMode	0x01	–	chama o SetMode de todos os módulos de abstração [SWS_MemIf_00038]
MemIf_Read	0x02	Std_ReturnType	lê Length bytes do bloco a partir de BlockOffset para DataBufferPtr [SWS_MemIf_00039]
MemIf_Write	0x03	Std_ReturnType	escreve um bloco [SWS_MemIf_00040]
MemIf_Cancel	0x04	–	cancela o pedido em curso [SWS_MemIf_00041]
MemIf_GetStatus	0x05	MemIf_StatusType	estado do módulo [SWS_MemIf_00042]
MemIf_GetJobResult	0x06	MemIf_JobResultType	Resultado da última tarefa [SWS_MemIf_00043]
MemIf_InvalidateBlock	0x07	Std_ReturnType	invalida um bloco [SWS_MemIf_00044]
MemIf_GetVersionInfo	0x08	–	Informação de versão, reentrante [SWS_MemIf_00045]
MemIf_EraseImmediateBlock	0x09	Std_ReturnType	apaga um bloco [SWS_MemIf_00046]

Diagrama de sequência: uma tarefa de escrita é aceita de forma síncrona através de MemIf, executada de forma assíncrona no driver e concluída via callback ou polling. Fontes: SWS Ea p. 41, SWS Fee p. 48, ErrorDescription p. 60, [SWS_MemIf_00040]

Estado, resultado de job e modo de operação

MemIf_GetStatus fornece o estado do módulo selecionado [SWS_MemIf_00042]. São possíveis MEMIF_UNINIT, MEMIF_IDLE, MEMIF_BUSY e MEMIF_BUSY_INTERNAL. Em MEMIF_BUSY_INTERNAL, o módulo de abstração está ocupado com gerenciamento interno, enquanto o driver pode estar busy ou idle [SWS_MemIf_00064]. A especificação do Fee concretiza as condições e cita como exemplo de gerenciamento interno a reorganização da flash (garbage collection) SWS Fee p. 30. No driver de flash, o estado já pode ser consultado antes da inicialização e é então MEMIF_UNINIT SWS Fls p. 35.

Diagrama de estados: ciclo de vida do estado do módulo visível via MemIf_GetStatus. Fontes: [SWS_MemIf_00064], SWS Fee p. 30

MemIf_GetJobResult fornece o resultado da última tarefa [SWS_MemIf_00043] [SWS_MemIf_00065]. Leitura, escrita e apagamento compartilham um único resultado de job, de modo que apenas o da última tarefa pode ser consultado. Com a aceitação de uma nova tarefa, ele é definido como MEMIF_JOB_PENDING SWS Fls p. 36; o Fee fala da última tarefa aceita SWS Fee p. 31. Além de OK, FAILED e CANCELED, existem dois resultados relacionados a blocos. MEMIF_BLOCK_INCONSISTENT significa que o bloco está corrompido ou não foi encontrado; MEMIF_BLOCK_INVALID significa que ele está marcado como inválido [SWS_MemIf_00065].

Diagrama de estados: uma tarefa aceita permanece em PENDING e termina em exatamente um dos resultados finais. Fontes: [SWS_MemIf_00065], SWS Fls p. 36, SWS Fee p. 31

MemIf_SetMode é o único serviço que não possui DeviceIndex e chama SetMode de todos os módulos de abstração [SWS_MemIf_00038]. Os modos são MEMIF_MODE_SLOW e MEMIF_MODE_FAST [SWS_MemIf_00066]. Nos drivers, isso representa acesso de leitura lento ou acesso SPI normal, por um lado, e acesso de leitura rápido ou burst SPI, por outro. Eep_SetMode não deve ser chamado durante uma operação em andamento SWS Eep p. 34. Fls_SetMode rejeita uma solicitação no estado busy quando a verificação está ativa SWS Fls p. 42. Interpretação: como MemIf_SetMode atinge todos os módulos, ele só deve ser chamado quando todos os dispositivos reportarem MEMIF_IDLE. Pergunta Q-d6ee630fca619042 (aberta)

Cancelamento de tarefas em andamento

MemIf_Cancel chama a função Cancel do módulo selecionado [SWS_MemIf_00041]. O cancelamento em si é síncrono, mas assíncrono em relação ao hardware: o hardware ainda pode continuar em execução quando a chamada já tiver retornado SWS Fee p. 45 SWS Ea p. 44. O resultado do job passa a ser MEMIF_JOB_CANCELED [SWS_MemIf_00065], o que o Fee considera expressamente como uma falha SWS Fee p. 31.

Para o caminho da flash, a especificação do driver mostra a cadeia MemIf_Cancel → Fee_Cancel → Fls_Cancel com notificações de erro subsequentes. Ela também exige que Fls_Cancel não seja chamado durante uma Fls_MainFunction em andamento. Existem dois caminhos para isso: as funções de job do NvM e do driver de flash são sincronizadas, ou a task da Fls_MainFunction não é interrompida SWS Fls p. 58.

Diagrama de sequência: o cancelamento é executado de forma síncrona através de todas as camadas, a notificação de erro segue e, em seguida, GetJobResult reporta CANCELED. Fontes: SWS Fls p. 58, SWS Fee p. 45, [SWS_MemIf_00041]

Regras de chamada, reentrância e incorporação no BSW

Com exceção de MemIf_GetVersionInfo, todos os serviços não são reentrantes [SWS_MemIf_00045] [SWS_MemIf_00040]. Chamadas paralelas a partir de múltiplos contextos devem, portanto, ser excluídas. Como o estado e o resultado do job por módulo refletem apenas a última tarefa, o chamador só deve emitir uma nova tarefa após a conclusão da anterior SWS Fls p. 36.

O exemplo de mapeamento de memória de um cluster ICC2 «MEM» apresenta o MemIf juntamente com o NvM. Lá, MemIf_SetMode é modelado como BswCalledEntity, e o MemIf possui o prefixo de seção MEMIF SWS MemoryMapping p. 50. O BSW Distribution Guide cita MEMIF ao lado de FLS e FEE como exemplo de «Type I»; o escopo de aplicação pode ser limitado a um único núcleo via SwAddrMethod com escopo local EXP BSWDistributionGuide p. 31. Supõe-se que, em sistemas multinúcleo, o MemIf deva, portanto, ser operado localmente no núcleo. Pergunta Q-d998fdc58e0bcddd (aberta)

Comportamento em caso de erro

O MemIf reconhece dois erros de desenvolvimento. MEMIF_E_PARAM_DEVICE (0x01) representa um DeviceIndex incorreto, MEMIF_E_PARAM_POINTER (0x02) representa um ponteiro NULL [SWS_MemIf_00006]. Eles são reportados através do Det_ReportError opcional [SWS_MemIf_00048]. Códigos de erro específicos não são retornados através da API de acordo com a tabela de rastreamento SWS MemIf p. 12.

Se a detecção de erros de desenvolvimento estiver ativa e um erro for detectado, Read, Write, InvalidateBlock e EraseImmediateBlock retornam E_NOT_OK [SWS_MemIf_00039] [SWS_MemIf_00040] [SWS_MemIf_00044] [SWS_MemIf_00046]. MemIf_GetJobResult retorna MEMIF_JOB_FAILED SWS MemIf p. 21 nesse caso. Caso contrário, o valor do módulo é repassado inalterado.

Diagrama de atividades: verificação de parâmetros com detecção de erros de desenvolvimento ativa e repasse do resultado do módulo. Fontes: [SWS_MemIf_00006], [SWS_MemIf_00048], SWS MemIf p. 18, SWS MemIf p. 21

Erros de tempo de execução da memória não são detectados pelo MemIf, mas sim pelo Fee ou Ea; o próprio MemIf não reage a eles («N/A»). No modo de polling, o NvM lê o erro através de MemIf_GetJobResult como MEMIF_JOB_FAILED, e a recuperação cabe ao NvM ErrorDescription p. 58 ErrorDescription p. 60. Uma versão mais recente descreve essa recuperação mais detalhadamente. Segundo ela, em tarefas de escrita, o NvM incrementa um contador de repetições, cancela após exceder o limite e reporta NVM_E_REQ_FAILED ao DEM EXP ErrorDescription p. 45. Para a R20-11, esse detalhe não está normativamente comprovado aqui.

Evidências mais detalhadas

• Definições de API com Service-IDs, reentrância e valores de retorno: [SWS_MemIf_00038] a [SWS_MemIf_00046].
• Tipos de dados para estado, resultado de job e modo: [SWS_MemIf_00064], [SWS_MemIf_00065], [SWS_MemIf_00066]; tipos importados: [SWS_MemIf_00037].
• Regras de mapeamento (macros, DeviceIndex, distribuição): SWS MemIf p. 17.
• Interfaces obrigatórias e opcionais: [SWS_MemIf_00047], [SWS_MemIf_00048]; códigos de erro: [SWS_MemIf_00006].
• Fluxos para escrita e cancelamento: SWS Fee p. 48, SWS Fls p. 58.
• Cadeia de erros até o NvM na R20-11: ErrorDescription p. 58.