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 inicio debe cumplir con los siguientes requisitos:

  • Cumplimiento de 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 la GBL autentique las imágenes de arranque.

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

  • Particionamiento dinámico. El firmware de inicio debe implementar la lógica de selección de ranuras para que admita la lectura de la ranura de inicio 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 poder modificar la línea de comandos del kernel, el árbol de dispositivos (DTB) y la configuración de inicio con las personalizaciones del OEM necesarias para iniciar el dispositivo.

  • Cargando la VM protegida. El objeto binario debe cargar correctamente el firmware de la VM protegida preverificado 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 inicio debe admitir la API de asignación de memoria de UEFI.

Requisitos para la implementación

Para que 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) llamadas android_esp_a y android_esp_b en un dispositivo de almacenamiento en bloques al que pueda acceder el SOC.

    • Un dispositivo de almacenamiento en bloques es un dispositivo de almacenamiento en el que se puede leer o escribir en unidades de bloques. Algunos ejemplos son los dispositivos UFS, eMMC y de tarjeta 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 inalámbricas (OTA) y las reversiones durante el período de asistencia de esta versión de Android.
    • El GBL tiene un tamaño aproximado de 2 MB sin comprimir. 8 MB es suficiente para tener en cuenta cualquier crecimiento debido a funciones adicionales durante los próximos siete años.
    • En caso de una actualización de GBL, debes actualizar toda la partición android_esp_${SLOT_SUFFIX}. La actualización inalámbrica de Android no admite una actualización solo de 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 de GBL certificada por Google con tu solución de firma preferida y que almacenes la compilación resultante y los metadatos de la firma dentro de la partición android_esp_${SLOT_SUFFIX}.

    • La firma del OEM DEBE dejar intacto el certificado de GBL Y no debe haber ningún encabezado aplicado al objeto binario.
    • La compilación de GBL para desarrolladores se usa estrictamente con fines de desarrollo y depuración. La compilación no se puede enviar y Google no la certificará.
  • GBL debe almacenarse en la ruta de acceso /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 recupera las imágenes de arranque y las imágenes de pvmfw del disco.
    • EFI_RNG_PROTOCOL para canarios de pila, valores de inicialización de KASLR y valores de inicialización de RNG
    • Servicios de asignación de memoria para asignar memoria temporal para realizar cálculos de AVB y DICE
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL proporciona una opción para las implementaciones sin operaciones, 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 a GBL. Estas variables se deben configurar con el valor 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830 de GBL_EFI_VENDOR_GUID, y deben permanecer como de solo lectura y protegidas contra alteraciones cuando el bootloader esté bloqueado.

    • 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.
    • gbl_fw_product_first_api_level debe establecerse en el nivel de API del SDK con el que se envió el dispositivo y debe permanecer fijo durante toda la vida útil del producto, independientemente de las actualizaciones de software. Esta variable debe tener el mismo valor que la propiedad del sistema ro.product.first_api_level.
  • Los protocolos UEFI que se recomiendan cuando se integra GBL se documentan en Protocolos UEFI de GBL.

Compatibilidad con el firmware de inicio

Con las modificaciones necesarias para admitir los requisitos de la sección anterior, las siguientes implementaciones de firmware 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. Es un proyecto de cargador de arranque de código abierto flexible y de uso generalizado que está ganando compatibilidad con UEFI para el uso de GBL.
  • LittleKernel (LK). Es un bootloader 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 único objeto binario de app de 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 el 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 inicio.

Para depurar esta compilación de GBL, puedes descargar cualquiera de estos artefactos para ayudar en 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 la fuente con repo.
  • La compilación para desarrolladores de GBL correspondiente es útil para la puesta en marcha o una depuración menos sofisticada de un problema que afecta a la compilación de producción firmada.
  • La tabla de símbolos es útil para la compilación de desarrolladores de GBL con un depurador de hardware y GDB.

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

Crea un GBL

Para compilar GBL, haz lo siguiente:

  1. Verifica que tengas instaladas la herramienta de repo y la inicialización de Bazel:

    sudo apt install repo bazel-bootstrap
    
  2. Inicializa tu directorio actual para controlar el 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 de UEFI:

    tools/bazel run //bootable/libbootloader:gbl_efi_dist
    

Prueba la GBL en el dispositivo virtual de Android

  1. Ejecuta GBL en 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.

Informa errores y comunícate con el equipo del bootloader

Para informar un error del GBL, navega al componente del cargador de arranque genérico de Android en Buganizer.

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