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 de 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. O firmware 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 rápida.

  • Particionamento dinâmico. O firmware de inicialização precisa implementar a lógica de seleção de slot para que ele possa ler o slot de inicialização A/B correto e seja compatível com partições dinâmicas e dados do usuário em super.

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

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

  • Gerenciamento de memória. O firmware de inicialização precisa ser compatível com a API de alocação de memória UEFI.

Requisitos de implementação

Para que a GBL seja implementada corretamente no seu dispositivo, é necessário atender aos seguintes requisitos:

  • O dispositivo precisa ter duas partições FAT de 4 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. Por exemplo, dispositivos UFS, eMMC e cartão SD.
    • O FAT é usado porque é um sistema de arquivos simples e onipresente.
    • 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 OTA durante o período de suporte dessa versão do Android.
    • O GBL tem aproximadamente 2 MB descompactados. 4 MB são suficientes para considerar qualquer crescimento devido a recursos adicionais nos próximos sete anos.
    • Em caso de atualização da GBL, é necessário atualizar toda a partição android_esp_${SLOT_SUFFIX}. Uma atualização somente GBL não é compatível com a OTA do Android.
    • 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 o build de produção certificado mais recente da ramificação de lançamento correspondente do GBL. Recomendamos que você assine a cópia certificada pelo Google da GBL usando sua solução de assinatura preferida e armazene os metadados de build e assinatura resultantes 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 build GBL para desenvolvedores é usada estritamente para fins de desenvolvimento e depuração. O build não pode ser enviado e não será certificado pelo Google.

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

  • Implemente os protocolos UEFI e Android UEFI necessários para oferecer suporte ao GBL. O build de produção do GBL não é inicializado 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, seeds de KASLR e seeds de 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 nulas, mas o GBL registra usando esse protocolo por padrão.
    • 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 do AVF da cadeia DICE.

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

Suporte para firmware de inicialização

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

  • EDK2 (Tianocore). O EDK2 é uma implementação UEFI de código aberto muito usada. O suporte a 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 GBL

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

Extrair e executar o binário do GBL

O GBL é distribuído como um único binário de app UEFI. É possível atualizar esse binário de forma independente do firmware 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 implantar a versão mais recente certificada pelo Google do GBL e integrá-la à sua cadeia de inicialização.

Criar 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, o comando cvd start usa o app UEFI para inicializar o Android.

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

Para informar um bug do GBL, acesse o componente Android Generic Bootloader no Buganizer.

Em caso de dúvidas, entre em contato com a equipe da GBL enviando um e-mail para android-gbl@google.com.