Skip to content

Commit b502c60

Browse files
dimorinnydpursellsoftware-dovrmuthiahSergii Parubochyi
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: Ram Muthiah <[email protected]> Co-authored-by: Sergii Parubochyi <[email protected]> Co-authored-by: Yecheng Zhao <[email protected]> Signed-off-by: Dmitrii Merkurev <[email protected]>
1 parent b1d5b84 commit b502c60

File tree

7 files changed

+882
-0
lines changed

7 files changed

+882
-0
lines changed

‎EmbeddedPkg/Include/Protocol/GblEfiAbSlot.h‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
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 AB Slot Protocol.
11+
Offers firmware helpers for Android A/B slot metadata and boot-reason handling.
12+
13+
Related docs:
14+
https://cs.android.com/android/kernel/superproject/+/common-android-mainline:bootable/libbootloader/gbl/docs/gbl_efi_ab_slot_protocol.md
15+
*/
16+
17+
#ifndef GBL_EFI_AB_SLOT_PROTOCOL_H_
18+
#define GBL_EFI_AB_SLOT_PROTOCOL_H_
19+
20+
#include <Uefi/UefiBaseType.h>
21+
22+
//
23+
// {9a7a7db4-614b-4a08-3df9-006f49b0d80c}
24+
//
25+
#define GBL_EFI_AB_SLOT_PROTOCOL_GUID \
26+
{ 0x9a7a7db4, 0x614b, 0x4a08, { 0x3d, 0xf9, 0x00, 0x6f, 0x49, 0xb0, 0xd8, 0x0c } }
27+
28+
#define GBL_EFI_AB_SLOT_PROTOCOL_VERSION 0x00000000
29+
30+
typedef struct _GBL_EFI_AB_SLOT_PROTOCOL GBL_EFI_AB_SLOT_PROTOCOL;
31+
typedef struct _GBL_EFI_SLOT_INFO GBL_EFI_SLOT_INFO;
32+
typedef struct _GBL_EFI_SLOT_METADATA_BLOCK GBL_EFI_SLOT_METADATA_BLOCK;
33+
34+
/*
35+
Snapshot-merge state (Virtual A/B).
36+
*/
37+
typedef enum {
38+
GBL_EFI_SLOT_MERGE_STATUS_NONE = 0,
39+
GBL_EFI_SLOT_MERGE_STATUS_UNKNOWN,
40+
GBL_EFI_SLOT_MERGE_STATUS_SNAPSHOTTED,
41+
GBL_EFI_SLOT_MERGE_STATUS_MERGING,
42+
GBL_EFI_SLOT_MERGE_STATUS_CANCELLED
43+
} GBL_EFI_SLOT_MERGE_STATUS;
44+
45+
/*
46+
Why a slot became unbootable.
47+
*/
48+
typedef enum {
49+
GBL_EFI_UNBOOTABLE_REASON_UNKNOWN = 0,
50+
GBL_EFI_UNBOOTABLE_REASON_NO_MORE_TRIES,
51+
GBL_EFI_UNBOOTABLE_REASON_SYSTEM_UPDATE,
52+
GBL_EFI_UNBOOTABLE_REASON_USER_REQUESTED,
53+
GBL_EFI_UNBOOTABLE_REASON_VERIFICATION_FAILURE
54+
} GBL_EFI_UNBOOTABLE_REASON;
55+
56+
/*
57+
Android boot-mode codes.
58+
*/
59+
typedef enum {
60+
GBL_EFI_BOOT_MODE_NORMAL = 0,
61+
GBL_EFI_BOOT_MODE_RECOVERY,
62+
GBL_EFI_BOOT_MODE_FASTBOOTD,
63+
GBL_EFI_BOOT_MODE_BOOTLOADER,
64+
} GBL_EFI_BOOT_MODE;
65+
66+
/*
67+
Per-slot state.
68+
*/
69+
struct _GBL_EFI_SLOT_INFO {
70+
UINT32 Suffix; // UTF-8 code-point of slot letter
71+
UINT32 UnbootableReason; // GBL_EFI_UNBOOTABLE_REASON
72+
UINT8 Priority;
73+
UINT8 Tries;
74+
UINT8 Successful; // 1 if slot booted once
75+
};
76+
77+
/*
78+
Global slot-metadata block.
79+
*/
80+
struct _GBL_EFI_SLOT_METADATA_BLOCK {
81+
UINT8 UnbootableMetadata; // 1 if reasons tracked
82+
UINT8 MaxRetries;
83+
UINT8 SlotCount;
84+
UINT8 MergeStatus; // GBL_EFI_SLOT_MERGE_STATUS
85+
};
86+
87+
/// Load immutable slot metadata.
88+
typedef
89+
EFI_STATUS
90+
(EFIAPI *GBL_EFI_AB_SLOT_LOAD_BOOT_DATA)(
91+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
92+
OUT GBL_EFI_SLOT_METADATA_BLOCK *Metadata
93+
);
94+
95+
/// Get info for slot by index.
96+
typedef
97+
EFI_STATUS
98+
(EFIAPI *GBL_EFI_AB_SLOT_GET_SLOT_INFO)(
99+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
100+
IN UINT8 Index,
101+
OUT GBL_EFI_SLOT_INFO *Info
102+
);
103+
104+
/// Get info for current slot.
105+
typedef
106+
EFI_STATUS
107+
(EFIAPI *GBL_EFI_AB_SLOT_GET_CURRENT_SLOT)(
108+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
109+
OUT GBL_EFI_SLOT_INFO *Info
110+
);
111+
112+
/// Decide next slot; optionally mark boot attempt.
113+
typedef
114+
EFI_STATUS
115+
(EFIAPI *GBL_EFI_AB_SLOT_GET_NEXT_SLOT)(
116+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
117+
IN BOOLEAN MarkBootAttempt,
118+
OUT GBL_EFI_SLOT_INFO *Info
119+
);
120+
121+
/// Make slot active.
122+
typedef
123+
EFI_STATUS
124+
(EFIAPI *GBL_EFI_AB_SLOT_SET_ACTIVE_SLOT)(
125+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
126+
IN UINT8 Index
127+
);
128+
129+
/// Mark slot unbootable with reason.
130+
typedef
131+
EFI_STATUS
132+
(EFIAPI *GBL_EFI_AB_SLOT_SET_SLOT_UNBOOTABLE)(
133+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
134+
IN UINT8 Index,
135+
IN UINT32 UnbootableReason // GBL_EFI_UNBOOTABLE_REASON
136+
);
137+
138+
/// Re-initialise all slot metadata.
139+
typedef
140+
EFI_STATUS
141+
(EFIAPI *GBL_EFI_AB_SLOT_REINITIALIZE)(
142+
IN GBL_EFI_AB_SLOT_PROTOCOL *This
143+
);
144+
145+
/// Read boot mode.
146+
typedef
147+
EFI_STATUS
148+
(EFIAPI *GBL_EFI_AB_SLOT_GET_BOOT_MODE)(
149+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
150+
OUT UINT32 *Mode // GBL_EFI_BOOT_MODE
151+
);
152+
153+
/// Set boot mode.
154+
typedef
155+
EFI_STATUS
156+
(EFIAPI *GBL_EFI_AB_SLOT_SET_BOOT_MODE)(
157+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
158+
IN UINT32 Mode // GBL_EFI_BOOT_MODE
159+
);
160+
161+
/// Flush metadata to persistent storage.
162+
typedef
163+
EFI_STATUS
164+
(EFIAPI *GBL_EFI_AB_SLOT_FLUSH)(
165+
IN GBL_EFI_AB_SLOT_PROTOCOL *This
166+
);
167+
168+
/*
169+
Firmware-published protocol instance.
170+
*/
171+
struct _GBL_EFI_AB_SLOT_PROTOCOL {
172+
UINT32 Version;
173+
GBL_EFI_AB_SLOT_LOAD_BOOT_DATA LoadBootData;
174+
GBL_EFI_AB_SLOT_GET_SLOT_INFO GetSlotInfo;
175+
GBL_EFI_AB_SLOT_GET_CURRENT_SLOT GetCurrentSlot;
176+
GBL_EFI_AB_SLOT_GET_NEXT_SLOT GetNextSlot;
177+
GBL_EFI_AB_SLOT_SET_ACTIVE_SLOT SetActiveSlot;
178+
GBL_EFI_AB_SLOT_SET_SLOT_UNBOOTABLE SetSlotUnbootable;
179+
GBL_EFI_AB_SLOT_REINITIALIZE Reinitialize;
180+
GBL_EFI_AB_SLOT_GET_BOOT_MODE GetBootMode;
181+
GBL_EFI_AB_SLOT_SET_BOOT_MODE SetBootMode;
182+
GBL_EFI_AB_SLOT_FLUSH Flush;
183+
};
184+
185+
#endif // GBL_EFI_AB_SLOT_PROTOCOL_H_

‎EmbeddedPkg/Include/Protocol/GblEfiAvb.h‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
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+
// Still in progress
29+
#define GBL_EFI_AVB_PROTOCOL_REVISION 0x00000000
30+
31+
typedef struct _GBL_EFI_AVB_PROTOCOL GBL_EFI_AVB_PROTOCOL;
32+
typedef struct _GBL_EFI_AVB_PARTITION GBL_EFI_AVB_PARTITION;
33+
typedef struct _GBL_EFI_AVB_VERIFICATION_RESULT GBL_EFI_AVB_VERIFICATION_RESULT;
34+
35+
/*
36+
Os-boot state colour per Android Verified Boot.
37+
*/
38+
typedef enum {
39+
GBL_EFI_AVB_BOOT_STATE_GREEN,
40+
GBL_EFI_AVB_BOOT_STATE_YELLOW,
41+
GBL_EFI_AVB_BOOT_STATE_ORANGE,
42+
GBL_EFI_AVB_BOOT_STATE_RED_EIO,
43+
GBL_EFI_AVB_BOOT_STATE_RED,
44+
} GBL_EFI_AVB_BOOT_STATE_COLOR;
45+
46+
/*
47+
Vbmeta key validation status.
48+
*/
49+
typedef enum {
50+
GBL_EFI_AVB_VALID,
51+
GBL_EFI_AVB_VALID_CUSTOM_KEY,
52+
GBL_EFI_AVB_INVALID,
53+
} GBL_EFI_AVB_KEY_VALIDATION_STATUS;
54+
55+
/*
56+
Result of AVB verification to be consumed by firmware UI / ROT.
57+
*/
58+
struct _GBL_EFI_AVB_VERIFICATION_RESULT {
59+
UINT32 Color; // GBL_EFI_AVB_BOOT_STATE_COLOR
60+
CONST CHAR8 *Digest; // Hex digest (NULL if verification failed)
61+
62+
CONST CHAR8 *BootVersion;
63+
CONST CHAR8 *BootSecurityPatch;
64+
CONST CHAR8 *SystemVersion;
65+
CONST CHAR8 *SystemSecurityPatch;
66+
CONST CHAR8 *VendorVersion;
67+
CONST CHAR8 *VendorSecurityPatch;
68+
};
69+
70+
/*
71+
Extra partition name requested for verification.
72+
*/
73+
struct _GBL_EFI_AVB_PARTITION {
74+
UINTN NameLen; // in/out
75+
CHAR8 *Name; // caller-allocated
76+
};
77+
78+
/// Get extra partitions to verify.
79+
typedef
80+
EFI_STATUS
81+
(EFIAPI *GBL_EFI_AVB_READ_PARTITIONS_TO_VERIFY)(
82+
IN GBL_EFI_AVB_PROTOCOL *This,
83+
IN OUT UINTN *NumberOfPartitions,
84+
IN OUT GBL_EFI_AVB_PARTITION *Partitions
85+
);
86+
87+
/// Report dm-verity corruption reboot.
88+
typedef
89+
EFI_STATUS
90+
(EFIAPI *GBL_EFI_AVB_READ_IS_DM_VERITY_ERROR)(
91+
IN GBL_EFI_AVB_PROTOCOL *This,
92+
OUT BOOLEAN *IsDmVerityError
93+
);
94+
95+
/// Verify that vbmeta public key is trusted.
96+
typedef
97+
EFI_STATUS
98+
(EFIAPI *GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY)(
99+
IN GBL_EFI_AVB_PROTOCOL *This,
100+
IN CONST UINT8 *PublicKeyData,
101+
IN UINTN PublicKeyLength,
102+
IN CONST UINT8 *PublicKeyMetadata,
103+
IN UINTN PublicKeyMetadataLength,
104+
OUT UINT32 *ValidationStatus // GBL_EFI_AVB_KEY_VALIDATION_STATUS
105+
);
106+
107+
/// Query device unlock state.
108+
typedef
109+
EFI_STATUS
110+
(EFIAPI *GBL_EFI_AVB_READ_IS_DEVICE_UNLOCKED)(
111+
IN GBL_EFI_AVB_PROTOCOL *This,
112+
OUT BOOLEAN *IsUnlocked
113+
);
114+
115+
/// Read rollback-index fuse.
116+
typedef
117+
EFI_STATUS
118+
(EFIAPI *GBL_EFI_AVB_READ_ROLLBACK_INDEX)(
119+
IN GBL_EFI_AVB_PROTOCOL *This,
120+
IN UINTN IndexLocation,
121+
OUT UINT64 *RollbackIndex
122+
);
123+
124+
/// Program rollback-index fuse.
125+
typedef
126+
EFI_STATUS
127+
(EFIAPI *GBL_EFI_AVB_WRITE_ROLLBACK_INDEX)(
128+
IN GBL_EFI_AVB_PROTOCOL *This,
129+
IN UINTN IndexLocation,
130+
IN UINT64 RollbackIndex
131+
);
132+
133+
/// Read persistent key-value pair.
134+
typedef
135+
EFI_STATUS
136+
(EFIAPI *GBL_EFI_AVB_READ_PERSISTENT_VALUE)(
137+
IN GBL_EFI_AVB_PROTOCOL *This,
138+
IN CONST CHAR8 *Name,
139+
OUT UINT8 *Value,
140+
IN OUT UINTN *ValueSize
141+
);
142+
143+
/// Write or erase persistent key-value pair.
144+
typedef
145+
EFI_STATUS
146+
(EFIAPI *GBL_EFI_AVB_WRITE_PERSISTENT_VALUE)(
147+
IN GBL_EFI_AVB_PROTOCOL *This,
148+
IN CONST CHAR8 *Name,
149+
IN CONST UINT8 *Value,
150+
IN UINTN ValueSize
151+
);
152+
153+
/// Handle overall AVB verification result.
154+
typedef
155+
EFI_STATUS
156+
(EFIAPI *GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT)(
157+
IN GBL_EFI_AVB_PROTOCOL *This,
158+
IN CONST GBL_EFI_AVB_VERIFICATION_RESULT *Result
159+
);
160+
161+
/*
162+
Firmware-published protocol instance.
163+
*/
164+
struct _GBL_EFI_AVB_PROTOCOL {
165+
UINT64 Revision;
166+
GBL_EFI_AVB_READ_PARTITIONS_TO_VERIFY ReadPartitionsToVerify;
167+
GBL_EFI_AVB_READ_IS_DM_VERITY_ERROR ReadIsDmVerityError;
168+
GBL_EFI_AVB_VALIDATE_VBMETA_PUBLIC_KEY ValidateVbmetaPublicKey;
169+
GBL_EFI_AVB_READ_IS_DEVICE_UNLOCKED ReadIsDeviceUnlocked;
170+
GBL_EFI_AVB_READ_ROLLBACK_INDEX ReadRollbackIndex;
171+
GBL_EFI_AVB_WRITE_ROLLBACK_INDEX WriteRollbackIndex;
172+
GBL_EFI_AVB_READ_PERSISTENT_VALUE ReadPersistentValue;
173+
GBL_EFI_AVB_WRITE_PERSISTENT_VALUE WritePersistentValue;
174+
GBL_EFI_AVB_HANDLE_VERIFICATION_RESULT HandleVerificationResult;
175+
};
176+
177+
#endif // GBL_EFI_AVB_PROTOCOL_H_

0 commit comments

Comments
 (0)