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, inicialização de recuperação e fastboot.

  • Particionamento dinâmico. O firmware de inicialização precisa implementar a lógica de seleção de slot para suportar a leitura do slot de inicialização A/B correto e ser 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 8 MB (ou mais) chamadas android_esp_a e android_esp_b em um dispositivo de transferência por blocos acessível pelo SOC.

    • Um dispositivo de transferência por blocos é 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. 8 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 dentro da partição FAT.

  • 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 a 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 a 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.

Registrar bugs e entrar em contato com a equipe do bootloader

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.