Implantar o GBL

Nesta página, explicamos como implantar o binário do carregador de inicialização genérico (GBL, na sigla em inglês).

Requisitos do firmware de inicialização

Para usar o GBL, o firmware de inicialização precisa atender aos seguintes requisitos:

• Conformidade com a Unified Extensible Firmware Interface (UEFI). O firmware precisa implementar e usar os protocolos UEFI necessários. Ele também precisa permitir extensões específicas do fornecedor usando protocolos UEFI definidos.

• Segurança. O firmware precisa implementar todos os requisitos da inicialização verificada do Android (AVB, na sigla em inglês), permitindo que o GBL autentique imagens de inicialização.

• Modos de inicialização. O binário precisa ser capaz de processar vários modos de inicialização, como inicialização normal, de recuperação e fastboot.

• Particionamento dinâmico. O firmware de inicialização precisa implementar a lógica de seleção de slot para oferecer suporte à leitura do slot de inicialização A/B correto e ser compatível com partições dinâmicas e dados do usuário no super.

• Configuração do SO. O firmware precisa ser capaz de modificar a linha de comando do kernel, a árvore de dispositivos (DTB, na sigla em inglês) e a configuração de inicialização com as personalizações do OEM necessárias para inicializar o dispositivo.

• Carregamento de VMs protegidas. O binário precisa carregar corretamente o firmware de VM protegida pré-verificado antes do kernel do Android na presença de VMs protegidas. Para mais informações, consulte Sequência de inicialização do Microdroid.

• Gerenciamento de memória. O firmware de inicialização precisa oferecer suporte à API de alocação de memória UEFI.

Requisitos de implementação

Para que o GBL seja implementado corretamente no dispositivo, você precisa atender aos seguintes requisitos:

• O dispositivo precisa conter duas partições FAT de 8 MB (ou mais) chamadas android_esp_a e android_esp_b em um dispositivo de bloco acessível pelo SOC.

  • Um dispositivo de bloco é um dispositivo de armazenamento que pode ser lido ou gravado em unidades de blocos. Exemplos incluem dispositivos UFS, eMMC e cartão SD.
  • O FAT é usado porque é um sistema de arquivos onipresente e simples.
  • Recomendamos que você escolha o sistema de arquivos FAT adequado às suas necessidades entre FAT12, FAT16 e FAT32.
  • As duas partições são necessárias para atualizações e rollbacks over-the-air (OTA) durante a janela de suporte dessa versão do Android.
  • O GBL tem aproximadamente 2 MB descompactados. 8 MB são suficientes para considerar qualquer crescimento devido a recursos adicionais nos próximos sete anos.
  • No caso de uma atualização do GBL, é necessário atualizar toda a partição android_esp_${SLOT_SUFFIX}. Uma atualização somente do GBL não é compatível com o Android OTA.
  • O GUID do tipo de partição usado para as duas partições FAT precisa corresponder ao GUID da partição do sistema EFI C12A7328-F81F-11D2-BA4B-00A0C93EC93B.

• A versão do GBL implantada precisa ser a versão de produção certificada mais recente do branch de lançamento do GBL correspondente. Recomendamos que você assine a cópia certificada pelo Google do GBL usando a solução de assinatura preferida e armazene a versão resultante e os metadados de assinatura na partição android_esp_${SLOT_SUFFIX}.

  • O certificado GBL PRECISA ser deixado intacto pela assinatura do OEM, e não pode haver um cabeçalho aplicado ao binário.
  • A versão do GBL para desenvolvedores é usada estritamente para fins de desenvolvimento e depuração. A versão não pode ser enviada e não será certificada pelo Google.

• O GBL precisa ser armazenado no caminho /EFI/BOOT/BOOTAA64.EFI na partição FAT.

• Implemente os protocolos UEFI e Android UEFI necessários para oferecer suporte ao GBL. A versão de produção do GBL não é inicializada se essas interfaces não forem compatíveis.

  • EFI_BLOCK_IO_PROTOCOL ou EFI_BLOCK_IO2_PROTOCOL busca as imagens de inicialização e pvmfw do disco
  • EFI_RNG_PROTOCOL para canários de pilha, sementes KASLR e sementes RNG
  • Serviços de alocação de memória para alocação de memória temporária para fazer cálculos de AVB e DICE
  • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL oferece uma opção para implementações sem operação, mas o GBL registra esse protocolo por padrão
  • GBL_EFI_AVB_PROTOCOL acessa chaves públicas e índices de rollback para verificar imagens de inicialização
  • GBL_EFI_BOOT_CONTROL_PROTOCOL adquire metadados de slot e motivos de inicialização do firmware
  • GBL_EFI_AVF_PROTOCOL gera dados de configuração AVF da cadeia DICE

• O firmware precisa fornecer variáveis UEFI para o GBL. Essas variáveis precisam ser definidas com o valor GBL_EFI_VENDOR_GUID 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830.

  • gbl_fw_api_level precisa ser definido como o nível da API do firmware da plataforma, indicando o nível da API do software do fornecedor. Essa variável precisa ter o mesmo valor da propriedade do sistema ro.board.api_level.

• Os protocolos UEFI que são altamente recomendados ao integrar o GBL estão documentados em Protocolos UEFI do GBL.

Suporte ao firmware de inicialização

Com as modificações necessárias para oferecer suporte aos requisitos na seção anterior, as seguintes implementações de firmware UEFI funcionam com o GBL:

• EDK2 (Tianocore). Um EDK2 é uma implementação UEFI de código aberto popular. O suporte ao GBL é necessário para carregadores de inicialização baseados em EDK2, e o suporte a UEFI já está presente.
• U-Boot. Um projeto de carregador de inicialização de código aberto flexível e amplamente usado que está ganhando compatibilidade com UEFI para uso do GBL.
• LittleKernel (LK). Um carregador de inicialização de código aberto usado por alguns fornecedores.

Executar o GBL

Você pode receber um binário GBL pré-criado para executar ou criar seu próprio e executá-lo.

Receber e executar o binário GBL

O GBL é distribuído como um único binário de app UEFI. É possível atualizar esse binário de forma independente do firmware de base do dispositivo usando o mecanismo de atualização padrão do Android.

A partir do Android 16, se você enviar um dispositivo baseado no chipset ARM-64, recomendamos que implante a versão mais recente certificada pelo Google do GBL e a integre à sua cadeia de inicialização.

Para depurar essa versão do GBL, você pode baixar qualquer um desses artefatos para ajudar na depuração:

• A tabela de símbolos usa um depurador de hardware e o GDB para a versão do GBL certificada pelo Google.
• O manifesto faz mudanças na versão assinada recriando essa versão do GBL da origem usando repo.
• A versão do GBL para desenvolvedores correspondente é útil para a inicialização ou uma depuração menos sofisticada de um problema que afeta a versão de produção assinada.
• A tabela de símbolos é útil para a versão do GBL para desenvolvedores com um depurador de hardware e o GDB.

Criar o GBL

Para criar o GBL:

1. Verifique se você tem a ferramenta repo e o bootstrap do Bazel instalados:

   sudo apt install repo bazel-bootstrap
   

2. Inicialize o diretório atual para controle de origem usando o arquivo de manifesto uefi-gbl-mainline:

   repo init -u https://android.googlesource.com/kernel/manifest -b uefi-gbl-mainline
   repo sync -j16
   

3. Crie o app UEFI:

   tools/bazel run //bootable/libbootloader:gbl_efi_dist
   

Testar o GBL no dispositivo virtual Android

1. Execute o GBL no Cuttlefish:

   cvd start --android_efi_loader=path_to_the_UEFI_app ...
   

   Em vez de inicializar o Android diretamente, esse comando cvd start usa o app UEFI para inicializar o Android.

Informar bugs e entrar em contato com a equipe do carregador de inicialização

Para informar um bug do GBL, acesse o componente do carregador de inicialização genérico do Android no Buganizer.

Se tiver dúvidas, entre em contato com a equipe do GBL. Envie um e-mail para android-gbl@google.com.