This document lists every UEFI protocol that GBL may potentially use, and describes the use case with any requirements.
These protocols are taken from an external source, typically the UEFI spec.
EFI_BLOCK_IO_PROTOCOLUsed to read the GPT, load images from disk, and write data back to disk in e.g. in fastboot.
This is required even if the Block I/O 2 Protocol is provided, as some use cases might want to use this simpler API.
EFI_BLOCK_IO2_PROTOCOLIf provided, GBL may use this protocol instead of the Block I/O Protocol as a performance optimization; for example during fastboot flashing it may flash to disk while concurrently receiving the next image over USB.
EFI_DEVICE_PATH_PROTOCOLUsed for logging the GBL image path to the console on load. This can be useful as a “Hello world” proof-of-concept that GBL is running and can interact with the UEFI protocols.
This logging requires all three of:
EFI_DEVICE_PATH_TO_TEXT_PROTOCOLUsed for logging the GBL image path to the console on load. This can be useful as a “Hello world” proof-of-concept that GBL is running and can interact with the UEFI protocols.
This logging requires all three of:
EFI_LOADED_IMAGE_PROTOCOLUsed for logging the GBL image path to the console on load. This can be useful as a “Hello world” proof-of-concept that GBL is running and can interact with the UEFI protocols.
This logging requires all three of:
Used by libavb for image verification.
Dynamic memory allocation can be minimized, but not completely eliminated, by providing preallocated image buffers via the GBL Image Loading Protocol.
RISCV_EFI_BOOT_PROTOCOLUsed to query the boot hart ID which is required to pass to the kernel.
EFI_SIMPLE_NETWORK_PROTOCOLUsed to provide fastboot over TCP. This can be enabled by itself, or in addition to fastboot over USB.
Currently if this protocol is available GBL will always start fastboot over TCP, but in the future this functionality will be restricted to dev builds only. Production devices should not expose fastboot over TCP.
GBL only uses the Simple Network Protocol, and will not use higher-level protocols such as the TCP4/6 Protocols even if they are available.
EFI_SIMPLE_TEXT_INPUT_PROTOCOLThis is currently used to look for the ‘f’ key on the serial line during boot, which will trigger GBL to enter fastboot mode. If not provided, GBL will skip this check.
We plan to remove this and instead use a more general protocol to allow devices to specify their own custom fastboot triggers.
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOLUsed for logging and debugging. Implementations must provide this protocol, but the functions may be no-ops.
Protocols defined by a community and used across the ecosystem, but not officially part of the UEFI specification. None of these protocols are required.
This protocol allows the firmware (FW) to inspect the final device tree and apply necessary fixups.
GBL will validate the applied changes and prevent booting if any of the security limitations (listed below) are violated. Any errors will be reported through the UEFI log.
TODO (b/353272981): Add limitations
This protocol was proposed by U-Boot and is currently used by the Kernel UEFI stub.
These protocols are defined by GBL to provide specific functionality that is not available elsewhere.
Majority of these custom protocols aren't required, with the intention that dev boards that support a typical set of UEFI protocols should be able to use GBL with a minimal firmware modifications and still get some basic booting functionality.
However, without these protocols GBL will be missing key features such as USB fastboot and verified boot, so production targets and more full-featured dev boards will need to implement them.
GBL_EFI_FASTBOOT_PROTOCOLUsed to provide an interface for
GBL_EFI_FASTBOOT_USB_PROTOCOLUsed to provide fastboot over USB. This can be enabled by itself, or in addition to fastboot over TCP.
GBL_EFI_OS_CONFIGURATION_PROTOCOLUsed for runtime fixups of data provided to the OS such as command line and device tree. If not provided, the data in the OS images loaded from disk will be used without modification.
Used to read and write A/B slot metadata. If not provided, GBL will load from either the _a slot or a slotless boot partition.
All components that interact with A/B slot metadata must use the same format. Typically these components are:
This protocol allows the device to implement its own A/B metadata format while still allowing GBL to implement the boot flow logic.
Used to provide buffers to load the images for verification and boot process.
In addition this protocol provides a list of additional custom partitions to be verified before booting, for boards that want to verify data in addition to the standard boot partitions.
GBL_EFI_AVB_PROTOCOLThis protocol delegates some of AVB-related logic to the firmware, including tasks such as verifying public keys, handling verification results, and managing the device’s secure state (e.g., ROT, lock state, rollback indexes, etc.).