Как развернуть GBL

На этой странице объясняется, как развернуть двоичный файл Generic Bootloader (GBL).

Требования к встроенному ПО для загрузки

Чтобы использовать GBL, встроенное ПО загрузчика должно соответствовать следующим требованиям:

  • Соответствие единому расширяемому интерфейсу встроенного ПО (UEFI). Встроенное ПО должно реализовывать и использовать необходимые протоколы UEFI. Встроенное ПО также должно поддерживать расширения, относящиеся к определенному поставщику, с использованием определенных протоколов UEFI.

  • Безопасность Встроенное ПО должно соответствовать всем требованиям к проверке при запуске Android (AVB), чтобы загрузчик мог выполнить аутентификацию загрузочных образов.

  • Режимы загрузки. Двоичный файл должен поддерживать различные режимы загрузки, такие как обычная загрузка, загрузка в режиме восстановления и быстрая загрузка.

  • Динамическое разделение. В прошивке загрузчика должна быть реализована логика выбора слота, чтобы она поддерживала чтение правильного загрузочного слота A/B и была совместима с динамическими разделами и данными пользователя в суперразделе.

  • Конфигурация ОС. Встроенное ПО должно поддерживать изменение командной строки ядра, дерева устройств (DTB) и bootconfig с помощью настроек OEM, необходимых для загрузки устройства.

  • Загрузка защищенной ВМ. Двоичный файл должен правильно загружать предварительно проверенную защищенную прошивку виртуальной машины до ядра Android при наличии защищенных виртуальных машин. Подробную информацию можно найти в разделе Последовательность загрузки.

  • Управление памятью. Встроенное ПО для загрузки должно поддерживать API распределения памяти UEFI.

Требования к реализации

Чтобы правильно реализовать GBL на устройстве, необходимо выполнить следующие требования:

  • На устройстве должно быть два раздела FAT размером не менее 8 МБ с названиями android_esp_a и android_esp_b на блочном устройстве, доступном для SOC.

    • Блочное устройство – это устройство хранения данных, на которое можно записывать данные и с которого можно считывать данные блоками. например UFS, eMMC и SD-карты.
    • FAT используется потому, что это распространенная и простая файловая система.
    • Рекомендуем выбрать файловую систему FAT, подходящую для ваших нужд: FAT12, FAT16 или FAT32.
    • Оба раздела необходимы для беспроводных обновлений и откатов в течение всего периода поддержки этой версии Android.
    • Размер файла GBL в несжатом виде составляет примерно 2 МБ. 8 МБ достаточно, чтобы учесть рост, связанный с добавлением новых функций в течение следующих семи лет.
    • При обновлении GBL необходимо обновить весь раздел android_esp_${SLOT_SUFFIX}. Беспроводное обновление Android не поддерживает обновление только GBL.
    • Используемый для обоих разделов FAT GUID типа раздела должен соответствовать GUID системного раздела EFI C12A7328-F81F-11D2-BA4B-00A0C93EC93B.

  • Развернутая версия GBL должна быть последней сертифицированной рабочей сборкой из соответствующей ветки выпуска GBL. Мы рекомендуем подписать сертифицированную Google копию GBL с помощью предпочитаемого вами решения для подписи и сохранить полученную сборку и метаданные подписи в разделе android_esp_${SLOT_SUFFIX}.

    • Сертификат GBL должен быть сохранен в целости и сохранности подписью OEM, а к двоичному файлу не должен применяться заголовок.
    • Сборка GBL для разработчиков используется исключительно для разработки и отладки. Сборка не может быть отправлена и не будет сертифицирована Google.

  • Файл GBL должен храниться по пути /EFI/BOOT/BOOTAA64.EFI в разделе FAT.

  • Реализуйте необходимые протоколы UEFI и Android UEFI для поддержки GBL. Если эти интерфейсы не поддерживаются, загрузка производственной версии GBL невозможна.

    • EFI_BLOCK_IO_PROTOCOL или EFI_BLOCK_IO2_PROTOCOL извлекает загрузочные образы и образы pvmfw с диска.
    • EFI_RNG_PROTOCOL для канареек стека, KASLR и RNG
    • Сервисы распределения памяти для выделения временной памяти для вычислений AVB и DICE.
    • EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL позволяет реализовать функцию бездействия, но по умолчанию GBL регистрирует данные с помощью этого протокола.
    • GBL_EFI_AVB_PROTOCOL получает доступ к открытым ключам и индексам отката, чтобы проверить загрузочные образы.
    • GBL_EFI_BOOT_CONTROL_PROTOCOL получает метаданные слота и причины загрузки от встроенного ПО
    • GBL_EFI_AVF_PROTOCOL генерирует данные конфигурации AVF из цепочки DICE.

  • Встроенное ПО должно предоставлять переменные UEFI для GBL. Для этих переменных должно быть задано значение 5a6d92f3-a2d0-4083-91a1-a50f6c3d9830 (GBL_EFI_VENDOR_GUID).

    • Значение gbl_fw_api_level должно соответствовать уровню API встроенного ПО платформы, указывая на уровень API ПО поставщика. Значение этой переменной должно совпадать со значением системного свойства ro.board.api_level.

  • Протоколы UEFI, которые настоятельно рекомендуется использовать при интеграции GBL, описаны в статье Протоколы UEFI для GBL.

Поддержка встроенного ПО для загрузки

С учетом изменений, необходимых для поддержки требований, описанных в предыдущем разделе, следующие реализации встроенного ПО UEFI работают с GBL:

  • EDK2 (Tianocore). EDK2 – популярная реализация UEFI с открытым исходным кодом. Поддержка GBL необходима для загрузчиков на основе EDK2, а поддержка UEFI уже есть.
  • U-Boot. Гибкий и широко используемый проект загрузчика с открытым исходным кодом, который получает совместимость с UEFI для использования GBL.
  • LittleKernel (LK). Загрузчик с открытым исходным кодом, используемый некоторыми поставщиками.

Запуск GBL

Вы можете получить готовый двоичный файл GBL для запуска или создать собственный и запустить его.

Как получить и запустить исполняемый файл GBL

GBL распространяется как один исполняемый файл приложения UEFI. Вы можете обновить этот двоичный файл независимо от базового встроенного ПО устройства, используя стандартный механизм обновления Android.

Начиная с Android 16, если вы поставляете устройство на базе чипсета ARM-64, мы настоятельно рекомендуем вам развернуть последнюю сертифицированную Google версию GBL и интегрировать ее в цепочку загрузки.

Чтобы отладить сборку GBL, вы можете скачать любой из следующих артефактов:

  • В таблице символов используется аппаратный отладчик и GDB для сборки GBL, сертифицированной Google.
  • Манифест вносит изменения в подписанную сборку, воссоздавая эту сборку GBL из источника с помощью repo.
  • Соответствующая сборка для разработчиков GBL полезна для запуска или менее сложной отладки проблемы, влияющей на подписанную рабочую сборку.
  • Таблица символов полезна для сборки GBL для разработчиков с аппаратным отладчиком и GDB.

Чтобы посмотреть сертифицированные двоичные файлы и символы во всех выпусках, перейдите на страницу Сборки GBL.

Создание GBL

Чтобы создать GBL:

  1. Убедитесь, что у вас установлены инструмент repo и загрузчик Bazel:

    sudo apt install repo bazel-bootstrap

  2. Инициализируйте текущий каталог для управления исходным кодом с помощью файла манифеста uefi-gbl-mainline:

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

  3. Создайте приложение UEFI:

    tools/bazel run //bootable/libbootloader:gbl_efi_dist

Как протестировать GBL на виртуальном устройстве Android

  1. Чтобы запустить GBL в Cuttlefish:

    cvd start --android_efi_loader=path_to_the_UEFI_app ...

    Вместо прямой загрузки Android эта команда cvd start использует приложение UEFI для загрузки Android.

Как сообщить об ошибке и связаться с командой загрузчика

Чтобы сообщить об ошибке в GBL, перейдите к компоненту Android Generic Bootloader в Buganizer.

Если у вас есть вопросы, свяжитесь с командой GBL по адресу android-gbl@google.com.