Google is committed to advancing racial equity for Black communities. See how.

Imagens genéricas do sistema

Uma imagem genérica do sistema (GSI, na sigla em inglês) é uma imagem do sistema com configurações ajustadas para dispositivos Android. Ela é considerada uma implementação de Android puro com código do Android Open Source Project (AOSP) não modificado que qualquer dispositivo com Android 8.1 ou versões posteriores pode executar.

As GSIs são usadas para executar testes de VTS e CTS-on-GSI. A imagem do sistema de um dispositivo Android é substituída por uma GSI e testada com o Teste de fornecedor (VTS, na sigla em inglês) e o Teste de compatibilidade (CTS, na sigla em inglês) para garantir que o dispositivo implemente as interfaces do fornecedor corretamente com a versão mais recente do Android.

Para começar a usar GSIs, leia as seções a seguir para ver mais detalhes sobre as configurações de GSI (e as variações permitidas), os tipos (GSI Android e GSI legada) e os binários do fornecedor e dependências de VNDK. Quando estiver tudo pronto para usar uma GSI, faça o download da GSI e compile-a para seu dispositivo de destino. Depois, atualize a GSI para um dispositivo Android.

Configuração e variações de GSI

A GSI atual do Android tem a seguinte configuração:

  • Treble. A GSI inclui compatibilidade total com as modificações de arquitetura baseadas em HIDL (também conhecidas como Treble) introduzidas no Android 8.0, incluindo compatibilidade com as interfaces HIDL. Você pode usar uma GSI em qualquer dispositivo Android que use interfaces de fornecedores HIDL. Para ver mais detalhes, consulte Recursos de arquitetura.
  • Verificação de inicialização. A GSI não inclui uma solução para verificação de inicialização (como vboot 1.0 ou AVB). Para atualizar a GSI em um dispositivo que seja lançado com o Android 9 ou versão anterior, é necessário que o dispositivo tenha um método para desativar a verificação de inicialização.
  • Sistemas de arquivos. A GSI usa o sistema de arquivos ext4.
  • Layout de partição. A GSI usa o layout de partição sistema como raiz.

A GSI atual do Android inclui as seguintes variações principais:

  • Arquitetura da CPU. Compatível com diferentes instruções de CPU (ARM, x86 etc.) e quantidades de bits de CPU (32 ou 64 bits).

Destinos de GSI para testes de conformidade com o Treble

A GSI usada para teste de conformidade é determinada pela versão do Android com que o dispositivo é lançado.

Tipo de dispositivo Versão de destino
Dispositivos lançados com o Android 10 aosp_$arch-user
Dispositivos lançados com o Android 9 aosp_$arch-userdebug
Dispositivos lançados com o Android 8.0 ou o Android 8.1 aosp_$arch_ab-userdebug

Todas as GSIs são criadas a partir do codebase do Android 10 e cada arquitetura de CPU tem um binário GSI correspondente. Veja a lista de destinos de criação em Como criar GSIs.

Mudanças na GSI do Android 10

Os dispositivos lançados com o Android 10 precisam usar as GSIs dessa versão do sistema para testes de conformidade. Isso inclui as seguintes mudanças importantes das GSIs anteriores:

  • Versão do usuário. A GSI tem uma versão do usuário a partir do Android 10. No Android 10, a GSI de versão do usuário pode ser usada em testes de conformidade CTS-on-GSI/VTS. Consulte o Teste VTS com Debid Ramdisk para ver mais detalhes.
  • Formato não esparso. GSI com destinos aosp_$arch são criadas com formato não esparso. Você pode usar img2simg para converter uma GSI não esparsa em formato esparso, se necessário.
  • Sistema como raiz. O destino de criação da GSI legada chamado aosp_$arch_a foi descontinuado. Para os dispositivos que fizeram upgrade do Android 8 ou 8.1 para o Android 10 com ramdisk e que não têm o sistema como raiz, use a GSI legada aosp_$arch_ab. O init com upgrade no ramdisk é compatível com system.img de OEM com layout de sistema como raiz.

Para testar os dispositivos com o Android 9 ou 10 com CTS-on-GSI, use os destinos de criação da GSI do Android.

GSI legada

GSIs legadas nomeadas com o sufixo _ab (por exemplo, aosp_arm64_ab). Essas GSIs são criadas a partir da árvore de origem do Android 10, mas contêm as seguintes configurações compatíveis com versões anteriores para dispositivos que fizeram upgrade do Android 8 ou 8.1:

  • Espaço do usuário de 32 bits + interface Binder de 32 bits. As GSIs de 32 bits podem continuar usando a interface Binder de 32 bits.
  • VNDK do 8.1. Os dispositivos podem usar o VNDK do 8.1 incluso.
  • Diretórios de ativação. Alguns dispositivos legados usam diretórios como pontos de montagem (por exemplo, /bluetooth, /firmware/radio e /persist).

Para testar os dispositivos lançados com o Android 8 ou 8.1 com CTS-on-GSI, use os destinos de criação de GSI legada.

Mudanças na GSI do Android 9

As GSIs do Android 9 incluem as seguintes mudanças importantes das GSIs anteriores:

  • Combinação de GSI e emulador. As GSIs são criadas com base nas imagens do sistema de produtos emuladores, como aosp_arm64 e aosp_x86.
  • Sistema como raiz. Nas versões anteriores do Android, os dispositivos que não eram compatíveis com atualizações A/B podiam ativar a imagem do sistema no diretório /system. No Android 9, a raiz da imagem do sistema é ativada como a raiz do dispositivo.
  • Interface Binder de 64 bits. No Android 8.x, as GSIs de 32 bits usavam a interface Binder de 32 bits. O Android 9 não é compatível com a interface Binder de 32 bits, então GSIs de 32 bits e de 64 bits usam a interface Binder de 64 bits.
  • Obrigatoriedade do VNDK. No Android 8.1, o VNDK era opcional. A partir do Android 9, o VNDK é obrigatório. Portanto, BOARD_VNDK_VERSION precisa ser definido.
  • Propriedade do sistema compatível. O Android 9 ativa a verificação de acesso para propriedades de sistema compatíveis (PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true).

Alterações no Keymaster do Android 9

Nas versões anteriores do Android, os dispositivos que implementavam o Keymaster 3 ou versões anteriores precisavam verificar se as informações de versão (ro.build.version.release e ro.build.version.security_patch) relatadas pelo sistema em execução correspondiam às informações de versão relatadas pelo carregador de inicialização. Essa informação geralmente vinha do cabeçalho da imagem de inicialização.

No Android 9 e versões posteriores, esse requisito foi modificado para permitir que os fornecedores inicializem uma GSI. Especificamente, o Keymaster não pode mais realizar a verificação porque as informações de versão relatadas pela GSI podem não corresponder às informações relatadas pelo carregador de inicialização do fornecedor. No caso de dispositivos que implementam o Keymaster 3 ou versões anteriores, os fornecedores precisam modificar a implementação do Keymaster para ignorar a verificação (ou fazer upgrade para o Keymaster 4). Para ver mais detalhes sobre o Keymaster, consulte Armazenamento de chaves protegido por hardware.

Binários do fornecedor e dependências do VNDK

Os dispositivos que passam por upgrade para o Android 10 têm diferentes caminhos de upgrade, dependendo da versão dos binários do fornecedor em uso no dispositivo e das configurações relacionadas ao VNDK usadas para criar os dispositivos. A tabela a seguir resume a compatibilidade da GSI legada com dispositivos que passaram por upgrade:

Caso de uso Versão dos
binários
do fornecedor
BOARD_VNDK_VERSION Versão dos binários do sistema
da GSI legada
Compatível com a GSI legada
0 8.0 (qualquer) 10 Não
1 8.1 (vazio) 10 Não
2 8.1 current 10 Sim
3 10 current 10 Sim

O caso de uso compatível mais comum é o 2, em que a GSI legada é compatível com dispositivos que executam o Android 8.1 e foram criados com BOARD_VNDK_VERSION definido como current.

O caso 1 não é compatível. Nesses casos, as GSIs legadas NÃO são compatíveis com dispositivos que executam o Android 8.1 em que BOARD_VNDK_VERSION foi omitido da versão. Não é possível oferecer compatibilidade a esses dispositivos, porque seus binários de fornecedores dependem de bibliotecas compartilhadas do Android 8.1 não VNDK, que não estão incluídas em GSIs legadas. Para tornar esses dispositivos compatíveis com a GSI legada, é necessário seguir um destes procedimentos:

  • Ativar BOARD_VNDK_VERSION sem BOARD_VNDK_RUNTIME_DISABLE (caso de uso 2)

    OU

  • Adaptar/fazer upgrade dos binários do fornecedor para depender de bibliotecas compartilhadas do Android 10 (caso de uso 3).

Download de GSIs

Você pode fazer o download de GSIs pré-criadas pelo site de integração contínua (CI) do AOSP, em ci.android.com (link em inglês). Se o tipo de GSI para sua plataforma de hardware não estiver disponível para download, consulte a seção a seguir para ver mais detalhes sobre como criar GSIs para destinos específicos.

Como criar GSIs

A partir do Android 9, cada versão do Android tem uma ramificação de GSI chamada DESSERT-gsi no AOSP. Por exemplo, android10-gsi é a ramificação de GSI no Android 10. As ramificações de GSI incluem o conteúdo do Android com todos os patches de segurança e de GSI aplicados.

Para criar uma GSI, configure a árvore de origem do Android fazendo o download de uma ramificação de GSI e escolhendo um destino de criação da GSI. Use as tabelas de destino de criação abaixo para determinar a versão correta da GSI para seu dispositivo. Quando a criação for concluída, a GSI se tornará a imagem do sistema (ou seja, system.img) e aparecerá na pasta de saída out/target/product/generic_arm64. A criação também gera vbmeta.img, que você pode usar para desativar a verificação de inicialização nos dispositivos por meio da Inicialização verificada do Android.

Por exemplo, para gerar o destino de criação aosp_arm64-userdebug da GSI legada na ramificação de GSI android10-gsi, execute os seguintes comandos:

$ repo init -u https://android.googlesource.com/platform/manifest -b android10-gsi
$ repo sync -cq
$ source build/envsetup.sh
$ lunch aosp_arm64-userdebug
$ make -j4

Destinos de criação de GSI do Android

Os destinos de criação de GSI a seguir são destinados a dispositivos lançados com Android 9 ou versões posteriores. Devido à redução nas variações entre as arquiteturas, o Android 10 inclui apenas quatro produtos GSI.

Nome da GSI Arquitetura da CPU Quantidade de bits da interface Binder Sistema como raiz Versão de destino
aosp_arm ARM 64 Y aosp_arm-user
aosp_arm-userdebug
aosp_arm64 ARM64 64 Y aosp_arm64-user
aosp_arm64-userdebug
aosp_x86 x86 64 Y aosp_x86-user
aosp_x86-userdebug
aosp_x86_64 x86-64 64 Y aosp_x86_64-user
aosp_x86_64-userdebug

Destinos de criação de GSI legada

Os destinos de criação da GSI legada a seguir são para dispositivos que fizeram upgrade do Android 8.0 ou 8.1 para o Android 10. Os nomes das GSI legadas incluem o sufixo _ab para diferenciá-los dos nomes da GSI do Android 10.

Nome da GSI Arquitetura da CPU Quantidade de bits da interface Binder Sistema como raiz Versão de destino
aosp_arm_ab ARM 32 Y aosp_arm_ab-userdebug
aosp_arm_64b_ab ARM 64 Y aosp_arm_64b_ab-userdebug
aosp_arm64_ab ARM64 64 Y aosp_arm64_ab-userdebug
aosp_x86_ab x86 32 Y aosp_x86_ab-userdebug
aosp_x86_64_ab x86-64 64 Y aosp_x86_64_ab-userdebug

Requisitos de atualização de GSIs com flash

Os dispositivos Android podem ter designs diferentes. Portanto, não existe um comando ou um conjunto de instruções genéricos para aplicar a GSI a todos os dispositivos. Verifique com o fabricante do dispositivo Android se há instruções explícitas de atualização. Siga estas etapas como uma diretriz geral:

  1. Verifique se o dispositivo tem as seguintes características:
    • A conformidade com o Treble;
    • Um método para desbloquear dispositivos, para que eles possam ser atualizados usando fastboot;
    • Um método para desativar a verificação de inicialização (por exemplo, vboot 1.0 ou AVB)
    • Um estado desbloqueado para torná-lo atualizável por meio de fastboot. Para garantir que você tem a versão mais recente do fastboot, crie-o a partir da árvore de origem do Android.
  2. Desative a verificação de inicialização.
  3. Limpe a partição atual do sistema e, em seguida, atualize a GSI com flash para a partição.
  4. Exclua permanentemente os dados do usuário e limpe outras partições necessárias (por exemplo, dados do usuário e partições do sistema).
  5. Reinicialize o dispositivo.

Por exemplo, para atualizar uma GSI com flash para qualquer dispositivo Pixel:

  1. Inicialize no modo fastboot e desbloqueie o carregador de inicialização. Os dispositivos que têm compatibilidade com fastbootd também precisam ser inicializados com fastbootd por:
    $ fastboot reboot fastboot
  2. Desative a verificação de inicialização do Android (AVB, na sigla em inglês) atualizando com flash o vbmeta.img:
    $ fastboot --disable-verification flash vbmeta vbmeta.img
  3. Limpe e atualize a GSI com flash para a partição do sistema:
    $ fastboot erase system
    $ fastboot flash system system.img
    
  4. Exclua permanentemente os dados do usuário e limpe outras partições necessárias (por exemplo, dados do usuário e partições do sistema).
    $ fastboot -w
  5. Reinicialize:
    $ fastboot reboot
Em dispositivos Android 10 com partições de sistema menores, a seguinte mensagem de erro pode aparecer ao atualizar a GSI:
    Resizing 'system_a'    FAILED (remote: 'Not enough space to resize partition')
    fastboot: error: Command failed
Use o comando a seguir para excluir a partição do produto e liberar espaço para a partição do sistema. Isso fornece espaço extra para atualizar a GSI:
$ fastboot delete-logical-partition product_a
O postfix _a precisa corresponder ao ID do slot da partição do sistema, como system_a nesse exemplo.

Como contribuir com GSIs

O Android aceita de braços abertos suas contribuições para o desenvolvimento de GSI. Você pode participar e ajudar na melhoria da GSI da seguinte forma:

  • Criando um patch de GSI. DESSERT-gsi não é um branch de desenvolvimento e aceita apenas seleções do branch master do AOSP. Por esse motivo, você precisa fazer o seguinte para enviar um patch de GSI:
    1. Enviar o patch para a ramificação master do AOSP.
    2. Selecionar o patch para DESSERT-gsi.
    3. Informar um bug para que a seleção seja analisada.
  • Informando bugs da GSI ou fazendo outras sugestões. Leia as instruções em Como informar bugs e depois procure ou registre bugs de GSI (link em inglês).

Dicas

Como mudar o modo da barra de navegação usando adb

Ao inicializar com uma GSI, o modo da barra de navegação é configurado pelo fornecedor. É possível mudar o modo da barra de navegação executando o seguinte comando adb no momento da execução.

adb exec-out cmd overlay enable-exclusive com.android.internal.systemui.navbar.mode

Em que mode pode ser threebutton, twobutton, gestural e assim por diante.