Skip to content

Commit 7d78077

Browse files
dimorinnydpursellsoftware-dovrmuthiahSergii Parubochyi
committed
EmbeddedPkg: Introduce GBL protocols
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 41c8bf0 commit 7d78077

File tree

7 files changed

+868
-0
lines changed

7 files changed

+868
-0
lines changed

‎EmbeddedPkg/Include/Protocol/GblEfiAbSlot.h‎

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

‎EmbeddedPkg/Include/Protocol/GblEfiAvb.h‎

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

0 commit comments

Comments
 (0)