Transição de heaps ION para DMA-BUF (somente kernel 5.4)

No Android 12, o GKI 2.0 substitui o alocador ION por heaps DMA-BUF pelos seguintes motivos:

  • Segurança: como cada heap de DMA-BUF é um dispositivo de caractere separado, o acesso a cada heap pode ser controlado separadamente com sepolicy. Isso não era possível com o ION porque a alocação de qualquer heap exigia acesso ao dispositivo /dev/ion.
  • Estabilidade da ABI: ao contrário do ION, a interface IOCTL do framework de heaps DMA-BUF é estável na ABI porque é mantida no kernel Linux upstream.
  • Padronização: o framework de heaps DMA-BUF oferece uma UAPI bem definida. O ION permitia flags personalizadas e IDs de heap que impediam o desenvolvimento de um framework de teste comum, porque a implementação do ION em cada dispositivo podia se comportar de maneira diferente.

A ramificação android12-5.10 do kernel comum do Android desativou o CONFIG_ION em 1o de março de 2021.

Contexto

Confira a seguir uma breve comparação entre os heaps ION e DMA-BUF.

Semelhanças entre o framework de heaps ION e DMA-BUF

  • Os frameworks de heaps ION e DMA-BUF são exportadores de DMA-BUF baseados em heap.
  • Eles permitem que cada heap defina o próprio alocador e as operações DMA-BUF.
  • A performance de alocação é semelhante porque ambos os esquemas precisam de um único IOCTL para a alocação.

Diferenças entre o framework de heaps ION e DMA-BUF

heaps ION Heaps DMA-BUF
Todas as alocações ION são feitas com /dev/ion. Cada heap de DMA-BUF é um dispositivo de caractere presente em /dev/dma_heap/<heap_name>.
O ION oferece suporte a flags particulares de heap. Os heaps DMA-BUF não oferecem suporte a flags privadas de heap. Cada tipo diferente de alocação é feito em uma pilha diferente. Por exemplo, as variantes de pilha do sistema em cache e sem cache são pilhas separadas localizadas em /dev/dma_heap/system e /dev/dma_heap/system_uncached.
O ID/máscara e as flags da pilha precisam ser especificados para a alocação. O nome do heap é usado para a alocação.

As seções a seguir listam os componentes que lidam com o ION e descrevem como trocá-los para o framework de heaps DMA-BUF.

Transição de drivers do kernel de heaps ION para DMA-BUF

Drivers do kernel que implementam heaps ION

Os heaps ION e DMA-BUF permitem que cada heap implemente os próprios alocadores e operações DMA-BUF. Para mudar de uma implementação de heap ION para uma implementação de heap DMA-BUF, use um conjunto diferente de APIs para registrar o heap. Esta tabela mostra as APIs de registro de heap ION e as APIs de heap DMA-BUF equivalentes.

heaps ION Heaps DMA-BUF
void ion_device_add_heap(struct ion_heap *heap) struct dma_heap *dma_heap_add(const struct dma_heap_export_info *exp_info);
void ion_device_remove_heap(struct ion_heap *heap) void dma_heap_put(struct dma_heap *heap);

Os heaps DMA-BUF não são compatíveis com flags particulares. Portanto, cada variante do heap precisa ser registrada individualmente usando a API dma_heap_add(). Para facilitar o compartilhamento de código, é recomendável registrar todas as variantes do mesmo heap no mesmo driver. Este exemplo de dma-buf: system_heap mostra a implementação das variantes em cache e sem cache do heap do sistema.

Use este dma-buf: heaps: example template para criar um heap DMA-BUF do zero.

Drivers do kernel alocando diretamente de pilhas ION

O framework de heaps DMA-BUF também oferece uma interface de alocação para clientes no kernel. Em vez de especificar a máscara e as flags de heap para selecionar o tipo de alocação, a interface oferecida pelos heaps DMA-BUF usa um nome de heap como entrada.

Veja a seguir a API de alocação ION no kernel e as APIs de alocação de heap DMA-BUF equivalentes. Os drivers do kernel podem usar a API dma_heap_find() para consultar a existência de um heap. A API retorna um ponteiro para uma instância de struct dma_heap, que pode então ser transmitida como um argumento para a API dma_heap_buffer_alloc().

heaps ION Heaps DMA-BUF
struct dma_buf *ion_alloc(size_t len, unsigned int heap_id_mask, unsigned int flags)

struct dma_heap *dma_heap_find(const char *name)

struct dma_buf *struct dma_buf *dma_heap_buffer_alloc(struct dma_heap *heap, size_t len, unsigned int fd_flags, unsigned int heap_flags)

Drivers do kernel que usam DMA-BUFs

Nenhuma mudança é necessária para drivers que importam apenas DMA-BUFs, porque um buffer alocado de um heap ION se comporta exatamente da mesma forma que um buffer alocado de um heap DMA-BUF equivalente.

Transição dos clientes do espaço do usuário do ION para heaps de DMA-BUF

Para facilitar a transição para clientes do espaço do usuário do ION, uma biblioteca de abstração chamada libdmabufheap está disponível. libdmabufheap oferece suporte à alocação em heaps DMA-BUF e heaps ION. Primeiro, ele verifica se existe um heap DMA-BUF com o nome especificado. Caso contrário, ele retorna para um heap ION equivalente, se houver.

Os clientes precisam inicializar um objeto BufferAllocator durante a inicialização em vez de abrir /dev/ion using ion_open(). Isso ocorre porque os descritores de arquivos criados pela abertura /dev/ion e /dev/dma_heap/<heap_name> são gerenciados internamente pelo objeto BufferAllocator.

Para mudar de libion para libdmabufheap, modifique o comportamento dos clientes da seguinte maneira:

  • Mantenha o controle do nome do heap a ser usado para a alocação, em vez do ID/máscara de cabeça e da flag de heap.
  • Substitua a API ion_alloc_fd(), que usa uma máscara de heap e um argumento de flag, pela API BufferAllocator::Alloc(), que usa um nome de heap.

Esta tabela ilustra essas mudanças mostrando como libion e libdmabufheap fazem uma alocação de heap do sistema sem cache.

Tipo de alocação libion libdmabufheap
Alocação em cache do heap do sistema ion_alloc_fd(ionfd, size, 0, ION_HEAP_SYSTEM, ION_FLAG_CACHED, &fd) allocator->Alloc("system", size)
Alocação sem cache do heap do sistema ion_alloc_fd(ionfd, size, 0, ION_HEAP_SYSTEM, 0, &fd) allocator->Alloc("system-uncached", size)

A variante de heap do sistema sem cache está aguardando aprovação upstream, mas já faz parte do ramo android12-5.10.

Para oferecer suporte ao upgrade de dispositivos, a API MapNameToIonHeap() permite mapear um nome de heap para parâmetros de heap ION (nome de heap ou máscara e flags) para permitir que essas interfaces usem alocações baseadas em nome. Confira um exemplo de alocação com base no nome.

A documentação de todas as APIs expostas por libdmabufheap está disponível. A biblioteca também expõe um arquivo de cabeçalho para uso por clientes C.

Implementação de referência do Gralloc

A implementação gralloc do Hikey960 usa libdmabufheap para que você possa a usar como uma implementação de referência.

Adições obrigatórias de ueventd

Para qualquer novo heap DMA-BUF específico do dispositivo criado, adicione uma nova entrada ao arquivo ueventd.rc do dispositivo. Este Exemplo de configuração de ueventd para oferecer suporte a heaps DMA-BUF demonstra como isso é feito para o heap do sistema DMA-BUF.

Adições de política de segurança obrigatórias

Adicionar permissões sepolicy para permitir que um cliente do espaço do usuário acesse um novo heap DMA-BUF. Este exemplo de adicionar permissões necessárias mostra as permissões de sepolicy criadas para vários clientes acessarem o heap do sistema DMA-BUF.

Acessar pilhas do fornecedor no código do framework

Para garantir a conformidade com o Treble, o código do framework só pode alocar de categorias pré-aprovadas de heaps de fornecedor.

Com base no feedback recebido dos parceiros, o Google identificou duas categorias de montões de fornecedores que precisam ser acessadas pelo código do framework:

  1. Pilhas com base no heap do sistema com otimizações de desempenho específicas do dispositivo ou do SoC.
  2. Pilhas a serem alocadas na memória protegida.

Pilhas com base no heap do sistema com otimizações de desempenho específicas do dispositivo ou do SoC

Para oferecer suporte a esse caso de uso, a implementação de heap do sistema de heap DMA-BUF padrão pode ser substituída.

  • O CONFIG_DMABUF_HEAPS_SYSTEM está desativado no gki_defconfig para que ele seja um módulo de fornecedor.
  • Os testes de compliance do VTS garantem que o heap exista em /dev/dma_heap/system. Os testes também verificam se o heap pode ser alocado a partir do qual é possível alocar o heap e se o descritor de arquivo retornado (fd) pode ser mapeado na memória (mapeado) do espaço do usuário.

Os pontos anteriores também são verdadeiros para a variante sem cache da pilha do sistema, embora a existência dela não seja obrigatória para dispositivos totalmente coerentes com E/S.

Heaps a serem alocados da memória protegida

As implementações de heap seguras precisam ser específicas do fornecedor, já que o kernel comum do Android não oferece suporte a uma implementação de heap segura genérica.

  • Registre suas implementações específicas do fornecedor como /dev/dma_heap/system-secure<vendor-suffix>.
  • Essas implementações de heap são opcionais.
  • Se os heaps existirem, os testes VTS garantem que as alocações possam ser feitas a partir deles.
  • Os componentes do framework recebem acesso a esses heaps para que possam ativar o uso de heaps por meio das HALs do Codec2 HAL/não vinculadas e de mesmo processo. No entanto, os recursos genéricos do framework do Android não podem depender deles devido à variabilidade nos detalhes de implementação. Se uma implementação de heap segura genérica for adicionada ao kernel comum do Android no futuro, ela precisará usar uma ABI diferente para evitar conflitos com a atualização de dispositivos.

Alocador de codec 2 para heaps DMA-BUF

Um alocador codec2 para a interface de heaps DMA-BUF está disponível no AOSP.

A interface do repositório de componentes que permite que os parâmetros de heap sejam especificados pelo HAL C2 está disponível com o alocador de heap DMA-BUF C2.

Exemplo de fluxo de transição para um heap ION

Para facilitar a transição de heaps ION para DMA-BUF, libdmabufheap permite mudar um heap por vez. As etapas a seguir demonstram um fluxo de trabalho sugerido para fazer a transição de um heap ION não legado chamado my_heap que oferece suporte a uma flag, ION_FLAG_MY_FLAG.

Etapa 1:crie equivalentes do heap ION no framework DMA-BUF. Neste exemplo, como o heap ION my_heap oferece suporte a uma flag ION_FLAG_MY_FLAG, registramos dois heaps DMA-BUF:

  • O comportamento de my_heap corresponde exatamente ao comportamento do heap ION com a flag ION_FLAG_MY_FLAG desativada.
  • O comportamento my_heap_special corresponde exatamente ao comportamento do heap ION com a flag ION_FLAG_MY_FLAG ativada.

Etapa 2:crie as mudanças de ueventd para os novos montões de DMA-BUF my_heap e my_heap_special. Nesse ponto, os heaps aparecem como /dev/dma_heap/my_heap e /dev/dma_heap/my_heap_special, com as permissões pretendidas.

Etapa 3:para clientes que alocam de my_heap, modifique os makefiles para vincular a libdmabufheap. Durante a inicialização do cliente, instancie um objeto BufferAllocator e use a API MapNameToIonHeap() para mapear a combinação <ION heap name/mask, flag> em nomes de heap DMA-BUF equivalentes.

Exemplo:

allocator->MapNameToIonHeap("my_heap_special" /* name of DMA-BUF heap */, "my_heap" /* name of the ION heap */, ION_FLAG_MY_FLAG /* ion flags */ )

Em vez de usar a API MapNameToIonHeap() com os parâmetros de nome e flag, é possível criar o mapeamento de <ION heap mask, flag> para nomes de heap DMA-BUF equivalentes definindo o parâmetro de nome de heap ION como vazio.

Etapa 4:substitua as invocações de ion_alloc_fd() por BufferAllocator::Alloc() usando o nome de heap apropriado.

Tipo de alocação libion libdmabufheap
Alocação de my_heap com a flag ION_FLAG_MY_FLAG desativada ion_alloc_fd(ionfd, size, 0, ION_HEAP_MY_HEAP, 0, &fd) allocator->Alloc("my_heap", size)
Alocação de my_heap com a sinalização ION_FLAG_MY_FLAG definida ion_alloc_fd(ionfd, size, 0, ION_HEAP_MY_HEAP, ION_FLAG_MY_FLAG, &fd) allocator->Alloc("my_heap_special", size)

Nesse ponto, o cliente é funcional, mas ainda está alocando do heap ION porque não tem as permissões de sepolicy necessárias para abrir o heap DMA-BUF.

Etapa 5:crie as permissões de sepolicy necessárias para que o cliente acesse os novos montões de DMA-BUF. O cliente agora está totalmente equipado para alocar a partir do novo heap DMA-BUF.

Etapa 6:verifique se as alocações estão acontecendo no novo heap DMA-BUF analisando o logcat.

Etapa 7:desative o heap ION my_heap no kernel. Se o código do cliente não precisar oferecer suporte à atualização de dispositivos (cujas kernels podem oferecer suporte apenas a pilhas ION), você também poderá remover as invocações MapNameToIonHeap().