1# GBL EFI Image Loading Protocol 2 3This document describes the GBL Image Loading protocol. This optional protocol 4defines interfaces that can be used by EFI applications to specify implement 5customised buffer location in memory. And additional images for verification. 6 7||| 8| :--- | :--- | 9| **Status** | Work in progress | 10| **Created** | 2024-12-11 | 11 12 13## GBL_EFI_IMAGE_LOADING_PROTOCOL 14 15### Summary 16 17This protocol allows firmware to provide platform reserved memory spaces to 18applications for a specific usage or feature, or alternatively, specify the 19amount of memory the application should allocate dynamically for it. 20 21It also provides interface to communicate additional images to be verified by 22GBL. 23 24### GUID 25 26```c 27// {db84b4fa-53bd-4436-98a7-4e0271428ba8} 28#define GBL_EFI_IMAGE_LOADING_PROTOCOL_GUID \ 29 { \ 30 0xdb84b4fa, 0x53bd, 0x4436, { \ 31 0x98, 0xa7, 0x4e, 0x02, 0x71, 0x42, 0x8b, 0xa8 \ 32 } \ 33 } 34``` 35 36### Revision Number 37 38```c 39#define GBL_EFI_IMAGE_PROTOCOL_PROTOCOL_REVISION 0x00010000 40``` 41 42### Protocol Interface Structure 43 44```c 45typedef struct _GBL_EFI_IMAGE_LOADING_PROTOCOL { 46 UINT64 Revision; 47 GBL_EFI_GET_IMAGE_BUFFER GetBuffer; 48 GBL_EFI_GET_VERIFY_PARTITIONS GetVerifyPartitions; 49} GBL_EFI_IMAGE_LOADING_PROTOCOL; 50``` 51 52### Parameters 53 54**Revision** \ 55The revision to which the GBL_EFI_IMAGE_BUFFER_PROTOCOL adheres. All future 56revisions must be backwards compatible. If a future version is not backwards 57compatible, a different GUID must be used. 58 59**GetBuffer** \ 60Query custom buffer for the image. See 61[`GBL_EFI_IMAGE_LOADING_PROTOCOL.GetBuffer()`](#gbl_efi_image_loading_protocolgetbuffer). 62 63**GetVerifyPartitions** \ 64Query for list of partitions to be verified by GBL. See 65[`GBL_EFI_IMAGE_LOADING_PROTOCOL.GetVerifyPartitions()`](#gbl_efi_image_loading_protocolgetverifypartitions). 66 67 68## GBL_EFI_IMAGE_LOADING_PROTOCOL.GetBuffer() 69 70### Summary 71 72`GetBuffer()` is used by GBL to get buffers for loading different images into 73RAM. 74 75### Prototype 76 77```c 78typedef 79EFI_STATUS 80(EFIAPI *GBL_EFI_GET_IMAGE_BUFFER) ( 81 IN GBL_EFI_IMAGE_LOADING_PROTOCOL *This, 82 IN GBL_EFI_IMAGE_INFO *ImageInfo, 83 OUT GBL_EFI_IMAGE_BUFFER *Buffer, 84) 85``` 86 87### Parameters 88 89**This** \ 90A pointer to the 91[`GBL_EFI_IMAGE_LOADING_PROTOCOL`](#gbl_efi_image_loading_protocol) instance. 92 93**ImageInfo** \ 94Information for the requested buffer. See 95[`GBL_EFI_IMAGE_INFO`](#gbl_efi_image_info) for details. 96 97**Buffer** \ 98Output pointer for `GBL_EFI_IMAGE_BUFFER`. See 99[`GBL_EFI_IMAGE_BUFFER`](#gbl_efi_image_buffer) for details. 100 101### Description 102 103The interface is for the firmware to provide platform reserved memory spaces 104to, or instruct caller to allocate specific amount of memory for the usage 105context described in `GBL_EFI_IMAGE_INFO.StrUtf16`. The usage context is 106application specific and may represent usages such as buffers for loading 107specific partitions, sharing data with secure world, and downloading in 108fastboot etc. 109 110If platform has a reserved memory space for the usage context, 111`GBL_EFI_IMAGE_BUFFER.Memory` and `GBL_EFI_IMAGE_BUFFER.SizeBytes` should be 112set to the address and size of the memory. Ownership of the provided memory 113must be passed exclusively to GBL, and must not be retained for any other 114purpose by firmware. 115 116If the caller should allocate memory dynamically by itself for the usage 117context, `GBL_EFI_IMAGE_BUFFER.Memory` should be set to NULL and 118`GBL_EFI_IMAGE_BUFFER.SizeBytes` should be set to the amount of memory caller 119should allocate. 120 121Caller may pass a suggested size via `GBL_EFI_IMAGE_INFO.SizeBytes` based on 122its run time knowledge. Implementation should eventually determine the size. 123 124### Status Codes Returned 125 126||| 127| --- | --- | 128| EFI_SUCCESS | Buffer provided successfully | 129| EFI_OUT_OF_RESOURCES | Failed to allocate buffers due to lack of free memory | 130 131### Related Definitions 132 133#### GBL_EFI_IMAGE_BUFFER 134 135```c 136typedef 137struct GBL_EFI_IMAGE_BUFFER { 138 VOID *Memory; 139 UINTN SizeBytes; 140} GBL_EFI_IMAGE_BUFFER; 141``` 142 143**Memory** \ 144Start address of the reserved buffer or NULL if caller should allocate. 145 146**SizeBytes** \ 147Size of the reserved buffer or amount of memory caller should allocate. 148 149## GBL_EFI_IMAGE_LOADING_PROTOCOL.GetVerifyPartitions() 150 151### Summary 152 153Query for list of partitions to be verified by GBL. 154 155### Prototype 156 157```c 158typedef 159EFI_STATUS 160(EFIAPI *GBL_EFI_GET_VERIFY_PARTITIONS) ( 161 IN GBL_EFI_IMAGE_LOADING_PROTOCOL *This, 162 IN OUT UINTN *NumberOfPartitions, 163 IN OUT GBL_EFI_PARTITION_NAME *Partitions, 164); 165``` 166 167### Parameters 168 169**This** \ 170A pointer to the 171[`GBL_EFI_IMAGE_LOADING_PROTOCOL`](#gbl_efi_image_loading_protocol) instance. 172 173**NumberOfPartitions** \ 174Number of elements in `Partitions[]`. Should be updated to 175number of partitions returned. If there are no partitions to be verified, 176`NumberOfPartitions` should be set to 0. 177 178**Partitions** \ 179Array of partitions' names that should be verified. Should be update on return. 180And contain `NumberOfPartitions` valid elements. 181 182### Description 183 184This function is used to override list of partitions to be verified by GBL. 185 186If this function is not implemented or returns `EFI_UNSUPPORTED` GBL will verify 187default list of partitions. 188 189[`GBL_EFI_PARTITION_NAME`](#gbl_efi_partition_name) is struct representing 190partition name. Partition name is UCS-2 string of at most 191`PARTITION_NAME_LEN_U16` elements with terminating `NULL` element. 192 193### Status Codes Returned 194 195||| 196| --- | --- | 197| EFI_SUCCESS | Successfully provided additional partitions to verify | 198| EFI_INVALID_PARAMETER | If `Partitions[]` is `NULL`, where `NumberOfPartitions != 0` | 199 200### Related Definitions 201 202#### GBL_EFI_PARTITION_NAME 203 204```c 205const size_t PARTITION_NAME_LEN_U16 = 36; 206 207typedef 208struct GBL_EFI_PARTITION_NAME { 209 CHAR16 StrUtf16[PARTITION_NAME_LEN_U16]; 210} GBL_EFI_PARTITION_NAME; 211``` 212 213**StrUtf16** \ 214UCS-2 C-String. This string contains partition name, that identifies what 215partition to use for additional validation. The string is at most 216`PARTITION_NAME_LEN_U16` of char16_t elements. E.g. `u"boot"`, `u"fdt"` 217 218#### GBL_EFI_IMAGE_INFO 219 220```c 221const size_t PARTITION_NAME_LEN_U16 = 36; 222 223typedef 224struct GBL_EFI_IMAGE_INFO { 225 CHAR16 ImageType[PARTITION_NAME_LEN_U16]; 226 UINTN SizeBytes; 227} GBL_EFI_IMAGE_INFO; 228``` 229 230**ImageType** \ 231UCS-2 C-String. This string describes the usage context for the buffer being 232queried. It should be at most `PARTITION_NAME_LEN_U16` of char16_t elements 233including terminating `u'\0'`. E.g. `u"dtb"` 234 235Below are usage strings reserved by GBL. 236 237```c 238//****************************************************** 239// GBL reserved image types 240//****************************************************** 241// Buffer for loading, verifying and fixing up OS images. 242#define GBL_IMAGE_TYPE_OS_LOAD L"os_load" 243// Buffer for use as fastboot download buffer. 244#define GBL_IMAGE_TYPE_FASTBOOT L"fastboot" 245``` 246 247**SizeBytes** \ 248Size of the buffer or allocation suggested by the caller. 249