Fornecedor APEX

É possível usar o formato de arquivo APEX para empacotar e instalar módulos do SO Android de nível inferior. Ele permite a criação e instalação independentes de componentes, como serviços e bibliotecas nativas, implementações HAL, firmware, arquivos de configuração etc.

Os APEXs de fornecedores são instalados automaticamente pelo sistema de build na partição /vendor e ativados no ambiente de execução por apexd, assim como os APEXs em outras partições.

Casos de uso

Modularização das imagens de fornecedores

Os APEXs facilitam o agrupamento e a modularização naturais de implementações de recursos em imagens de fornecedores.

Quando as imagens de fornecedores são criadas como uma combinação de APNs de fornecedores criados de forma independente, os fabricantes de dispositivos podem escolher facilmente as implementações específicas do fornecedor desejadas para os dispositivos. Os fabricantes podem até mesmo criar um novo fornecedor APEX se nenhum dos APEXs fornecidos atender às necessidades ou se eles tiverem um hardware personalizado novo.

Por exemplo, um OEM pode escolher compor o dispositivo com o APEX de implementação de Wi-Fi do AOSP, o APEX de implementação de Bluetooth do SoC e um APEX de implementação de telefonia OEM personalizado.

Sem APEXs de fornecedor, uma implementação com tantas dependências entre os componentes do fornecedor requer coordenação e rastreamento cuidadosos. Ao unir todos os componentes (incluindo arquivos de configuração e bibliotecas extras) em APEXs com interfaces claramente definidas em qualquer ponto de comunicação entre recursos, os diferentes componentes se tornam intercambiáveis.

Iteração do desenvolvedor

Os APEXs do fornecedor ajudam os desenvolvedores a iterar mais rapidamente ao desenvolver módulos do fornecedor, agrupando uma implementação de recurso inteira, como o HAL do Wi-Fi, dentro de um APEX do fornecedor. Os desenvolvedores podem criar e enviar individualmente o APEX do fornecedor para testar as mudanças, em vez de recriar toda a imagem do fornecedor.

Isso simplifica e acelera o ciclo de iteração para desenvolvedores que trabalham principalmente em uma área de recurso e querem iterar apenas nessa área de recurso.

O agrupamento natural de uma área de recurso em um APEX também simplifica o processo de criação, envio e teste de mudanças para essa área. Por exemplo, a reinstalação de um APEX atualiza automaticamente todas as bibliotecas agrupadas ou arquivos de configuração incluídos no APEX.

O agrupamento de uma área de recurso em um APEX também simplifica a depuração ou a reversão quando um comportamento inadequado do dispositivo é observado. Por exemplo, se a telefonia estiver funcionando mal em um novo build, os desenvolvedores poderão tentar instalar um APEX de implementação de telefonia mais antigo em um dispositivo (sem precisar atualizar um build completo) e verificar se o comportamento correto é restaurado.

Exemplo de fluxo de trabalho:

# Build the entire device and flash. OR, obtain an already-flashed device.
source build/envsetup.sh && lunch oem_device-userdebug
m
fastboot flashall -w

# Test the device.
... testing ...

# Check previous behavior using a vendor APEX from one week ago, downloaded from
# your continuous integration build.
... download command ...
adb install <path to downloaded APEX>
adb reboot
... testing ...

# Edit and rebuild just the APEX to change and test behavior.
... edit APEX source contents ...
m <apex module name>
adb install out/<path to built APEX>
adb reboot
... testing ...

Exemplos

Noções básicas

Consulte a página principal Formato de arquivo APEX para informações genéricas sobre o APEX, incluindo requisitos do dispositivo, detalhes do formato de arquivo e etapas de instalação.

Em Android.bp, definir a propriedade vendor: true faz com que um módulo APEX seja um APEX do fornecedor.

apex {
  ..
  vendor: true,
  ..
}

Binários e bibliotecas compartilhadas

Um APEX inclui dependências transitivas dentro do payload do APEX, a menos que tenha interfaces estáveis.

As interfaces nativas estáveis para dependências APEX do fornecedor incluem cc_library com bibliotecas stubs e LLNDK. Essas dependências são excluídas do empacotamento e são registradas no manifesto do APEX. O manifesto é processado por linkerconfig para que as dependências nativas externas estejam disponíveis durante a execução.

No snippet abaixo, o APEX contém o binário (my_service) e as dependências não estáveis (arquivos *.so).

apex {
  ..
  vendor: true,
  binaries: ["my_service"],
  ..
}

No snippet a seguir, o APEX contém a biblioteca compartilhada my_standalone_libe qualquer uma das dependências não estáveis (conforme descrito acima).

apex {
  ..
  vendor: true,
  native_shared_libs: ["my_standalone_lib"],
  ..
}

Tornar o APEX menor

O APEX pode ficar maior porque agrupa dependências não estáveis. Recomendamos o uso da vinculação estática. Bibliotecas comuns, como libc++.so e libbase.so, podem ser vinculadas estaticamente a binários HAL. Criar uma dependência para fornecer uma interface estável pode ser outra opção. A dependência não será incluída no APEX.

Implementações de HAL

Para definir uma implementação do HAL, forneça os binários e as bibliotecas correspondentes dentro de um APEX do fornecedor semelhante aos exemplos abaixo:

Para encapsular totalmente a implementação do HAL, o APEX também precisa especificar todos os fragmentos e scripts de inicialização relevantes do VINTF.

Fragmentos de VINTF

Os fragmentos VINTF podem ser veiculados de um APEX do fornecedor quando estão localizados em etc/vintf do APEX.

Use a propriedade prebuilts para incorporar os fragmentos VINTF ao APEX.

apex {
  ..
  vendor: true,
  prebuilts: ["fragment.xml"],
  ..
}

prebuilt_etc {
  name: "fragment.xml",
  src: "fragment.xml",
  sub_dir: "vintf",
}

APIs de consulta

Quando fragmentos VINTF forem adicionados ao APEX, use APIs libbinder_ndk para acessar os mapeamentos de interfaces HAL e nomes APEX.

  • AServiceManager_isUpdatableViaApex("com.android.foo.IFoo/default") : true se a instância da HAL estiver definida em APEX.
  • AServiceManager_getUpdatableApexName("com.android.foo.IFoo/default", ...): pega o nome do APEX que define a instância do HAL.
  • AServiceManager_openDeclaredPassthroughHal("mapper", "instance", ...): use para abrir um HAL de passagem.

Scripts de inicialização

Os APEXs podem incluir scripts de inicialização de duas maneiras: (A) um arquivo de texto pré-criado no payload do APEX ou (B) um script de inicialização regular em /vendor/etc. É possível definir os dois para o mesmo APEX.

Script de inicialização no APEX:

prebuilt_etc {
  name: "myinit.rc",
  src: "myinit.rc"
}

apex {
  ..
  vendor: true,
  prebuilts: ["myinit.rc"],
  ..
}

Os scripts de inicialização em APEXes de fornecedores podem ter definições de service e diretivas de on <property or event>.

Verifique se uma definição service aponta para um binário no mesmo APEX. Por exemplo, o com.android.foo APEX pode definir um serviço chamado foo-service.

on foo-service /apex/com.android.foo/bin/foo
  ...

Tenha cuidado ao usar diretivas on. Como os scripts de inicialização em APEXes são analisados e executados após a ativação dos APEXes, alguns eventos ou propriedades não podem ser usados. Use apex.all.ready=true para disparar ações o mais cedo possível. Os APEXes de inicialização podem usar on init, mas não on early-init.

Firmware

Exemplo:

Incorpore o firmware em um APEX do fornecedor com o tipo de módulo prebuilt_firmware, conforme a seguir.

prebuilt_firmware {
  name: "my.bin",
  src: "path_to_prebuilt_firmware",
  vendor: true,
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.bin"],  // installed inside APEX as /etc/firmware/my.bin
  ..
}

Os módulos prebuilt_firmware são instalados no diretório <apex name>/etc/firmware do APEX. ueventd verifica os diretórios /apex/*/etc/firmware para encontrar módulos de firmware.

O file_contexts do APEX precisa rotular todas as entradas de payload de firmware corretamente para garantir que esses arquivos sejam acessíveis por ueventd no momento da execução. Normalmente, o rótulo vendor_file é suficiente. Exemplo:

(/.*)? u:object_r:vendor_file:s0

Módulos do kernel

Incorpore módulos de kernel em um APEX do fornecedor como módulos pré-criados, conforme mostrado abaixo.

prebuilt_etc {
  name: "my.ko",
  src: "my.ko",
  vendor: true,
  sub_dir: "modules"
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.ko"],  // installed inside APEX as /etc/modules/my.ko
  ..
}

O file_contexts do APEX precisa rotular corretamente todas as entradas de payload do módulo do kernel. Exemplo:

/etc/modules(/.*)? u:object_r:vendor_kernel_modules:s0

Os módulos do kernel precisam ser instalados explicitamente. O exemplo de script init abaixo na partição do fornecedor mostra a instalação via insmod:

my_init.rc:

on early-boot
  insmod /apex/myapex/etc/modules/my.ko
  ..

Sobreposições de recursos de tempo de execução

Exemplo:

Incorpore sobreposições de recursos de execução em um APEX do fornecedor usando a propriedade rros.

runtime_resource_overlay {
    name: "my_rro",
    soc_specific: true,
}


apex {
  ..
  vendor: true,
  rros: ["my_rro"],  // installed inside APEX as /overlay/my_rro.apk
  ..
}

Outros arquivos de configuração

Os APEXs de fornecedores oferecem suporte a vários outros arquivos de configuração, normalmente encontrados na partição do fornecedor como pré-criados dentro dos APEXs do fornecedor, e muitos outros estão sendo adicionados.

Exemplos:

APEXes de fornecedor de inicialização

Alguns serviços HAL, como keymint, precisam estar disponíveis antes que os APEX sejam ativados. Essas HALs geralmente definem early_hal na definição de serviço no script init. Outro exemplo é a classe animation, que geralmente é iniciada antes do evento post-fs-data. Quando esse serviço HAL inicial é empacotado no APEX do fornecedor, faça com que o "vendorBootstrap": true do APEX seja o principal para que ele possa ser ativado mais cedo. Os APEXes de inicialização só podem ser ativados no local pré-criado, como /vendor/apex, e não em /data/apex.

Propriedades do sistema

Estas são as propriedades do sistema que o framework lê para oferecer suporte a APEXes do fornecedor:

  • input_device.config_file.apex=<apex name>: quando definido, os arquivos de configuração de entrada (*.idc, *.kl e *.kcm) são pesquisados no diretório /etc/usr do APEX.
  • ro.vulkan.apex=<apex name>: quando definido, o driver Vulkan é carregado do APEX. Como o driver Vulkan é usado por HALs iniciais, torne o APEX Bootstrap APEX e configure esse namespace de linker para ficar visível.

Defina as propriedades do sistema em scripts init usando o comando setprop.

Recursos extras de desenvolvimento

Seleção do APEX na inicialização

Exemplo:

Os desenvolvedores também podem instalar várias versões de APEXs de fornecedores que compartilham o mesmo nome e chave de APEX e, em seguida, escolher qual versão será ativada durante cada inicialização usando sysprops persistentes. Para alguns casos de uso de desenvolvedores, isso pode ser mais simples do que instalar uma nova cópia do APEX usando adb install.

Exemplos de casos de uso:

  • Instalar três versões do APEX do fornecedor do HAL do Wi-Fi: as equipes de controle de qualidade podem executar testes manuais ou automatizados usando uma versão, reinicializar para outra versão e realizar os testes novamente, comparando os resultados finais.
  • Instale duas versões do APEX do fornecedor do HAL da câmera, atual e experimental. Os dogfooders podem usar a versão experimental sem fazer o download e instalar um arquivo extra, para que possam alternar facilmente.

Durante a inicialização, o apexd procura sysprops seguindo um formato específico para ativar a versão correta do APEX.

Os formatos esperados para a chave de propriedade são:

  • Bootconfig
    • Usado para definir o valor padrão em BoardConfig.mk.
    • androidboot.vendor.apex.<apex name>
  • sysprop persistente
    • Usado para mudar o valor padrão definido em um dispositivo já inicializado.
    • Substitui o valor de bootconfig, se presente.
    • persist.vendor.apex.<apex name>

O valor da propriedade precisa ser o nome de arquivo do APEX que será ativado.

// Default version.
apex {
  name: "com.oem.camera.hal.my_apex_default",
  vendor: true,
  ..
}

// Non-default version.
apex {
  name: "com.oem.camera.hal.my_apex_experimental",
  vendor: true,
  ..
}

A versão padrão também precisa ser configurada usando bootconfig em BoardConfig.mk:

# Example for APEX "com.oem.camera.hal" with the default above:
BOARD_BOOTCONFIG += \
    androidboot.vendor.apex.com.oem.camera.hal=com.oem.camera.hal.my_apex_default

Depois que o dispositivo for inicializado, mude a versão ativada definindo o sysprop persistente:

$ adb root;
$ adb shell setprop \
    persist.vendor.apex.com.oem.camera.hal \
    com.oem.camera.hal.my_apex_experimental;
$ adb reboot;

Se o dispositivo oferecer suporte à atualização do bootconfig após a atualização flash (por exemplo, com comandos fastboot oem), a alteração da propriedade bootconfig para o APEX instalado várias vezes também mudará a versão ativada na inicialização.

Para dispositivos de referência virtuais baseados no Cuttlefish, use o comando --extra_bootconfig_args para definir a propriedade bootconfig diretamente durante a inicialização. Exemplo:

launch_cvd --noresume \
  --extra_bootconfig_args "androidboot.vendor.apex.com.oem.camera.hal:=com.oem.camera.hal.my_apex_experimental";