AIDL para HALs

O Android 11 introduz a capacidade de usar a AIDL para HALs no Android, tornando possível implementar partes do Android sem a HIDL. Faça a transição das HALs para usar a AIDL exclusivamente sempre que possível (quando as HALs upstream usam a HIDL, ela precisa ser usada).

As HALs que usam a AIDL para se comunicar entre componentes do framework, como os em system.img, e componentes de hardware, como os em vendor.img, precisam usar a AIDL estável. No entanto, para se comunicar em uma partição, por exemplo, de uma HAL para outra, não há restrição no mecanismo de IPC a ser usado.

Motivação

A AIDL existe há mais tempo que a HIDL e é usada em muitos outros lugares, como entre componentes do framework do Android ou em apps. Agora que a AIDL tem suporte à estabilidade, é possível implementar uma pilha inteira com um único ambiente de execução de IPC. A AIDL também tem um sistema de controle de versão melhor do que a HIDL. Confira algumas vantagens da AIDL:

  • Usar uma única linguagem de IPC significa ter apenas uma coisa para aprender, depurar, otimizar e proteger.
  • A AIDL oferece suporte ao controle de versão no local para os proprietários de uma interface:
    • Os proprietários podem adicionar métodos ao final das interfaces ou campos a parcelables. Isso significa que é mais fácil controlar a versão do código ao longo dos anos, e o custo anual também é menor (os tipos podem ser alterados no local e não há necessidade de bibliotecas extras para cada versão da interface).
    • As interfaces de extensão podem ser anexadas no ambiente de execução em vez de no sistema de tipos. Portanto, não é necessário redefinir as extensões downstream para versões mais recentes das interfaces.
  • Uma interface AIDL atual pode ser usada diretamente quando o proprietário escolhe estabilizá-la. Antes, era necessário criar uma cópia inteira da interface na HIDL.

Criar no ambiente de execução da AIDL

A AIDL tem três back-ends diferentes: Java, NDK e CPP. Para usar a AIDL estável, sempre use a cópia do sistema de libbinder em system/lib*/libbinder.so e fale em /dev/binder. Para o código na imagem vendor, isso significa que libbinder (do VNDK) não pode ser usado: essa biblioteca tem uma API C++ instável e internos instáveis. Em vez disso, o código nativo do fornecedor precisa usar o back-end NDK da AIDL, vincular a libbinder_ndk (que é apoiado pelo sistema libbinder.so) e vincular às bibliotecas NDK criadas por entradas aidl_interface. Para conferir os nomes exatos dos módulos, consulte Regras de nomenclatura de módulos.

Escrever uma interface HAL da AIDL

Para que uma interface AIDL seja usada entre o sistema e o fornecedor, ela precisa de duas mudanças:

  • Cada definição de tipo precisa ser anotada com @VintfStability.
  • A declaração aidl_interface precisa incluir stability: "vintf",.

Somente o proprietário de uma interface pode fazer essas mudanças.

Quando você faz essas mudanças, a interface precisa estar no manifesto do VINTF para funcionar. Teste isso (e requisitos relacionados, como verificar se as interfaces lançadas estão congeladas) usando o teste do conjunto de testes de fornecedor (VTS, na sigla em inglês) vts_treble_vintf_vendor_test. Você pode usar uma interface @VintfStability sem esses requisitos chamando AIBinder_forceDowngradeToLocalStability no back-end NDK, android::Stability::forceDowngradeToLocalStability no back-end C++ ou android.os.Binder#forceDowngradeToSystemStability no back-end Java em um objeto binder antes de ele ser enviado para outro processo.

Além disso, para máxima portabilidade de código e para evitar possíveis problemas, como bibliotecas adicionais desnecessárias, desative o back-end CPP.

O código mostra como desativar o back-end CPP:

    aidl_interface: {
        ...
        backend: {
            cpp: {
                enabled: false,
            },
        },
    }

Encontrar interfaces HAL da AIDL

As interfaces AIDL estáveis do AOSP para HALs estão em pastas aidl nos mesmos diretórios de base das interfaces HIDL:

  • hardware/interfaces é para interfaces normalmente fornecidas pelo hardware.
  • frameworks/hardware/interfaces é para interfaces de alto nível fornecidas ao hardware.
  • system/hardware/interfaces é para interfaces de baixo nível fornecidas ao hardware.

Coloque interfaces de extensão em outros hardware/interfaces subdiretórios em vendor ou hardware.

Interfaces de extensão

O Android tem um conjunto de interfaces oficiais do AOSP em cada versão. Quando os parceiros do Android querem adicionar recursos a essas interfaces, eles não devem mudá-las diretamente, porque isso torna o ambiente de execução do Android incompatível com o ambiente de execução do AOSP. Evite mudar essas interfaces para que a imagem da GSI continue funcionando.

As extensões podem ser registradas de duas maneiras diferentes:

No entanto, quando uma extensão é registrada, os componentes específicos do fornecedor (ou seja, que não fazem parte do AOSP upstream) usam a interface, e conflitos de mesclagem não são possíveis. No entanto, quando modificações downstream são feitas nos componentes do AOSP upstream, podem ocorrer conflitos de mesclagem, e as seguintes estratégias são recomendadas:

  • Faça o upstream das adições de interface para o AOSP na próxima versão.
  • Faça o upstream das adições de interface que permitem mais flexibilidade (sem conflitos de mesclagem) na próxima versão.

Parcelables de extensão: ParcelableHolder

ParcelableHolder é uma instância da interface Parcelable que pode conter outra instância de Parcelable.

O principal caso de uso de ParcelableHolder é tornar Parcelable extensível. Por exemplo, imagine que os implementadores de dispositivos esperam poder estender um definido pelo AOSP Parcelable, AospDefinedParcelable, para incluir os recursos de valor agregado.

Use a interface ParcelableHolder para estender Parcelable com seus recursos de valor agregado. A interface ParcelableHolder contém uma instância de Parcelable. Se você tentar adicionar campos diretamente a Parcelable, isso causará um erro:

parcelable AospDefinedParcelable {
  int a;
  String b;
  String x; // ERROR: added by a device implementer
  int[] y; // added by a device implementer
}

Como visto no código anterior, essa prática é interrompida porque os campos adicionados pelo implementador do dispositivo podem ter um conflito quando Parcelable é revisado nas próximas versões do Android.

Usando ParcelableHolder, o proprietário de um parcelable pode definir um ponto de extensão em uma instância de Parcelable:

parcelable AospDefinedParcelable {
  int a;
  String b;
  ParcelableHolder extension;
}

Em seguida, os implementadores de dispositivos podem definir a própria instância Parcelable para a extensão:

parcelable OemDefinedParcelable {
  String x;
  int[] y;
}

A nova Parcelable instância pode ser anexada ao original Parcelable com o ParcelableHolder campo:


// Java
AospDefinedParcelable ap = ...;
OemDefinedParcelable op = new OemDefinedParcelable();
op.x = ...;
op.y = ...;

ap.extension.setParcelable(op);

...

OemDefinedParcelable op = ap.extension.getParcelable(OemDefinedParcelable.class);

// C++
AospDefinedParcelable ap;
OemDefinedParcelable op;
std::shared_ptr<OemDefinedParcelable> op_ptr = make_shared<OemDefinedParcelable>();

ap.extension.setParcelable(op);
ap.extension.setParcelable(op_ptr);

...

std::shared_ptr<OemDefinedParcelable> op_ptr;

ap.extension.getParcelable(&op_ptr);

// NDK
AospDefinedParcelable ap;
OemDefinedParcelable op;
ap.extension.setParcelable(op);

...

std::optional<OemDefinedParcelable> op;
ap.extension.getParcelable(&op);

// Rust
let mut ap = AospDefinedParcelable { .. };
let op = Rc::new(OemDefinedParcelable { .. });

ap.extension.set_parcelable(Rc::clone(&op));

...

let op = ap.extension.get_parcelable::<OemDefinedParcelable>();

Nomes de instâncias do servidor HAL da AIDL

Por convenção, os serviços HAL da AIDL têm um nome de instância no formato $package.$type/$instance. Por exemplo, uma instância da HAL do vibrador é registrada como android.hardware.vibrator.IVibrator/default.

Escrever um servidor HAL da AIDL

Os servidores AIDL @VintfStability precisam ser declarados no manifesto do VINTF. Por exemplo:

    <hal format="aidl">
        <name>android.hardware.vibrator</name>
        <version>1</version>
        <fqname>IVibrator/default</fqname>
    </hal>

Caso contrário, eles precisam registrar um serviço AIDL normalmente. Ao executar testes VTS, espera-se que todas as HALs AIDL declaradas estejam disponíveis.

Escrever um cliente AIDL

Os clientes AIDL precisam se declarar na matriz de compatibilidade. Por exemplo:

    <hal format="aidl" optional="true">
        <name>android.hardware.vibrator</name>
        <version>1-2</version>
        <interface>
            <name>IVibrator</name>
            <instance>default</instance>
        </interface>
    </hal>

Converter uma HAL atual da HIDL para a AIDL

Use a ferramenta hidl2aidl para converter uma interface HIDL para AIDL.

Recursos do hidl2aidl:

  • Crie arquivos AIDL (.aidl) com base nos arquivos HAL (.hal) do pacote especificado.
  • Crie regras de build para o pacote AIDL recém-criado com todos os back-ends ativados.
  • Crie métodos de tradução nos back-ends Java, CPP e NDK para traduzir dos tipos HIDL para os tipos AIDL.
  • Crie regras de build para bibliotecas de tradução com dependências necessárias.
  • Crie declarações estáticas para garantir que os enumeradores HIDL e AIDL tenham os mesmos valores nos back-ends CPP e NDK.

Siga estas etapas para converter um pacote de arquivos HAL em arquivos AIDL:

  1. Crie a ferramenta localizada em system/tools/hidl/hidl2aidl.

    A criação dessa ferramenta na origem mais recente oferece a experiência mais completa. Você pode usar a versão mais recente para converter interfaces em ramificações mais antigas de versões anteriores:

    m hidl2aidl

  2. Execute a ferramenta com um diretório de saída seguido do pacote a ser convertido.

    Opcionalmente, use o argumento -l para adicionar o conteúdo de um novo arquivo de licença à parte de cima de todos os arquivos gerados. Use a licença e a data corretas:

    hidl2aidl -o <output directory> -l <file with license> <package>

    Exemplo:

    hidl2aidl -o . -l my_license.txt android.hardware.nfc@1.2

  3. Leia os arquivos gerados e corrija os problemas com a conversão:

    • conversion.log contém todos os problemas não tratados a serem corrigidos primeiro.
    • Os arquivos AIDL gerados podem ter avisos e sugestões que precisam de ação. Esses comentários começam com //.
    • Limpe e faça melhorias no pacote.
    • Verifique a @JavaDerive anotação para recursos que podem ser necessários, como toString ou equals.

  4. Crie apenas os destinos necessários:

    • Desative os back-ends que não serão usados. Prefira o back-end NDK ao back-end CPP . Consulte Criar no ambiente de execução da AIDL.
    • Remova bibliotecas de tradução ou qualquer código gerado que não será usado.

  5. Consulte Principais diferenças entre AIDL e HIDL:

    • O uso de Status e exceções integradas da AIDL geralmente melhora a interface e remove a necessidade de outro tipo de status específico da interface.
    • Os argumentos da interface AIDL em métodos não são @nullable por padrão, como eram na HIDL.

SEPolicy para HALs da AIDL

Um tipo de serviço AIDL visível para o código do fornecedor precisa ter o atributo hal_service_type. Caso contrário, a configuração da sepolicy é a mesma de qualquer outro serviço AIDL (embora haja atributos especiais para HALs). Confira um exemplo de definição de um contexto de serviço HAL:

    type hal_foo_service, service_manager_type, hal_service_type;

Para a maioria dos serviços definidos pela plataforma, um contexto de serviço com o tipo correto já é adicionado (por exemplo, android.hardware.foo.IFoo/default já está marcado como hal_foo_service). No entanto, se um cliente do framework oferece suporte a vários nomes de instância, outros nomes de instância precisam ser adicionados em arquivos service_contexts específicos do dispositivo:

    android.hardware.foo.IFoo/custom_instance u:object_r:hal_foo_service:s0

Ao criar um novo tipo de HAL, é necessário adicionar atributos HAL. Um atributo HAL específico pode ser associado a vários tipos de serviço (cada um deles pode ter várias instâncias, como discutido anteriormente). Para uma HAL, foo, há hal_attribute(foo). Essa macro define os atributos hal_foo_client e hal_foo_server. Para um determinado domínio, as macros hal_client_domain e hal_server_domain associam um domínio a um determinado atributo HAL. Por exemplo, o servidor do sistema como um cliente dessa HAL corresponde à política hal_client_domain(system_server, hal_foo). Um servidor HAL inclui hal_server_domain(my_hal_domain, hal_foo) de maneira semelhante.

Normalmente, para um determinado atributo HAL, também crie um domínio como hal_foo_default para HALs de referência ou exemplo. No entanto, alguns dispositivos usam esses domínios para os próprios servidores. A distinção entre domínios para vários servidores só é importante se houver vários servidores que atendem à mesma interface e precisam de um conjunto de permissões diferente nas implementações. Em todas essas macros, hal_foo não é um objeto de sepolicy. Em vez disso, esse token é usado por essas macros para se referir ao grupo de atributos associados a um par de servidores cliente.

No entanto, até agora, hal_foo_service e hal_foo (o par de atributos de hal_attribute(foo)) não estão associados. Um atributo HAL é associado a serviços HAL da AIDL usando a macro hal_attribute_service (as HALs da HIDL usam a macro hal_attribute_hwservice). Por exemplo, hal_attribute_service(hal_foo, hal_foo_service). Isso significa que os processos hal_foo_client podem acessar a HAL e os processos hal_foo_server podem registrar a HAL. A aplicação dessas regras de registro é feita pelo gerenciador de contexto (servicemanager).

Os nomes de serviço nem sempre correspondem aos atributos HAL. Por exemplo, hal_attribute_service(hal_foo, hal_foo2_service). Em geral, como isso implica que os serviços são sempre usados juntos, você pode remover o hal_foo2_service e usar hal_foo_service para todos os contextos de serviço. Quando as HALs definem várias instâncias hal_attribute_service, é porque o nome do atributo HAL original não é geral o suficiente e não pode ser alterado.

Reunindo tudo isso, um exemplo de HAL é assim:

    public/attributes:
    // define hal_foo, hal_foo_client, hal_foo_server
    hal_attribute(foo)

    public/service.te
    // define hal_foo_service
    type hal_foo_service, hal_service_type, protected_service, service_manager_type

    public/hal_foo.te:
    // allow binder connection from client to server
    binder_call(hal_foo_client, hal_foo_server)
    // allow client to find the service, allow server to register the service
    hal_attribute_service(hal_foo, hal_foo_service)
    // allow binder communication from server to service_manager
    binder_use(hal_foo_server)

    private/service_contexts:
    // bind an AIDL service name to the selinux type
    android.hardware.foo.IFooXxxx/default u:object_r:hal_foo_service:s0

    private/<some_domain>.te:
    // let this domain use the hal service
    binder_use(some_domain)
    hal_client_domain(some_domain, hal_foo)

    vendor/<some_hal_server_domain>.te
    // let this domain serve the hal service
    hal_server_domain(some_hal_server_domain, hal_foo)

Interfaces de extensão anexadas

Uma extensão pode ser anexada a qualquer interface binder, seja uma interface de nível superior registrada diretamente com o administrador do serviço ou uma subinterface. Ao receber uma extensão, confirme se o tipo dela é o esperado. Você só pode definir extensões no processo que atende a um binder.

Use extensões anexadas sempre que uma extensão modificar a funcionalidade de uma HAL atual. Quando uma capacidade totalmente nova é necessária, esse mecanismo não é necessário, e você pode registrar uma interface de extensão diretamente com o administrador do serviço. As interfaces de extensão anexadas fazem mais sentido quando são anexadas a subinterfaces, porque essas hierarquias podem ser profundas ou de várias instâncias. O uso de uma extensão global para espelhar a hierarquia de interface binder de outro serviço exige uma contabilidade extensa para fornecer recursos equivalentes a extensões anexadas diretamente.

Para definir uma extensão em um binder, use as seguintes APIs:

  • Back-end NDK: AIBinder_setExtension
  • Back-end Java: android.os.Binder.setExtension
  • Back-end CPP: android::Binder::setExtension
  • Back-end Rust: binder::Binder::set_extension

Para receber uma extensão em um binder, use as seguintes APIs:

  • Back-end NDK: AIBinder_getExtension
  • Back-end Java: android.os.IBinder.getExtension
  • Back-end CPP: android::IBinder::getExtension
  • Back-end Rust: binder::Binder::get_extension

Você pode encontrar mais informações sobre essas APIs na documentação da função getExtension no back-end correspondente. Um exemplo de como usar extensões está em hardware/interfaces/tests/extension/vibrator.

Principais diferenças entre AIDL e HIDL

Ao usar HALs da AIDL ou interfaces HAL da AIDL, esteja ciente das diferenças em comparação com a gravação de HALs da HIDL.

  • A sintaxe da linguagem AIDL é mais próxima do Java. A sintaxe da HIDL é semelhante à do C++.
  • Todas as interfaces AIDL têm status de erro integrados. Em vez de criar tipos de status personalizados, crie ints de status constantes em arquivos de interface e use EX_SERVICE_SPECIFIC nos back-ends CPP e NDK e ServiceSpecificException no back-end Java. Consulte Tratamento de erros.
  • A AIDL não inicia automaticamente pools de linhas de execução quando objetos binder são enviados. É necessário iniciá-los manualmente (consulte Gerenciamento de linhas de execução).
  • A AIDL não é interrompida em erros de transporte não verificados (a HIDL Return é interrompida em erros não verificados).
  • A AIDL pode declarar apenas um tipo por arquivo.
  • Os argumentos da AIDL podem ser especificados como in, out, ou inout, além de o parâmetro de saída (não há callbacks síncronos).
  • A AIDL usa fd como o tipo primitivo em vez de handle.
  • A HIDL usa versões principais para mudanças incompatíveis e versões secundárias para mudanças compatíveis. Na AIDL, as mudanças compatíveis com versões anteriores são feitas no local. A AIDL não tem um conceito explícito de versões principais. Em vez disso, isso é incorporado aos nomes de pacotes. Por exemplo, a AIDL pode usar o nome do pacote bluetooth2.
  • A AIDL não herda a prioridade em tempo real por padrão. A função setInheritRt precisa ser usada por binder para ativar a herança de prioridade em tempo real.

Testes para HALs

Esta seção descreve as práticas recomendadas para testar HALs. Essas práticas são válidas mesmo que o teste de integração da HAL não esteja no VTS.

O Android depende do VTS para verificar as implementações HAL esperadas. O VTS ajuda a garantir que o Android seja compatível com versões anteriores de implementações antigas de fornecedores. As implementações que falham no VTS têm problemas de compatibilidade conhecidos que podem impedir que elas funcionem com versões futuras do SO.

Há duas partes principais do VTS para HALs.

1. Verificar se as HALs no dispositivo são conhecidas e esperadas pelo Android

O Android depende de uma lista estática e precisa de todas as HALs instaladas. Essa lista é expressa no manifesto do VINTF. Testes especiais em toda a plataforma verificam a integridade das camadas HAL em todo o sistema. Antes de escrever qualquer teste específico da HAL, também é necessário executar esses testes, porque eles podem informar se uma HAL tem configurações VINTF inconsistentes.

Esse conjunto de testes pode ser encontrado em test/vts-testcase/hal/treble/vintf. Se você estiver trabalhando em uma implementação HAL do fornecedor, use vts_treble_vintf_vendor_test para verificá-la. Você pode executar esse teste com o comando atest vts_treble_vintf_vendor_test.

Esses testes são responsáveis por verificar:

  • Cada interface @VintfStability declarada em um manifesto do VINTF está congelada em uma versão lançada conhecida. Isso verifica se os dois lados da interface concordam com a definição exata dessa versão da interface. Isso é necessário para a operação básica.
  • Todas as HALs declaradas em um manifesto do VINTF estão disponíveis nesse dispositivo. Qualquer cliente com permissões suficientes para usar um serviço HAL declarado precisa poder acessar e usar esses serviços a qualquer momento.
  • Todas as HALs declaradas em um manifesto do VINTF estão atendendo à versão da interface que elas declaram no manifesto.
  • Não há HALs obsoletas sendo veiculadas em um dispositivo. O Android suspende o suporte para versões mais antigas de interfaces HAL, conforme descrito no ciclo de vida do FCM.
  • As HALs necessárias estão presentes no dispositivo. Algumas HALs são necessárias para que o Android funcione corretamente.

2. Verificar o comportamento esperado de cada HAL

Cada interface HAL tem os próprios testes VTS para verificar o comportamento esperado dos clientes. Os casos de teste são executados em cada instância de uma interface HAL declarada e aplicam um comportamento específico com base na versão da interface implementada.

Em C++, você pode acessar uma lista de todas as HALs instaladas no sistema com a função android::getAidlHalInstanceNames em libaidlvintf_gtest_helper. No Rust, use binder::get_declared_instances.

Esses testes tentam cobrir todos os aspectos da implementação HAL em que o framework do Android se baseia ou pode se basear no futuro.

Esses testes incluem a verificação do suporte a recursos, o tratamento de erros e qualquer outro comportamento que um cliente possa esperar do serviço.

Marcos do VTS para o desenvolvimento de HALs

Os testes VTS (ou qualquer teste) precisam ser mantidos atualizados ao criar ou modificar as interfaces HAL do Android.

Os testes VTS precisam ser concluídos e estar prontos para verificar as implementações do fornecedor antes de serem congelados para versões da API do fornecedor do Android. Eles precisam estar prontos antes que as interfaces sejam congeladas para que os desenvolvedores possam criar as implementações, verificá-las e fornecer feedback aos desenvolvedores de interface HAL.

Testar no Cuttlefish

Quando o hardware não está disponível, o Android usa o Cuttlefish como um veículo de desenvolvimento para interfaces HAL. Isso permite testes de integração escalonáveis do Android.

Os testes hal_implementation_test verificam se o Cuttlefish tem implementações das versões mais recentes da interface HAL para garantir que o Android esteja pronto para processar as novas interfaces e que os testes VTS estejam prontos para testar as novas implementações do fornecedor assim que novos hardwares e dispositivos estiverem disponíveis.