Skip to content

Commit 8eea4e5

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 8eea4e5

File tree

7 files changed

+878
-0
lines changed

7 files changed

+878
-0
lines changed

‎EmbeddedPkg/Include/Protocol/GblEfiAbSlot.h‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
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-reason codes.
58+
*/
59+
typedef enum {
60+
GBL_EFI_BOOT_REASON_EMPTY = 0,
61+
GBL_EFI_BOOT_REASON_UNKNOWN = 1,
62+
GBL_EFI_BOOT_REASON_WATCHDOG = 14,
63+
GBL_EFI_BOOT_REASON_KERNEL_PANIC = 15,
64+
GBL_EFI_BOOT_REASON_RECOVERY = 3,
65+
GBL_EFI_BOOT_REASON_BOOTLOADER = 55,
66+
GBL_EFI_BOOT_REASON_COLD = 56,
67+
GBL_EFI_BOOT_REASON_HARD = 57,
68+
GBL_EFI_BOOT_REASON_WARM = 58,
69+
GBL_EFI_BOOT_REASON_SHUTDOWN = 59,
70+
GBL_EFI_BOOT_REASON_REBOOT = 18,
71+
GBL_EFI_BOOT_REASON_FASTBOOTD = 196
72+
} GBL_EFI_BOOT_REASON;
73+
74+
/*
75+
Per-slot state.
76+
*/
77+
struct _GBL_EFI_SLOT_INFO {
78+
UINT32 Suffix; // UTF-8 code-point of slot letter
79+
UINT32 UnbootableReason; // GBL_EFI_UNBOOTABLE_REASON
80+
UINT8 Priority;
81+
UINT8 Tries;
82+
UINT8 Successful; // 1 if slot booted once
83+
};
84+
85+
/*
86+
Global slot-metadata block.
87+
*/
88+
struct _GBL_EFI_SLOT_METADATA_BLOCK {
89+
UINT8 UnbootableMetadata; // 1 if reasons tracked
90+
UINT8 MaxRetries;
91+
UINT8 SlotCount;
92+
UINT8 MergeStatus; // GBL_EFI_SLOT_MERGE_STATUS
93+
};
94+
95+
/// Load immutable slot metadata.
96+
typedef
97+
EFI_STATUS
98+
(EFIAPI *GBL_EFI_AB_SLOT_LOAD_BOOT_DATA)(
99+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
100+
OUT GBL_EFI_SLOT_METADATA_BLOCK *Metadata
101+
);
102+
103+
/// Get info for slot by index.
104+
typedef
105+
EFI_STATUS
106+
(EFIAPI *GBL_EFI_AB_SLOT_GET_SLOT_INFO)(
107+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
108+
IN UINT8 Index,
109+
OUT GBL_EFI_SLOT_INFO *Info
110+
);
111+
112+
/// Get info for current slot.
113+
typedef
114+
EFI_STATUS
115+
(EFIAPI *GBL_EFI_AB_SLOT_GET_CURRENT_SLOT)(
116+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
117+
OUT GBL_EFI_SLOT_INFO *Info
118+
);
119+
120+
/// Decide next slot; optionally mark boot attempt.
121+
typedef
122+
EFI_STATUS
123+
(EFIAPI *GBL_EFI_AB_SLOT_GET_NEXT_SLOT)(
124+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
125+
IN BOOLEAN MarkBootAttempt,
126+
OUT GBL_EFI_SLOT_INFO *Info
127+
);
128+
129+
/// Make slot active.
130+
typedef
131+
EFI_STATUS
132+
(EFIAPI *GBL_EFI_AB_SLOT_SET_ACTIVE_SLOT)(
133+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
134+
IN UINT8 Index
135+
);
136+
137+
/// Mark slot unbootable with reason.
138+
typedef
139+
EFI_STATUS
140+
(EFIAPI *GBL_EFI_AB_SLOT_SET_SLOT_UNBOOTABLE)(
141+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
142+
IN UINT8 Index,
143+
IN UINT32 UnbootableReason // GBL_EFI_UNBOOTABLE_REASON
144+
);
145+
146+
/// Re-initialise all slot metadata.
147+
typedef
148+
EFI_STATUS
149+
(EFIAPI *GBL_EFI_AB_SLOT_REINITIALIZE)(
150+
IN GBL_EFI_AB_SLOT_PROTOCOL *This
151+
);
152+
153+
/// Read boot reason and sub-reason string.
154+
typedef
155+
EFI_STATUS
156+
(EFIAPI *GBL_EFI_AB_SLOT_GET_BOOT_REASON)(
157+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
158+
OUT UINT32 *Reason, // GBL_EFI_BOOT_REASON
159+
IN OUT UINTN *SubreasonLength,
160+
OUT CHAR8 *Subreason
161+
);
162+
163+
/// Set boot reason and sub-reason string.
164+
typedef
165+
EFI_STATUS
166+
(EFIAPI *GBL_EFI_AB_SLOT_SET_BOOT_REASON)(
167+
IN GBL_EFI_AB_SLOT_PROTOCOL *This,
168+
IN UINT32 Reason, // GBL_EFI_BOOT_REASON
169+
IN UINTN SubreasonLength,
170+
IN CONST CHAR8 *Subreason
171+
);
172+
173+
/// Flush metadata to persistent storage.
174+
typedef
175+
EFI_STATUS
176+
(EFIAPI *GBL_EFI_AB_SLOT_FLUSH)(
177+
IN GBL_EFI_AB_SLOT_PROTOCOL *This
178+
);
179+
180+
/*
181+
Firmware-published protocol instance.
182+
*/
183+
struct _GBL_EFI_AB_SLOT_PROTOCOL {
184+
UINT32 Version;
185+
GBL_EFI_AB_SLOT_LOAD_BOOT_DATA LoadBootData;
186+
GBL_EFI_AB_SLOT_GET_SLOT_INFO GetSlotInfo;
187+
GBL_EFI_AB_SLOT_GET_CURRENT_SLOT GetCurrentSlot;
188+
GBL_EFI_AB_SLOT_GET_NEXT_SLOT GetNextSlot;
189+
GBL_EFI_AB_SLOT_SET_ACTIVE_SLOT SetActiveSlot;
190+
GBL_EFI_AB_SLOT_SET_SLOT_UNBOOTABLE SetSlotUnbootable;
191+
GBL_EFI_AB_SLOT_REINITIALIZE Reinitialize;
192+
GBL_EFI_AB_SLOT_GET_BOOT_REASON GetBootReason;
193+
GBL_EFI_AB_SLOT_SET_BOOT_REASON SetBootReason;
194+
GBL_EFI_AB_SLOT_FLUSH Flush;
195+
};
196+
197+
#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)