4 Copyright (c) 2006, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 #include <IndustryStandard/Usb.h>
21 // Global ID for the USB I/O Protocol
23 #define EFI_USB_IO_PROTOCOL_GUID \
25 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
28 typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL
;
31 // Related Definition for EFI USB I/O protocol
35 // USB standard descriptors and reqeust
37 typedef USB_DEVICE_REQUEST EFI_USB_DEVICE_REQUEST
;
38 typedef USB_DEVICE_DESCRIPTOR EFI_USB_DEVICE_DESCRIPTOR
;
39 typedef USB_CONFIG_DESCRIPTOR EFI_USB_CONFIG_DESCRIPTOR
;
40 typedef USB_INTERFACE_DESCRIPTOR EFI_USB_INTERFACE_DESCRIPTOR
;
41 typedef USB_ENDPOINT_DESCRIPTOR EFI_USB_ENDPOINT_DESCRIPTOR
;
44 // USB data transfer direction
50 } EFI_USB_DATA_DIRECTION
;
53 // USB Transfer Results
55 #define EFI_USB_NOERROR 0x00
56 #define EFI_USB_ERR_NOTEXECUTE 0x01
57 #define EFI_USB_ERR_STALL 0x02
58 #define EFI_USB_ERR_BUFFER 0x04
59 #define EFI_USB_ERR_BABBLE 0x08
60 #define EFI_USB_ERR_NAK 0x10
61 #define EFI_USB_ERR_CRC 0x20
62 #define EFI_USB_ERR_TIMEOUT 0x40
63 #define EFI_USB_ERR_BITSTUFF 0x80
64 #define EFI_USB_ERR_SYSTEM 0x100
67 Async USB transfer callback routine.
69 @param Data Data received or sent via the USB Asynchronous Transfer, if the
70 transfer completed successfully.
71 @param DataLength The length of Data received or sent via the Asynchronous
72 Transfer, if transfer successfully completes.
73 @param Context Data passed from UsbAsyncInterruptTransfer() request.
74 @param Status Indicates the result of the asynchronous transfer.
76 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
77 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
82 (EFIAPI
*EFI_ASYNC_USB_TRANSFER_CALLBACK
) (
90 // Prototype for EFI USB I/O protocol
95 This function is used to manage a USB device with a control transfer pipe. A control transfer is
96 typically used to perform device initialization and configuration.
98 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
99 @param Request A pointer to the USB device request that will be sent to the USB
101 @param Direction Indicates the data direction.
102 @param Timeout Indicating the transfer should be completed within this time frame.
103 The units are in milliseconds.
104 @param Data A pointer to the buffer of data that will be transmitted to USB
105 device or received from USB device.
106 @param DataLength The size, in bytes, of the data buffer specified by Data.
107 @param Status A pointer to the result of the USB transfer.
109 @retval EFI_SUCCESS The control transfer has been successfully executed.
110 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
111 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
112 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
113 @retval EFI_TIMEOUT The control transfer fails due to timeout.
118 (EFIAPI
*EFI_USB_IO_CONTROL_TRANSFER
) (
119 IN EFI_USB_IO_PROTOCOL
*This
,
120 IN EFI_USB_DEVICE_REQUEST
*Request
,
121 IN EFI_USB_DATA_DIRECTION Direction
,
123 IN OUT VOID
*Data OPTIONAL
,
124 IN UINTN DataLength OPTIONAL
,
129 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
130 typically used to transfer large amounts of data to/from USB devices.
132 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
133 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
135 @param Data A pointer to the buffer of data that will be transmitted to USB
136 device or received from USB device.
137 @param DataLength The size, in bytes, of the data buffer specified by Data.
138 @param Timeout Indicating the transfer should be completed within this time frame.
139 The units are in milliseconds.
140 @param Status This parameter indicates the USB transfer status.
142 @retval EFI_SUCCESS The bulk transfer has been successfully executed.
143 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
144 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
145 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
146 @retval EFI_TIMEOUT The control transfer fails due to timeout.
151 (EFIAPI
*EFI_USB_IO_BULK_TRANSFER
) (
152 IN EFI_USB_IO_PROTOCOL
*This
,
153 IN UINT8 DeviceEndpoint
,
155 IN OUT UINTN
*DataLength
,
161 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous
162 Interrupt Transfer is typically used to query a device's status at a fixed rate. For example,
163 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at
166 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
167 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
169 @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If
170 FALSE, the interrupt transfer is deleted from the device's interrupt
172 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be
174 @param DataLength Specifies the length, in bytes, of the data to be received from the
176 @param Context Data passed to the InterruptCallback function.
177 @param InterruptCallback The Callback function. This function is called if the asynchronous
178 interrupt transfer is completed.
180 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.
181 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
186 (EFIAPI
*EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER
) (
187 IN EFI_USB_IO_PROTOCOL
*This
,
188 IN UINT8 DeviceEndpoint
,
189 IN BOOLEAN IsNewTransfer
,
190 IN UINTN PollingInterval OPTIONAL
,
191 IN UINTN DataLength OPTIONAL
,
192 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL
,
193 IN VOID
*Context OPTIONAL
197 This function is used to manage a USB device with an interrupt transfer pipe.
199 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
200 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
202 @param Data A pointer to the buffer of data that will be transmitted to USB
203 device or received from USB device.
204 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the
205 amount of data actually transferred.
206 @param Timeout The time out, in seconds, for this transfer.
207 @param Status This parameter indicates the USB transfer status.
209 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.
210 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
211 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.
212 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
213 @retval EFI_TIMEOUT The transfer fails due to timeout.
217 (EFIAPI
*EFI_USB_IO_SYNC_INTERRUPT_TRANSFER
) (
218 IN EFI_USB_IO_PROTOCOL
*This
,
219 IN UINT8 DeviceEndpoint
,
221 IN OUT UINTN
*DataLength
,
227 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
228 transfer is typically used to transfer streaming data.
230 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
231 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
233 @param Data A pointer to the buffer of data that will be transmitted to USB
234 device or received from USB device.
235 @param DataLength The size, in bytes, of the data buffer specified by Data.
236 @param Status This parameter indicates the USB transfer status.
238 @retval EFI_SUCCESS The isochronous transfer has been successfully executed.
239 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
240 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status
241 is returned in Status.
242 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
243 @retval EFI_TIMEOUT The transfer fails due to timeout.
247 (EFIAPI
*EFI_USB_IO_ISOCHRONOUS_TRANSFER
) (
248 IN EFI_USB_IO_PROTOCOL
*This
,
249 IN UINT8 DeviceEndpoint
,
256 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
257 transfer is typically used to transfer streaming data.
259 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
260 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
262 @param Data A pointer to the buffer of data that will be transmitted to USB
263 device or received from USB device.
264 @param DataLength The size, in bytes, of the data buffer specified by Data.
265 @param Context Data passed to the IsochronousCallback() function.
266 @param IsochronousCallback The IsochronousCallback() function.
268 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted
270 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
271 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
276 (EFIAPI
*EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER
) (
277 IN EFI_USB_IO_PROTOCOL
*This
,
278 IN UINT8 DeviceEndpoint
,
281 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,
282 IN VOID
*Context OPTIONAL
286 Resets and reconfigures the USB controller. This function will work for all USB devices except
289 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
291 @retval EFI_SUCCESS The USB controller was reset.
292 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
293 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.
298 (EFIAPI
*EFI_USB_IO_PORT_RESET
) (
299 IN EFI_USB_IO_PROTOCOL
*This
303 Retrieves the USB Device Descriptor.
305 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
306 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.
308 @retval EFI_SUCCESS The device descriptor was retrieved successfully.
309 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
310 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.
315 (EFIAPI
*EFI_USB_IO_GET_DEVICE_DESCRIPTOR
) (
316 IN EFI_USB_IO_PROTOCOL
*This
,
317 OUT EFI_USB_DEVICE_DESCRIPTOR
*DeviceDescriptor
321 Retrieves the USB Device Descriptor.
323 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
324 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
326 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.
327 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
328 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not
334 (EFIAPI
*EFI_USB_IO_GET_CONFIG_DESCRIPTOR
) (
335 IN EFI_USB_IO_PROTOCOL
*This
,
336 OUT EFI_USB_CONFIG_DESCRIPTOR
*ConfigurationDescriptor
340 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
341 within a USB device is equivalently to a USB Controller within the current configuration.
343 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
344 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
345 the configuration setting.
346 @retval EFI_SUCCESS The interface descriptor retrieved successfully.
347 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
348 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be
349 correctly configured.
354 (EFIAPI
*EFI_USB_IO_GET_INTERFACE_DESCRIPTOR
) (
355 IN EFI_USB_IO_PROTOCOL
*This
,
356 OUT EFI_USB_INTERFACE_DESCRIPTOR
*InterfaceDescriptor
360 Retrieves an Endpoint Descriptor within a USB Controller.
362 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
363 @param EndpointIndex Indicates which endpoint descriptor to retrieve.
364 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
367 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.
368 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
369 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be
370 correctly configured.
375 (EFIAPI
*EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR
) (
376 IN EFI_USB_IO_PROTOCOL
*This
,
377 IN UINT8 EndpointIndex
,
378 OUT EFI_USB_ENDPOINT_DESCRIPTOR
*EndpointDescriptor
382 Retrieves a Unicode string stored in a USB Device.
384 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
385 @param LangID The Language ID for the string being retrieved.
386 @param StringID The ID of the string being retrieved.
387 @param String A pointer to a buffer allocated by this function with
388 AllocatePool() to store the string.
390 @retval EFI_SUCCESS The string was retrieved successfully.
391 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.
392 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.
397 (EFIAPI
*EFI_USB_IO_GET_STRING_DESCRIPTOR
) (
398 IN EFI_USB_IO_PROTOCOL
*This
,
405 Retrieves all the language ID codes that the USB device supports.
407 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
408 @param LangIDTable Language ID for the string the caller wants to get.
409 @param TableSize The size, in bytes, of the table LangIDTable.
411 @retval EFI_SUCCESS The support languages were retrieved successfully.
416 (EFIAPI
*EFI_USB_IO_GET_SUPPORTED_LANGUAGE
) (
417 IN EFI_USB_IO_PROTOCOL
*This
,
418 OUT UINT16
**LangIDTable
,
419 OUT UINT16
*TableSize
423 // Protocol Interface Structure
425 struct _EFI_USB_IO_PROTOCOL
{
429 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer
;
430 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer
;
431 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer
;
432 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer
;
433 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer
;
434 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer
;
437 // Common device request
439 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor
;
440 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor
;
441 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor
;
442 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor
;
443 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor
;
444 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages
;
447 // Reset controller's parent port
449 EFI_USB_IO_PORT_RESET UsbPortReset
;
452 extern EFI_GUID gEfiUsbIoProtocolGuid
;