From d18aa3dc463bca1e794426e79313c78b048d2888 Mon Sep 17 00:00:00 2001 From: Dmitrii Merkurev Date: Fri, 5 Sep 2025 21:27:44 +0000 Subject: [PATCH] EmbeddedPkg: Introduce GBL protocols MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Proposed by Google to boot Android using GBL: 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/Include/Protocol/GblEfiAvb.h | 161 ++++++++++++++++++ EmbeddedPkg/Include/Protocol/GblEfiAvf.h | 55 ++++++ .../Include/Protocol/GblEfiBootControl.h | 131 ++++++++++++++ .../Include/Protocol/GblEfiBootMemory.h | 78 +++++++++ EmbeddedPkg/Include/Protocol/GblEfiDebug.h | 52 ++++++ EmbeddedPkg/Include/Protocol/GblEfiFastboot.h | 147 ++++++++++++++++ .../Protocol/GblEfiFastbootTransport.h | 82 +++++++++ .../Include/Protocol/GblEfiOsConfiguration.h | 96 +++++++++++ 8 files changed, 802 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/Include/Protocol/GblEfiAvb.h b/EmbeddedPkg/Include/Protocol/GblEfiAvb.h new file mode 100644 index 000000000000..ccedd5aee532 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiAvb.h @@ -0,0 +1,161 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI AVB Protocol. + Delegates Android Verified Boot (AVB) board-specific logic to firmware. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_avb_protocol.md +*/ + +#ifndef GBL_EFI_AVB_PROTOCOL_H_ +#define GBL_EFI_AVB_PROTOCOL_H_ + +#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 0x00000003 + +typedef struct _GBL_EFI_AVB_PROTOCOL GBL_EFI_AVB_PROTOCOL; + +typedef UINT64 GBL_EFI_AVB_DEVICE_STATUS; +STATIC CONST GBL_EFI_AVB_DEVICE_STATUS GBL_EFI_AVB_DEVICE_STATUS_UNLOCKED = 0x1 << 0; +STATIC CONST GBL_EFI_AVB_DEVICE_STATUS GBL_EFI_AVB_DEVICE_STATUS_DM_VERITY_FAILED = 0x1 << 1; + +typedef UINT64 GBL_EFI_AVB_BOOT_COLOR; +STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_RED = 0x1 << 0; +STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_ORANGE = 0x1 << 1; +STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_YELLOW = 0x1 << 2; +STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_GREEN = 0x1 << 3; +STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_RED_EIO = 0x1 << 4; + +typedef UINT64 GBL_EFI_AVB_PARTITION_FLAGS; +static const GBL_EFI_AVB_PARTITION_FLAGS GBL_EFI_AVB_PARTITION_OPTIONAL = 0x1 << 0; + +typedef enum { + GBL_EFI_AVB_KEY_VALIDATION_STATUS_INVALID = 0, + GBL_EFI_AVB_KEY_VALIDATION_STATUS_VALID_CUSTOM_KEY, + GBL_EFI_AVB_KEY_VALIDATION_STATUS_VALID +} GBL_EFI_AVB_KEY_VALIDATION_STATUS; + +typedef struct { + UINTN BaseNameLen; + CHAR8 *BaseName; // UTF-8, null terminated + GBL_EFI_AVB_PARTITION_FLAGS Flags; +} GBL_EFI_AVB_PARTITION; + +typedef struct { + CHAR8 *BaseName; // UTF-8 null terminated + UINTN DataSize; + 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; + // UTF-8, null terminated + CONST CHAR8 *Digest; + 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_PARTITIONS_TO_VERIFY)( + IN GBL_EFI_AVB_PROTOCOL *This, + IN OUT UINTN *NumberOfPartitions, + IN OUT GBL_EFI_AVB_PARTITION *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 + ); + +struct _GBL_EFI_AVB_PROTOCOL { + UINT64 Revision; + GBL_EFI_AVB_READ_PARTITIONS_TO_VERIFY ReadPartitionsToVerify; + 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; +}; + +#endif // GBL_EFI_AVB_PROTOCOL_H_ diff --git a/EmbeddedPkg/Include/Protocol/GblEfiAvf.h b/EmbeddedPkg/Include/Protocol/GblEfiAvf.h new file mode 100644 index 000000000000..3d96bb8389c0 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiAvf.h @@ -0,0 +1,55 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI AVF Protocol. + Supplies GBL with vendor DICE handover and Secret Keeper public key + needed for Android Virtualization Framework. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_avf_protocol.md +*/ + +#ifndef GBL_EFI_AVF_PROTOCOL_H_ +#define GBL_EFI_AVF_PROTOCOL_H_ + +#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 0x00000001 + +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; +}; + +#endif // GBL_EFI_AVF_PROTOCOL_H_ diff --git a/EmbeddedPkg/Include/Protocol/GblEfiBootControl.h b/EmbeddedPkg/Include/Protocol/GblEfiBootControl.h new file mode 100644 index 000000000000..8bc057dbd988 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiBootControl.h @@ -0,0 +1,131 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI Boot Control Protocol. + Delegates boot target manipulation logic to firmware. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_boot_control_protocol.md +*/ + +#ifndef GBL_EFI_BOOT_CONTROL_PROTOCOL_H_ +#define GBL_EFI_BOOT_CONTROL_PROTOCOL_H_ + +#include +#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 0x00000002 + +typedef struct _GBL_EFI_BOOT_CONTROL_PROTOCOL GBL_EFI_BOOT_CONTROL_PROTOCOL; + +typedef enum { + GBL_EFI_UNBOOTABLE_REASON_UNKNOWN_REASON, + GBL_EFI_UNBOOTABLE_REASON_NO_MORE_TRIES, + GBL_EFI_UNBOOTABLE_REASON_SYSTEM_UPDATE, + GBL_EFI_UNBOOTABLE_REASON_USER_REQUESTED, + GBL_EFI_UNBOOTABLE_REASON_VERIFICATION_FAILURE +} GBL_EFI_UNBOOTABLE_REASON; + +typedef enum { + GBL_EFI_ONE_SHOT_BOOT_MODE_NONE, + GBL_EFI_ONE_SHOT_BOOT_MODE_BOOTLOADER, + GBL_EFI_ONE_SHOT_BOOT_MODE_RECOVERY +} GBL_EFI_ONE_SHOT_BOOT_MODE; + +typedef struct { + // One UTF-8 encoded single character. + UINT32 Suffix; + // GBL_EFI_UNBOOTABLE_REASON + UINT8 UnbootableReason; + UINT8 Priority; + UINT8 Tries; + UINT8 Successful; +} GBL_EFI_SLOT_INFO; + +typedef struct { + UINTN KernelSize; + PHYSICAL_ADDRESS Kernel; + UINTN RamdiskSize; + PHYSICAL_ADDRESS Ramdisk; + UINTN DeviceTreeSize; + PHYSICAL_ADDRESS DeviceTree; + UINT64 Reserved[8]; +} GBL_EFI_LOADED_OS; + +typedef +VOID +(EFIAPI *GBL_EFI_START_OS)( + IN UINTN DescriptorSize, + IN UINT32 DescriptorVersion, + IN UINTN NumDescriptors, + IN CONST EFI_MEMORY_DESCRIPTOR *MemoryMap, + IN CONST GBL_EFI_LOADED_OS *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, + OUT GBL_EFI_START_OS *StartOsCallback + ); + +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; +}; + +#endif // GBL_EFI_BOOT_CONTROL_PROTOCOL_H_ diff --git a/EmbeddedPkg/Include/Protocol/GblEfiBootMemory.h b/EmbeddedPkg/Include/Protocol/GblEfiBootMemory.h new file mode 100644 index 000000000000..c608de7a82c6 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiBootMemory.h @@ -0,0 +1,78 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI Boot Memory Protocol. + Provides APIs for retrieving and synchronizing boot and partition buffers. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_boot_memory_protocol.md +*/ + +#ifndef GBL_EFI_BOOT_MEMORY_PROTOCOL_H_ +#define GBL_EFI_BOOT_MEMORY_PROTOCOL_H_ + +#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 0x00000001 + +typedef struct _GBL_EFI_BOOT_MEMORY_PROTOCOL GBL_EFI_BOOT_MEMORY_PROTOCOL; + +typedef enum { + GBL_EFI_BOOT_BUFFER_TYPE_GENERAL_LOAD = 0, + GBL_EFI_BOOT_BUFFER_TYPE_KERNEL, + GBL_EFI_BOOT_BUFFER_TYPE_RAMDISK, + GBL_EFI_BOOT_BUFFER_TYPE_FDT, + GBL_EFI_BOOT_BUFFER_TYPE_PVMFW_DATA, + GBL_EFI_BOOT_BUFFER_TYPE_FASTBOOT_DOWNLOAD, +} GBL_EFI_BOOT_BUFFER_TYPE; + +typedef enum { + GBL_EFI_PARTITION_BUFFER_FLAG_PRELOADED = 1u << 0, +} 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 GBL_EFI_PARTITION_BUFFER_FLAG *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 GBL_EFI_BOOT_BUFFER_TYPE BufType, + 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; +}; + +#endif // GBL_EFI_BOOT_MEMORY_PROTOCOL_H_ diff --git a/EmbeddedPkg/Include/Protocol/GblEfiDebug.h b/EmbeddedPkg/Include/Protocol/GblEfiDebug.h new file mode 100644 index 000000000000..fac80cc36792 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiDebug.h @@ -0,0 +1,52 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI Debug Protocol. + Allows GBL to notify firmware of fatal errors or debug events. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_debug_protocol.md +*/ + +#ifndef GBL_EFI_DEBUG_PROTOCOL_H_ +#define GBL_EFI_DEBUG_PROTOCOL_H_ + +#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 0x00000001 + +typedef struct _GBL_EFI_DEBUG_PROTOCOL GBL_EFI_DEBUG_PROTOCOL; + +typedef enum { + GBL_EFI_DEBUG_ERROR_TAG_ASSERTION_ERROR, + GBL_EFI_DEBUG_ERROR_TAG_PARTITION, + GBL_EFI_DEBUG_ERROR_TAG_LOAD_IMAGE, + GBL_EFI_DEBUG_ERROR_TAG_BOOT_ERROR +} 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 GBL_EFI_DEBUG_ERROR_TAG Tag + ); + +struct _GBL_EFI_DEBUG_PROTOCOL { + UINT64 Revision; + GBL_EFI_DEBUG_FATAL_ERROR FatalError; +}; + +#endif // GBL_EFI_DEBUG_PROTOCOL_H_ diff --git a/EmbeddedPkg/Include/Protocol/GblEfiFastboot.h b/EmbeddedPkg/Include/Protocol/GblEfiFastboot.h new file mode 100644 index 000000000000..5fe46e2a158e --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiFastboot.h @@ -0,0 +1,147 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI Fastboot Protocol. + Platform-specific helpers for Android Fastboot operations. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_fastboot_protocol.md +*/ + +#ifndef GBL_EFI_FASTBOOT_PROTOCOL_H_ +#define GBL_EFI_FASTBOOT_PROTOCOL_H_ + +#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 0x00000004 + +#define GBL_EFI_FASTBOOT_SERIAL_NUMBER_MAX_LEN_UTF8 32 + +typedef struct _GBL_EFI_FASTBOOT_PROTOCOL GBL_EFI_FASTBOOT_PROTOCOL; + +typedef enum { + GBL_EFI_FASTBOOT_MESSAGE_TYPE_OKAY, + GBL_EFI_FASTBOOT_MESSAGE_TYPE_FAIL, + GBL_EFI_FASTBOOT_MESSAGE_TYPE_INFO +} GBL_EFI_FASTBOOT_MESSAGE_TYPE; + +typedef enum { + GBL_EFI_FASTBOOT_ERASE_ACTION_ERASE_AS_PHYSICAL_PARTITION, + GBL_EFI_FASTBOOT_ERASE_ACTION_NOOP +} GBL_EFI_FASTBOOT_ERASE_ACTION; + +typedef enum { + GBL_EFI_FASTBOOT_COMMAND_EXEC_RESULT_PROHIBITED, + GBL_EFI_FASTBOOT_COMMAND_EXEC_RESULT_DEFAULT_IMPL, + GBL_EFI_FASTBOOT_COMMAND_EXEC_RESULT_CUSTOM_IMPL +} GBL_EFI_FASTBOOT_COMMAND_EXEC_RESULT; + +typedef +VOID +(EFIAPI *GBL_EFI_FASTBOOT_GET_VAR_ALL_CALLBACK)( + IN VOID *Context, + IN CONST CHAR8 *CONST *Args, + IN UINTN NumArgs, + IN CONST CHAR8 *Value + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_MESSAGE_SENDER)( + IN VOID *Context, + IN GBL_EFI_FASTBOOT_MESSAGE_TYPE MsgType, + IN CONST CHAR8 *Msg, + IN UINTN MsgLen + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_GET_VAR)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN CONST CHAR8 *CONST *Args, + IN UINTN NumArgs, + OUT UINT8 *Out, + IN OUT UINTN *OutSize + ); + +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, + OUT UINT8 *Out, + IN OUT UINTN *OutSize, + OUT UINTN *OutRemain + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_SET_LOCK)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN BOOLEAN Critical, + IN BOOLEAN Lock + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_GET_LOCK)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN BOOLEAN Critical, + OUT BOOLEAN *OutLock + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_FASTBOOT_VENDOR_ERASE)( + IN GBL_EFI_FASTBOOT_PROTOCOL *This, + IN CONST CHAR8 *PartName, + IN UINTN PartNameLen, + OUT GBL_EFI_FASTBOOT_ERASE_ACTION *Action + ); + +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 DownloadDataUsedLen, + IN UINT8 *DownloadData, + IN UINTN DownloadDataFullSize, + OUT GBL_EFI_FASTBOOT_COMMAND_EXEC_RESULT *Implementation, + IN GBL_EFI_FASTBOOT_MESSAGE_SENDER Sender, + IN VOID *Context + ); + +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_SET_LOCK SetLock; + GBL_EFI_FASTBOOT_GET_LOCK GetLock; + GBL_EFI_FASTBOOT_VENDOR_ERASE VendorErase; + GBL_EFI_FASTBOOT_COMMAND_EXEC CommandExec; +}; + +#endif // GBL_EFI_FASTBOOT_PROTOCOL_H_ diff --git a/EmbeddedPkg/Include/Protocol/GblEfiFastbootTransport.h b/EmbeddedPkg/Include/Protocol/GblEfiFastbootTransport.h new file mode 100644 index 000000000000..086f0f971eb2 --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiFastbootTransport.h @@ -0,0 +1,82 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI Fastboot Transport Protocol. + Enables firmware to expose a transport interface for Android Fastboot. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_fastboot_transport_protocol.md +*/ + +#ifndef GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL_H_ +#define GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL_H_ + +#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 0x00000001 + +typedef struct _GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL; + +typedef enum { + GBL_EFI_FASTBOOT_RX_MODE_SINGLE_PACKET = 0, + GBL_EFI_FASTBOOT_RX_MODE_FIXED_LENGTH, +} 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 GBL_EFI_FASTBOOT_RX_MODE 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; +}; + +#endif // GBL_EFI_FASTBOOT_TRANSPORT_PROTOCOL_H_ diff --git a/EmbeddedPkg/Include/Protocol/GblEfiOsConfiguration.h b/EmbeddedPkg/Include/Protocol/GblEfiOsConfiguration.h new file mode 100644 index 000000000000..fedf54375c8a --- /dev/null +++ b/EmbeddedPkg/Include/Protocol/GblEfiOsConfiguration.h @@ -0,0 +1,96 @@ +/** @file + + Copyright (c) 2025, The Android Open Source Project. + + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +/* + GBL EFI OS Configuration Protocol. + Lets firmware fix up kernel bootconfig, and choose device-tree components at + boot time. + + Related docs: + https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_os_configuration_protocol.md +*/ + +#ifndef GBL_EFI_OS_CONFIGURATION_PROTOCOL_H_ +#define GBL_EFI_OS_CONFIGURATION_PROTOCOL_H_ + +#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 0x00000001 + +typedef struct _GBL_EFI_OS_CONFIGURATION_PROTOCOL GBL_EFI_OS_CONFIGURATION_PROTOCOL; + +typedef enum { + GBL_EFI_DEVICE_TREE_TYPE_DEVICE_TREE, + GBL_EFI_DEVICE_TREE_TYPE_OVERLAY, + GBL_EFI_DEVICE_TREE_TYPE_PVM_DA_OVERLAY, +} GBL_EFI_DEVICE_TREE_TYPE; + +typedef enum { + GBL_EFI_DEVICE_TREE_SOURCE_BOOT, + GBL_EFI_DEVICE_TREE_SOURCE_VENDOR_BOOT, + GBL_EFI_DEVICE_TREE_SOURCE_DTBO, + GBL_EFI_DEVICE_TREE_SOURCE_DTB, +} 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; + UINT32 Custom[4]; +} 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 CONST CHAR8 *BootConfig, + IN UINTN BootConfigSize, + OUT CHAR8 *Fixup, + IN OUT UINTN *FixupBufferSize + ); + +typedef +EFI_STATUS +(EFIAPI *GBL_EFI_SELECT_DEVICE_TREES)( + IN GBL_EFI_OS_CONFIGURATION_PROTOCOL *This, + IN OUT GBL_EFI_VERIFIED_DEVICE_TREE *DeviceTrees, + IN UINTN NumDeviceTrees + ); + +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; +}; + +#endif // GBL_EFI_OS_CONFIGURATION_PROTOCOL_H_