1# GBL EFI Fastboot Protocol 2 3This document describes the GBL Fastboot protocol. The protocol defines 4interfaces that can be used by EFI applications to query and modify vendor-specific 5information on a device that may be desired in the context of a fastboot environment. 6 7| | | 8|:------------|-------------------:| 9| **Status** | *Work in progress* | 10| **Created** | 2024-9-11 | 11 12## `GBL_EFI_FASTBOOT_PROTOCOL` 13 14### Summary 15 16This protocol provides interfaces for platform-specific operations during Fastboot. 17This can include support for vendor defined variables or variables whose query 18requires cooperation with vendor firmware, OEM commands, 19 20### GUID 21```c 22// {c67e48a0-5eb8-4127-be89-df2ed93d8a9a} 23#define GBL_EFI_FASTBOOT_PROTOCOL_GUID \ 24 { \ 25 0xc67e48a0, 0x5eb8, 0x4127, { \ 26 0xbe, 0x89, 0xdf, 0x2e, 0xd9, 0x3d, 0x8a, 0x9a \ 27 } \ 28 } 29``` 30 31### Revision Number 32 33```c 34#define GBL_EFI_FASTBOOT_PROTOCOL_REVISION 0x00000000 35``` 36 37### Protocol Interface Structure 38 39```c 40#define GBL_EFI_FASTBOOT_SERIAL_NUMBER_MAX_LEN_UTF8 32 41 42typedef struct _GBL_EFI_FASTBOOT_PROTOCOL { 43 UINT32 Revision 44 CHAR8 SerialNumber[GBL_EFI_FASTBOOT_SERIAL_NUMBER_MAX_LEN_UTF8]; 45 GBL_EFI_FASTBOOT_GET_VAR GetVar; 46 GBL_EFI_FASTBOOT_GET_VAR_ALL GetVarAll; 47 GBL_EFI_FASTBOOT_RUN_OEM_FUNCTION RunOemFunction; 48 GBL_EFI_FASTBOOT_GET_POLICY GetPolicy; 49 GBL_EFI_FASTBOOT_SET_LOCK SetLock; 50 GBL_EFI_FASTBOOT_CLEAR_LOCK ClearLock; 51 GBL_EFI_FASTBOOT_GET_PARTITION_PERMISSIONS GetPartitionPermissions; 52 GBL_EFI_FASTBOOT_WIPE_USER_DATA WipeUserData; 53} GBL_EFI_FASTBOOT_PROTOCOL; 54``` 55 56### Parameters 57 58**Revision** 59 60The revision to which the `GBL_EFI_FASTBOOT_PROTOCOL` adheres. 61All future revisions must be backwards compatible. 62If a future version is not backwards compatible, a different GUID must be used. 63 64**SerialNumber** 65 66The device serial number expressed as a Null-terminated UTF-8 encoded string. 67If the device serial number is 32 bytes long, the Null terminator must be excluded. 68If the device serial number is longer than 32 bytes, it must be truncated. 69 70**GetVar** 71 72Gets the value for the given fastboot variable. 73See [`GBL_EFI_FASTBOOT_PROTOCOL.GetVar()`](#gbl_efi_fastboot_protocolgetvar). 74 75**GetVarAll** 76 77Iterates all combinations of arguments and values for all fastboot variables. 78See [`GBL_EFI_FASTBOOT_PROTOCOL.GetVarAll()`](#gbl_efi_fastboot_protocolgetvarall). 79 80**RunOemFunction** 81 82Runs an OEM-defined command on the device. 83See [`GBL_EFI_FASTBOOT_PROTOCOL.RunOemFunction()`](#gbl_efi_fastboot_protocolrunoemfunction). 84 85**GetPolicy** 86 87Querys device policy including device lock state, whether the device firmware 88supports a 'critical' lock, and whether the device is capable of booting from 89an image loaded directly into RAM. 90See [`GBL_EFI_FASTBOOT_PROTOCOL.GetPolicy()`](#gbl_efi_fastboot_protocolgetpolicy). 91 92**SetLock** 93 94Enables device locks according to the provided ORed lock definitions. 95See [`GBL_EFI_FASTBOOT_PROTOCOL.SetLock()`](#gbl_efi_fastboot_protocolsetlock). 96 97**ClearLock** 98 99Removes devices locks according to the provided ORed lock definitions. 100See [`GBL_EFI_FASTBOOT_PROTOCOL.ClearLock()`](#gbl_efi_fastboot_protocolclearlock). 101 102**GetPartitionPermissions** 103 104Queries permissions information about the provided partition. 105See [`GBL_EFI_FASTBOOT_PROTOCOL.GetPartitionPermissions()`](#gbl_efi_fastboot_protocolgetpartitionpermissions). 106 107**WipeUserData** 108 109Erases all partitions containing user data. 110See [`GBL_EFI_FASTBOOT_PROTOCOL.WipeUserData()`](#gbl_efi_fastboot_protocolwipeuserdata). 111 112## `GBL_EFI_FASTBOOT_PROTOCOL.GetVar()` 113 114### Summary 115 116Gets the value for a fastboot variable. 117 118### Prototype 119 120```c 121typedef 122EFI_STATUS 123(EFIAPI * GBL_EFI_FASTBOOT_GET_VAR)( 124 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 125 IN CONST CHAR8* CONST* Args, 126 IN UINTN NumArgs, 127 OUT CHAR8* Buf, 128 IN OUT UINTN* BufSize, 129); 130``` 131 132### Parameters 133 134*This* 135 136A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) 137instance. 138 139*Args* 140 141A pointer to an array of NULL-terminated strings that contains the name of the 142variable followed by additional arguments. 143 144*NumArgs* 145 146The number of elements in the *Args* array. 147 148*Buf* 149 150A pointer to the data buffer to store the value of the variable as a UTF-8 151encoded string. 152 153*BufSize* 154 155On entry, the size in bytes of *Buf*. 156On exit, the size in bytes of the UTF-8 encoded string describing the value, 157excluding any Null-terminator. 158 159### Description 160 161`GetVar()` queries internal data structures and drivers to determine the value 162of the given variable. Variables may have zero or more additional arguments. 163These arguments are parsed by the caller and passed to `GetVar()` as an array 164of NULL-terminated UTF-8 encoded string. 165 166An example client interaction: 167```bash 168# A variable with no argument. 169$ fastboot getvar max-download-size 170OKAY0x20000000 171 172# A variable with two arguments. 173$ fastboot getvar block-device:0:total-blocks 174OKAY0x800000000000 175``` 176 177### Status Codes Returned 178 179| Return Code | Semantics | 180|:------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 181| `EFI_SUCCESS` | The variable was found and its value successfully serialized. | 182| `EFI_INVALID_PARAMETER` | One of *This*, *Args*, *Buf*, or *BufSize* is `NULL` | 183| `EFI_NOT_FOUND` | The first element of *Args* does not contain a known variable. | 184| `EFI_UNSUPPORTED` | The contents of *Args* do not contain a known variable with valid aruments. Any of the subarguments may be unknown, or too many or too few subarguments may be provided. | 185| `EFI_BUFFER_TOO_SMALL` | *Buf* is too small to store the serialized variable string. The value of *BufSize* is modified to contain the minimum necessary buffer size. | 186 187## `GBL_EFI_FASTBOOT_PROTOCOL.GetVarAll()` 188 189### Summary 190 191Iterates all combinations of variables and values. 192 193### Prototype 194 195```c 196typedef 197EFI_STATUS 198(EFIAPI * GBL_EFI_FASTBOOT_GET_VAR_ALL)( 199 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 200 IN VOID* Context 201 IN GBL_EFI_GET_VAR_ALL_CALLBACK GetVarAllCallback, 202); 203``` 204 205### Parameters 206 207*This* 208 209A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) 210instance. 211 212*Context* 213 214A pointer to the context data for `GetVarAllCallback`. 215 216*GetVarAllCallback* 217 218A pointer to a function of type `GBL_EFI_GET_VAR_ALL_CALLBACK`. It receives as 219parameter the `Context` pointer passed to this function, an array of 220NULL-terminated UTF8 strings containing variable name and additional arguments, 221the array length, and a NULL-terminated string representing the value. 222 223### Related Definitions 224 225```c 226typedef 227VOID (*GBL_EFI_GET_VAR_ALL_CALLBACK) ( 228 IN VOID* Context 229 IN CONST CHAR8* CONST* Args, 230 IN UINTN NumArgs, 231 IN CONST CHAR8* Value, 232); 233``` 234*Context* 235 236The pointer to the context passed to `GetVarAll()`. 237 238*Args* 239 240A pointer to an array of NULL-terminated strings that contains the name of the 241variable followed by additional arguments. 242 243*NumArgs* 244 245The number of elements in the *Args* array. 246 247*Value* 248 249A NULL-terminated string representing the value. 250 251### Description 252 253`GetVarAll()` iterates all combinations of arguments and values for all fastboot 254variables. For each combination, the function invokes the caller provided 255callback `GetVarAllCallback()` and passes the context, arguments and value. 256 257### Status Codes Returned 258 259| Return Code | Semantics | 260|:------------------------|:------------------------------------------------| 261| `EFI_SUCCESS` | Operation is successful. | 262| `EFI_INVALID_PARAMETER` | One of *This* or *GetVarAllCallback* is `NULL`. | 263 264## `GBL_EFI_FASTBOOT_PROTOCOL.RunOemFunction()` 265 266### Summary 267 268Runs a vendor defined function that requires firmware support. 269 270### Prototype 271 272```c 273typedef 274EFI_STATUS 275(EFIAPI * GBL_EFI_FASTBOOT_RUN_OEM_FUNCTION)( 276 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 277 IN CHAR8* Command, 278 IN UINTN CommandLen, 279 OUT CHAR8* Buf, 280 IN OUT UINTN* BufSize, 281); 282``` 283 284### Parameters 285 286*This* 287 288A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) instance. 289 290*Command* 291 292The command to run as a Null-terminated UTF-8 encoded string. 293 294*CommandLen* 295 296The length of the command in bytes, excluding any Null-terminator. 297 298*Buf* 299 300A pointer to the data buffer to store any output the command generates 301as a UTF-8 encoded, Null-terminated string. 302On success, this output will be sent to the connected client as an INFO message. 303On failure, this output will be sent to the connected client as a FAIL message. 304 305**Note:** GBL is the only expected caller for any method of 306`GBL_EFI_FASTBOOT_PROTOCOL`, including `RunOemFunction()`. 307For a non-zero `BufSize`, GBL and all other callers are required to set the 308first byte of `Buf` to `0`. GBL and all other callers are responsible for 309parsing `Buf` until the first Null-terminator or for `Buf + BufSize` bytes, 310whichever occurs first. 311 312*BufSize* 313 314On entry, the size in bytes of `Buf`. 315On exit, the size in bytes of the UTF-8 encoded string describing the value, 316excluding any Null-terminator. 317 318### Description 319 320`RunOemFunction()` runs a vendor defined Oem function. These functions can take 321arbitrary arguments or subcommands. The caller does no parsing or verification. 322All parsing and verification is the responsibility of the method 323implementation. Oem functions can display power or battery information, print 324or iterate over UEFI variables, or conduct arbitrary other operations. 325 326### Status Codes Returned 327 328| Return Code | Semantics | 329|:------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 330| `EFI_SUCCESS` | The call completed successfully. | 331| `EFI_INVALID_PARAMETER` | One of *This*, *Command*, *CommandLen*, *Buf*, or *BufSize* is `NULL` or improperly aligned. | 332| `EFI_BUFFER_TOO_SMALL` | The provided buffer is too small to store the serialized representation of the command output. The value of `BufSize` is modified to contain the minimum necessary buffer size. | 333| `EFI_UNSUPPORTED` | The command is not supported or is nonsensical. | 334| `EFI_ACCESS_DENIED` | The operation is not permitted in the current lock state. | 335 336## `GBL_EFI_FASTBOOT_PROTOCOL.GetPolicy()` 337 338### Summary 339 340Gets the device policy pertaining to locking and booting directly from RAM. 341 342### Prototype 343 344```c 345typedef 346EFI_STATUS 347(EFIAPI * GBL_EFI_FASTBOOT_GET_POLICY)( 348 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 349 OUT GBL_EFI_FASTBOOT_POLICY* Policy, 350); 351``` 352 353### Related Definitions 354 355```c 356typedef struct _GBL_EFI_FASTBOOT_POLICY { 357 // Indicates whether device can be unlocked. 358 BOOL CanUnlock; 359 // Device firmware supports 'critical' partition locking. 360 BOOL HasCriticalLock; 361 // Indicates whether device allows booting 362 // from images loaded directly from RAM. 363 BOOL CanRamBoot; 364} GBL_EFI_FASTBOOT_POLICY; 365 366``` 367 368### Parameters 369 370*This* 371 372A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) instance. 373 374*Policy* 375 376On exit contains the device policy. 377See [Related Definitions](#related-definitions-2) for the definition of `GBL_EFI_FASTBOOT_POLICY`. 378 379### Description 380 381Depending on various factors including whether the device 382is a development target or end-user device, 383certain operations may be prohibited. 384In particular, loading an image directly into RAM and then booting it 385is generally not permitted on anything except development hardware. 386Developer workflows and CI/CD infrastructure need to be able to query 387whether a device is able to be unlocked and whether RAM booting is permitted. 388 389See [`SetLock()`](#gbl_efi_fastboot_protocolsetlock) and [`ClearLock()`](#gbl_efi_fastboot_protocolclearlock) 390for methods that modify the device lock state. Querying lock state is handled by Android Verified Boot. 391 392### Status Codes 393 394| Return Code | Semantics | 395|:------------------------|:-----------------------------------------------------------| 396| `EFI_SUCCESS` | The device policy was successfuly retrieved. | 397| `EFI_INVALID_PARAMETER` | One of *This* or *Policy* is `NULL` or improperly aligned. | 398 399## `GBL_EFI_FASTBOOT_PROTOCOL.SetLock()` 400 401### Summary 402 403Sets device partition locks. 404 405### Prototype 406 407```c 408typedef 409EFI_STATUS 410(EFIAPI * GBL_EFI_FASTBOOT_SET_LOCK)( 411 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 412 IN UINT64 LockState, 413); 414``` 415 416### Related Definitions 417 418```c 419typedef enum _GBL_EFI_FASTBOOT_LOCK_FLAGS { 420 // All device partitions are locked. 421 GBL_EFI_FASTBOOT_GBL_EFI_LOCKED = 0x1 << 0, 422 // All 'critical' device partitions are locked. 423 // The 'critical' lock is optional, 424 // and which partitions are locked by the critical lock 425 // is a vendor implementation detail. 426 GBL_EFI_FASTBOOT_GBL_EFI_CRITICAL_LOCKED = 0x1 << 1, 427} GBL_EFI_FASTBOOT_LOCK_FLAGS; 428 429``` 430 431### Parameters 432 433*This* 434 435A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) instance. 436 437*LockState* 438 439The ORed value of all device partition locks to enable. 440When locked, partitions generally cannot be read, written, or erased via fastboot. 441See [Related Definitions](#related-definitions-3) for valid lock flags. 442 443### Description 444 445Device lock state determines what operations can be performed on device partitions. 446`SetLock()` enables the locks defined in *LockState*, some of which may already be set. 447No locks are cleared by any call to `SetLock()`. 448 449### Status Codes Returned 450 451| Return Code | Semantics | 452|:------------------------|:---------------------------------------------------| 453| `EFI_SUCCESS` | The call completed successfully. | 454| `EFI_INVALID_PARAMETER` | *This* is `NULL` or improperly aligned. | 455| `EFI_INVALID_PARAMETER` | The lock flags in *LockState* are invalid. | 456| `EFI_ACCESS_DENIED` | Device policy prohibited the change in lock state. | 457 458## `GBL_EFI_FASTBOOT_PROTOCOL.ClearLock()` 459 460### Summary 461 462Clears device partition locks. 463 464### Prototype 465 466```c 467typedef 468EFI_STATUS 469(EFIAPI * GBL_EFI_FASTBOOT_CLEAR_LOCK)( 470 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 471 IN UINT64 LockState, 472); 473``` 474 475### Parameters 476 477*This* 478 479A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) instance. 480 481*LockState* 482 483The ORed value of all device partition locks to disable. 484See the [Related Definitions](#related-definitions-3) for `SetLock()` for valid lock flags. 485 486### Description 487 488Device lock state determines what operations can be performed on device partitions. 489`ClearLock()` disables the locks defined in *LockState*, some of which may already be cleared. 490 491### Status Codes Returned 492 493| Return Code | Semantics | 494|:------------------------|:---------------------------------------------------| 495| `EFI_SUCCESS` | The call completed successfully. | 496| `EFI_INVALID_PARAMETER` | *This* is `NULL` or improperly aligned. | 497| `EFI_INVALID_PARAMETER` | The lock flags in *LockState* are invalid. | 498| `EFI_ACCESS_DENIED` | Device policy prohibited the change in lock state. | 499 500## `GBL_EFI_FASTBOOT_PROTOCOL.GetPartitionPermissions()` 501 502### Summary 503 504Gets access permission information about the given partition. 505 506### Prototype 507 508```c 509typedef 510EFI_STATUS 511(EFIAPI * GBL_EFI_FASTBOOT_GET_PARTITION_PERMISSIONS)( 512 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 513 IN CHAR8* PartName, 514 IN UINTN PartNameLen, 515 OUT UINT64 Permissions, 516); 517``` 518 519### Related Definitions 520 521```c 522typedef enum _GBL_EFI_FASTBOOT_PARTITION_PERMISSION_FLAGS { 523 // Firmware can read the given partition and send its data to fastboot client. 524 GBL_EFI_FASTBOOT_PARTITION_READ = 0x1 << 0, 525 // Firmware can overwrite the given partition. 526 GBL_EFI_FASTBOOT_PARTITION_WRITE = 0x1 << 1, 527 // Firmware can erase the given partition. 528 GBL_EFI_FASTBOOT_PARTITION_ERASE = 0x1 << 2, 529} GBL_EFI_FASTBOOT_PARTITION_PERMISSION_FLAGS; 530 531``` 532 533### Parameters 534 535*This* 536 537A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) instance. 538 539*PartName* 540 541The name of the partition to query as a UTF-8 encoded, Null-terminated string. 542 543*PartNameLen* 544 545The length of *PartName* in bytes, excluding any Null-terminator. 546 547*Permissions* 548 549On exit contains the ORed flags detailing the current fastboot permissions for 550the given partition. 551See [Related Definitions](#related-definitions-4) for flag value semantics. 552 553### Description 554 555Depending on device lock state, Android Verified Boot policy, and other factors, 556various partitions may have restricted permissions within a fastboot environment. 557`GetPartitionPermissions()` retrieves the current permissions 558for the requested partition. 559 560By default, unless overridden by device policy, no operations are permitted on 561any partition when the device is locked, and all operations are permitted 562on all partitions when the device is unlocked. 563 564### Status Codes 565 566| Return Code | Semantics | 567|:------------------------|:-----------------------------------------------------------------------------------| 568| `EFI_SUCCESS` | The partition permision information was successfully queried. | 569| `EFI_INVALID_PARAMETER` | One of *This*, *PartName*, or *Permissions* is `NULL` or improperly aligned. | 570| `EFI_NOT_FOUND` | There is no partition named *PartName*. | 571| `EFI_UNSUPPORTED` | The device does not have a partition permission policy different from the default. | 572 573## `GBL_EFI_FASTBOOT_PROTOCOL.WipeUserData()` 574 575### Summary 576 577Erases all partitions containing user data. 578 579### Prototype 580 581```c 582typedef 583EFI_STATUS 584(EFIAPI * GBL_EFI_FASTBOOT_WIPE_USER_DATA)( 585 IN GBL_EFI_FASTBOOT_PROTOCOL* This, 586); 587``` 588 589### Parameters 590 591*This* 592 593A pointer to the [`GBL_EFI_FASTBOOT_PROTOCOL`](#protocol-interface-structure) instance. 594 595### Description 596 597Device user data is often stored on a dedicated partition 598apart from kernel images or other system data. 599This helps protect user data during system upgrades. 600`WipeUserData()` erases all user data partitions. 601This can be used to restore a device to its factory settings, 602as part of a refurbishment process, or for testing purposes. 603 604### Status Codes 605 606| Return Code | Semantics | 607|:------------------------|:----------------------------------------------------------| 608| `EFI_SUCCESS` | User data was successfully wiped. | 609| `EFI_INVALID_PARAMETER` | *This* is `NULL` or improperly aligned. | 610| `EFI_ACCESS_DENIED` | The operation is not permitted in the current lock state. | 611| `EFI_DEVICE_ERROR` | There was a block device or storage error. | 612 613