GBL bereitstellen

Auf dieser Seite wird beschrieben, wie Sie die Generic Bootloader-Binärdatei (GBL) bereitstellen.

Anforderungen an die Boot-Firmware

Damit Sie GBL verwenden können, muss die Boot-Firmware die folgenden Anforderungen erfüllen:

  • UEFI-Konformität (Unified Extensible Firmware Interface) Die Firmware muss die erforderlichen UEFI-Protokolle implementieren und verwenden. Die Firmware muss auch anbieterspezifische Erweiterungen mithilfe definierter UEFI-Protokolle ermöglichen.

  • Sicherheit Die Firmware muss alle Anforderungen für Android Bootmodus mit Verifikation (AVB) erfüllen, damit GBL Boot-Images authentifizieren kann.

  • Bootmodi Die Binärdatei sollte verschiedene Bootmodi verarbeiten können, z. B. normaler Boot, Wiederherstellungs-Boot und Fastboot.

  • Dynamische Partitionierung Die Boot-Firmware muss eine Logik zur Slot-Auswahl implementieren, damit sie den richtigen A/B-Boot-Slot lesen kann und mit dynamischen Partitionen und Nutzerdaten in „super“ kompatibel ist.

  • Betriebssystemkonfiguration Die Firmware muss die Kernel-Befehlszeile, den Gerätebaum (Device Tree, DTB) und die Bootkonfiguration mit OEM-Anpassungen ändern können, die zum Booten des Geräts erforderlich sind.

  • Laden geschützter VMs Die Binärdatei sollte die vorab bestätigte geschützte VM-Firmware korrekt laden, bevor der Android-Kernel bei Vorhandensein geschützter VMs geladen wird. Weitere Informationen finden Sie unter Microdroid Bootsequenz.

  • Speicherverwaltung Die Boot-Firmware muss die UEFI-API für die Arbeitsspeicherzuweisung unterstützen.

Implementierungsanforderungen

Damit GBL auf Ihrem Gerät korrekt implementiert werden kann, müssen die folgenden Anforderungen erfüllt sein:

  • Ihr Gerät muss zwei FAT-Partitionen mit einer Größe von mindestens 8 MB enthalten, die auf einem Blockgerät mit dem Namen android_esp_a und android_esp_b gespeichert sind und auf das der SOC zugreifen kann.

    • Ein Blockgerät ist ein Speichergerät, von dem in Blöcken gelesen und in das in Blöcken geschrieben werden kann. Beispiele sind UFS-, eMMC- und SD-Kartengeräte.
    • FAT wird verwendet, weil es ein weit verbreitetes und unkompliziertes Dateisystem ist.
    • Wir empfehlen, das für Ihre Anforderungen geeignete FAT-Dateisystem aus FAT12, FAT16 und FAT32 auszuwählen.
    • Beide Partitionen sind für Over-the-Air-Updates (OTA) und Rollbacks während des Supportzeitraums dieser Android-Version erforderlich.
    • GBL ist unkomprimiert etwa 2 MB groß. 8 MB reichen aus, um das Wachstum aufgrund zusätzlicher Funktionen in den nächsten sieben Jahren zu berücksichtigen.
    • Im Falle eines GBL-Updates müssen Sie die gesamte Partition android_esp_${SLOT_SUFFIX} aktualisieren. Ein reines GBL-Update wird von Android OTA nicht unterstützt.
    • Die für beide FAT-Partitionen verwendete GUID des Partitionstyps muss der GUID der EFI-Systempartition C12A7328-F81F-11D2-BA4B-00A0C93EC93B entsprechen.

  • Die bereitgestellte Version von GBL muss der neueste zertifizierte Produktions-Build aus dem entsprechenden GBL-Release-Branch sein. Wir empfehlen, die von Google zertifizierte Kopie von GBL mit Ihrer bevorzugten Signaturlösung zu signieren und den resultierenden Build und die Signaturmetadaten in der Partition android_esp_${SLOT_SUFFIX} zu speichern.

    • Das GBL-Zertifikat MUSS von der OEM-Signatur intakt gelassen werden UND es darf kein Header auf die Binärdatei angewendet werden.
    • Der GBL-Build für Entwickler wird ausschließlich für Entwicklungs- und Debugging-Zwecke verwendet. Der Build kann nicht ausgeliefert werden und wird nicht von Google zertifiziert.

  • GBL muss unter dem Pfad /EFI/BOOT/BOOTAA64.EFI in der FAT-Partition gespeichert werden.

  • Implementieren Sie die erforderlichen UEFI- und Android-UEFI-Protokolle, um GBL zu unterstützen. Der Produktions-Build von GBL kann nicht gebootet werden, wenn diese Schnittstellen nicht unterstützt werden.

    • EFI_BLOCK_IO_PROTOCOL oder EFI_BLOCK_IO2_PROTOCOL ruft die Boot-Images und pvmfw-Images von der Festplatte ab.
    • EFI_RNG_PROTOCOL für Stack-Canaries, KASLR-Seeds und RNG-Seeds
    • Speicherzuweisungsdienste für die Zuweisung von Scratch-Speicher für AVB- und DICE-Berechnungen
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL bietet eine Option für No-Op-Implementierungen, aber GBL protokolliert standardmäßig über dieses Protokoll.
    • GBL_EFI_AVB_PROTOCOL greift auf öffentliche Schlüssel und Rollback-Indizes zu, um Boot-Images zu überprüfen.
    • GBL_EFI_BOOT_CONTROL_PROTOCOL ruft Slot-Metadaten und Boot-Gründe von der Firmware ab.
    • GBL_EFI_AVF_PROTOCOL generiert AVF-Konfigurationsdaten aus der DICE-Kette.

  • Die Firmware muss UEFI-Variablen für GBL bereitstellen. Diese Variablen müssen mit dem Wert GBL_EFI_VENDOR_GUID 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830 festgelegt werden.

    • gbl_fw_api_level muss auf die API-Ebene der Plattform-Firmware festgelegt werden, die die API-Ebene der Anbietersoftware angibt. Diese Variable muss denselben Wert wie die Systemeigenschaft ro.board.api_level haben.

  • Die UEFI-Protokolle, die bei der Integration von GBL dringend empfohlen werden, sind dokumentiert unter GBL-UEFI-Protokolle.

Unterstützung für Boot-Firmware

Mit den Änderungen, die zur Unterstützung der Anforderungen im vorherigen Abschnitt erforderlich sind, funktionieren die folgenden UEFI-Firmware-Implementierungen mit GBL:

  • EDK2 (Tianocore). EDK2 ist eine beliebte Open-Source-UEFI-Implementierung. Für EDK2-basierte Bootloader ist GBL-Unterstützung erforderlich, UEFI-Unterstützung ist bereits vorhanden.
  • U-Boot. Ein flexibles und weit verbreitetes Open-Source-Bootloader-Projekt, das UEFI-Kompatibilität für die GBL-Nutzung erhält.
  • LittleKernel (LK) Ein Open-Source-Bootloader, der von einigen Anbietern verwendet wird.

GBL ausführen

Sie können eine vorgefertigte GBL-Binärdatei abrufen, um sie auszuführen, oder eine eigene erstellen und ausführen.

GBL-Binärdatei abrufen und ausführen

GBL wird als einzelne UEFI-App-Binärdatei verteilt. Sie können diese Binärdatei unabhängig von der Basis-Firmware des Geräts mit dem Standard-Update-Mechanismus von Android aktualisieren.

Ab Android 16 empfehlen wir dringend, die neueste von Google zertifizierte Version von GBL bereitzustellen und in Ihre Bootkette zu integrieren, wenn Sie ein Gerät mit einem ARM-64-Chipsatz ausliefern.

Wenn Sie diesen GBL-Build debuggen möchten, können Sie eines dieser Artefakte herunterladen, um das Debugging zu erleichtern:

  • Die Symboltabelle verwendet einen Hardware-Debugger und GDB für den von Google zertifizierten GBL-Build.
  • Das Manifest nimmt Änderungen am signierten Build vor, indem es diesen GBL-Build aus der Quelle mit repo neu erstellt.
  • Der entsprechende GBL-Entwickler-Build ist nützlich für die Inbetriebnahme oder ein weniger aufwendiges Debugging eines Problems, das den signierten Produktions-Build betrifft.
  • Die Symboltabelle ist für den GBL-Entwickler-Build mit einem Hardware-Debugger und GDB nützlich.

GBL erstellen

So erstellen Sie GBL:

  1. Prüfen Sie, ob das Tool repo und Bazel Bootstrap installiert sind:

    sudo apt install repo bazel-bootstrap

  2. Initialisieren Sie das aktuelle Verzeichnis für die Quellcodeverwaltung mit der Manifestdatei uefi-gbl-mainline:

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

  3. Erstellen Sie die UEFI-App:

    tools/bazel run //bootable/libbootloader:gbl_efi_dist

GBL auf dem virtuellen Android-Gerät testen

  1. Führen Sie GBL in Cuttlefish aus:

    cvd start --android_efi_loader=path_to_the_UEFI_app ...

    Anstatt Android direkt zu booten, verwendet dieser Befehl cvd start die UEFI-App, um Android zu booten.

Fehler melden und das Bootloader-Team kontaktieren

Wenn Sie einen Fehler für GBL melden möchten, rufen Sie die Komponente „Android Generic Bootloader“ in Buganizer auf.

Bei Fragen wenden Sie sich an das GBL-Team. Senden Sie eine E-Mail an android-gbl@google.com.