Esegui il deployment di GBL

Questa pagina spiega come eseguire il deployment del binario Generic Bootloader (GBL).

Requisiti del firmware di avvio

Per utilizzare GBL, il firmware di avvio deve soddisfare i seguenti requisiti:

  • Conformità a Unified Extensible Firmware Interface (UEFI). Il firmware deve implementare e utilizzare i protocolli UEFI richiesti. Il firmware deve anche consentire estensioni specifiche del fornitore utilizzando protocolli UEFI definiti.

  • Sicurezza Il firmware deve implementare tutti i requisiti per l'avvio verificato di Android (AVB), consentendo a GBL di autenticare le immagini di avvio.

  • Modalità di avvio. Il binario deve essere in grado di gestire varie modalità di avvio, ad esempio avvio normale, avvio del ripristino e fastboot.

  • Partizionamento dinamico. Il firmware di avvio deve implementare la logica di selezione dello slot in modo da supportare la lettura dello slot di avvio A/B corretto ed essere compatibile con le partizioni dinamiche e i dati utente in super.

  • Configurazione del sistema operativo. Il firmware deve essere in grado di modificare la riga di comando del kernel, il device tree (DTB) e bootconfig con le personalizzazioni OEM necessarie per avviare il dispositivo.

  • Caricamento della VM protetta. Il binario deve caricare correttamente il firmware della VM protetta preverificata prima del kernel Android in presenza di VM protette. Per ulteriori informazioni, consulta la sequenza di avvio di Microdroid.

  • Gestione della memoria. Il firmware di avvio deve supportare l'API di allocazione della memoria UEFI.

Requisiti di implementazione

Per implementare correttamente GBL sul tuo dispositivo, devi soddisfare i seguenti requisiti:

  • Il dispositivo deve contenere due partizioni FAT32 di 4 MB (o più grandi) denominate android_esp_a e android_esp_b su un dispositivo a blocchi accessibile dal SOC.

    • Un dispositivo a blocchi è un dispositivo di archiviazione che può essere letto o scritto in unità di blocchi. Alcuni esempi includono dispositivi UFS, eMMC e schede SD.
    • FAT32 viene utilizzato perché è un file system onnipresente e semplice.
    • Entrambe le partizioni sono necessarie per gli aggiornamenti over-the-air (OTA) e i rollback per la durata del periodo di supporto di questa versione di Android.
    • GBL è di circa 2 MB non compressi. 4 MB sono sufficienti per tenere conto di qualsiasi crescita dovuta a funzionalità aggiuntive nei prossimi sette anni.
    • In caso di aggiornamento di GBL, devi aggiornare l'intera partizione android_esp_${SLOT_SUFFIX}. Un aggiornamento solo GBL non è supportato da Android OTA.

  • La versione di GBL di cui è stato eseguito il deployment deve essere l'ultima build di produzione certificata del ramo di release di GBL corrispondente. Ti consigliamo di firmare la copia della GBL certificata da Google utilizzando la tua soluzione di firma preferita e di archiviare i metadati della build e della firma risultanti all'interno della partizione android_esp_${SLOT_SUFFIX}.

    • Il certificato GBL DEVE essere lasciato intatto dalla firma OEM e non deve essere applicata alcuna intestazione al binario.
    • La build GBL per sviluppatori viene utilizzata esclusivamente a scopo di sviluppo e debug. La build non può essere spedita e non verrà certificata da Google.

  • Il file GBL deve essere archiviato nel percorso /EFI/BOOT/BOOTAA64.EFI all'interno della partizione FAT32.

  • Implementa i protocolli UEFI e Android UEFI richiesti per supportare GBL. La build di produzione di GBL non viene avviata se queste interfacce non sono supportate.

    • EFI_BLOCK_IO_PROTOCOL o EFI_BLOCK_IO2_PROTOCOL recupera le immagini di avvio e le immagini pvmfw dal disco
    • EFI_RNG_PROTOCOL per stack canary, seed KASLR e seed RNG
    • Servizi di allocazione della memoria per l'allocazione della memoria scratch per eseguire calcoli AVB e DICE
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL fornisce un'opzione per le implementazioni no-op, ma GBL registra tramite questo protocollo per impostazione predefinita
    • GBL_EFI_AVB_PROTOCOL accede alle chiavi pubbliche e agli indici di rollback per verificare le immagini di avvio
    • GBL_EFI_BOOT_CONTROL_PROTOCOL acquisisce i metadati dello slot e i motivi di avvio dal firmware
    • GBL_EFI_AVF_PROTOCOL genera dati di configurazione AVF dalla catena DICE

  • I protocolli UEFI fortemente consigliati durante l'integrazione di GBL sono documentati in Protocolli UEFI GBL.

Supporto del firmware di avvio

Con le modifiche necessarie per supportare i requisiti della sezione precedente, le seguenti implementazioni del firmware UEFI funzionano con GBL:

  • EDK2 (Tianocore). EDK2 è un'implementazione UEFI open source molto diffusa. È necessario il supporto GBL per i bootloader basati su EDK2 e il supporto UEFI è già presente.
  • U-Boot. Un progetto di bootloader open source flessibile e ampiamente utilizzato che sta ottenendo la compatibilità UEFI per l'utilizzo di GBL.
  • LittleKernel (LK). Un bootloader open source utilizzato da alcuni fornitori.

Esegui GBL

Puoi ottenere un binario GBL precompilato da eseguire o crearne uno personalizzato ed eseguirlo.

Ottenere ed eseguire il programma binario GBL

GBL viene distribuito come singolo binario dell'app UEFI. Puoi aggiornare questo file binario indipendentemente dal firmware di base del dispositivo utilizzando il meccanismo di aggiornamento standard di Android.

A partire da Android 16, se spedisci un dispositivo basato sul chipset ARM-64, ti consigliamo vivamente di implementare l'ultima versione certificata da Google di GBL e di integrarla nella catena di avvio.

Build GBL

Per creare GBL:

  1. Verifica di aver installato lo strumento repo e Bazel bootstrap:

    sudo apt install repo bazel-bootstrap

  2. Inizializza la directory corrente per il controllo del codice sorgente utilizzando il file manifest uefi-gbl-mainline:

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

  3. Crea l'app UEFI:

    tools/bazel run //bootable/libbootloader:gbl_efi_dist

Testare GBL sul dispositivo virtuale Android

  1. Esegui GBL in Cuttlefish:

    cvd start --android_efi_loader=path_to_the_UEFI_app ...

    Anziché avviare direttamente Android, questo comando cvd start utilizza l'app UEFI per avviare Android.

Segnalare bug e contattare il team del bootloader

Per segnalare un bug per il GBL, vai al componente Android Generic Bootloader in Buganizer.

Per eventuali domande, contatta il team GBL inviando un'email all'indirizzo android-gbl@google.com.