Skip to content

Commit cb15d7b

Browse files
dimorinnydpursellsoftware-dovjakobvukaloviczhangxp1998
committed
EmbeddedPkg: Introduce GBL protocols
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 <[email protected]> Co-authored-by: Dov Shlachter <[email protected]> Co-authored-by: Jakob Vukalović <[email protected]> Co-authored-by: Kelvin Zhang <[email protected]> Co-authored-by: Ram Muthiah <[email protected]> Co-authored-by: Sergii Parubochyi <[email protected]> Co-authored-by: Yecheng Zhao <[email protected]> Co-authored-by: Yi-Yo Chiang <[email protected]> Signed-off-by: Dmitrii Merkurev <[email protected]>
1 parent 4380456 commit cb15d7b

File tree

7 files changed

+844
-0
lines changed

7 files changed

+844
-0
lines changed

‎EmbeddedPkg/Include/Protocol/GblEfiAvb.h‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
/** @file
2+
3+
Copyright (c) 2025, The Android Open Source Project.
4+
5+
SPDX-License-Identifier: BSD-2-Clause-Patent
6+
7+
**/
8+
9+
/*
10+
GBL EFI AVB Protocol.
11+
Delegates Android Verified Boot (AVB) board-specific logic to firmware.
12+
13+
Related docs:
14+
https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_avb_protocol.md
15+
*/
16+
17+
#ifndef GBL_EFI_AVB_PROTOCOL_H_
18+
#define GBL_EFI_AVB_PROTOCOL_H_
19+
20+
#include <Uefi/UefiBaseType.h>
21+
22+
//
23+
// {6bc66b9a-d5c9-4c02-9da9-50af198d912c}
24+
//
25+
#define GBL_EFI_AVB_PROTOCOL_GUID \
26+
{ 0x6bc66b9a, 0xd5c9, 0x4c02, { 0x9d, 0xa9, 0x50, 0xaf, 0x19, 0x8d, 0x91, 0x2c } }
27+
28+
#define GBL_EFI_AVB_PROTOCOL_REVISION 0x00000003
29+
30+
typedef struct _GBL_EFI_AVB_PROTOCOL GBL_EFI_AVB_PROTOCOL;
31+
32+
typedef UINT64 GBL_EFI_AVB_DEVICE_STATUS;
33+
STATIC CONST GBL_EFI_AVB_DEVICE_STATUS GBL_EFI_AVB_DEVICE_STATUS_UNLOCKED = 0x1 << 0;
34+
STATIC CONST GBL_EFI_AVB_DEVICE_STATUS GBL_EFI_AVB_DEVICE_STATUS_DM_VERITY_FAILED = 0x1 << 1;
35+
36+
typedef UINT64 GBL_EFI_AVB_BOOT_COLOR;
37+
STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_RED = 0x1 << 0;
38+
STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_ORANGE = 0x1 << 1;
39+
STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_YELLOW = 0x1 << 2;
40+
STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_GREEN = 0x1 << 3;
41+
STATIC CONST GBL_EFI_AVB_BOOT_COLOR GBL_EFI_AVB_BOOT_COLOR_RED_EIO = 0x1 << 4;
42+
43+
typedef UINT64 GBL_EFI_AVB_PARTITION_FLAGS;
44+
static const GBL_EFI_AVB_PARTITION_FLAGS GBL_EFI_AVB_PARTITION_OPTIONAL = 0x1 << 0;
45+
46+
typedef enum {
47+
GBL_EFI_AVB_KEY_VALIDATION_STATUS_INVALID = 0,
48+
GBL_EFI_AVB_KEY_VALIDATION_STATUS_VALID_CUSTOM_KEY,
49+
GBL_EFI_AVB_KEY_VALIDATION_STATUS_VALID
50+
} GBL_EFI_AVB_KEY_VALIDATION_STATUS;
51+
52+
typedef struct {
53+
UINTN BaseNameLen;
54+
CHAR8 *BaseName; // UTF-8, null terminated
55+
GBL_EFI_AVB_PARTITION_FLAGS Flags;
56+
} GBL_EFI_AVB_PARTITION;
57+
58+
typedef struct {
59+
CHAR8 *BaseName; // UTF-8 null terminated
60+
UINTN DataSize;
61+
UINT8 *Data;
62+
} GBL_EFI_AVB_LOADED_PARTITION;
63+
64+
typedef struct {
65+
CONST CHAR8 *BasePartitionName; // UTF-8, null terminated
66+
CONST CHAR8 *Key; // UTF-8, null terminated
67+
UINTN ValueSize;
68+
CONST UINT8 *Value;
69+
} GBL_EFI_AVB_PROPERTY;
70+
71+
typedef struct {
72+
GBL_EFI_AVB_BOOT_COLOR ColorFlags;
73+
// UTF-8, null terminated
74+
CONST CHAR8 *Digest;
75+
UINTN NumPartitions;
76+
CONST GBL_EFI_AVB_LOADED_PARTITION *Partitions;
77+
UINTN NumProperties;
78+
CONST GBL_EFI_AVB_PROPERTY *Properties;
79+
UINT64 Reserved[8];
80+
} GBL_EFI_AVB_VERIFICATION_RESULT;
81+
82+
typedef
83+
EFI_STATUS
84+
(EFIAPI *GBL_EFI_AVB_READ_PARTITIONS_TO_VERIFY)(
85+
IN GBL_EFI_AVB_PROTOCOL *This,
86+
IN OUT UINTN *NumberOfPartitions,
87+
IN OUT GBL_EFI_AVB_PARTITION *Partitions
88+
);
89+
90+
typedef
91+
EFI_STATUS
92+
(EFIAPI *GBL_EFI_AVB_READ_DEVICE_STATUS)(
93+
IN GBL_EFI_AVB_PROTOCOL *This,
94+
OUT GBL_EFI_AVB_DEVICE_STATUS *StatusFlags
95+
);
96+
97+
typedef
98+
EFI_STATUS
99+
(EFIAPI *GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY)(
100+
IN GBL_EFI_AVB_PROTOCOL *This,
101+
IN UINTN PublicKeyLength,
102+
IN CONST UINT8 *PublicKeyData,
103+
IN UINTN PublicKeyMetadataLength,
104+
IN CONST UINT8 *PublicKeyMetadata,
105+
OUT UINT32 *ValidationStatus // GBL_EFI_AVB_KEY_VALIDATION_STATUS
106+
);
107+
108+
typedef
109+
EFI_STATUS
110+
(EFIAPI *GBL_EFI_AVB_READ_ROLLBACK_INDEX)(
111+
IN GBL_EFI_AVB_PROTOCOL *This,
112+
IN UINTN IndexLocation,
113+
OUT UINT64 *RollbackIndex
114+
);
115+
116+
typedef
117+
EFI_STATUS
118+
(EFIAPI *GBL_EFI_AVB_WRITE_ROLLBACK_INDEX)(
119+
IN GBL_EFI_AVB_PROTOCOL *This,
120+
IN UINTN IndexLocation,
121+
IN UINT64 RollbackIndex
122+
);
123+
124+
typedef
125+
EFI_STATUS
126+
(EFIAPI *GBL_EFI_AVB_READ_PERSISTENT_VALUE)(
127+
IN GBL_EFI_AVB_PROTOCOL *This,
128+
IN CONST CHAR8 *Name,
129+
IN OUT UINTN *ValueSize,
130+
OUT UINT8 *Value
131+
);
132+
133+
typedef
134+
EFI_STATUS
135+
(EFIAPI *GBL_EFI_AVB_WRITE_PERSISTENT_VALUE)(
136+
IN GBL_EFI_AVB_PROTOCOL *This,
137+
IN CONST CHAR8 *Name,
138+
IN UINTN ValueSize,
139+
IN CONST UINT8 *Value
140+
);
141+
142+
typedef
143+
EFI_STATUS
144+
(EFIAPI *GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT)(
145+
IN GBL_EFI_AVB_PROTOCOL *This,
146+
IN CONST GBL_EFI_AVB_VERIFICATION_RESULT *Result
147+
);
148+
149+
struct _GBL_EFI_AVB_PROTOCOL {
150+
UINT64 Revision;
151+
GBL_EFI_AVB_READ_PARTITIONS_TO_VERIFY ReadPartitionsToVerify;
152+
GBL_EFI_AVB_READ_DEVICE_STATUS ReadDeviceStatus;
153+
GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY ValidateVbmetaPublicKey;
154+
GBL_EFI_AVB_READ_ROLLBACK_INDEX ReadRollbackIndex;
155+
GBL_EFI_AVB_WRITE_ROLLBACK_INDEX WriteRollbackIndex;
156+
GBL_EFI_AVB_READ_PERSISTENT_VALUE ReadPersistentValue;
157+
GBL_EFI_AVB_WRITE_PERSISTENT_VALUE WritePersistentValue;
158+
GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT HandleVerificationResult;
159+
};
160+
161+
#endif // GBL_EFI_AVB_PROTOCOL_H_

‎EmbeddedPkg/Include/Protocol/GblEfiAvf.h‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
/** @file
2+
3+
Copyright (c) 2025, The Android Open Source Project.
4+
5+
SPDX-License-Identifier: BSD-2-Clause-Patent
6+
7+
**/
8+
9+
/*
10+
GBL EFI AVF Protocol.
11+
Supplies GBL with vendor DICE handover and Secret Keeper public key
12+
needed for Android Virtualization Framework.
13+
14+
Related docs:
15+
https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_avf_protocol.md
16+
*/
17+
18+
#ifndef GBL_EFI_AVF_PROTOCOL_H_
19+
#define GBL_EFI_AVF_PROTOCOL_H_
20+
21+
#include <Uefi/UefiBaseType.h>
22+
23+
//
24+
// {e7f1c4a6-0a52-4f61-bd98-9e60b559452a}
25+
//
26+
#define GBL_EFI_AVF_PROTOCOL_GUID \
27+
{ 0xe7f1c4a6, 0x0a52, 0x4f61, { 0xbd, 0x98, 0x9e, 0x60, 0xb5, 0x59, 0x45, 0x2a } }
28+
29+
#define GBL_EFI_AVF_PROTOCOL_REVISION 0x00000001
30+
31+
typedef struct _GBL_EFI_AVF_PROTOCOL GBL_EFI_AVF_PROTOCOL;
32+
33+
typedef
34+
EFI_STATUS
35+
(EFIAPI *GBL_EFI_AVF_READ_VENDOR_DICE_HANDOVER)(
36+
IN GBL_EFI_AVF_PROTOCOL *This,
37+
IN OUT UINTN *HandoverSize,
38+
OUT UINT8 *Handover
39+
);
40+
41+
typedef
42+
EFI_STATUS
43+
(EFIAPI *GBL_EFI_AVF_READ_SECRET_KEEPER_PUBLIC_KEY)(
44+
IN GBL_EFI_AVF_PROTOCOL *This,
45+
IN OUT UINTN *PublicKeySize,
46+
OUT UINT8 *PublicKey
47+
);
48+
49+
struct _GBL_EFI_AVF_PROTOCOL {
50+
UINT64 Revision;
51+
GBL_EFI_AVF_READ_VENDOR_DICE_HANDOVER ReadVendorDiceHandover;
52+
GBL_EFI_AVF_READ_SECRET_KEEPER_PUBLIC_KEY ReadSecretKeeperPublicKey;
53+
};
54+
55+
#endif // GBL_EFI_AVF_PROTOCOL_H_

‎EmbeddedPkg/Include/Protocol/GblEfiBootControl.h‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
/** @file
2+
3+
Copyright (c) 2025, The Android Open Source Project.
4+
5+
SPDX-License-Identifier: BSD-2-Clause-Patent
6+
7+
**/
8+
9+
/*
10+
GBL EFI Boot Control Protocol.
11+
Delegates boot target manipulation logic to firmware.
12+
13+
Related docs:
14+
https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_boot_control_protocol.md
15+
*/
16+
17+
#ifndef GBL_EFI_BOOT_CONTROL_PROTOCOL_H_
18+
#define GBL_EFI_BOOT_CONTROL_PROTOCOL_H_
19+
20+
#include <Uefi/UefiBaseType.h>
21+
#include <Uefi/UefiSpec.h>
22+
23+
//
24+
// {d382db1b-9ac2-11f0-84c7-047bcba96019}
25+
//
26+
#define GBL_EFI_BOOT_CONTROL_PROTOCOL_GUID \
27+
{ 0xd382db1b, 0x9ac2, 0x11f0, { 0x84, 0xc7, 0x04, 0x7b, 0xcb, 0xa9, 0x60, 0x19 } }
28+
29+
#define GBL_EFI_BOOT_CONTROL_PROTOCOL_REVISION 0x00000002
30+
31+
typedef struct _GBL_EFI_BOOT_CONTROL_PROTOCOL GBL_EFI_BOOT_CONTROL_PROTOCOL;
32+
33+
typedef enum {
34+
GBL_EFI_UNBOOTABLE_REASON_UNKNOWN_REASON,
35+
GBL_EFI_UNBOOTABLE_REASON_NO_MORE_TRIES,
36+
GBL_EFI_UNBOOTABLE_REASON_SYSTEM_UPDATE,
37+
GBL_EFI_UNBOOTABLE_REASON_USER_REQUESTED,
38+
GBL_EFI_UNBOOTABLE_REASON_VERIFICATION_FAILURE
39+
} GBL_EFI_UNBOOTABLE_REASON;
40+
41+
typedef enum {
42+
GBL_EFI_ONE_SHOT_BOOT_MODE_NONE,
43+
GBL_EFI_ONE_SHOT_BOOT_MODE_BOOTLOADER,
44+
GBL_EFI_ONE_SHOT_BOOT_MODE_RECOVERY
45+
} GBL_EFI_ONE_SHOT_BOOT_MODE;
46+
47+
typedef struct {
48+
// One UTF-8 encoded single character.
49+
UINT32 Suffix;
50+
// GBL_EFI_UNBOOTABLE_REASON
51+
UINT8 UnbootableReason;
52+
UINT8 Priority;
53+
UINT8 Tries;
54+
UINT8 Successful;
55+
} GBL_EFI_SLOT_INFO;
56+
57+
typedef struct {
58+
UINTN KernelSize;
59+
PHYSICAL_ADDRESS Kernel;
60+
UINTN RamdiskSize;
61+
PHYSICAL_ADDRESS Ramdisk;
62+
UINTN DeviceTreeSize;
63+
PHYSICAL_ADDRESS DeviceTree;
64+
} GBL_EFI_LOADED_OS;
65+
66+
typedef
67+
VOID
68+
(EFIAPI *GBL_EFI_START_OS)(
69+
IN UINTN DescriptorSize,
70+
IN UINT32 DescriptorVersion,
71+
IN UINTN NumDescriptors,
72+
IN CONST EFI_MEMORY_DESCRIPTOR *MemoryMap,
73+
IN CONST GBL_EFI_LOADED_OS *Os
74+
);
75+
76+
typedef
77+
EFI_STATUS
78+
(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_SLOT_COUNT)(
79+
IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This,
80+
OUT UINT8 *SlotCount
81+
);
82+
83+
typedef
84+
EFI_STATUS
85+
(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_SLOT_INFO)(
86+
IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This,
87+
IN UINT8 Index,
88+
OUT GBL_EFI_SLOT_INFO *Info
89+
);
90+
91+
typedef
92+
EFI_STATUS
93+
(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_CURRENT_SLOT)(
94+
IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This,
95+
OUT GBL_EFI_SLOT_INFO *Info
96+
);
97+
98+
typedef
99+
EFI_STATUS
100+
(EFIAPI *GBL_EFI_BOOT_CONTROL_SET_ACTIVE_SLOT)(
101+
IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This,
102+
IN UINT8 Index
103+
);
104+
105+
typedef
106+
EFI_STATUS
107+
(EFIAPI *GBL_EFI_BOOT_CONTROL_GET_ONE_SHOT_BOOT_MODE)(
108+
IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This,
109+
OUT UINT32 *Mode // GBL_EFI_ONE_SHOT_BOOT_MODE
110+
);
111+
112+
typedef
113+
EFI_STATUS
114+
(EFIAPI *GBL_EFI_BOOT_CONTROL_HANDLE_LOADED_OS)(
115+
IN GBL_EFI_BOOT_CONTROL_PROTOCOL *This,
116+
IN CONST GBL_EFI_LOADED_OS *Os,
117+
OUT GBL_EFI_START_OS *StartOsCallback
118+
);
119+
120+
struct _GBL_EFI_BOOT_CONTROL_PROTOCOL {
121+
UINT64 Revision;
122+
GBL_EFI_BOOT_CONTROL_GET_SLOT_COUNT GetSlotCount;
123+
GBL_EFI_BOOT_CONTROL_GET_SLOT_INFO GetSlotInfo;
124+
GBL_EFI_BOOT_CONTROL_GET_CURRENT_SLOT GetCurrentSlot;
125+
GBL_EFI_BOOT_CONTROL_SET_ACTIVE_SLOT SetActiveSlot;
126+
GBL_EFI_BOOT_CONTROL_GET_ONE_SHOT_BOOT_MODE GetOneShotBootMode;
127+
GBL_EFI_BOOT_CONTROL_HANDLE_LOADED_OS HandleLoadedOs;
128+
};
129+
130+
#endif // GBL_EFI_BOOT_CONTROL_PROTOCOL_H_

0 commit comments

Comments
 (0)