Skip to content

EmbeddedPkg: introduce GBL protocols #11145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

EmbeddedPkg: introduce GBL protocols #11145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 161 additions & 0 deletions EmbeddedPkg/Include/Protocol/GblEfiAvb.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <Uefi/UefiBaseType.h>

//
// {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_
55 changes: 55 additions & 0 deletions EmbeddedPkg/Include/Protocol/GblEfiAvf.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <Uefi/UefiBaseType.h>

//
// {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_
131 changes: 131 additions & 0 deletions EmbeddedPkg/Include/Protocol/GblEfiBootControl.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <Uefi/UefiBaseType.h>
#include <Uefi/UefiSpec.h>

//
// {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_
Loading
Loading