1# GBL UEFI Protocols 2 3This document lists every UEFI protocol that GBL may potentially use, and 4describes the use case with any requirements. 5 6## Upstream Protocols 7 8These protocols are taken from an external source, typically the UEFI spec. 9 10### BlockIoProtocol 11 12* [`EFI_BLOCK_IO_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/13_Protocols_Media_Access.html#efi-block-io-protocol) 13* required 14 15Used to read the GPT, load images from disk, and write data back to disk in 16e.g. in fastboot. 17 18This is required even if the Block I/O 2 Protocol is provided, as some use cases 19might want to use this simpler API. 20 21### BlockIo2Protocol 22 23* [`EFI_BLOCK_IO2_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/13_Protocols_Media_Access.html#block-i-o-2-protocol) 24* optional: enables performance optimizations 25 26If provided, GBL may use this protocol instead of the Block I/O Protocol as a 27performance optimization; for example during fastboot flashing it may flash to 28disk while concurrently receiving the next image over USB. 29 30### DevicePathProtocol 31 32* [`EFI_DEVICE_PATH_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/10_Protocols_Device_Path_Protocol.html#efi-device-path-protocol) 33* optional: enables logging the image path on GBL start 34 35Used for logging the GBL image path to the console on load. This can be useful 36as a "Hello world" proof-of-concept that GBL is running and can interact with 37the UEFI protocols. 38 39This logging requires all three of: 40* Device Path Protocol 41* Device Path to Text Protocol 42* Loaded Image Protocol 43 44### DevicePathToTextProtocol 45 46* [`EFI_DEVICE_PATH_TO_TEXT_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/10_Protocols_Device_Path_Protocol.html#device-path-to-text-protocol) 47* optional: enables logging the image path on GBL start 48 49Used for logging the GBL image path to the console on load. This can be useful 50as a "Hello world" proof-of-concept that GBL is running and can interact with 51the UEFI protocols. 52 53This logging requires all three of: 54* Device Path Protocol 55* Device Path to Text Protocol 56* Loaded Image Protocol 57 58### LoadedImageProtocol 59 60* [`EFI_LOADED_IMAGE_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/09_Protocols_EFI_Loaded_Image.html#efi-loaded-image-protocol) 61* optional: enables logging the image path on GBL start 62 63Used for logging the GBL image path to the console on load. This can be useful 64as a "Hello world" proof-of-concept that GBL is running and can interact with 65the UEFI protocols. 66 67This logging requires all three of: 68* Device Path Protocol 69* Device Path to Text Protocol 70* Loaded Image Protocol 71 72### Memory Allocation Services 73 74* [Memory allocation services](https://uefi.org/specs/UEFI/2.10/07_Services_Boot_Services.html#memory-allocation-services) 75* all required 76 77Used by libavb for image verification. 78 79Dynamic memory allocation can be minimized, but not completely eliminated, by 80providing preallocated image buffers via the GBL Image Loading Protocol. 81 82### RiscvBootProtocol 83 84* [`RISCV_EFI_BOOT_PROTOCOL`](https://github.com/riscv-non-isa/riscv-uefi/blob/main/boot_protocol.adoc) 85* required for RISC-V targets 86 87Used to query the boot hart ID which is required to pass to the kernel. 88 89### SimpleNetworkProtocol 90 91* [`EFI_SIMPLE_NETWORK_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/24_Network_Protocols_SNP_PXE_BIS.html#simple-network-protocol) 92* optional: enables fastboot over TCP 93 94Used to provide fastboot over TCP. This can be enabled by itself, or in 95addition to fastboot over USB. 96 97Currently if this protocol is available GBL will always start fastboot over TCP, 98but in the future this functionality will be restricted to dev builds only. 99Production devices should not expose fastboot over TCP. 100 101GBL only uses the Simple Network Protocol, and will not use higher-level 102protocols such as the TCP4/6 Protocols even if they are available. 103 104### SimpleTextInputProtocol 105 106* [`EFI_SIMPLE_TEXT_INPUT_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/12_Protocols_Console_Support.html#simple-text-input-protocol) 107* optional: enables the 'f' key to enter fastboot 108 109This is currently used to look for the 'f' key on the serial line during boot, 110which will trigger GBL to enter fastboot mode. If not provided, GBL will skip 111this check. 112 113We plan to remove this and instead use a more general protocol to allow devices 114to specify their own custom fastboot triggers. 115 116### SimpleTextOutputProtocol 117 118* [`EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL`](https://uefi.org/specs/UEFI/2.10/12_Protocols_Console_Support.html#simple-text-output-protocol) 119* required, but can be no-op 120 121Used for logging and debugging. Implementations must provide this protocol, but 122the functions may be no-ops. 123 124## Community Protocols 125 126Protocols defined by a community and used across the ecosystem, but not officially 127part of the UEFI specification. None of these protocols are required. 128 129### DtFixupProtocol 130 131* original [proposal](https://github.com/U-Boot-EFI/EFI_DT_FIXUP_PROTOCOL) 132* [upstream](https://github.com/u-boot/u-boot/blob/master/include/efi_dt_fixup.h) 133* optional: allows FW to modify the final device tree 134 135This protocol allows the firmware (FW) to inspect the final device tree and apply 136necessary fixups. 137 138GBL will validate the applied changes and prevent booting if any of the security 139limitations (listed below) are violated. Any errors will be reported through the 140UEFI log. 141 142TODO (b/353272981): Add limitations 143 144This protocol was proposed by U-Boot and is currently used by the Kernel UEFI stub. 145 146## GBL Custom Protocols 147 148These protocols are defined by GBL to provide specific functionality that is 149not available elsewhere. 150 151Majority of these custom protocols aren't required, with the intention that dev 152boards that support a typical set of UEFI protocols should be able to use GBL 153with a minimal firmware modifications and still get some basic booting functionality. 154 155However, without these protocols GBL will be missing key features such as 156USB fastboot and verified boot, so production targets and more full-featured dev 157boards will need to implement them. 158 159### GblFastbootProtocol 160 161* [`GBL_EFI_FASTBOOT_PROTOCOL`](./gbl_efi_fastboot_protocol.md) 162* optional: enables custom fastboot functionality. 163 164Used to provide an interface for 165* Custom variables 166* OEM commands 167* Device lock/unlock controls 168* Lock-contingent partition permission information 169* User data erasure 170 171### GblFastbootUsbProtocol 172 173* [`GBL_EFI_FASTBOOT_USB_PROTOCOL`](./GBL_EFI_FASTBOOT_USB_PROTOCOL.md) 174* optional: enables fastboot over USB 175 176Used to provide fastboot over USB. This can be enabled by itself, or in 177addition to fastboot over TCP. 178 179### GblOsConfigurationProtocol 180 181* [`GBL_EFI_OS_CONFIGURATION_PROTOCOL`](./gbl_os_configuration_protocol.md) 182* optional: enables runtime fixups of OS data 183 184Used for runtime fixups of data provided to the OS such as command line and 185device tree. If not provided, the data in the OS images loaded from disk will 186be used without modification. 187 188### GblSlotProtocol 189 190* TODO(b/359946695): link documentation 191* optional: enables A/B slotted booting 192 193Used to read and write A/B slot metadata. If not provided, GBL will 194load from either the `_a` slot or a slotless boot partition. 195 196All components that interact with A/B slot metadata must use the same format. 197Typically these components are: 198 1991. The UEFI firmware selecting which GBL slot to load 2002. GBL selecting which OS slot to load 2013. The OS update engine updating the metadata when a new version is downloaded 202 203This protocol allows the device to implement its own A/B metadata format while 204still allowing GBL to implement the boot flow logic. 205 206### GblImageLoadingProtocol 207 208* TODO(b/359946775): link documentation 209* optional: enables loading images to predefined memory locations 210 211Used to provide buffers to load the images for verification and boot process. 212 213In addition this protocol provides a list of additional custom partitions to be 214verified before booting, for boards that want to verify data in addition to the 215standard boot partitions. 216 217### GblAvbProtocol 218 219* [`GBL_EFI_AVB_PROTOCOL`](./gbl_avb_protocol.md) 220* required for production devices: enables AVB-related firmware callbacks. 221 222This protocol delegates some of AVB-related logic to the firmware, including 223tasks such as verifying public keys, handling verification results, and 224managing the device’s secure state (e.g., ROT, lock state, rollback indexes, 225etc.). 226