Esegui il deployment di GBL

Questa pagina spiega come fare il deployment del file binario del bootloader generico (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 i 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 programma binario deve essere in grado di gestire varie modalità di avvio, come l'avvio normale, l'avvio di 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, l'albero dei dispositivi (DTB) e la configurazione di avvio con le personalizzazioni OEM necessarie per avviare il dispositivo.

  • Caricamento della VM protetta. Il file binario deve caricare correttamente il firmware della VM protetta preverificato prima del kernel Android in presenza di VM protette. Per ulteriori informazioni, consulta 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 FAT di 8 MB (o più) denominate android_esp_a e android_esp_b su un dispositivo a blocchi accessibile dal SOC.

    • Un dispositivo a blocchi è un dispositivo di archiviazione da cui è possibile leggere o scrivere in unità di blocchi. Esempi includono dispositivi UFS, eMMC e schede SD.
    • FAT viene utilizzato perché è un file system onnipresente e semplice.
    • Ti consigliamo di scegliere il file system FAT più adatto alle tue esigenze tra FAT12, FAT16 e FAT32.
    • Entrambe le partizioni sono necessarie per gli aggiornamenti over-the-air (OTA) e i rollback per la durata della finestra di supporto di questa versione di Android.
    • GBL è di circa 2 MB non compressi. 8 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}. L'aggiornamento solo di GBL non è supportato da Android OTA.
    • Il GUID del tipo di partizione utilizzato per entrambe le partizioni FAT deve corrispondere al GUID della partizione di sistema EFI C12A7328-F81F-11D2-BA4B-00A0C93EC93B.

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

    • La firma OEM NON deve modificare il certificato GBL e non deve essere applicata alcuna intestazione al programma binario.
    • La build GBL dello sviluppatore viene utilizzata esclusivamente per scopi di sviluppo e debug. La build non può essere spedita e non verrà certificata da Google.

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

  • 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 i canarini dello stack, i seed KASLR e i seed RNG
    • Servizi di allocazione della memoria per l'allocazione della memoria temporanea per eseguire i calcoli AVB e DICE
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL fornisce un'opzione per le implementazioni no-op, ma GBL registra i log 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 i dati di configurazione AVF dalla catena DICE

  • Il firmware deve fornire le variabili UEFI a GBL. Queste variabili devono essere impostate con il valore GBL_EFI_VENDOR_GUID 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830.

    • gbl_fw_api_level deve essere impostato sul livello API del firmware della piattaforma, che indica il livello API del software del fornitore. Questa variabile deve avere lo stesso valore della proprietà di sistema ro.board.api_level.

  • 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 nella sezione precedente, le seguenti implementazioni del firmware UEFI funzionano con GBL:

  • EDK2 (Tianocore). EDK2 è un'implementazione UEFI open source molto diffusa. È necessario il supporto di 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 acquisendo la compatibilità UEFI per l'utilizzo di GBL.
  • LittleKernel (LK). Un bootloader open source utilizzato da alcuni fornitori.

Esegui GBL

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

Ottieni ed esegui il programma binario GBL

GBL viene distribuito come un singolo programma 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 su chipset ARM-64, ti consigliamo vivamente di eseguire il deployment dell'ultima versione di GBL certificata da Google e di integrarla nella catena di avvio.

Crea GBL

Per creare GBL:

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

    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

Testa GBL su Android Virtual Device

  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.

Segnala bug e contatta il team del bootloader

Per segnalare un bug per GBL, vai al componente Bootloader generico di Android in Buganizer.

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