]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/UsbIo.h
UefiCpuPkg: Move AsmRelocateApLoopStart from Mpfuncs.nasm to AmdSev.nasm
[mirror_edk2.git] / MdePkg / Include / Protocol / UsbIo.h
1 /** @file
2 EFI Usb I/O Protocol as defined in UEFI specification.
3 This protocol is used by code, typically drivers, running in the EFI
4 boot services environment to access USB devices like USB keyboards,
5 mice and mass storage devices. In particular, functions for managing devices
6 on USB buses are defined here.
7
8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
9 SPDX-License-Identifier: BSD-2-Clause-Patent
10
11 **/
12
13 #ifndef __USB_IO_H__
14 #define __USB_IO_H__
15
16 #include <IndustryStandard/Usb.h>
17
18 //
19 // Global ID for the USB I/O Protocol
20 //
21 #define EFI_USB_IO_PROTOCOL_GUID \
22 { \
23 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
24 }
25
26 typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL;
27
28 //
29 // Related Definition for EFI USB I/O protocol
30 //
31
32 //
33 // USB standard descriptors and reqeust
34 //
35 typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST;
36 typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR;
37 typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR;
38 typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR;
39 typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR;
40
41 ///
42 /// USB data transfer direction
43 ///
44 typedef enum {
45 EfiUsbDataIn,
46 EfiUsbDataOut,
47 EfiUsbNoData
48 } EFI_USB_DATA_DIRECTION;
49
50 //
51 // USB Transfer Results
52 //
53 #define EFI_USB_NOERROR 0x00
54 #define EFI_USB_ERR_NOTEXECUTE 0x01
55 #define EFI_USB_ERR_STALL 0x02
56 #define EFI_USB_ERR_BUFFER 0x04
57 #define EFI_USB_ERR_BABBLE 0x08
58 #define EFI_USB_ERR_NAK 0x10
59 #define EFI_USB_ERR_CRC 0x20
60 #define EFI_USB_ERR_TIMEOUT 0x40
61 #define EFI_USB_ERR_BITSTUFF 0x80
62 #define EFI_USB_ERR_SYSTEM 0x100
63
64 /**
65 Async USB transfer callback routine.
66
67 @param Data Data received or sent via the USB Asynchronous Transfer, if the
68 transfer completed successfully.
69 @param DataLength The length of Data received or sent via the Asynchronous
70 Transfer, if transfer successfully completes.
71 @param Context Data passed from UsbAsyncInterruptTransfer() request.
72 @param Status Indicates the result of the asynchronous transfer.
73
74 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
75 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
76
77 **/
78 typedef
79 EFI_STATUS
80 (EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK)(
81 IN VOID *Data,
82 IN UINTN DataLength,
83 IN VOID *Context,
84 IN UINT32 Status
85 );
86
87 //
88 // Prototype for EFI USB I/O protocol
89 //
90
91 /**
92 This function is used to manage a USB device with a control transfer pipe. A control transfer is
93 typically used to perform device initialization and configuration.
94
95 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
96 @param Request A pointer to the USB device request that will be sent to the USB
97 device.
98 @param Direction Indicates the data direction.
99 @param Timeout Indicating the transfer should be completed within this time frame.
100 The units are in milliseconds.
101 @param Data A pointer to the buffer of data that will be transmitted to USB
102 device or received from USB device.
103 @param DataLength The size, in bytes, of the data buffer specified by Data.
104 @param Status A pointer to the result of the USB transfer.
105
106 @retval EFI_SUCCESS The control transfer has been successfully executed.
107 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
108 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
109 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
110 @retval EFI_TIMEOUT The control transfer fails due to timeout.
111
112 **/
113 typedef
114 EFI_STATUS
115 (EFIAPI *EFI_USB_IO_CONTROL_TRANSFER)(
116 IN EFI_USB_IO_PROTOCOL *This,
117 IN EFI_USB_DEVICE_REQUEST *Request,
118 IN EFI_USB_DATA_DIRECTION Direction,
119 IN UINT32 Timeout,
120 IN OUT VOID *Data OPTIONAL,
121 IN UINTN DataLength OPTIONAL,
122 OUT UINT32 *Status
123 );
124
125 /**
126 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
127 typically used to transfer large amounts of data to/from USB devices.
128
129 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
130 @param DeviceEndpoint The destination USB device endpoint to which the
131 device request is being sent. DeviceEndpoint must
132 be between 0x01 and 0x0F or between 0x81 and 0x8F,
133 otherwise EFI_INVALID_PARAMETER is returned. If
134 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
135 is returned. The MSB of this parameter indicates
136 the endpoint direction. The number "1" stands for
137 an IN endpoint, and "0" stands for an OUT endpoint.
138 @param Data A pointer to the buffer of data that will be transmitted to USB
139 device or received from USB device.
140 @param DataLength The size, in bytes, of the data buffer specified by Data.
141 On input, the size, in bytes, of the data buffer specified by Data.
142 On output, the number of bytes that were actually transferred.
143 @param Timeout Indicating the transfer should be completed within this time frame.
144 The units are in milliseconds. If Timeout is 0, then the
145 caller must wait for the function to be completed until
146 EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
147 @param Status This parameter indicates the USB transfer status.
148
149 @retval EFI_SUCCESS The bulk transfer has been successfully executed.
150 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
151 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
152 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
153 @retval EFI_TIMEOUT The control transfer fails due to timeout.
154
155 **/
156 typedef
157 EFI_STATUS
158 (EFIAPI *EFI_USB_IO_BULK_TRANSFER)(
159 IN EFI_USB_IO_PROTOCOL *This,
160 IN UINT8 DeviceEndpoint,
161 IN OUT VOID *Data,
162 IN OUT UINTN *DataLength,
163 IN UINTN Timeout,
164 OUT UINT32 *Status
165 );
166
167 /**
168 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous
169 Interrupt Transfer is typically used to query a device's status at a fixed rate. For example,
170 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at
171 a fixed rate.
172
173 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
174 @param DeviceEndpoint The destination USB device endpoint to which the
175 device request is being sent. DeviceEndpoint must
176 be between 0x01 and 0x0F or between 0x81 and 0x8F,
177 otherwise EFI_INVALID_PARAMETER is returned. If
178 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
179 is returned. The MSB of this parameter indicates
180 the endpoint direction. The number "1" stands for
181 an IN endpoint, and "0" stands for an OUT endpoint.
182 @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If
183 FALSE, the interrupt transfer is deleted from the device's interrupt
184 transfer queue.
185 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be
186 executed.This parameter is required when IsNewTransfer is TRUE. The
187 value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned.
188 The units are in milliseconds.
189 @param DataLength Specifies the length, in bytes, of the data to be received from the
190 USB device. This parameter is only required when IsNewTransfer is TRUE.
191 @param InterruptCallback The Callback function. This function is called if the asynchronous
192 interrupt transfer is completed. This parameter is required
193 when IsNewTransfer is TRUE.
194 @param Context Data passed to the InterruptCallback function. This is an optional
195 parameter and may be NULL.
196
197 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.
198 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
199
200 **/
201 typedef
202 EFI_STATUS
203 (EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER)(
204 IN EFI_USB_IO_PROTOCOL *This,
205 IN UINT8 DeviceEndpoint,
206 IN BOOLEAN IsNewTransfer,
207 IN UINTN PollingInterval OPTIONAL,
208 IN UINTN DataLength OPTIONAL,
209 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL,
210 IN VOID *Context OPTIONAL
211 );
212
213 /**
214 This function is used to manage a USB device with an interrupt transfer pipe.
215
216 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
217 @param DeviceEndpoint The destination USB device endpoint to which the
218 device request is being sent. DeviceEndpoint must
219 be between 0x01 and 0x0F or between 0x81 and 0x8F,
220 otherwise EFI_INVALID_PARAMETER is returned. If
221 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
222 is returned. The MSB of this parameter indicates
223 the endpoint direction. The number "1" stands for
224 an IN endpoint, and "0" stands for an OUT endpoint.
225 @param Data A pointer to the buffer of data that will be transmitted to USB
226 device or received from USB device.
227 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the
228 amount of data actually transferred.
229 @param Timeout The time out, in seconds, for this transfer. If Timeout is 0,
230 then the caller must wait for the function to be completed
231 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the
232 transfer is not completed in this time frame, then EFI_TIMEOUT is returned.
233 @param Status This parameter indicates the USB transfer status.
234
235 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.
236 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
237 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.
238 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
239 @retval EFI_TIMEOUT The transfer fails due to timeout.
240 **/
241 typedef
242 EFI_STATUS
243 (EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER)(
244 IN EFI_USB_IO_PROTOCOL *This,
245 IN UINT8 DeviceEndpoint,
246 IN OUT VOID *Data,
247 IN OUT UINTN *DataLength,
248 IN UINTN Timeout,
249 OUT UINT32 *Status
250 );
251
252 /**
253 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
254 transfer is typically used to transfer streaming data.
255
256 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
257 @param DeviceEndpoint The destination USB device endpoint to which the
258 device request is being sent. DeviceEndpoint must
259 be between 0x01 and 0x0F or between 0x81 and 0x8F,
260 otherwise EFI_INVALID_PARAMETER is returned. If
261 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
262 is returned. The MSB of this parameter indicates
263 the endpoint direction. The number "1" stands for
264 an IN endpoint, and "0" stands for an OUT endpoint.
265 @param Data A pointer to the buffer of data that will be transmitted to USB
266 device or received from USB device.
267 @param DataLength The size, in bytes, of the data buffer specified by Data.
268 @param Status This parameter indicates the USB transfer status.
269
270 @retval EFI_SUCCESS The isochronous transfer has been successfully executed.
271 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
272 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status
273 is returned in Status.
274 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
275 @retval EFI_TIMEOUT The transfer fails due to timeout.
276 **/
277 typedef
278 EFI_STATUS
279 (EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER)(
280 IN EFI_USB_IO_PROTOCOL *This,
281 IN UINT8 DeviceEndpoint,
282 IN OUT VOID *Data,
283 IN UINTN DataLength,
284 OUT UINT32 *Status
285 );
286
287 /**
288 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
289 transfer is typically used to transfer streaming data.
290
291 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
292 @param DeviceEndpoint The destination USB device endpoint to which the
293 device request is being sent. DeviceEndpoint must
294 be between 0x01 and 0x0F or between 0x81 and 0x8F,
295 otherwise EFI_INVALID_PARAMETER is returned. If
296 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
297 is returned. The MSB of this parameter indicates
298 the endpoint direction. The number "1" stands for
299 an IN endpoint, and "0" stands for an OUT endpoint.
300 @param Data A pointer to the buffer of data that will be transmitted to USB
301 device or received from USB device.
302 @param DataLength The size, in bytes, of the data buffer specified by Data.
303 This is an optional parameter and may be NULL.
304 @param IsochronousCallback The IsochronousCallback() function.This function is
305 called if the requested isochronous transfer is completed.
306 @param Context Data passed to the IsochronousCallback() function.
307
308 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted
309 to the system.
310 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
311 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
312
313 **/
314 typedef
315 EFI_STATUS
316 (EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER)(
317 IN EFI_USB_IO_PROTOCOL *This,
318 IN UINT8 DeviceEndpoint,
319 IN OUT VOID *Data,
320 IN UINTN DataLength,
321 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,
322 IN VOID *Context OPTIONAL
323 );
324
325 /**
326 Resets and reconfigures the USB controller. This function will work for all USB devices except
327 USB Hub Controllers.
328
329 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
330
331 @retval EFI_SUCCESS The USB controller was reset.
332 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
333 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.
334
335 **/
336 typedef
337 EFI_STATUS
338 (EFIAPI *EFI_USB_IO_PORT_RESET)(
339 IN EFI_USB_IO_PROTOCOL *This
340 );
341
342 /**
343 Retrieves the USB Device Descriptor.
344
345 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
346 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.
347
348 @retval EFI_SUCCESS The device descriptor was retrieved successfully.
349 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
350 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.
351
352 **/
353 typedef
354 EFI_STATUS
355 (EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR)(
356 IN EFI_USB_IO_PROTOCOL *This,
357 OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor
358 );
359
360 /**
361 Retrieves the USB Device Descriptor.
362
363 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
364 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
365 Descriptor.
366 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.
367 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
368 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not
369 be configured.
370
371 **/
372 typedef
373 EFI_STATUS
374 (EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR)(
375 IN EFI_USB_IO_PROTOCOL *This,
376 OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor
377 );
378
379 /**
380 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
381 within a USB device is equivalently to a USB Controller within the current configuration.
382
383 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
384 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
385 the configuration setting.
386 @retval EFI_SUCCESS The interface descriptor retrieved successfully.
387 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
388 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be
389 correctly configured.
390
391 **/
392 typedef
393 EFI_STATUS
394 (EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR)(
395 IN EFI_USB_IO_PROTOCOL *This,
396 OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor
397 );
398
399 /**
400 Retrieves an Endpoint Descriptor within a USB Controller.
401
402 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
403 @param EndpointIndex Indicates which endpoint descriptor to retrieve.
404 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
405 a USB controller.
406
407 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.
408 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
409 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be
410 correctly configured.
411
412 **/
413 typedef
414 EFI_STATUS
415 (EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR)(
416 IN EFI_USB_IO_PROTOCOL *This,
417 IN UINT8 EndpointIndex,
418 OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor
419 );
420
421 /**
422 Retrieves a string stored in a USB Device.
423
424 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
425 @param LangID The Language ID for the string being retrieved.
426 @param StringID The ID of the string being retrieved.
427 @param String A pointer to a buffer allocated by this function with
428 AllocatePool() to store the string.If this function
429 returns EFI_SUCCESS, it stores the string the caller
430 wants to get. The caller should release the string
431 buffer with FreePool() after the string is not used any more.
432
433 @retval EFI_SUCCESS The string was retrieved successfully.
434 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.
435 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.
436
437 **/
438 typedef
439 EFI_STATUS
440 (EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR)(
441 IN EFI_USB_IO_PROTOCOL *This,
442 IN UINT16 LangID,
443 IN UINT8 StringID,
444 OUT CHAR16 **String
445 );
446
447 /**
448 Retrieves all the language ID codes that the USB device supports.
449
450 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
451 @param LangIDTable Language ID for the string the caller wants to get.
452 This is a 16-bit ID defined by Microsoft. This
453 buffer pointer is allocated and maintained by
454 the USB Bus Driver, the caller should not modify
455 its contents.
456 @param TableSize The size, in bytes, of the table LangIDTable.
457
458 @retval EFI_SUCCESS The support languages were retrieved successfully.
459
460 **/
461 typedef
462 EFI_STATUS
463 (EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE)(
464 IN EFI_USB_IO_PROTOCOL *This,
465 OUT UINT16 **LangIDTable,
466 OUT UINT16 *TableSize
467 );
468
469 ///
470 /// The EFI_USB_IO_PROTOCOL provides four basic transfers types described
471 /// in the USB 1.1 Specification. These include control transfer, interrupt
472 /// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL
473 /// also provides some basic USB device/controller management and configuration
474 /// interfaces. A USB device driver uses the services of this protocol to manage USB devices.
475 ///
476 struct _EFI_USB_IO_PROTOCOL {
477 //
478 // IO transfer
479 //
480 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer;
481 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer;
482 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer;
483 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer;
484 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer;
485 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;
486
487 //
488 // Common device request
489 //
490 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor;
491 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor;
492 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor;
493 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor;
494 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor;
495 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages;
496
497 //
498 // Reset controller's parent port
499 //
500 EFI_USB_IO_PORT_RESET UsbPortReset;
501 };
502
503 extern EFI_GUID gEfiUsbIoProtocolGuid;
504
505 #endif