1# EFI Android Boot Protocol
2
3This document describes the Android Boot protocol. The protocol defines
4interfaces that can be used by EFI applications to implement an Android
5bootloader in compliance with the Android Verified Boot(AVB) requirement and
6tooling interfaces such as the Fastboot over USB protocol.
7
8|||
9| ----------- | ----------- |
10| **Status** | Work in progress |
11| **Created** | 2024-3-21 |
12
13
14## EFI_ANDROID_BOOT_PROTOCOL
15
16### Summary
17
18This protocol provides interfaces for platform-specific AVB operations, such as
19reading/writing antirollback indices, persistant values, and performing AVB
20public key validation etc. It also defines interfaces that abstract platform
21USB controller for interfacing with the Android Fastboot tooling. These include
22starting/stopping a Fastboot USB interface and sending/receiving USB packets.
23
24### GUID
25
26```c
27// {6281a893-ac23-4ca7-b281-340ef8168955}
28#define EFI_ANDROID_BOOT_PROTOCOL_GUID               \
29  {                                                  \
30    0x6281a893, 0xac23, 0x4ca7, {                    \
31      0xb2, 0x81, 0x34, 0x0e, 0xf8, 0x16, 0x89, 0x55 \
32    }                                                \
33  }
34```
35
36### Revision Number
37
38```c
39#define EFI_ANDROID_BOOT_PROTOCOL_REVISION 0x00000000
40```
41
42### Protocol Interface Structure
43
44```c
45typedef struct _EFI_ANDROID_BOOT_PROTOCOL {
46  UINT64                                          Revision;
47  EFI_ANDROID_BOOT_FASTBOOT_USB_INTERFACE_START   FastbootUsbInterfaceStart;
48  EFI_ANDROID_BOOT_FASTBOOT_USB_INTERFACE_STOP    FastbootUsbInterfaceStop;
49  EFI_ANDROID_BOOT_FASTBOOT_USB_RECEIVE           FastbootUsbReceive;
50  EFI_ANDROID_BOOT_FASTBOOT_USB_SEND              FastbootUsbSend;
51  EFI_EVENT                                       WaitForSendCompletion;
52} EFI_ANDROID_BOOT_PROTOCOL;
53```
54
55### Parameters
56
57**Revision**
58The revision to which the EFI_ANDROID_BOOT_PROTOCOL adheres. All future revisions must be
59backwards compatible. If a future version is not backwards compatible, a
60different GUID must be used.
61
62**FastbootUsbInterfaceStart**
63Starts a USB interface for Fastboot traffic. See
64[`EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbInterfaceStart()`](#efi_android_boot_protocolfastbootusbinterfacestart).
65
66**FastbootUsbInterfaceStop**
67Stops the USB interface started by `FastbootUsbInterfaceStart()`. See
68[`EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbInterfaceStop()`](#efi_android_boot_protocolfastbootusbinterfacestop).
69
70**FastbootUsbReceive**
71Polls and receives the next USB packet if available. See
72[`EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbReceive()`](#efi_android_boot_protocolfastbootusbreceive).
73
74**FastbootUsbSend**
75Sends a USB packet. See
76[`EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbSend()`](#efi_android_boot_protocolfastbootusbsend).
77
78**WaitForSendCompletion**
79Event used with `EFI_BOOT_SERVICES.WaitForEvent()` to wait for the previous
80packet sent by `FastbootUsbSend()` to complete.
81
82
83## EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbInterfaceStart()
84
85### Summary
86
87Starts a USB interface for Fastboot.
88
89### Prototype
90
91```c
92typedef
93EFI_STATUS
94(EFIAPI * EFI_ANDROID_BOOT_FASTBOOT_USB_INTERFACE_START)(
95  IN EFI_ANDROID_BOOT_PROTOCOL  *This,
96  OUT UINTN                     *MaxPacketSize,
97  );
98```
99
100### Parameters
101
102*This*
103A pointer to the [`EFI_ANDROID_BOOT_PROTOCOL`](#efi_android_boot_protocol) instance.
104
105*MaxPacketSize*
106On exit, set to the maximum packet size in bytes allowed by the USB interface.
107
108### Description
109
110`FastbootUsbInterfaceStart()` shoud start and expose a device mode USB inteface
111that can be used by `FastbootUsbReceive()` and `FastbootUsbSend()` to exchange
112USB packets. In order for the interface to be compatible with the Android
113Fastboot tool, the interface setup should meet the following requirement:
114
115* The USB interface should contain two bulk endpoints (in, out).
116* Max packet size must be 64 bytes for full-speed, 512 bytes for high-speed and
1171024 bytes for Super Speed USB.
118* The class, subclass and protocol code in the USB interface descriptor should be
119set to the values specified by the upstream Fastboot USB protocol:
120  * Interface class: 0xff (Vendor specific)
121  * Interface subclass: 0x42 (ADB)
122  * Interface protocol: 0x03 (Fastboot)
123* The USB device descriptor should provide a valid serial number string
124descriptor.
125
126**Note**: EFI_USBFN_IO_PROTOCOL is not used because: 1) it lacks support for
127specifying serial number and USB3.0 at the time this protocol is drafted. 2)
128Other than the requirement above, the rest of USB configuration required by
129EFI_USBFN_IO_PROTOCOL is not concerned by the Fastboot USB protocol. The
130abstracted interfaces allow EFI Fastboot applications to avoid having to know
131how to configure a full USB.
132
133**Note**: This protocol is not applicable to platforms that only operate in USB
134host mode. However, platforms that support xHCI debug capability (DbC) can
135present as a USB device and thus communicate with a host. Future revision of
136this protocol and Android Fastboot tool may support this usecase.
137
138### Status Codes Returned
139
140|||
141| ----------- | ----------- |
142| EFI_SUCCESS | USB interface is started successfully. |
143| EFI_INVALID_PARAMETER | A parameter is invalid. |
144| EFI_ALREADY_STARTED | USB interface is already started. |
145| EFI_NO_RESPONSE | USB is not connected |
146| EFI_UNSUPPORTED | USB is not supported by the platform |
147| EFI_DEVICE_ERROR | The physical device reported an error. |
148
149## EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbInterfaceStop()
150
151### Summary
152
153Stops the USB interface started by `FastbootUsbInterfaceStart()`.
154
155### Prototype
156
157```c
158typedef
159EFI_STATUS
160(EFIAPI * EFI_ANDROID_BOOT_FASTBOOT_USB_INTERFACE_STOP)(
161  IN EFI_ANDROID_BOOT_PROTOCOL  *This
162  );
163```
164
165### Parameters
166
167*This*
168A pointer to the [`EFI_ANDROID_BOOT_PROTOCOL`](#efi_android_boot_protocol)
169instance.
170
171### Description
172
173`FastbootUsbInterfaceStop()` should abort any pending transfer and remove the
174USB interface started by `FastbootUsbInterfaceStart()` from the USB descriptors.
175Upon successful return, the device should no longer be visible as a Fastboot
176device from the host.
177
178### Status Codes Returned
179
180|||
181| ----------- | ----------- |
182| EFI_SUCCESS | USB interface is stopped successfully.|
183| EFI_INVALID_PARAMETER | A parameter is invalid.|
184| EFI_NOT_STARTED | The USB interface is not started.|
185| EFI_DEVICE_ERROR | The physical device reported an error.|
186
187## EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbReceive()
188
189### Summary
190
191Receives a USB packet from the interface started by
192`FastbootUsbInterfaceStart()`.
193
194### Prototype
195
196```c
197typedef
198EFI_STATUS
199(EFIAPI * EFI_ANDROID_BOOT_FASTBOOT_USB_RECEIVE)(
200  IN EFI_ANDROID_BOOT_PROTOCOL  *This,
201  IN OUT UINTN                  *BufferSize,
202  OUT VOID                      *Buffer,
203  );
204```
205
206### Parameters
207
208*This*
209A pointer to the [`EFI_ANDROID_BOOT_PROTOCOL`](#efi_android_boot_protocol)
210instance.
211
212*BufferSize*
213On entry, the size in bytes of `Buffer`. On exit, the size in bytes of the
214packet that was received.
215
216*Buffer*
217A pointer to the data buffer to receive the USB packet.
218
219### Description
220
221`FastbootUsbReceive()` should poll and, if available, receive the next USB
222packet from the Fastboot USB interface into the provided buffer.
223
224### Status Codes Returned
225
226|||
227| ----------- | ----------- |
228| EFI_SUCCESS | A new USB packet is received successfully. |
229| EFI_INVALID_PARAMETER | A parameter is invalid.|
230| EFI_NOT_STARTED | The USB interface is not started.|
231| EFI_NOT_READY | No packet has been received from the interface.|
232| EFI_BUFFER_TOO_SMALL | Buffer is too small for the next packet. `BufferSize` should be updated to the required size in this case. |
233| EFI_DEVICE_ERROR | The physical device reported an error.|
234
235## EFI_ANDROID_BOOT_PROTOCOL.FastbootUsbSend()
236
237### Summary
238
239Sends a USB packet from the USB interface started by
240`FastbootUsbInterfaceStart()`.
241
242### Prototype
243
244```c
245typedef
246EFI_STATUS
247(EFIAPI * EFI_ANDROID_BOOT_FASTBOOT_USB_SEND)(
248  IN EFI_ANDROID_BOOT_PROTOCOL  *This,
249  IN OUT UINTN                  *BufferSize,
250  IN CONST VOID                 *Buffer,
251  );
252```
253
254### Parameters
255
256*This*
257A pointer to the [`EFI_ANDROID_BOOT_PROTOCOL`](#efi_android_boot_protocol)
258instance.
259
260*BufferSize*
261On entry, the size in bytes of `Buffer` to be sent. If the size is greater than
262the maximum packet size of the USB interface, it should be set to the maximum
263packet size and EFI_BAD_BUFFER_SIZE should be returned.
264
265*Buffer*
266A pointer to the data buffer to be sent.
267
268### Description
269
270`FastbootUsbSend()` should copy the provided packet into an internal Tx buffer
271owned by the protocol driver and initiate the send. The interface is
272non-blocking and should return immediately. It should not accept any new packet
273if the previous one hasn't complete.
274
275### Status Codes Returned
276
277|||
278| ----------- | ----------- |
279| EFI_SUCCESS | The USB packet is sent successfully. |
280| EFI_INVALID_PARAMETER | A parameter is invalid.|
281| EFI_NOT_STARTED | The USB interface is not started.|
282| EFI_NOT_READY | The previous packet is still pending. |
283| EFI_BAD_BUFFER_SIZE | `BufferSize` is greater than the maximum packet size of the USB interface. `BufferSize` should be updated to the maximum packet size in this case. |
284| EFI_DEVICE_ERROR | The physical device reported an error.|
285