Men-deploy GBL

Halaman ini menjelaskan cara men-deploy biner Generic Bootloader (GBL).

Persyaratan firmware booting

Untuk menggunakan GBL, firmware booting harus memenuhi persyaratan berikut:

  • Kepatuhan Unified Extensible Firmware Interface (UEFI). Firmware harus mengimplementasikan dan menggunakan protokol UEFI yang diperlukan. Firmware juga harus mengizinkan ekstensi khusus vendor menggunakan protokol UEFI yang ditentukan.

  • Keamanan. Firmware harus menerapkan semua persyaratan untuk Booting Terverifikasi Android (AVB), sehingga GBL dapat mengautentikasi boot image.

  • Mode booting. Biner harus dapat menangani berbagai mode booting, seperti booting normal, booting pemulihan, dan fastboot.

  • Partisi dinamis. Firmware booting harus menerapkan logika pemilihan slot agar mendukung pembacaan slot booting A/B yang benar dan kompatibel dengan partisi dinamis dan data pengguna di super.

  • Konfigurasi OS. Firmware harus mampu mengubah command line kernel, device tree (DTB), dan bootconfig dengan penyesuaian OEM yang diperlukan untuk mem-booting perangkat.

  • VM yang dilindungi sedang dimuat. Biner harus memuat firmware VM yang dilindungi dan telah diverifikasi sebelumnya dengan benar sebelum kernel Android jika ada VM yang dilindungi. Untuk informasi lebih lanjut, lihat urutan booting Microdroid.

  • Manajemen memori. Firmware booting harus mendukung API alokasi memori UEFI.

Persyaratan penerapan

Agar GBL diterapkan dengan benar di perangkat, Anda harus memenuhi persyaratan berikut:

  • Perangkat Anda harus berisi dua partisi FAT berukuran 8 MB (atau lebih besar) yang diberi nama android_esp_a dan android_esp_b pada perangkat blok yang dapat diakses oleh SOC.

    • Perangkat blok adalah perangkat penyimpanan yang dapat dibaca atau ditulis dalam unit blok. Contohnya mencakup perangkat UFS, eMMC, dan kartu SD.
    • FAT digunakan karena merupakan sistem file yang umum dan sederhana.
    • Sebaiknya pilih sistem file FAT yang sesuai dengan kebutuhan Anda dari FAT12, FAT16, dan FAT32.
    • Kedua partisi diperlukan untuk update OTA dan rollback selama periode dukungan versi Android ini.
    • GBL berukuran sekitar 2 MB tanpa kompresi. 8 MB sudah cukup untuk memperhitungkan pertumbuhan apa pun karena fitur tambahan selama tujuh tahun ke depan.
    • Jika terjadi update GBL, Anda harus mengupdate seluruh partisi android_esp_${SLOT_SUFFIX}. Update khusus GBL tidak didukung oleh OTA Android.
    • GUID jenis partisi yang digunakan untuk kedua partisi FAT harus sesuai dengan GUID Partisi Sistem EFI C12A7328-F81F-11D2-BA4B-00A0C93EC93B.
  • Versi GBL yang di-deploy harus merupakan build produksi bersertifikasi terbaru dari cabang rilis GBL yang sesuai. Sebaiknya Anda menandatangani salinan GBL bersertifikasi Google menggunakan solusi penandatanganan pilihan Anda dan menyimpan metadata build dan tanda tangan yang dihasilkan di dalam partisi android_esp_${SLOT_SUFFIX}.

    • Sertifikat GBL HARUS dibiarkan utuh oleh tanda tangan OEM DAN tidak boleh ada header yang diterapkan ke biner.
    • Build GBL developer digunakan secara ketat untuk tujuan pengembangan dan debug. Build tidak dapat dikirim dan tidak akan disertifikasi oleh Google.
  • GBL harus disimpan di jalur /EFI/BOOT/BOOTAA64.EFI dalam partisi FAT.

  • Terapkan protokol UEFI dan Android UEFI yang diperlukan untuk mendukung GBL. Build produksi GBL gagal melakukan booting jika antarmuka ini tidak didukung.

    • EFI_BLOCK_IO_PROTOCOL atau EFI_BLOCK_IO2_PROTOCOL mengambil boot image dan image pvmfw dari disk
    • EFI_RNG_PROTOCOL untuk stack canary, seed KASLR, dan seed RNG
    • Layanan Alokasi Memori untuk alokasi memori sementara guna melakukan komputasi AVB dan DICE
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL menyediakan opsi untuk implementasi no-op, tetapi GBL mencatat log melalui protokol ini secara default
    • GBL_EFI_AVB_PROTOCOL mengakses kunci publik dan indeks rollback untuk memverifikasi boot image
    • GBL_EFI_BOOT_CONTROL_PROTOCOL memperoleh metadata slot dan alasan booting dari firmware
    • GBL_EFI_AVF_PROTOCOL menghasilkan data konfigurasi AVF dari rantai DICE
  • Firmware harus menyediakan variabel UEFI ke GBL. Variabel ini harus ditetapkan dengan nilai GBL_EFI_VENDOR_GUID 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830, dan harus tetap hanya baca dan terlindungi dari modifikasi tidak sah saat bootloader dikunci.

    • gbl_fw_api_level harus ditetapkan ke level API firmware platform, yang menunjukkan level API software vendor. Variabel ini harus memiliki nilai yang sama dengan properti sistem ro.board.api_level.
    • gbl_fw_product_first_api_level harus ditetapkan ke level API SDK yang disertakan dalam perangkat dan harus tetap sama selama masa pakai produk, terlepas dari update software. Variabel ini harus memiliki nilai yang sama dengan properti sistem ro.product.first_api_level.
  • Protokol UEFI yang sangat direkomendasikan saat mengintegrasikan GBL didokumentasikan dalam Protokol UEFI GBL.

Dukungan firmware booting

Dengan modifikasi yang diperlukan untuk mendukung persyaratan di bagian sebelumnya, implementasi firmware UEFI berikut berfungsi dengan GBL:

  • EDK2 (Tianocore). EDK2 adalah implementasi UEFI open source yang populer. Dukungan GBL diperlukan untuk bootloader berbasis EDK2, dan dukungan UEFI sudah ada.
  • U-Boot. Project bootloader open source yang fleksibel dan banyak digunakan, yang mendapatkan kompatibilitas UEFI untuk penggunaan GBL.
  • LittleKernel (LK). Bootloader open source yang digunakan oleh beberapa vendor.

Menjalankan GBL

Anda dapat memperoleh biner GBL bawaan untuk dijalankan atau membuat biner Anda sendiri dan menjalankannya.

Mendapatkan dan menjalankan biner GBL

GBL didistribusikan sebagai satu biner aplikasi UEFI. Anda dapat mengupdate biner ini secara independen dari firmware dasar perangkat menggunakan mekanisme update standar Android.

Mulai Android 16, jika Anda mengirimkan perangkat berbasis chipset ARM-64, sebaiknya deploy versi terbaru yang disertifikasi Google dari GBL dan integrasikan ke dalam rantai booting Anda.

Untuk men-debug build GBL ini, Anda dapat mendownload salah satu artefak ini untuk membantu proses debug:

  • Tabel simbol menggunakan debugger hardware plus GDB untuk build GBL bersertifikasi Google.
  • Manifes membuat perubahan pada build yang ditandatangani dengan membuat ulang build GBL ini dari sumber menggunakan repo.
  • Build developer GBL yang sesuai berguna untuk bringup atau debug yang kurang canggih dari masalah yang memengaruhi build prod yang ditandatangani.
  • Tabel simbol berguna untuk build developer GBL dengan debugger hardware dan GDB.

Untuk melihat biner dan simbol bersertifikasi di semua rilis, lihat build rilis GBL.

Membangun GBL

Untuk membangun GBL:

  1. Pastikan Anda telah menginstal alat repo dan bootstrap Bazel:

    sudo apt install repo bazel-bootstrap
    
  2. Lakukan inisialisasi direktori Anda saat ini untuk kontrol sumber menggunakan file manifes uefi-gbl-mainline:

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

    tools/bazel run //bootable/libbootloader:gbl_efi_dist
    

Menguji GBL di Perangkat Virtual Android

  1. Jalankan GBL dalam Cuttlefish:

    cvd start --android_efi_loader=path_to_the_UEFI_app ...
    

    Command cvd start ini menggunakan aplikasi UEFI untuk mem-booting Android, bukan mem-booting Android secara langsung.

Melaporkan bug dan menghubungi tim bootloader

Untuk melaporkan bug GBL, buka komponen Bootloader Generik Android di Buganizer.

Jika ada pertanyaan, hubungi tim GBL, kirim email ke android-gbl@google.com.