Back-ends AIDL

Um back-end AIDL é um destino para geração de código stub. Ao usar arquivos AIDL, você sempre os usa em um idioma específico com um tempo de execução específico. Dependendo do contexto, você deve usar back-ends AIDL diferentes.

AIDL tem os seguintes back-ends:

• Essas superfícies de API são estáveis, mas muitas das APIs, como as de gerenciamento de serviços, são reservadas para uso interno da plataforma e não estão disponíveis para aplicativos. Para obter mais informações sobre como usar AIDL em aplicativos, consulte a documentação do desenvolvedor .
• O back-end Rust foi introduzido no Android 12; o back-end do NDK está disponível a partir do Android 10.
• A caixa Rust é construída sobre libbinder_ndk . Os APEXes usam a caixa de fichário da mesma forma que qualquer outra pessoa no lado do sistema. A parte Rust é empacotada em um APEX e enviada dentro dele. Depende do libbinder_ndk.so na partição do sistema.

Construir sistemas

Dependendo do backend, há duas maneiras de compilar AIDL em código stub. Para obter mais detalhes sobre os sistemas de compilação, consulte a Referência do módulo Soong .

Sistema de compilação principal

Em qualquer módulo Android.bp cc_ ou java_ (ou em seus equivalentes Android.mk ), os arquivos .aidl podem ser especificados como arquivos de origem. Nesse caso, os backends Java/CPP do AIDL são usados ​​(não o backend NDK) e as classes para usar os arquivos AIDL correspondentes são adicionadas ao módulo automaticamente. Opções como local_include_dirs , que informa ao sistema de compilação que o caminho raiz para os arquivos AIDL nesse módulo podem ser especificados nesses módulos em um grupo aidl: Observe que o back-end Rust é apenas para uso com Rust. Os módulos rust_ são tratados de maneira diferente, pois os arquivos AIDL não são especificados como arquivos de origem. Em vez disso, o módulo aidl_interface produz um rustlib chamado <aidl_interface name>-rust que pode ser vinculado. Para obter mais detalhes, consulte o exemplo de Rust AIDL .

aidl_interface

Consulte AIDL estável . Os tipos usados ​​com este sistema de compilação devem ser estruturados; isto é, expresso em AIDL diretamente. Isso significa que parcelables personalizados não podem ser usados.

Tipos

Você pode considerar o compilador aidl como uma implementação de referência para tipos. Ao criar uma interface, invoque aidl --lang=<backend> ... para ver o arquivo de interface resultante. Ao usar o módulo aidl_interface , você pode visualizar a saída em out/soong/.intermediates/<path to module>/ .

^{1. No Android 12 ou superior, as matrizes de bytes usam uint8_t em vez de int8_t por motivos de compatibilidade.}

^{2. O backend C++ suporta List<T> onde T é um de String , IBinder , ParcelFileDescriptor ou parcelable. No Android T (AOSP experimental) ou superior, T pode ser qualquer tipo não primitivo (incluindo tipos de interface), exceto matrizes. O AOSP recomenda que você use tipos de array como T[] , pois eles funcionam em todos os back-ends.}

^{3. O back-end do NDK suporta List<T> onde T é um de String , ParcelFileDescriptor ou parcelable. No Android T (AOSP experimental) ou superior, T pode ser qualquer tipo não primitivo, exceto matrizes.}

^{4. Os tipos são passados ​​de forma diferente para o código Rust dependendo se são entrada (um argumento) ou uma saída (um valor retornado).}

^{5. Os tipos de união são compatíveis com o Android 12 e superior.}

^{6. No Android T (AOSP experimental) ou superior, os arrays de tamanho fixo são suportados. Arrays de tamanho fixo podem ter várias dimensões (por exemplo int[3][4] ). No backend Java, arrays de tamanho fixo são representados como tipos de array.}

Direcionalidade (entrada/saída/saída)

Ao especificar os tipos de argumentos para funções, você pode especificá-los como in , out ou inout . Isso controla em qual direção as informações são passadas para uma chamada IPC. in é a direção padrão e indica que os dados são passados ​​do chamador para o receptor. out significa que os dados são passados ​​do chamador para o chamador. inout é a combinação de ambos. No entanto, a equipe do Android recomenda que você evite usar o especificador de argumento inout . Se você usar inout com uma interface com versão e um receptor mais antigo, os campos adicionais que estão presentes apenas no chamador serão redefinidos para seus valores padrão. Com relação a Rust, um tipo de inout normal recebe &mut Vec<T> e um tipo de inout de lista recebe &mut Vec<T> .

UTF8/UTF16

Com o backend CPP você pode escolher se as strings são utf-8 ou utf-16. Declare strings como @utf8InCpp String em AIDL para convertê-las automaticamente em utf-8. Os back-ends NDK e Rust sempre usam strings utf-8. Para obter mais informações sobre a anotação utf8InCpp , consulte Anotações em AIDL .

Nulidade

Você pode anotar tipos que podem ser nulos no back-end Java com @nullable para expor valores nulos aos back-ends CPP e NDK. No back-end Rust, esses tipos @nullable são expostos como Option<T> . Os servidores nativos rejeitam valores nulos por padrão. As únicas exceções a isso são os tipos interface e IBinder , que sempre podem ser nulos para leituras NDK e gravações CPP/NDK. Para obter mais informações sobre a anotação nullable , consulte Anotações em AIDL .

Parcelamentos personalizados

Nos back-ends C++ e Java no sistema de compilação principal, você pode declarar um parcelable que é implementado manualmente em um back-end de destino (em C++ ou em Java).

    package my.package;
    parcelable Foo;

ou com declaração de cabeçalho C++:

    package my.package;
    parcelable Foo cpp_header "my/package/Foo.h";

Então você pode usar este parcelable como um tipo em arquivos AIDL, mas não será gerado pelo AIDL.

Rust não suporta parcelamentos personalizados.

Valores padrão

Parceláveis ​​estruturados podem declarar valores padrão por campo para primitivos, String se arrays desses tipos.

    parcelable Foo {
      int numField = 42;
      String stringField = "string value";
      char charValue = 'a';
      ...
    }

No backend Java, quando os valores padrão estão ausentes, os campos são inicializados como valores zero para tipos primitivos e null para tipos não primitivos.

Em outros back-ends, os campos são inicializados com valores inicializados padrão quando os valores padrão não são definidos. Por exemplo, no back-end C++, os campos String são inicializados como uma string vazia e os campos List<T> são inicializados como um vector<T> vazio. Os campos @nullable são inicializados como campos de valor nulo.

Manipulação de erros

O sistema operacional Android fornece tipos de erros integrados para os serviços usarem ao relatar erros. Eles são usados ​​pelo binder e podem ser usados ​​por qualquer serviço que implemente uma interface do binder. Seu uso está bem documentado na definição AIDL e não requer nenhum status definido pelo usuário ou tipo de retorno.

Quando uma função AIDL relata um erro, a função pode não inicializar ou modificar os parâmetros de saída. Especificamente, os parâmetros de saída podem ser modificados se o erro ocorrer durante o unparceling ao invés de ocorrer durante o processamento da própria transação. Em geral, ao obter um erro de uma função inout , todos out , bem como o valor de retorno (que atua como um parâmetro de out em alguns back-ends), devem ser considerados em estado indefinido.

Se a interface AIDL exigir valores de erro adicionais que não são cobertos pelos tipos de erro internos, eles poderão usar o erro interno específico do serviço especial que permite a inclusão de um valor de erro específico do serviço definido pelo usuário . Esses erros específicos do serviço são normalmente definidos na interface AIDL como uma enum const int ou int -backed e não são analisados ​​pelo binder.

Em Java, os erros são mapeados para exceções, como android.os.RemoteException . Para exceções específicas de serviço, Java usa android.os.ServiceSpecificException junto com o erro definido pelo usuário.

O código nativo no Android não usa exceções. O back-end CPP usa android::binder::Status . O back-end do NDK usa ndk::ScopedAStatus . Todo método gerado pelo AIDL retorna um desses, representando o status do método. O back-end Rust usa os mesmos valores de código de exceção que o NDK, mas os converte em erros Rust nativos ( StatusCode , ExceptionCode ) antes de entregá-los ao usuário. Para erros específicos do serviço, o Status ou ScopedAStatus usa EX_SERVICE_SPECIFIC junto com o erro definido pelo usuário.

Os tipos de erro integrados podem ser encontrados nos seguintes arquivos:

Usando vários back-ends

Estas instruções são específicas para o código da plataforma Android. Esses exemplos usam um tipo definido, my.package.IFoo . Para obter instruções sobre como usar o back-end Rust, consulte o exemplo Rust AIDL na página Android Rust Patterns .

Tipos de importação

Seja o tipo definido uma interface, parcelable ou união, você pode importá-lo em Java:

    import my.package.IFoo;

Ou no back-end do CPP:

    #include <my/package/IFoo.h>

Ou no backend do NDK (observe o namespace extra aidl ):

    #include <aidl/my/package/IFoo.h>

Ou no back-end Rust:

    use my_package::aidl::my::package::IFoo;

Embora você possa importar um tipo aninhado em Java, nos backends CPP/NDK você deve incluir o cabeçalho para seu tipo raiz. Por exemplo, ao importar um tipo aninhado Bar definido em my/package/IFoo.aidl ( IFoo é o tipo raiz do arquivo) você deve incluir <my/package/IFoo.h> para o backend CPP (ou <aidl/my/package/IFoo.h> para o back-end do NDK).

Implementando serviços

Para implementar um serviço, você deve herdar da classe stub nativa. Essa classe lê comandos do driver do binder e executa os métodos que você implementa. Imagine que você tenha um arquivo AIDL como este:

    package my.package;
    interface IFoo {
        int doFoo();
    }

Em Java, você deve estender desta classe:

    import my.package.IFoo;
    public class MyFoo extends IFoo.Stub {
        @Override
        int doFoo() { ... }
    }

No back-end do CPP:

    #include <my/package/BnFoo.h>
    class MyFoo : public my::package::BnFoo {
        android::binder::Status doFoo(int32_t* out) override;
    }

No back-end do NDK (observe o namespace extra aidl ):

    #include <aidl/my/package/BnFoo.h>
    class MyFoo : public aidl::my::package::BnFoo {
        ndk::ScopedAStatus doFoo(int32_t* out) override;
    }

No back-end Rust:

    use aidl_interface_name::aidl::my::package::IFoo::{BnFoo, IFoo};
    use binder;

    /// This struct is defined to implement IRemoteService AIDL interface.
    pub struct MyFoo;

    impl Interface for MyFoo {}

    impl IFoo for MyFoo {
        fn doFoo(&self) -> binder::Result<()> {
           ...
           Ok(())
        }
    }

Cadastrando e recebendo serviços

Os serviços na plataforma Android geralmente são registrados no processo servicemanager . Além das APIs abaixo, algumas APIs verificam o serviço (o que significa que elas retornam imediatamente se o serviço não estiver disponível). Verifique a interface do servicemanager correspondente para obter detalhes exatos. Essas operações só podem ser feitas ao compilar na plataforma Android.

Em Java:

    import android.os.ServiceManager;
    // registering
    ServiceManager.addService("service-name", myService);
    // getting
    myService = IFoo.Stub.asInterface(ServiceManager.getService("service-name"));
    // waiting until service comes up (new in Android 11)
    myService = IFoo.Stub.asInterface(ServiceManager.waitForService("service-name"));
    // waiting for declared (VINTF) service to come up (new in Android 11)
    myService = IFoo.Stub.asInterface(ServiceManager.waitForDeclaredService("service-name"));

No back-end do CPP:

    #include <binder/IServiceManager.h>
    // registering
    defaultServiceManager()->addService(String16("service-name"), myService);
    // getting
    status_t err = getService<IFoo>(String16("service-name"), &myService);
    // waiting until service comes up (new in Android 11)
    myService = waitForService<IFoo>(String16("service-name"));
    // waiting for declared (VINTF) service to come up (new in Android 11)
    myService = waitForDeclaredService<IFoo>(String16("service-name"));

No back-end do NDK (observe o namespace extra aidl ):

    #include <android/binder_manager.h>
    // registering
    status_t err = AServiceManager_addService(myService->asBinder().get(), "service-name");
    // getting
    myService = IFoo::fromBinder(SpAIBinder(AServiceManager_getService("service-name")));
    // is a service declared in the VINTF manifest
    // VINTF services have the type in the interface instance name.
    bool isDeclared = AServiceManager_isDeclared("android.hardware.light.ILights/default");
    // wait until a service is available (if isDeclared or you know it's available)
    myService = IFoo::fromBinder(SpAIBinder(AServiceManager_waitForService("service-name")));

No back-end Rust:

use myfoo::MyFoo;
use binder;
use aidl_interface_name::aidl::my::package::IFoo::BnFoo;

fn main() {
    binder::ProcessState::start_thread_pool();
    // [...]
    let my_service = MyFoo;
    let my_service_binder = BnFoo::new_binder(
        my_service,
        BinderFeatures::default(),
    );
    binder::add_service("myservice", my_service_binder).expect("Failed to register service?");
    // Does not return - spawn or perform any work you mean to do before this call.
    binder::ProcessState::join_thread_pool()
}

Ligação à morte

Você pode solicitar uma notificação quando um serviço que hospeda um fichário morre. Isso pode ajudar a evitar o vazamento de proxies de retorno de chamada ou auxiliar na recuperação de erros. Faça essas chamadas em objetos de proxy de fichário.

• Em Java, use android.os.IBinder::linkToDeath .
• No back-end CPP, use android::IBinder::linkToDeath .
• No back-end do NDK, use AIBinder_linkToDeath .
• No back-end Rust, crie um objeto DeathRecipient e chame my_binder.link_to_death(&mut my_death_recipient) . Observe que, como o DeathRecipient possui o retorno de chamada, você deve manter esse objeto ativo enquanto desejar receber notificações.

Relatórios de bugs e API de depuração para serviços

Quando bugreports são executados (por exemplo, com adb bugreport ), eles coletam informações de todo o sistema para ajudar na depuração de vários problemas. Para serviços AIDL, relatórios de bugs usam dumpsys binários em todos os serviços registrados com o gerenciador de serviço para despejar suas informações no relatório de bugs. Você também pode usar dumpsys na linha de comando para obter informações de um serviço com dumpsys SERVICE [ARGS] . Nos back-ends C++ e Java, você pode controlar a ordem em que os serviços são despejados usando argumentos adicionais para addService . Você também pode usar dumpsys --pid SERVICE para obter o PID de um serviço durante a depuração.

Para adicionar saída personalizada ao seu serviço, você pode substituir o método dump em seu objeto de servidor como se estivesse implementando qualquer outro método IPC definido em um arquivo AIDL. Ao fazer isso, você deve restringir o despejo à permissão do aplicativo android.permission.DUMP ou restringir o despejo a UIDs específicos.

No back-end Java:

    @Override
    protected void dump(@NonNull FileDescriptor fd, @NonNull PrintWriter fout,
        @Nullable String[] args) {...}

No back-end do CPP:

    status_t dump(int, const android::android::Vector<android::String16>&) override;

No back-end do NDK:

    binder_status_t dump(int fd, const char** args, uint32_t numArgs) override;

No back-end Rust, ao implementar a interface, especifique o seguinte (em vez de permitir o padrão):

    fn dump(&self, mut file: &File, args: &[&CStr]) -> binder::Result<()>

Obtendo descritor de interface dinamicamente

O descritor de interface identifica o tipo de uma interface. Isso é útil ao depurar ou quando você tem um fichário desconhecido.

Em Java, você pode obter o descritor de interface com código como:

    service = /* get ahold of service object */
    ... = service.asBinder().getInterfaceDescriptor();

No back-end do CPP:

    service = /* get ahold of service object */
    ... = IInterface::asBinder(service)->getInterfaceDescriptor();

Os back-ends NDK e Rust não oferecem suporte a essa funcionalidade.

Obtendo descritor de interface estaticamente

Às vezes (como ao registrar serviços @VintfStability ), você precisa saber qual é o descritor de interface estaticamente. Em Java, você pode obter o descritor adicionando código como:

    import my.package.IFoo;
    ... IFoo.DESCRIPTOR

No back-end do CPP:

    #include <my/package/BnFoo.h>
    ... my::package::BnFoo::descriptor

No back-end do NDK (observe o namespace extra aidl ):

    #include <aidl/my/package/BnFoo.h>
    ... aidl::my::package::BnFoo::descriptor

No back-end Rust:

    aidl::my::package::BnFoo::get_descriptor()

Intervalo de enumeração

Em back-ends nativos, você pode iterar sobre os valores possíveis que um enum pode assumir. Devido a considerações de tamanho de código, isso não é suportado em Java atualmente.

Para um enum MyEnum definido em AIDL, a iteração é fornecida da seguinte maneira.

No back-end do CPP:

    ::android::enum_range<MyEnum>()

No back-end do NDK:

   ::ndk::enum_range<MyEnum>()

No back-end Rust:

    MyEnum::enum_range()

Gerenciamento de tópicos

Cada instância do libbinder em um processo mantém um threadpool. Para a maioria dos casos de uso, isso deve ser exatamente um pool de encadeamentos, compartilhado em todos os back-ends. A única exceção a isso é quando o código do fornecedor pode carregar outra cópia do libbinder para falar com /dev/vndbinder . Como isso está em um nó de fichário separado, o pool de encadeamentos não é compartilhado.

Para o backend Java, o threadpool só pode aumentar de tamanho (já que já foi iniciado):

    BinderInternal.setMaxThreads(<new larger value>);

Para o back-end CPP, as seguintes operações estão disponíveis:

    // set max threadpool count (default is 15)
    status_t err = ProcessState::self()->setThreadPoolMaxThreadCount(numThreads);
    // create threadpool
    ProcessState::self()->startThreadPool();
    // add current thread to threadpool (adds thread to max thread count)
    IPCThreadState::self()->joinThreadPool();

Da mesma forma, no back-end do NDK:

    bool success = ABinderProcess_setThreadPoolMaxThreadCount(numThreads);
    ABinderProcess_startThreadPool();
    ABinderProcess_joinThreadPool();

No back-end Rust:

    binder::ProcessState::start_thread_pool();
    binder::add_service(“myservice”, my_service_binder).expect(“Failed to register service?”);
    binder::ProcessState::join_thread_pool();