Wdrażanie GBL

Na tej stronie dowiesz się, jak wdrożyć plik binarny ogólnego programu rozruchowego (GBL).

Wymagania dotyczące oprogramowania rozruchowego

Aby można było używać GBL, oprogramowanie rozruchowe musi spełniać te wymagania:

  • Zgodność z Unified Extensible Firmware Interface (UEFI). Oprogramowanie musi implementować i używać wymaganych protokołów UEFI. Musi też umożliwiać korzystanie z rozszerzeń specyficznych dla dostawcy za pomocą zdefiniowanych protokołów UEFI.

  • Zabezpieczenia. Oprogramowanie musi implementować wszystkie wymagania dotyczące weryfikacji podczas uruchamiania na Androidzie (AVB), co umożliwi GBL uwierzytelnianie obrazów rozruchowych.

  • Tryby uruchamiania. Plik binarny powinien obsługiwać różne tryby uruchamiania, takie jak normalne uruchamianie, uruchamianie w trybie odzyskiwania i fastboot.

  • Partycjonowanie dynamiczne. Oprogramowanie rozruchowe musi implementować logikę wyboru slotu, aby obsługiwać odczytywanie prawidłowego slotu rozruchowego A/B i być zgodne z partycjami dynamicznymi oraz danymi użytkownika w super.

  • Konfiguracja systemu operacyjnego. Oprogramowanie musi mieć możliwość modyfikowania wiersza poleceń jądra, drzewa urządzeń (DTB) i bootconfig za pomocą dostosowań OEM wymaganych do uruchomienia urządzenia.

  • Wczytywanie chronionej maszyny wirtualnej. Plik binarny powinien prawidłowo wczytywać wstępnie zweryfikowane oprogramowanie chronionej maszyny wirtualnej przed jądrem Androida w przypadku obecności chronionych maszyn wirtualnych. Więcej informacji znajdziesz w artykule Sekwencja uruchamiania Microdroida.

  • Zarządzanie pamięcią. Oprogramowanie rozruchowe musi obsługiwać interfejs API alokacji pamięci UEFI.

Wymagania związane z implementacją

Aby GBL zostało prawidłowo zaimplementowane na urządzeniu, musisz spełnić te wymagania:

  • Urządzenie musi zawierać 2 partycje FAT o rozmiarze 8 MB (lub większym) o nazwach android_esp_a i android_esp_b na urządzeniu blokowym dostępnym dla SOC.

    • Urządzenie blokowe to urządzenie pamięci masowej, z którego można odczytywać i na którym można zapisywać dane w jednostkach bloków. Przykłady to urządzenia UFS, eMMC i karty SD.
    • Używamy systemu FAT, ponieważ jest to powszechny i prosty system plików.
    • Zalecamy wybranie systemu plików FAT odpowiedniego do Twoich potrzeb spośród FAT12, FAT16 i FAT32.
    • Obie partycje są wymagane do aktualizacji bezprzewodowych (OTA) i wycofywania zmian przez cały okres obsługi tej wersji Androida.
    • GBL ma po rozpakowaniu około 2 MB. 8 MB wystarczy, aby uwzględnić wzrost rozmiaru spowodowany dodaniem funkcji w ciągu najbliższych 7 lat.
    • W przypadku aktualizacji GBL musisz zaktualizować całą partycję android_esp_${SLOT_SUFFIX}. Aktualizacja tylko GBL nie jest obsługiwana przez Android OTA.
    • Identyfikator GUID typu partycji używany w przypadku obu partycji FAT musi odpowiadać identyfikatorowi GUID partycji systemowej EFI C12A7328-F81F-11D2-BA4B-00A0C93EC93B.

  • Wdrożona wersja GBL musi być najnowszą certyfikowaną kompilacją produkcyjną z odpowiedniej gałęzi wydania GBL. Zalecamy podpisanie certyfikowanej przez Google kopii GBL za pomocą preferowanego rozwiązania do podpisywania i przechowywanie wynikowej kompilacji oraz metadanych podpisu w partycji android_esp_${SLOT_SUFFIX}.

    • Certyfikat GBL MUSI pozostać nienaruszony przez podpis OEM, a do pliku binarnego nie można stosować nagłówka.
    • Kompilacja GBL dla deweloperów jest używana wyłącznie do celów programistycznych i debugowania. Nie można jej dostarczyć i nie będzie certyfikowana przez Google.

  • GBL musi być przechowywany w ścieżce /EFI/BOOT/BOOTAA64.EFI w partycji FAT.

  • Aby obsługiwać GBL, zaimplementuj wymagane protokoły UEFI i Android UEFI. Jeśli te interfejsy nie są obsługiwane, kompilacja produkcyjna GBL nie uruchomi się.

    • EFI_BLOCK_IO_PROTOCOL lub EFI_BLOCK_IO2_PROTOCOL pobiera obrazy rozruchowe i obrazy pvmfw z dysku.
    • EFI_RNG_PROTOCOL w przypadku kanarków stosu, ziarna KASLR i ziarna RNG.
    • Usługi alokacji pamięci do alokacji pamięci roboczej na potrzeby obliczeń AVB i DICE.
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL zapewnia opcję implementacji bez operacji, ale GBL domyślnie loguje się za pomocą tego protokołu.
    • GBL_EFI_AVB_PROTOCOL uzyskuje dostęp do kluczy publicznych i indeksów wycofywania, aby zweryfikować obrazy rozruchowe.
    • GBL_EFI_BOOT_CONTROL_PROTOCOL pobiera metadane slotu i przyczyny uruchomienia z oprogramowania.
    • GBL_EFI_AVF_PROTOCOL generuje dane konfiguracyjne AVF z łańcucha DICE.

  • Oprogramowanie musi udostępniać GBL zmienne UEFI. Te zmienne muszą być ustawione na wartość GBL_EFI_VENDOR_GUID równą 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830.

    • gbl_fw_api_level musi być ustawiony na poziom interfejsu API oprogramowania platformy, co wskazuje poziom interfejsu API oprogramowania dostawcy. Ta zmienna musi mieć taką samą wartość jak właściwość systemu ro.board.api_level.

  • Protokoły UEFI, które są zdecydowanie zalecane podczas integrowania GBL, są opisane w artykule Protokoły GBL UEFI.

Obsługa oprogramowania rozruchowego

Po wprowadzeniu zmian niezbędnych do obsługi wymagań z poprzedniej sekcji te implementacje oprogramowania UEFI działają z GBL:

  • EDK2 (Tianocore). EDK2 to popularna implementacja UEFI typu open source. W przypadku programów rozruchowych opartych na EDK2 wymagana jest obsługa GBL, a obsługa UEFI jest już dostępna.
  • U-Boot. Elastyczny i powszechnie używany projekt programu rozruchowego typu open source, który zyskuje zgodność z UEFI na potrzeby używania GBL.
  • LittleKernel (LK). Program rozruchowy typu open source używany przez niektórych dostawców.

Uruchamianie GBL

Możesz pobrać wstępnie skompilowany plik binarny GBL, aby go uruchomić, lub skompilować własny i go uruchomić.

Pobieranie i uruchamianie pliku binarnego GBL

GBL jest rozpowszechniany jako pojedynczy plik binarny aplikacji UEFI. Możesz zaktualizować ten plik binarny niezależnie od podstawowego oprogramowania urządzenia za pomocą standardowego mechanizmu aktualizacji Androida.

Jeśli od Androida 16 wysyłasz urządzenie oparte na chipsecie ARM-64, zdecydowanie zalecamy wdrożenie najnowszej certyfikowanej przez Google wersji GBL i zintegrowanie jej z łańcuchem uruchamiania.

Aby debugować tę kompilację GBL, możesz pobrać dowolny z tych artefaktów, które pomogą w debugowaniu:

  • Tabela symboli używa debugera sprzętowego i GDB w przypadku kompilacji GBL certyfikowanej przez Google.
  • Manifest wprowadza zmiany w podpisanej kompilacji, odtwarzając tę kompilację GBL ze źródła za pomocą repo.
  • Odpowiednia kompilacja GBL dla deweloperów jest przydatna w przypadku uruchamiania lub mniej zaawansowanego debugowania problemu wpływającego na podpisaną kompilację produkcyjną.
  • Tabela symboli jest przydatna w przypadku kompilacji GBL dla deweloperów z debugerem sprzętowym i GDB.

Kompilowanie GBL

Aby skompilować GBL:

  1. Sprawdź, czy masz zainstalowane narzędzie repo i bootstrap Bazela:

    sudo apt install repo bazel-bootstrap

  2. Zainicjuj bieżący katalog na potrzeby kontroli źródła za pomocą pliku manifestu uefi-gbl-mainline:

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

  3. Skompiluj aplikację UEFI:

    tools/bazel run //bootable/libbootloader:gbl_efi_dist

Testowanie GBL na urządzeniu wirtualnym z Androidem

  1. Uruchom GBL w Cuttlefish:

    cvd start --android_efi_loader=path_to_the_UEFI_app ...

    Zamiast bezpośrednio uruchamiać Androida, to polecenie cvd start używa aplikacji UEFI do uruchamiania Androida.

Zgłaszanie błędów i kontaktowanie się z zespołem ds. programu rozruchowego

Aby zgłosić błąd dotyczący GBL, otwórz komponent ogólnego programu rozruchowego Androida w Buganizerze.

Jeśli masz pytania, skontaktuj się z zespołem GBL, wysyłając e-maila na adres android-gbl@google.com.