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