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.
8 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>
9 This program and the accompanying materials
10 are licensed and made available under the terms and conditions of the BSD License
11 which accompanies this distribution. The full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
22 #include <IndustryStandard/Usb.h>
25 // Global ID for the USB I/O Protocol
27 #define EFI_USB_IO_PROTOCOL_GUID \
29 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
32 typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL
;
35 // Related Definition for EFI USB I/O protocol
39 // USB standard descriptors and reqeust
41 typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST
;
42 typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR
;
43 typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR
;
44 typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR
;
45 typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR
;
48 /// USB data transfer direction
54 } EFI_USB_DATA_DIRECTION
;
57 // USB Transfer Results
59 #define EFI_USB_NOERROR 0x00
60 #define EFI_USB_ERR_NOTEXECUTE 0x01
61 #define EFI_USB_ERR_STALL 0x02
62 #define EFI_USB_ERR_BUFFER 0x04
63 #define EFI_USB_ERR_BABBLE 0x08
64 #define EFI_USB_ERR_NAK 0x10
65 #define EFI_USB_ERR_CRC 0x20
66 #define EFI_USB_ERR_TIMEOUT 0x40
67 #define EFI_USB_ERR_BITSTUFF 0x80
68 #define EFI_USB_ERR_SYSTEM 0x100
71 Async USB transfer callback routine.
73 @param Data Data received or sent via the USB Asynchronous Transfer, if the
74 transfer completed successfully.
75 @param DataLength The length of Data received or sent via the Asynchronous
76 Transfer, if transfer successfully completes.
77 @param Context Data passed from UsbAsyncInterruptTransfer() request.
78 @param Status Indicates the result of the asynchronous transfer.
80 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
81 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
86 (EFIAPI
*EFI_ASYNC_USB_TRANSFER_CALLBACK
)(
94 // Prototype for EFI USB I/O protocol
99 This function is used to manage a USB device with a control transfer pipe. A control transfer is
100 typically used to perform device initialization and configuration.
102 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
103 @param Request A pointer to the USB device request that will be sent to the USB
105 @param Direction Indicates the data direction.
106 @param Timeout Indicating the transfer should be completed within this time frame.
107 The units are in milliseconds.
108 @param Data A pointer to the buffer of data that will be transmitted to USB
109 device or received from USB device.
110 @param DataLength The size, in bytes, of the data buffer specified by Data.
111 @param Status A pointer to the result of the USB transfer.
113 @retval EFI_SUCCESS The control transfer has been successfully executed.
114 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
115 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
116 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
117 @retval EFI_TIMEOUT The control transfer fails due to timeout.
122 (EFIAPI
*EFI_USB_IO_CONTROL_TRANSFER
)(
123 IN EFI_USB_IO_PROTOCOL
*This
,
124 IN EFI_USB_DEVICE_REQUEST
*Request
,
125 IN EFI_USB_DATA_DIRECTION Direction
,
127 IN OUT VOID
*Data OPTIONAL
,
128 IN UINTN DataLength OPTIONAL
,
133 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
134 typically used to transfer large amounts of data to/from USB devices.
136 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
137 @param DeviceEndpoint The destination USB device endpoint to which the
138 device request is being sent. DeviceEndpoint must
139 be between 0x01 and 0x0F or between 0x81 and 0x8F,
140 otherwise EFI_INVALID_PARAMETER is returned. If
141 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
142 is returned. The MSB of this parameter indicates
143 the endpoint direction. The number "1" stands for
144 an IN endpoint, and "0" stands for an OUT endpoint.
145 @param Data A pointer to the buffer of data that will be transmitted to USB
146 device or received from USB device.
147 @param DataLength The size, in bytes, of the data buffer specified by Data.
148 On input, the size, in bytes, of the data buffer specified by Data.
149 On output, the number of bytes that were actually transferred.
150 @param Timeout Indicating the transfer should be completed within this time frame.
151 The units are in milliseconds. If Timeout is 0, then the
152 caller must wait for the function to be completed until
153 EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
154 @param Status This parameter indicates the USB transfer status.
156 @retval EFI_SUCCESS The bulk transfer has been successfully executed.
157 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
158 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
159 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
160 @retval EFI_TIMEOUT The control transfer fails due to timeout.
165 (EFIAPI
*EFI_USB_IO_BULK_TRANSFER
)(
166 IN EFI_USB_IO_PROTOCOL
*This
,
167 IN UINT8 DeviceEndpoint
,
169 IN OUT UINTN
*DataLength
,
175 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous
176 Interrupt Transfer is typically used to query a device's status at a fixed rate. For example,
177 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at
180 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
181 @param DeviceEndpoint The destination USB device endpoint to which the
182 device request is being sent. DeviceEndpoint must
183 be between 0x01 and 0x0F or between 0x81 and 0x8F,
184 otherwise EFI_INVALID_PARAMETER is returned. If
185 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
186 is returned. The MSB of this parameter indicates
187 the endpoint direction. The number "1" stands for
188 an IN endpoint, and "0" stands for an OUT endpoint.
189 @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If
190 FALSE, the interrupt transfer is deleted from the device's interrupt
192 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be
193 executed.This parameter is required when IsNewTransfer is TRUE. The
194 value must be between 1 to 255, otherwise EFI_INVALID_PARAMETER is returned.
195 The units are in milliseconds.
196 @param DataLength Specifies the length, in bytes, of the data to be received from the
197 USB device. This parameter is only required when IsNewTransfer is TRUE.
198 @param InterruptCallback The Callback function. This function is called if the asynchronous
199 interrupt transfer is completed. This parameter is required
200 when IsNewTransfer is TRUE.
201 @param Context Data passed to the InterruptCallback function. This is an optional
202 parameter and may be NULL.
204 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.
205 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
210 (EFIAPI
*EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER
)(
211 IN EFI_USB_IO_PROTOCOL
*This
,
212 IN UINT8 DeviceEndpoint
,
213 IN BOOLEAN IsNewTransfer
,
214 IN UINTN PollingInterval OPTIONAL
,
215 IN UINTN DataLength OPTIONAL
,
216 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL
,
217 IN VOID
*Context OPTIONAL
221 This function is used to manage a USB device with an interrupt transfer pipe.
223 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
224 @param DeviceEndpoint The destination USB device endpoint to which the
225 device request is being sent. DeviceEndpoint must
226 be between 0x01 and 0x0F or between 0x81 and 0x8F,
227 otherwise EFI_INVALID_PARAMETER is returned. If
228 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
229 is returned. The MSB of this parameter indicates
230 the endpoint direction. The number "1" stands for
231 an IN endpoint, and "0" stands for an OUT endpoint.
232 @param Data A pointer to the buffer of data that will be transmitted to USB
233 device or received from USB device.
234 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the
235 amount of data actually transferred.
236 @param Timeout The time out, in seconds, for this transfer. If Timeout is 0,
237 then the caller must wait for the function to be completed
238 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. If the
239 transfer is not completed in this time frame, then EFI_TIMEOUT is returned.
240 @param Status This parameter indicates the USB transfer status.
242 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.
243 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
244 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.
245 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
246 @retval EFI_TIMEOUT The transfer fails due to timeout.
250 (EFIAPI
*EFI_USB_IO_SYNC_INTERRUPT_TRANSFER
)(
251 IN EFI_USB_IO_PROTOCOL
*This
,
252 IN UINT8 DeviceEndpoint
,
254 IN OUT UINTN
*DataLength
,
260 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
261 transfer is typically used to transfer streaming data.
263 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
264 @param DeviceEndpoint The destination USB device endpoint to which the
265 device request is being sent. DeviceEndpoint must
266 be between 0x01 and 0x0F or between 0x81 and 0x8F,
267 otherwise EFI_INVALID_PARAMETER is returned. If
268 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
269 is returned. The MSB of this parameter indicates
270 the endpoint direction. The number "1" stands for
271 an IN endpoint, and "0" stands for an OUT endpoint.
272 @param Data A pointer to the buffer of data that will be transmitted to USB
273 device or received from USB device.
274 @param DataLength The size, in bytes, of the data buffer specified by Data.
275 @param Status This parameter indicates the USB transfer status.
277 @retval EFI_SUCCESS The isochronous transfer has been successfully executed.
278 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
279 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status
280 is returned in Status.
281 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
282 @retval EFI_TIMEOUT The transfer fails due to timeout.
286 (EFIAPI
*EFI_USB_IO_ISOCHRONOUS_TRANSFER
)(
287 IN EFI_USB_IO_PROTOCOL
*This
,
288 IN UINT8 DeviceEndpoint
,
295 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
296 transfer is typically used to transfer streaming data.
298 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
299 @param DeviceEndpoint The destination USB device endpoint to which the
300 device request is being sent. DeviceEndpoint must
301 be between 0x01 and 0x0F or between 0x81 and 0x8F,
302 otherwise EFI_INVALID_PARAMETER is returned. If
303 the endpoint is not a BULK endpoint, EFI_INVALID_PARAMETER
304 is returned. The MSB of this parameter indicates
305 the endpoint direction. The number "1" stands for
306 an IN endpoint, and "0" stands for an OUT endpoint.
307 @param Data A pointer to the buffer of data that will be transmitted to USB
308 device or received from USB device.
309 @param DataLength The size, in bytes, of the data buffer specified by Data.
310 This is an optional parameter and may be NULL.
311 @param IsochronousCallback The IsochronousCallback() function.This function is
312 called if the requested isochronous transfer is completed.
313 @param Context Data passed to the IsochronousCallback() function.
315 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted
317 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
318 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
323 (EFIAPI
*EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER
)(
324 IN EFI_USB_IO_PROTOCOL
*This
,
325 IN UINT8 DeviceEndpoint
,
328 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,
329 IN VOID
*Context OPTIONAL
333 Resets and reconfigures the USB controller. This function will work for all USB devices except
336 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
338 @retval EFI_SUCCESS The USB controller was reset.
339 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
340 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.
345 (EFIAPI
*EFI_USB_IO_PORT_RESET
)(
346 IN EFI_USB_IO_PROTOCOL
*This
350 Retrieves the USB Device Descriptor.
352 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
353 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.
355 @retval EFI_SUCCESS The device descriptor was retrieved successfully.
356 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
357 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.
362 (EFIAPI
*EFI_USB_IO_GET_DEVICE_DESCRIPTOR
)(
363 IN EFI_USB_IO_PROTOCOL
*This
,
364 OUT EFI_USB_DEVICE_DESCRIPTOR
*DeviceDescriptor
368 Retrieves the USB Device Descriptor.
370 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
371 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
373 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.
374 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
375 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not
381 (EFIAPI
*EFI_USB_IO_GET_CONFIG_DESCRIPTOR
)(
382 IN EFI_USB_IO_PROTOCOL
*This
,
383 OUT EFI_USB_CONFIG_DESCRIPTOR
*ConfigurationDescriptor
387 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
388 within a USB device is equivalently to a USB Controller within the current configuration.
390 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
391 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
392 the configuration setting.
393 @retval EFI_SUCCESS The interface descriptor retrieved successfully.
394 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
395 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be
396 correctly configured.
401 (EFIAPI
*EFI_USB_IO_GET_INTERFACE_DESCRIPTOR
)(
402 IN EFI_USB_IO_PROTOCOL
*This
,
403 OUT EFI_USB_INTERFACE_DESCRIPTOR
*InterfaceDescriptor
407 Retrieves an Endpoint Descriptor within a USB Controller.
409 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
410 @param EndpointIndex Indicates which endpoint descriptor to retrieve.
411 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
414 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.
415 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
416 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be
417 correctly configured.
422 (EFIAPI
*EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR
)(
423 IN EFI_USB_IO_PROTOCOL
*This
,
424 IN UINT8 EndpointIndex
,
425 OUT EFI_USB_ENDPOINT_DESCRIPTOR
*EndpointDescriptor
429 Retrieves a string stored in a USB Device.
431 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
432 @param LangID The Language ID for the string being retrieved.
433 @param StringID The ID of the string being retrieved.
434 @param String A pointer to a buffer allocated by this function with
435 AllocatePool() to store the string.If this function
436 returns EFI_SUCCESS, it stores the string the caller
437 wants to get. The caller should release the string
438 buffer with FreePool() after the string is not used any more.
440 @retval EFI_SUCCESS The string was retrieved successfully.
441 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.
442 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.
447 (EFIAPI
*EFI_USB_IO_GET_STRING_DESCRIPTOR
)(
448 IN EFI_USB_IO_PROTOCOL
*This
,
455 Retrieves all the language ID codes that the USB device supports.
457 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
458 @param LangIDTable Language ID for the string the caller wants to get.
459 This is a 16-bit ID defined by Microsoft. This
460 buffer pointer is allocated and maintained by
461 the USB Bus Driver, the caller should not modify
463 @param TableSize The size, in bytes, of the table LangIDTable.
465 @retval EFI_SUCCESS The support languages were retrieved successfully.
470 (EFIAPI
*EFI_USB_IO_GET_SUPPORTED_LANGUAGE
)(
471 IN EFI_USB_IO_PROTOCOL
*This
,
472 OUT UINT16
**LangIDTable
,
473 OUT UINT16
*TableSize
477 /// The EFI_USB_IO_PROTOCOL provides four basic transfers types described
478 /// in the USB 1.1 Specification. These include control transfer, interrupt
479 /// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL
480 /// also provides some basic USB device/controller management and configuration
481 /// interfaces. A USB device driver uses the services of this protocol to manage USB devices.
483 struct _EFI_USB_IO_PROTOCOL
{
487 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer
;
488 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer
;
489 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer
;
490 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer
;
491 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer
;
492 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer
;
495 // Common device request
497 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor
;
498 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor
;
499 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor
;
500 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor
;
501 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor
;
502 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages
;
505 // Reset controller's parent port
507 EFI_USB_IO_PORT_RESET UsbPortReset
;
510 extern EFI_GUID gEfiUsbIoProtocolGuid
;