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