Imagens genéricas do sistema

Uma imagem genérica do sistema (GSI) tem 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 9 ou versões mais recentes 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 Vendor Test Suite (VTS, na sigla em inglês) e o Conjunto de teste de compatibilidade (CTS) 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 abaixo e veja mais detalhes sobre os tipos e as configurações de GSI (e as variações permitidas). Quando estiver tudo pronto, faça o download e crie a GSI para o dispositivo de destino. Em seguida, atualize a GSI para um dispositivo Android.

Configuração e variações de GSI

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

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

  • 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 Destino de build
Dispositivos lançados com o Android 12 gsi_$arch-user (Assinado)
Dispositivos lançados com o Android 11 gsi_$arch-user (Assinado)
Dispositivos lançados com o Android 10 gsi_$arch-user (Assinado)
Dispositivos lançados com o Android 9 gsi_$arch-userdebug

Todas as GSIs são criadas usando a base de código do Android 12, e cada arquitetura de CPU tem um binário GSI correspondente. Veja a lista de destinos de build em Como criar GSIs.

Mudanças na GSI do Android 12

Os dispositivos lançados ou atualizados para o Android 12 precisam usar as GSIs dessa versão do sistema em testes de conformidade. Isso inclui estas mudanças importantes das GSIs anteriores:

  • Nome do destino. O nome do destino da GSI para testes de conformidade mudou para gsi_$arch. A GSI com o nome do destino aosp_$arch foi mantida para o uso de desenvolvedores de apps Android. O plano de teste CTS-on-GSI também foi reduzido para testar a interface de fornecedores.
  • A GSI legada vai ser desativada gradualmente. A GSI 12 remove as soluções alternativas que acomodam dispositivos com Android 8.0 ou 8.1 que não estão em conformidade total com o Treble.
  • Userdebug SEPolicy. A GSI gsi_$arch contém userdebug_plat_sepolicy.cil. Ao atualizar a vendor_boot-debug.img ou boot-debug.img específicas do OEM, o /system/bin/init carrega a userdebug_plat_sepolicy.cil da system.img da GSI. Consulte Teste VTS com ramdisk de depuração para ver mais detalhes.

Mudanças na GSI do Android 11

Os dispositivos lançados ou atualizados para o Android 11 precisam usar as GSIs dessa versão do sistema em testes de conformidade. Isso inclui estas mudanças importantes das GSIs anteriores:

  • Conteúdo do system_ext. O Android 11 define uma nova partição system_ext. A GSI coloca o conteúdo da extensão do sistema na pasta system/system_ext.
  • APEXs. A GSI contém APEXs nivelados e compactados. A propriedade do sistema ro.apex.updatable escolhe qual deles usar na partição do fornecedor durante a execução. Veja mais detalhes em Como configurar o sistema para oferecer suporte a atualizações APEX.

Mudanças na GSI do Android 10

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

  • Build do usuário. A GSI tem uma versão do usuário a partir do Android 10. No Android 10, a GSI do build do usuário pode ser usada em testes de conformidade CTS-on-GSI/VTS. Consulte Teste VTS com ramdisk de depuração 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. A init com upgrade no ramdisk oferece suporte a system.img de OEM com layout de sistema como raiz.
  • Verificação de inicialização. Ao usar a GSI, você só precisa desbloquear o dispositivo. Não é necessário desativar a verificação de inicialização.

Mudanças na GSI do Android 9

Os dispositivos lançados ou atualizados para o Android 9 precisam usar as GSIs dessa versão do sistema em testes de conformidade. Isso inclui estas mudanças importantes das GSIs anteriores:

  • Mescla 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 mais recentes, 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.

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. Se o tipo de GSI para sua plataforma de hardware não estiver disponível para download, consulte a seção a seguir e veja 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, android12-gsi é a ramificação de GSI no Android 12. 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.

Por exemplo, para criar o destino de build gsi_arm64-userdebug da GSI legada na ramificação de GSI android12-gsi, execute estes comandos: 

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

Destinos de build de GSI do Android

Os destinos de build de GSI abaixo são para dispositivos lançados com Android 9 ou versões mais recentes.

Nome da GSI Arquitetura da CPU Quantidade de bits da interface Binder Sistema como raiz Destino de build
gsi_arm ARM 64 Y gsi_arm-user
gsi_arm-userdebug
gsi_arm64 ARM64 64 Y gsi_arm64-user
gsi_arm64-userdebug
gsi_x86 x86 64 Y gsi_x86-user
gsi_x86-userdebug
gsi_x86_64 x86-64 64 Y gsi_x86_64-user
gsi_x86_64-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 estado desbloqueado que o torna atualizável usando fastboot. Para garantir que você tem a versão mais recente do fastboot, crie-o usando a árvore de origem do Android.
  2. Limpe a partição atual do sistema e, em seguida, atualize a GSI com flash para a partição.
  3. 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).
  4. Reinicialize o dispositivo.

Por exemplo, para atualizar uma GSI para qualquer dispositivo Pixel, faça o seguinte:

  1. Inicialize no modo fastboot e desbloqueie o carregador de inicialização.
  2. Os dispositivos que têm suporte a fastbootd também precisam ser inicializados com fastbootd usando: 
    $ fastboot reboot fastboot
  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 ou mais recentes com partições de sistema menores, a mensagem de erro abaixo pode aparecer durante a atualização da GSI: 
    Resizing 'system_a'    FAILED (remote: 'Not enough space to resize partition')
    fastboot: error: Command failed
Use o comando abaixo a fim de 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 é uma ramificação 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.