Esta página descreve as estruturas de dados e os métodos usados para comunicar buffers de operandos de maneira eficiente entre o driver e o framework.
No momento da compilação do modelo, o framework fornece os valores dos operandos constantes ao driver. Dependendo do ciclo de vida do operando constante, os valores dele estão localizados em um vetor HIDL ou em um pool de memória compartilhada.
- Se a vida útil for
CONSTANT_COPY, os valores estarão localizados no campooperandValuesda estrutura do modelo. Como os valores no vetor HIDL são copiados durante a comunicação entre processos (IPC, na sigla em inglês), isso geralmente é usado apenas para armazenar uma pequena quantidade de dados, como operandos escalares (por exemplo, o escalar de ativação emADD) e parâmetros de tensor pequenos (por exemplo, o tensor de forma emRESHAPE). - Se a vida útil for
CONSTANT_REFERENCE, os valores estarão localizados no campopoolsda estrutura do modelo. Somente os identificadores dos pools de memória compartilhada são duplicados durante a comunicação entre processos, em vez de copiar os valores brutos. Portanto, é mais eficiente armazenar uma grande quantidade de dados (por exemplo, os parâmetros de peso em convoluções) usando pools de memória compartilhada do que vetores HIDL.
No momento da execução do modelo, a estrutura fornece os buffers dos operandos de entrada e saída ao driver. Ao contrário das constantes de tempo de compilação que podem ser enviadas em um vetor HIDL, os dados de entrada e saída de uma execução são sempre comunicados por uma coleção de pools de memória.
O tipo de dados HIDL hidl_memory é usado na compilação e na execução para representar um pool de memória compartilhada não mapeado. O driver precisa mapear a memória de acordo para que ela possa ser usada com base no nome do tipo de dados hidl_memory.
Os nomes de memória compatíveis são:
ashmem: memória compartilhada do Android. Para mais detalhes, consulte memória.mmap_fd: memória compartilhada apoiada por um descritor de arquivo usandommap.hardware_buffer_blob: memória compartilhada apoiada por um AHardwareBuffer com o formatoAHARDWARE_BUFFER_FORMAT_BLOB. Disponível na HAL 1.2 de redes neurais (NN). Para mais detalhes, consulte AHardwareBuffer.hardware_buffer: memória compartilhada apoiada por um AHardwareBuffer geral que não usa o formatoAHARDWARE_BUFFER_FORMAT_BLOB. O buffer de hardware do modo não BLOB só é compatível com a execução do modelo.Disponível no NN HAL 1.2. Para mais detalhes, consulte AHardwareBuffer.
A partir da NN HAL 1.3, a NNAPI oferece suporte a domínios de memória que fornecem interfaces para alocar buffers gerenciados pelo driver. Os buffers gerenciados pelo driver também podem ser usados como entradas ou saídas de execução. Para mais detalhes, consulte Domínios de memória.
Os drivers da NNAPI precisam oferecer suporte ao mapeamento de nomes de memória ashmem e mmap_fd. A partir da
NN HAL 1.3, os drivers também precisam oferecer suporte ao mapeamento de hardware_buffer_blob. O suporte para o modo hardware_buffer geral não BLOB e domínios de memória é opcional.
AHardwareBuffer
AHardwareBuffer é um tipo de memória compartilhada que envolve um
buffer do Gralloc. No Android 10, a API Neural Networks (NNAPI) oferece suporte ao uso de AHardwareBuffer, permitindo que o driver faça execuções sem copiar dados, o que melhora o desempenho e o consumo de energia dos apps. Por exemplo, uma pilha de HAL
de câmera pode transmitir objetos AHardwareBuffer para a NNAPI para cargas de trabalho de aprendizado de máquina
usando identificadores AHardwareBuffer gerados pelas APIs NDK de câmera e NDK de mídia. Para mais informações, consulte
ANeuralNetworksMemory_createFromAHardwareBuffer.
Os objetos AHardwareBuffer usados na NNAPI são transmitidos ao driver por uma
struct hidl_memory chamada hardware_buffer ou hardware_buffer_blob.
A struct hidl_memory hardware_buffer_blob representa apenas objetos AHardwareBuffer
com o formato AHARDWAREBUFFER_FORMAT_BLOB.
As informações exigidas pelo framework são codificadas no campo hidl_handle da estrutura hidl_memory. O campo hidl_handle envolve native_handle,
que codifica todos os metadados necessários sobre um buffer
AHardwareBuffer ou Gralloc.
O driver precisa decodificar corretamente o campo hidl_handle fornecido e acessar a
memória descrita por hidl_handle. Quando o método getSupportedOperations_1_2,
getSupportedOperations_1_1 ou getSupportedOperations é
chamado, o driver precisa detectar se pode decodificar o hidl_handle fornecido e acessar a memória descrita por hidl_handle. A preparação do modelo vai falhar se o campo hidl_handle usado para um operando constante não for compatível. A execução vai falhar se o campo hidl_handle usado para um operando de entrada ou saída da execução não for compatível. É recomendável que o driver retorne um código de erro GENERAL_FAILURE se a preparação ou execução do modelo falhar.
Domínios de memória
Para dispositivos que executam o Android 11 ou versões mais recentes, a NNAPI oferece suporte a domínios de memória que fornecem interfaces para alocar buffers gerenciados pelo driver. Isso permite transmitir as memórias nativas do dispositivo entre as execuções, suprimindo a cópia e a transformação de dados desnecessários entre execuções consecutivas no mesmo driver. Esse fluxo é ilustrado na Figura 1.
Figura 1. Fluxo de dados de buffer usando domínios de memória
O recurso de domínio de memória é destinado a tensores que são, na maioria das vezes, internos ao driver e que não precisam de acesso frequente no lado do cliente. Alguns exemplos desses tensores incluem os tensores de estado em modelos sequenciais. Para tensores que precisam de acesso frequente à CPU no lado do cliente, é preferível usar pools de memória compartilhada.
Para oferecer suporte ao recurso de domínio de memória, implemente
IDevice::allocate
para permitir que o framework solicite a alocação de buffer gerenciado pelo driver. Durante a alocação, o framework fornece as seguintes propriedades e padrões de uso para o buffer:
BufferDescdescreve as propriedades necessárias do buffer.BufferRoledescreve o padrão de uso potencial do buffer como entrada ou saída de um modelo preparado. Vários papéis podem ser especificados durante a alocação do buffer, e o buffer alocado só pode ser usado como esses papéis especificados.
O buffer alocado é interno ao driver. Um driver pode escolher qualquer local de buffer ou layout de dados. Quando o buffer é alocado, o cliente do driver pode referenciar ou interagir com ele usando o token retornado ou o objeto IBuffer.
O token de IDevice::allocate é fornecido ao referenciar o buffer como
um dos objetos
MemoryPool
na estrutura
Request
de uma execução. Para impedir que um processo tente acessar o buffer alocado em outro processo, o driver precisa aplicar a validação adequada sempre que o buffer for usado. O driver precisa validar se o uso do buffer é uma das funções BufferRole fornecidas durante a alocação e falhar na execução imediatamente se o uso for ilegal.
O objeto
IBuffer
é usado para cópia explícita de memória. Em algumas situações, o cliente do
driver precisa inicializar o buffer gerenciado pelo driver em um pool de memória compartilhada
ou copiar o buffer para um pool de memória compartilhada. Exemplos de casos de uso:
- Inicialização do tensor de estado
- Armazenar em cache os resultados intermediários
- Execução de fallback na CPU
Para oferecer suporte a esses casos de uso, o driver precisa implementar
IBuffer::copyTo
e
IBuffer::copyFrom
com ashmem, mmap_fd e hardware_buffer_blob se for compatível com a alocação de domínio
de memória. É opcional para o driver oferecer suporte ao modo não BLOB
hardware_buffer.
Durante a alocação do buffer, as dimensões podem ser deduzidas dos operandos do modelo correspondentes de todas as funções especificadas por BufferRole e das dimensões fornecidas em BufferDesc. Com todas as informações dimensionais combinadas, o buffer pode ter dimensões ou classificação desconhecidas. Nesse caso, o buffer está em um estado flexível em que as dimensões são fixas quando usadas como uma entrada de modelo e em um estado dinâmico quando usadas como uma saída de modelo. O mesmo buffer pode ser usado com diferentes formatos de saídas em diferentes execuções, e o driver precisa processar o redimensionamento do buffer corretamente.
O domínio de memória é um recurso opcional. Um driver pode determinar que não é possível oferecer suporte a uma determinada solicitação de alocação por vários motivos. Exemplo:
- O buffer solicitado tem um tamanho dinâmico.
- O driver tem restrições de memória que impedem o processamento de buffers grandes.
É possível que várias linhas de execução diferentes leiam do buffer gerenciado pelo driver simultaneamente. O acesso simultâneo ao buffer para gravação ou leitura/gravação não é definido, mas não pode falhar no serviço de driver nem bloquear o caller indefinidamente. O driver pode retornar um erro ou deixar o conteúdo do buffer em um estado indeterminado.