From dfaa76349d4aedf19ff3e5b44e2ae4cbd12ce0d2 Mon Sep 17 00:00:00 2001 From: Dmitrii Merkurev Date: Thu, 28 May 2026 19:33:41 +0000 Subject: [PATCH] EmbeddedPkg: Introduce GBL protocols MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GBL (Generic Bootloader) is Google's UEFI-based bootloader for Android. It runs as an EFI application and delegates board- and platform-specific operations to the underlying firmware through GBL-defined EFI protocols. This patch adds only the header definitions (GUIDs, revisions and interfaces) for those protocols, covering Android Verified Boot, AVF, A/B boot-control, boot-memory, debug, Fastboot (and its transport) and OS configuration. For details, see: https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/README.md Co-authored-by: David Pursell Co-authored-by: Dov Shlachter Co-authored-by: Jakob Vukalović Co-authored-by: Kelvin Zhang Co-authored-by: Ram Muthiah Co-authored-by: Sergii Parubochyi Co-authored-by: Yecheng Zhao Co-authored-by: Yi-Yo Chiang Signed-off-by: Dmitrii Merkurev --- EmbeddedPkg/EmbeddedPkg.dec | 8 + EmbeddedPkg/Include/Protocol/GblEfiAvb.h | 187 ++++++++++++++++++ EmbeddedPkg/Include/Protocol/GblEfiAvf.h | 51 +++++ .../Include/Protocol/GblEfiBootControl.h | 113 +++++++++++ .../Include/Protocol/GblEfiBootMemory.h | 74 +++++++ EmbeddedPkg/Include/Protocol/GblEfiDebug.h | 48 +++++ EmbeddedPkg/Include/Protocol/GblEfiFastboot.h | 121 ++++++++++++ .../Protocol/GblEfiFastbootTransport.h | 78 ++++++++ .../Include/Protocol/GblEfiOsConfiguration.h | 93 +++++++++ 9 files changed, 773 insertions(+) create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiAvb.h create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiAvf.h create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiBootControl.h create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiBootMemory.h create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiDebug.h create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiFastboot.h create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiFastbootTransport.h create mode 100644 EmbeddedPkg/Include/Protocol/GblEfiOsConfiguration.h diff --git a/EmbeddedPkg/EmbeddedPkg.dec b/EmbeddedPkg/EmbeddedPkg.dec index 2daa785405..4388abbc92 100644 --- a/EmbeddedPkg/EmbeddedPkg.dec +++ b/EmbeddedPkg/EmbeddedPkg.dec @@ -85,6 +85,14 @@ gPlatformVirtualKeyboardProtocolGuid = { 0x0e3606d2, 0x1dc3, 0x4e6f, { 0xbe, 0x65, 0x39, 0x49, 0x82, 0xa2, 0x65, 0x47 }} gAndroidBootImgProtocolGuid = { 0x9859bb19, 0x407c, 0x4f8b, {0xbc, 0xe1, 0xf8, 0xda, 0x65, 0x65, 0xf4, 0xa5 }} gFdtClientProtocolGuid = { 0xE11FACA0, 0x4710, 0x4C8E, { 0xA7, 0xA2, 0x01, 0xBA, 0xA2, 0x59, 0x1B, 0x4C } } + gGblEfiAvbProtocolGuid = { 0x6bc66b9a, 0xd5c9, 0x4c02, { 0x9d, 0xa9, 0x50, 0xaf, 0x19, 0x8d, 0x91, 0x2c } } + gGblEfiAvfProtocolGuid = { 0xe7f1c4a6, 0x0a52, 0x4f61, { 0xbd, 0x98, 0x9e, 0x60, 0xb5, 0x59, 0x45, 0x2a } } + gGblEfiBootControlProtocolGuid = { 0xd382db1b, 0x9ac2, 0x11f0, { 0x84, 0xc7, 0x04, 0x7b, 0xcb, 0xa9, 0x60, 0x19 } } + gGblEfiBootMemoryProtocolGuid = { 0x309f2874, 0xad59, 0x4fd2, { 0xaf, 0x5e, 0xce, 0x0f, 0x4a, 0xb4, 0x01, 0xa6 } } + gGblEfiDebugProtocolGuid = { 0x98ca3da1, 0xc1ac, 0x4402, { 0x9c, 0x16, 0x75, 0x58, 0xd3, 0xed, 0x57, 0x05 } } + gGblEfiFastbootProtocolGuid = { 0xc67e48a0, 0x5eb8, 0x4127, { 0xbe, 0x89, 0xdf, 0x2e, 0xd9, 0x3d, 0x8a, 0x9a } } + gGblEfiFastbootTransportProtocolGuid = { 0xedade92c, 0x5c48, 0x440d, { 0x84, 0x9c, 0xe2, 0xa0, 0xc7, 0xe5, 0x51, 0x43 } } + gGblEfiOsConfigurationProtocolGuid = { 0xdda0d135, 0xaa5b, 0x42ff, { 0x85, 0xac, 0xe3, 0xad, 0x6e, 0xfb, 0x46, 0x19 } } [Ppis] gEdkiiEmbeddedGpioPpiGuid = { 0x21c3b115, 0x4e0b, 0x470c, { 0x85, 0xc7, 0xe1, 0x05, 0xa5, 0x75, 0xc9, 0x7b }} diff --git a/EmbeddedPkg/Include/Protocol/GblEfiAvb.h b/EmbeddedPkg/Include/Protocol/GblEfiAvb.h new file mode 100644 index 0000000000..983cd9d74e --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiAvb.h @@ -0,0 +1,187 @@ +/** @file + GBL EFI AVB Protocol. + + Delegates Android Verified Boot (AVB) board-specific logic to firmware. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_avb_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {6bc66b9a-d5c9-4c02-9da9-50af198d912c} +// +#define GBL_EFI_AVB_PROTOCOL_GUID \ + { 0x6bc66b9a, 0xd5c9, 0x4c02, { 0x9d, 0xa9, 0x50, 0xaf, 0x19, 0x8d, 0x91, 0x2c } } + +#define GBL_EFI_AVB_PROTOCOL_REVISION 0x00010000 + +typedef struct _GBL_EFI_AVB_PROTOCOL GBL_EFI_AVB_PROTOCOL; + +typedef UINT64 GBL_EFI_AVB_DEVICE_STATUS; +#define GBL_EFI_AVB_DEVICE_STATUS_UNLOCKED BIT0 +#define GBL_EFI_AVB_DEVICE_STATUS_DM_VERITY_FAILED BIT1 +#define GBL_EFI_AVB_DEVICE_STATUS_UNLOCKED_CRITICAL BIT2 +#define GBL_EFI_AVB_DEVICE_STATUS_UNLOCKABLE BIT3 + +typedef UINT64 GBL_EFI_AVB_BOOT_COLOR; +#define GBL_EFI_AVB_BOOT_COLOR_RED BIT0 +#define GBL_EFI_AVB_BOOT_COLOR_ORANGE BIT1 +#define GBL_EFI_AVB_BOOT_COLOR_YELLOW BIT2 +#define GBL_EFI_AVB_BOOT_COLOR_GREEN BIT3 +#define GBL_EFI_AVB_BOOT_COLOR_RED_EIO BIT4 + +typedef UINT64 GBL_EFI_AVB_PARTITION_FLAGS; +#define GBL_EFI_AVB_PARTITION_FLAG_VERIFY BIT0 +#define GBL_EFI_AVB_PARTITION_FLAG_VERIFY_IF_EXISTS BIT1 +#define GBL_EFI_AVB_PARTITION_FLAG_FLASH_CRITICAL BIT2 +#define GBL_EFI_AVB_PARTITION_FLAG_FDR BIT3 + +typedef enum { + GblEfiAvbKeyValidationStatusInvalid = 0, + GblEfiAvbKeyValidationStatusValidCustomKey, + GblEfiAvbKeyValidationStatusValid +} GBL_EFI_AVB_KEY_VALIDATION_STATUS; + +typedef enum { + GblEfiAvbLockTypeDevice = 0, + GblEfiAvbLockTypeCritical +} GBL_EFI_AVB_LOCK_TYPE; + +typedef enum { + GblEfiAvbLockStateUnlocked = 0, + GblEfiAvbLockStateLocked +} GBL_EFI_AVB_LOCK_STATE; + +typedef struct { + UINTN BaseNameLen; + CHAR8 *BaseName; // UTF-8, null terminated + GBL_EFI_AVB_PARTITION_FLAGS Flags; +} GBL_EFI_AVB_PARTITION_ATTRIBUTES; + +typedef struct { + CONST CHAR8 *BaseName; // UTF-8 null terminated + UINTN DataSize; + CONST UINT8 *Data; +} GBL_EFI_AVB_LOADED_PARTITION; + +typedef struct { + CONST CHAR8 *BasePartitionName; // UTF-8, null terminated + CONST CHAR8 *Key; // UTF-8, null terminated + UINTN ValueSize; + CONST UINT8 *Value; +} GBL_EFI_AVB_PROPERTY; + +typedef struct { + GBL_EFI_AVB_BOOT_COLOR ColorFlags; + CONST CHAR8 *Digest; // UTF-8, null terminated + UINTN NumPartitions; + CONST GBL_EFI_AVB_LOADED_PARTITION *Partitions; + UINTN NumProperties; + CONST GBL_EFI_AVB_PROPERTY *Properties; + UINT64 Reserved[8]; +} GBL_EFI_AVB_VERIFICATION_RESULT; + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_READ_PARTITION_ATTRIBUTES)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN OUT UINTN *NumPartitions, + IN OUT GBL_EFI_AVB_PARTITION_ATTRIBUTES *Partitions + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_READ_DEVICE_STATUS)( + IN GBL_EFI_AVB_PROTOCOL *This, + OUT GBL_EFI_AVB_DEVICE_STATUS *StatusFlags + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN UINTN PublicKeyLength, + IN CONST UINT8 *PublicKeyData, + IN UINTN PublicKeyMetadataLength, + IN CONST UINT8 *PublicKeyMetadata, + OUT UINT32 *ValidationStatus // GBL_EFI_AVB_KEY_VALIDATION_STATUS + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_READ_ROLLBACK_INDEX)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN UINTN IndexLocation, + OUT UINT64 *RollbackIndex + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_WRITE_ROLLBACK_INDEX)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN UINTN IndexLocation, + IN UINT64 RollbackIndex + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_READ_PERSISTENT_VALUE)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN CONST CHAR8 *Name, + IN OUT UINTN *ValueSize, + OUT UINT8 *Value + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_WRITE_PERSISTENT_VALUE)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN CONST CHAR8 *Name, + IN UINTN ValueSize, + IN CONST UINT8 *Value + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN CONST GBL_EFI_AVB_VERIFICATION_RESULT *Result + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_WRITE_LOCK_STATE)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN UINT8 Type, // GBL_EFI_AVB_LOCK_TYPE + IN UINT8 State // GBL_EFI_AVB_LOCK_STATE + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVB_FACTORY_DATA_RESET)( + IN GBL_EFI_AVB_PROTOCOL *This + ); + +struct _GBL_EFI_AVB_PROTOCOL { + UINT64 Revision; + GBL_EFI_AVB_READ_PARTITION_ATTRIBUTES ReadPartitionAttributes; + GBL_EFI_AVB_READ_DEVICE_STATUS ReadDeviceStatus; + GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY ValidateVbmetaPublicKey; + GBL_EFI_AVB_READ_ROLLBACK_INDEX ReadRollbackIndex; + GBL_EFI_AVB_WRITE_ROLLBACK_INDEX WriteRollbackIndex; + GBL_EFI_AVB_READ_PERSISTENT_VALUE ReadPersistentValue; + GBL_EFI_AVB_WRITE_PERSISTENT_VALUE WritePersistentValue; + GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT HandleVerificationResult; + GBL_EFI_AVB_WRITE_LOCK_STATE WriteLockState; + GBL_EFI_AVB_FACTORY_DATA_RESET FactoryDataReset; +}; + +extern EFI_GUID gGblEfiAvbProtocolGuid; diff --git a/EmbeddedPkg/Include/Protocol/GblEfiAvf.h b/EmbeddedPkg/Include/Protocol/GblEfiAvf.h new file mode 100644 index 0000000000..99fd243193 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiAvf.h @@ -0,0 +1,51 @@ +/** @file + GBL EFI AVF Protocol. + + Supplies GBL with vendor DICE handover and Secret Keeper public key + needed for Android Virtualization Framework. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_avf_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {e7f1c4a6-0a52-4f61-bd98-9e60b559452a} +// +#define GBL_EFI_AVF_PROTOCOL_GUID \ + { 0xe7f1c4a6, 0x0a52, 0x4f61, { 0xbd, 0x98, 0x9e, 0x60, 0xb5, 0x59, 0x45, 0x2a } } + +#define GBL_EFI_AVF_PROTOCOL_REVISION 0x00010000 + +typedef struct _GBL_EFI_AVF_PROTOCOL GBL_EFI_AVF_PROTOCOL; + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVF_READ_VENDOR_DICE_HANDOVER)( + IN GBL_EFI_AVF_PROTOCOL *This, + IN OUT UINTN *HandoverSize, + OUT UINT8 *Handover + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_AVF_READ_SECRET_KEEPER_PUBLIC_KEY)( + IN GBL_EFI_AVF_PROTOCOL *This, + IN OUT UINTN *PublicKeySize, + OUT UINT8 *PublicKey + ); + +struct _GBL_EFI_AVF_PROTOCOL { + UINT64 Revision; + GBL_EFI_AVF_READ_VENDOR_DICE_HANDOVER ReadVendorDiceHandover; + GBL_EFI_AVF_READ_SECRET_KEEPER_PUBLIC_KEY ReadSecretKeeperPublicKey; +}; + +extern EFI_GUID gGblEfiAvfProtocolGuid; diff --git a/EmbeddedPkg/Include/Protocol/GblEfiBootControl.h b/EmbeddedPkg/Include/Protocol/GblEfiBootControl.h new file mode 100644 index 0000000000..55733c9ab5 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiBootControl.h @@ -0,0 +1,113 @@ +/** @file + GBL EFI Boot Control Protocol. + + Delegates boot target manipulation logic to firmware. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_boot_control_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {d382db1b-9ac2-11f0-84c7-047bcba96019} +// +#define GBL_EFI_BOOT_CONTROL_PROTOCOL_GUID \ + { 0xd382db1b, 0x9ac2, 0x11f0, { 0x84, 0xc7, 0x04, 0x7b, 0xcb, 0xa9, 0x60, 0x19 } } + +#define GBL_EFI_BOOT_CONTROL_PROTOCOL_REVISION 0x00010000 + +typedef struct _GBL_EFI_BOOT_CONTROL_PROTOCOL GBL_EFI_BOOT_CONTROL_PROTOCOL; + +typedef enum { + GblEfiUnbootableReasonUnknownReason, + GblEfiUnbootableReasonNoMoreTries, + GblEfiUnbootableReasonSystemUpdate, + GblEfiUnbootableReasonUserRequested, + GblEfiUnbootableReasonVerificationFailure +} GBL_EFI_UNBOOTABLE_REASON; + +typedef enum { + GblEfiOneShotBootModeNone, + GblEfiOneShotBootModeBootloader, + GblEfiOneShotBootModeRecovery +} GBL_EFI_ONE_SHOT_BOOT_MODE; + +typedef struct { + UINT32 Suffix; // One UTF-8 encoded single character. + UINT8 UnbootableReason; // GBL_EFI_UNBOOTABLE_REASON + UINT8 Priority; + UINT8 RemainingTries; + UINT8 Successful; +} GBL_EFI_SLOT_INFO; + +typedef struct { + UINTN KernelSize; + EFI_PHYSICAL_ADDRESS Kernel; + UINTN RamdiskSize; + EFI_PHYSICAL_ADDRESS Ramdisk; + UINTN DeviceTreeSize; + EFI_PHYSICAL_ADDRESS DeviceTree; + UINT64 Reserved[8]; +} GBL_EFI_LOADED_OS; + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_SLOT_COUNT)( + IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This, + OUT UINT8 *SlotCount + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_SLOT_INFO)( + IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This, + IN UINT8 Index, + OUT GBL_EFI_SLOT_INFO *Info + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_CURRENT_SLOT)( + IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This, + OUT GBL_EFI_SLOT_INFO *Info + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_CONTROL_SET_ACTIVE_SLOT)( + IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This, + IN UINT8 Index + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_ONE_SHOT_BOOT_MODE)( + IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This, + OUT UINT32 *Mode // GBL_EFI_ONE_SHOT_BOOT_MODE + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_CONTROL_HANDLE_LOADED_OS)( + IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This, + IN CONST GBL_EFI_LOADED_OS *Os + ); + +struct _GBL_EFI_BOOT_CONTROL_PROTOCOL { + UINT64 Revision; + GBL_EFI_BOOT_CONTROL_GET_SLOT_COUNT GetSlotCount; + GBL_EFI_BOOT_CONTROL_GET_SLOT_INFO GetSlotInfo; + GBL_EFI_BOOT_CONTROL_GET_CURRENT_SLOT GetCurrentSlot; + GBL_EFI_BOOT_CONTROL_SET_ACTIVE_SLOT SetActiveSlot; + GBL_EFI_BOOT_CONTROL_GET_ONE_SHOT_BOOT_MODE GetOneShotBootMode; + GBL_EFI_BOOT_CONTROL_HANDLE_LOADED_OS HandleLoadedOs; +}; + +extern EFI_GUID gGblEfiBootControlProtocolGuid; diff --git a/EmbeddedPkg/Include/Protocol/GblEfiBootMemory.h b/EmbeddedPkg/Include/Protocol/GblEfiBootMemory.h new file mode 100644 index 0000000000..5c34230c77 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiBootMemory.h @@ -0,0 +1,74 @@ +/** @file + GBL EFI Boot Memory Protocol. + + Provides APIs for retrieving and synchronizing boot and partition buffers. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_boot_memory_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {309f2874-ad59-4fd2-af5e-ce0f4ab401a6} +// +#define GBL_EFI_BOOT_MEMORY_PROTOCOL_GUID \ + { 0x309f2874, 0xad59, 0x4fd2, { 0xaf, 0x5e, 0xce, 0x0f, 0x4a, 0xb4, 0x01, 0xa6 } } + +#define GBL_EFI_BOOT_MEMORY_PROTOCOL_REVISION 0x00010000 + +typedef struct _GBL_EFI_BOOT_MEMORY_PROTOCOL GBL_EFI_BOOT_MEMORY_PROTOCOL; + +typedef enum { + GblEfiBootBufferTypeGeneralLoad = 0, + GblEfiBootBufferTypeKernel, + GblEfiBootBufferTypeRamdisk, + GblEfiBootBufferTypeFdt, + GblEfiBootBufferTypePvmfwData, + GblEfiBootBufferTypeFastbootDownload +} GBL_EFI_BOOT_BUFFER_TYPE; + +typedef enum { + GblEfiPartitionBufferFlagPreloaded = BIT0 +} GBL_EFI_PARTITION_BUFFER_FLAG; + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_MEMORY_GET_PARTITION_BUFFER)( + IN GBL_EFI_BOOT_MEMORY_PROTOCOL *This, + IN CONST CHAR8 *BaseName, + OUT UINTN *Size, + OUT VOID **Addr, + OUT UINT32 *Flag // GBL_EFI_PARTITION_BUFFER_FLAG + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_MEMORY_SYNC_PARTITION_BUFFER)( + IN GBL_EFI_BOOT_MEMORY_PROTOCOL *This, + IN BOOLEAN SyncPreloaded + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_BOOT_MEMORY_GET_BOOT_BUFFER)( + IN GBL_EFI_BOOT_MEMORY_PROTOCOL *This, + IN UINT32 BufType, // GBL_EFI_BOOT_BUFFER_TYPE + OUT UINTN *Size, + OUT VOID **Addr + ); + +struct _GBL_EFI_BOOT_MEMORY_PROTOCOL { + UINT64 Revision; + GBL_EFI_BOOT_MEMORY_GET_PARTITION_BUFFER GetPartitionBuffer; + GBL_EFI_BOOT_MEMORY_SYNC_PARTITION_BUFFER SyncPartitionBuffer; + GBL_EFI_BOOT_MEMORY_GET_BOOT_BUFFER GetBootBuffer; +}; + +extern EFI_GUID gGblEfiBootMemoryProtocolGuid; diff --git a/EmbeddedPkg/Include/Protocol/GblEfiDebug.h b/EmbeddedPkg/Include/Protocol/GblEfiDebug.h new file mode 100644 index 0000000000..c67d089ae7 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiDebug.h @@ -0,0 +1,48 @@ +/** @file + GBL EFI Debug Protocol. + + Allows GBL to notify firmware of fatal errors or debug events. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_debug_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {98ca3da1-c1ac-4402-9c16-7558d3ed5705} +// +#define GBL_EFI_DEBUG_PROTOCOL_GUID \ + { 0x98ca3da1, 0xc1ac, 0x4402, { 0x9c, 0x16, 0x75, 0x58, 0xd3, 0xed, 0x57, 0x05 } } + +#define GBL_EFI_DEBUG_PROTOCOL_REVISION 0x00010000 + +typedef struct _GBL_EFI_DEBUG_PROTOCOL GBL_EFI_DEBUG_PROTOCOL; + +typedef enum { + GblEfiDebugErrorTagAssertionError, + GblEfiDebugErrorTagPartition, + GblEfiDebugErrorTagLoadImage, + GblEfiDebugErrorTagBootError +} GBL_EFI_DEBUG_ERROR_TAG; + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_DEBUG_FATAL_ERROR)( + IN GBL_EFI_DEBUG_PROTOCOL *This, + IN CONST VOID *FramePtr, + IN UINT64 Tag // GBL_EFI_DEBUG_ERROR_TAG + ); + +struct _GBL_EFI_DEBUG_PROTOCOL { + UINT64 Revision; + GBL_EFI_DEBUG_FATAL_ERROR FatalError; +}; + +extern EFI_GUID gGblEfiDebugProtocolGuid; diff --git a/EmbeddedPkg/Include/Protocol/GblEfiFastboot.h b/EmbeddedPkg/Include/Protocol/GblEfiFastboot.h new file mode 100644 index 0000000000..31514fd160 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiFastboot.h @@ -0,0 +1,121 @@ +/** @file + GBL EFI Fastboot Protocol. + + Platform-specific helpers for Android Fastboot operations. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_fastboot_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {c67e48a0-5eb8-4127-be89-df2ed93d8a9a} +// +#define GBL_EFI_FASTBOOT_PROTOCOL_GUID \ + { 0xc67e48a0, 0x5eb8, 0x4127, { 0xbe, 0x89, 0xdf, 0x2e, 0xd9, 0x3d, 0x8a, 0x9a } } + +#define GBL_EFI_FASTBOOT_PROTOCOL_REVISION 0x00010000 + +#define GBL_EFI_FASTBOOT_SERIAL_NUMBER_MAX_LEN_UTF8 32 +#define GBL_EFI_FASTBOOT_PARTITION_TYPE_BUF_LEN 56 + +typedef struct _GBL_EFI_FASTBOOT_PROTOCOL GBL_EFI_FASTBOOT_PROTOCOL; + +typedef enum { + GblEfiFastbootMessageTypeOkay, + GblEfiFastbootMessageTypeFail, + GblEfiFastbootMessageTypeInfo +} GBL_EFI_FASTBOOT_MESSAGE_TYPE; + +typedef enum { + GblEfiFastbootCommandExecResultProhibited, + GblEfiFastbootCommandExecResultDefaultImpl, + GblEfiFastbootCommandExecResultCustomImpl +} GBL_EFI_FASTBOOT_COMMAND_EXEC_RESULT; + +typedef +VOID +(EFIAPI *GBL_EFI_FASTBOOT_GET_VAR_ALL_CALLBACK)( + IN VOID *Context, + IN UINTN NumArgs, + IN CONST CHAR8 *CONST *Args, + IN CONST CHAR8 *Value + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_MESSAGE_SENDER)( + IN VOID *Context, + IN UINT32 MsgType, // GBL_EFI_FASTBOOT_MESSAGE_TYPE + IN UINTN MsgLen, + IN CONST CHAR8 *Msg + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_GET_VAR)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN UINTN NumArgs, + IN CONST CHAR8 *CONST *Args, + IN OUT UINTN *BufferSize, + OUT CHAR8 *Buffer + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_GET_VAR_ALL)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN VOID *Context, + IN GBL_EFI_FASTBOOT_GET_VAR_ALL_CALLBACK Callback + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_GET_STAGED)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN OUT UINTN *BufferSize, + OUT UINTN *BufferRemains, + OUT UINT8 *Buffer + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_COMMAND_EXEC)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN UINTN NumArgs, + IN CONST CHAR8 *CONST *Args, + IN UINTN DownloadBufferSize, + IN UINTN DownloadBufferUsedSize, + IN UINT8 *DownloadBuffer, + OUT UINT32 *Implementation, // GBL_EFI_FASTBOOT_COMMAND_EXEC_RESULT + IN GBL_EFI_FASTBOOT_MESSAGE_SENDER Sender, + IN VOID *Context + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_GET_PARTITION_TYPE)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN CONST CHAR8 *PartName, + IN OUT UINTN *PartTypeLen, + OUT CHAR8 *PartType + ); + +struct _GBL_EFI_FASTBOOT_PROTOCOL { + UINT64 Revision; + CHAR8 SerialNumber[GBL_EFI_FASTBOOT_SERIAL_NUMBER_MAX_LEN_UTF8]; + GBL_EFI_FASTBOOT_GET_VAR GetVar; + GBL_EFI_FASTBOOT_GET_VAR_ALL GetVarAll; + GBL_EFI_FASTBOOT_GET_STAGED GetStaged; + GBL_EFI_FASTBOOT_COMMAND_EXEC CommandExec; + GBL_EFI_FASTBOOT_GET_PARTITION_TYPE GetPartitionType; +}; + +extern EFI_GUID gGblEfiFastbootProtocolGuid; diff --git a/EmbeddedPkg/Include/Protocol/GblEfiFastbootTransport.h b/EmbeddedPkg/Include/Protocol/GblEfiFastbootTransport.h new file mode 100644 index 0000000000..c6a563f1cb --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiFastbootTransport.h @@ -0,0 +1,78 @@ +/** @file + GBL EFI Fastboot Transport Protocol. + + Enables firmware to expose a transport interface for Android Fastboot. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_fastboot_transport_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {edade92c-5c48-440d-849c-e2a0c7e55143} +// +#define GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL_GUID \ + { 0xedade92c, 0x5c48, 0x440d, { 0x84, 0x9c, 0xe2, 0xa0, 0xc7, 0xe5, 0x51, 0x43 } } + +#define GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL_REVISION 0x00010000 + +typedef struct _GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL; + +typedef enum { + GblEfiFastbootRxModeSinglePacket = 0, + GblEfiFastbootRxModeFixedLength +} GBL_EFI_FASTBOOT_RX_MODE; + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_TRANSPORT_START)( + IN GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL *This + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_TRANSPORT_STOP)( + IN GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL *This + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_TRANSPORT_RECEIVE)( + IN GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL *This, + IN OUT UINTN *BufferSize, + OUT VOID *Buffer, + IN UINT32 Mode // GBL_EFI_FASTBOOT_RX_MODE + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_TRANSPORT_SEND)( + IN GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL *This, + IN OUT UINTN *BufferSize, + IN CONST VOID *Buffer + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_TRANSPORT_FLUSH)( + IN GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL *This + ); + +struct _GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL { + UINT64 Revision; + CONST CHAR8 *Description; + GBL_EFI_FASTBOOT_TRANSPORT_START Start; + GBL_EFI_FASTBOOT_TRANSPORT_STOP Stop; + GBL_EFI_FASTBOOT_TRANSPORT_RECEIVE Receive; + GBL_EFI_FASTBOOT_TRANSPORT_SEND Send; + GBL_EFI_FASTBOOT_TRANSPORT_FLUSH Flush; +}; + +extern EFI_GUID gGblEfiFastbootTransportProtocolGuid; diff --git a/EmbeddedPkg/Include/Protocol/GblEfiOsConfiguration.h b/EmbeddedPkg/Include/Protocol/GblEfiOsConfiguration.h new file mode 100644 index 0000000000..c5276706ad --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiOsConfiguration.h @@ -0,0 +1,93 @@ +/** @file + GBL EFI OS Configuration Protocol. + + Lets firmware fix up kernel bootconfig, and choose device-tree components at + boot time. + + Related docs: + https://android.googlesource.com/platform/bootable/libbootloader/+/refs/heads/gbl-mainline/gbl/docs/gbl_efi_os_configuration_protocol.md + + Copyright (c) 2025, The Android Open Source Project.
+ SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#pragma once + +#include + +// +// {dda0d135-aa5b-42ff-85ac-e3ad6efb4619} +// +#define GBL_EFI_OS_CONFIGURATION_PROTOCOL_GUID \ + { 0xdda0d135, 0xaa5b, 0x42ff, { 0x85, 0xac, 0xe3, 0xad, 0x6e, 0xfb, 0x46, 0x19 } } + +#define GBL_EFI_OS_CONFIGURATION_PROTOCOL_REVISION 0x00010000 + +typedef struct _GBL_EFI_OS_CONFIGURATION_PROTOCOL GBL_EFI_OS_CONFIGURATION_PROTOCOL; + +typedef enum { + GblEfiDeviceTreeTypeDeviceTree, + GblEfiDeviceTreeTypeOverlay, + GblEfiDeviceTreeTypePvmDaOverlay +} GBL_EFI_DEVICE_TREE_TYPE; + +typedef enum { + GblEfiDeviceTreeSourceBoot, + GblEfiDeviceTreeSourceVendorBoot, + GblEfiDeviceTreeSourceDtbo, + GblEfiDeviceTreeSourceDtb +} GBL_EFI_DEVICE_TREE_SOURCE; + +typedef struct { + UINT32 Source; // GBL_EFI_DEVICE_TREE_SOURCE + UINT32 Type; // GBL_EFI_DEVICE_TREE_TYPE + UINT32 Id; + UINT32 Rev; + UINTN CustomSize; + CONST UINT8 *Custom; +} GBL_EFI_DEVICE_TREE_METADATA; + +typedef struct { + GBL_EFI_DEVICE_TREE_METADATA Metadata; + CONST VOID *DeviceTree; // 8-byte aligned, never NULL + BOOLEAN Selected; +} GBL_EFI_VERIFIED_DEVICE_TREE; + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FIXUP_BOOTCONFIG)( + IN GBL_EFI_OS_CONFIGURATION_PROTOCOL *This, + IN UINTN BootConfigSize, + IN CONST CHAR8 *BootConfig, + IN OUT UINTN *FixupBufferSize, + OUT CHAR8 *Fixup + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_SELECT_DEVICE_TREES)( + IN GBL_EFI_OS_CONFIGURATION_PROTOCOL *This, + IN UINTN NumDeviceTrees, + IN OUT GBL_EFI_VERIFIED_DEVICE_TREE *DeviceTrees + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_SELECT_FIT_CONFIGURATION)( + IN GBL_EFI_OS_CONFIGURATION_PROTOCOL *This, + IN UINTN FitSize, + IN CONST UINT8 *Fit, + IN UINTN MetadataSize, + IN CONST UINT8 *Metadata, + OUT UINTN *SelectedConfigurationOffset + ); + +struct _GBL_EFI_OS_CONFIGURATION_PROTOCOL { + UINT64 Revision; + GBL_EFI_FIXUP_BOOTCONFIG FixupBootConfig; + GBL_EFI_SELECT_DEVICE_TREES SelectDeviceTrees; + GBL_EFI_SELECT_FIT_CONFIGURATION SelectFitConfiguration; +}; + +extern EFI_GUID gGblEfiOsConfigurationProtocolGuid;