Implementa GBL

En esta página, se explica cómo implementar el objeto binario del cargador de arranque genérico (GBL).

Requisitos del firmware de inicio

Para usar GBL, el firmware de arranque debe cumplir con los siguientes requisitos:

  • Cumplimiento con la interfaz de firmware extensible unificada (UEFI) El firmware debe implementar y usar los protocolos UEFI requeridos. El firmware también debe permitir extensiones específicas del proveedor con protocolos UEFI definidos.

  • Seguridad El firmware debe implementar todos los requisitos del inicio verificado de Android (AVB), lo que permite que GBL autentique las imágenes de inicio.

  • Modos de inicio El binario debe poder controlar varios modos de inicio, como el inicio normal, el inicio de recuperación y el inicio rápido.

  • Es el particionamiento dinámico. El firmware de arranque debe implementar la lógica de selección de ranuras para que admita la lectura de la ranura de arranque A/B correcta y sea compatible con las particiones dinámicas y los datos del usuario en super.

  • Configuración del SO El firmware debe ser capaz de modificar la línea de comandos del kernel, el árbol de dispositivos (DTB) y bootconfig con las personalizaciones del OEM necesarias para iniciar el dispositivo.

  • Carga de la VM protegida. El objeto binario debe cargar correctamente el firmware de la VM protegida previamente verificada antes del kernel de Android en presencia de VMs protegidas. Para obtener más información, consulta la secuencia de inicio de Microdroid.

  • Administración de la memoria El firmware de arranque debe admitir la API de asignación de memoria de UEFI.

Requisitos para la implementación

Para que la GBL se implemente correctamente en tu dispositivo, debes cumplir con los siguientes requisitos:

  • Tu dispositivo debe contener dos particiones FAT de 8 MB (o más grandes) llamadas android_esp_a y android_esp_b en un dispositivo de almacenamiento en bloques al que pueda acceder el SOC.

    • Un dispositivo de bloque es un dispositivo de almacenamiento que se puede leer o escribir en unidades de bloques. Entre los ejemplos, se incluyen dispositivos UFS, eMMC y tarjetas SD.
    • Se usa FAT porque es un sistema de archivos omnipresente y sencillo.
    • Te recomendamos que elijas el sistema de archivos FAT adecuado para tus necesidades entre FAT12, FAT16 y FAT32.
    • Ambas particiones son necesarias para las actualizaciones y reversiones inalámbricas (OTA) durante el período de asistencia de esta versión de Android.
    • El GBL tiene aproximadamente 2 MB sin comprimir. 8 MB es suficiente para tener en cuenta cualquier crecimiento debido a las funciones adicionales durante los próximos siete años.
    • En caso de que se actualice la GBL, debes actualizar toda la partición android_esp_${SLOT_SUFFIX}. Android OTA no admite actualizaciones solo para GBL.
    • El GUID del tipo de partición que se usa para ambas particiones FAT debe corresponder al GUID de la partición del sistema EFI C12A7328-F81F-11D2-BA4B-00A0C93EC93B.

  • La versión de GBL implementada debe ser la compilación de producción certificada más reciente de la rama de lanzamiento de GBL correspondiente. Te recomendamos que firmes la copia certificada por Google de GBL con tu solución de firma preferida y que almacenes los metadatos de firma y compilación resultantes dentro de la partición android_esp_${SLOT_SUFFIX}.

    • El certificado de GBL DEBE quedar intacto después de la firma del OEM, y no debe aplicarse ningún encabezado al archivo binario.
    • La compilación de GBL para desarrolladores se usa estrictamente con fines de desarrollo y depuración. La compilación no se puede lanzar y Google no la certificará.

  • El archivo GBL debe almacenarse en la ruta /EFI/BOOT/BOOTAA64.EFI dentro de la partición FAT.

  • Implementa los protocolos UEFI y Android UEFI necesarios para admitir GBL. La compilación de producción de GBL no se inicia si no se admiten estas interfaces.

    • EFI_BLOCK_IO_PROTOCOL o EFI_BLOCK_IO2_PROTOCOL recuperan las imágenes de arranque y las imágenes de pvmfw del disco.
    • EFI_RNG_PROTOCOL para los canarios de pila, los valores semilla de KASLR y los valores semilla de RNG
    • Servicios de asignación de memoria para asignar memoria temporal y realizar cálculos de AVB y DICE
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL proporciona una opción para implementaciones no operativas, pero GBL registra a través de este protocolo de forma predeterminada.
    • GBL_EFI_AVB_PROTOCOL accede a las claves públicas y a los índices de reversión para verificar las imágenes de arranque.
    • GBL_EFI_BOOT_CONTROL_PROTOCOL adquiere metadatos de ranuras y motivos de inicio del firmware
    • GBL_EFI_AVF_PROTOCOL genera datos de configuración de AVF a partir de la cadena de DICE

  • El firmware debe proporcionar variables de UEFI al GBL. Estas variables se deben establecer con el valor GBL_EFI_VENDOR_GUID 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830.

    • gbl_fw_api_level debe establecerse en el nivel de API del firmware de la plataforma, lo que indica el nivel de API del software del proveedor. Esta variable debe tener el mismo valor que la propiedad del sistema ro.board.api_level.

  • Los protocolos de UEFI que se recomiendan en gran medida cuando se integra GBL se documentan en GBL UEFI Protocols.

Compatibilidad con el firmware de inicio

Con las modificaciones necesarias para admitir los requisitos de la sección anterior, las siguientes implementaciones de firmware de UEFI funcionan con GBL:

  • EDK2 (Tianocore). EDK2 es una implementación de UEFI de código abierto popular. Se necesita compatibilidad con GBL para los bootloaders basados en EDK2, y la compatibilidad con UEFI ya está presente.
  • U-Boot. Un proyecto de cargador de arranque de código abierto flexible y ampliamente utilizado que está ganando compatibilidad con UEFI para el uso de GBL.
  • LittleKernel (LK). Es un cargador de arranque de código abierto que usan algunos proveedores.

Ejecuta GBL

Puedes obtener un objeto binario de GBL compilado previamente para ejecutarlo o compilar el tuyo y ejecutarlo.

Obtén y ejecuta el objeto binario de GBL

GBL se distribuye como un solo objeto binario de la app para UEFI. Puedes actualizar este objeto binario de forma independiente del firmware base del dispositivo con el mecanismo de actualización estándar de Android.

A partir de Android 16, si envías un dispositivo basado en un chipset ARM-64, te recomendamos que implementes la versión más reciente certificada por Google de GBL y la integres en tu cadena de arranque.

Para depurar esta compilación de GBL, puedes descargar cualquiera de estos artefactos para ayudarte con la depuración:

  • La tabla de símbolos usa un depurador de hardware y GDB para la compilación de GBL certificada por Google.
  • El manifiesto realiza cambios en la compilación firmada recreando esta compilación de GBL desde el código fuente con repo.
  • La compilación para desarrolladores de GBL correspondiente es útil para la puesta en marcha o la depuración menos sofisticada de un problema que afecta la compilación de producción firmada.
  • La tabla de símbolos es útil para la compilación del desarrollador de GBL con un depurador de hardware y GDB.

Para ver los archivos binarios y los símbolos certificados en todas las versiones, consulta Compilaciones de lanzamiento de GBL.

Compila GBL

Para compilar GBL, haz lo siguiente:

  1. Verifica que tengas instaladas la herramienta repo y la secuencia de arranque de Bazel:

    sudo apt install repo bazel-bootstrap

  2. Inicializa tu directorio actual para el control de código fuente con el archivo de manifiesto uefi-gbl-mainline:

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

  3. Compila la app para UEFI:

    tools/bazel run //bootable/libbootloader:gbl_efi_dist

Prueba la GBL en el dispositivo virtual de Android

  1. Ejecuta GBL dentro de Cuttlefish:

    cvd start --android_efi_loader=path_to_the_UEFI_app ...

    En lugar de iniciar Android directamente, este comando cvd start usa la app de UEFI para iniciar Android.

Cómo informar errores y comunicarse con el equipo del cargador de arranque

Para informar un error del GBL, navega al componente Android Generic Bootloader en Buganizer.

Si tienes preguntas, comunícate con el equipo de GBL y envía un correo electrónico a android-gbl@google.com.