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.
20 #include <IndustryStandard/Usb.h>
23 // Global ID for the USB I/O Protocol
25 #define EFI_USB_IO_PROTOCOL_GUID \
27 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
30 typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL
;
33 Async USB transfer callback routine.
35 @param Data Data received or sent via the USB Asynchronous Transfer, if the
36 transfer completed successfully.
37 @param DataLength The length of Data received or sent via the Asynchronous
38 Transfer, if transfer successfully completes.
39 @param Context Data passed from UsbAsyncInterruptTransfer() request.
40 @param Status Indicates the result of the asynchronous transfer.
42 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
43 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
48 (EFIAPI
*EFI_ASYNC_USB_TRANSFER_CALLBACK
) (
56 // Prototype for EFI USB I/O protocol
61 This function is used to manage a USB device with a control transfer pipe. A control transfer is
62 typically used to perform device initialization and configuration.
64 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
65 @param Request A pointer to the USB device request that will be sent to the USB
67 @param Direction Indicates the data direction.
68 @param Data A pointer to the buffer of data that will be transmitted to USB
69 device or received from USB device.
70 @param Timeout Indicating the transfer should be completed within this time frame.
71 The units are in milliseconds.
72 @param DataLength The size, in bytes, of the data buffer specified by Data.
73 @param Status A pointer to the result of the USB transfer.
75 @retval EFI_SUCCESS The control transfer has been successfully executed.
76 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
77 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
78 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
79 @retval EFI_TIMEOUT The control transfer fails due to timeout.
84 (EFIAPI
*EFI_USB_IO_CONTROL_TRANSFER
) (
85 IN EFI_USB_IO_PROTOCOL
*This
,
86 IN EFI_USB_DEVICE_REQUEST
*Request
,
87 IN EFI_USB_DATA_DIRECTION Direction
,
89 IN OUT VOID
*Data OPTIONAL
,
90 IN UINTN DataLength OPTIONAL
,
95 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
96 typically used to transfer large amounts of data to/from USB devices.
98 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
99 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
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 Timeout Indicating the transfer should be completed within this time frame.
105 The units are in milliseconds.
106 @param Status This parameter indicates the USB transfer status.
108 @retval EFI_SUCCESS The bulk transfer has been successfully executed.
109 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
110 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
111 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
112 @retval EFI_TIMEOUT The control transfer fails due to timeout.
117 (EFIAPI
*EFI_USB_IO_BULK_TRANSFER
) (
118 IN EFI_USB_IO_PROTOCOL
*This
,
119 IN UINT8 DeviceEndpoint
,
121 IN OUT UINTN
*DataLength
,
127 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous
128 Interrupt Transfer is typically used to query a device's status at a fixed rate. For example,
129 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at
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 IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If
136 FALSE, the interrupt transfer is deleted from the device's interrupt
138 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be
140 @param DataLength Specifies the length, in bytes, of the data to be received from the
142 @param Context Data passed to the InterruptCallback function.
143 @param InterruptCallback The Callback function. This function is called if the asynchronous
144 interrupt transfer is completed.
146 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.
147 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
152 (EFIAPI
*EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER
) (
153 IN EFI_USB_IO_PROTOCOL
*This
,
154 IN UINT8 DeviceEndpoint
,
155 IN BOOLEAN IsNewTransfer
,
156 IN UINTN PollingInterval OPTIONAL
,
157 IN UINTN DataLength OPTIONAL
,
158 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL
,
159 IN VOID
*Context OPTIONAL
163 This function is used to manage a USB device with an interrupt transfer pipe.
165 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
166 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
168 @param Data A pointer to the buffer of data that will be transmitted to USB
169 device or received from USB device.
170 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the
171 amount of data actually transferred.
172 @param Timeout The time out, in seconds, for this transfer.
173 @param Status This parameter indicates the USB transfer status.
175 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.
176 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
177 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.
178 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
179 @retval EFI_TIMEOUT The transfer fails due to timeout.
183 (EFIAPI
*EFI_USB_IO_SYNC_INTERRUPT_TRANSFER
) (
184 IN EFI_USB_IO_PROTOCOL
*This
,
185 IN UINT8 DeviceEndpoint
,
187 IN OUT UINTN
*DataLength
,
193 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
194 transfer is typically used to transfer streaming data.
196 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
197 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
199 @param Data A pointer to the buffer of data that will be transmitted to USB
200 device or received from USB device.
201 @param DataLength The size, in bytes, of the data buffer specified by Data.
202 @param Status This parameter indicates the USB transfer status.
204 @retval EFI_SUCCESS The isochronous transfer has been successfully executed.
205 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
206 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status
207 is returned in Status.
208 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
209 @retval EFI_TIMEOUT The transfer fails due to timeout.
213 (EFIAPI
*EFI_USB_IO_ISOCHRONOUS_TRANSFER
) (
214 IN EFI_USB_IO_PROTOCOL
*This
,
215 IN UINT8 DeviceEndpoint
,
222 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
223 transfer is typically used to transfer streaming data.
225 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
226 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
228 @param Data A pointer to the buffer of data that will be transmitted to USB
229 device or received from USB device.
230 @param DataLength The size, in bytes, of the data buffer specified by Data.
231 @param Context Data passed to the IsochronousCallback() function.
232 @param IsochronousCallback The IsochronousCallback() function.
234 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted
236 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
237 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
242 (EFIAPI
*EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER
) (
243 IN EFI_USB_IO_PROTOCOL
*This
,
244 IN UINT8 DeviceEndpoint
,
247 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,
248 IN VOID
*Context OPTIONAL
252 Resets and reconfigures the USB controller. This function will work for all USB devices except
255 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
257 @retval EFI_SUCCESS The USB controller was reset.
258 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
259 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.
264 (EFIAPI
*EFI_USB_IO_PORT_RESET
) (
265 IN EFI_USB_IO_PROTOCOL
*This
269 Retrieves the USB Device Descriptor.
271 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
272 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.
274 @retval EFI_SUCCESS The device descriptor was retrieved successfully.
275 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
276 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.
281 (EFIAPI
*EFI_USB_IO_GET_DEVICE_DESCRIPTOR
) (
282 IN EFI_USB_IO_PROTOCOL
*This
,
283 OUT EFI_USB_DEVICE_DESCRIPTOR
*DeviceDescriptor
287 Retrieves the USB Device Descriptor.
289 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
290 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
292 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.
293 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
294 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not
300 (EFIAPI
*EFI_USB_IO_GET_CONFIG_DESCRIPTOR
) (
301 IN EFI_USB_IO_PROTOCOL
*This
,
302 OUT EFI_USB_CONFIG_DESCRIPTOR
*ConfigurationDescriptor
306 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
307 within a USB device is equivalently to a USB Controller within the current configuration.
309 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
310 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
311 the configuration setting.
312 @retval EFI_SUCCESS The interface descriptor retrieved successfully.
313 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
314 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be
315 correctly configured.
320 (EFIAPI
*EFI_USB_IO_GET_INTERFACE_DESCRIPTOR
) (
321 IN EFI_USB_IO_PROTOCOL
*This
,
322 OUT EFI_USB_INTERFACE_DESCRIPTOR
*InterfaceDescriptor
326 Retrieves an Endpoint Descriptor within a USB Controller.
328 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
329 @param EndpointIndex Indicates which endpoint descriptor to retrieve.
330 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
333 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.
334 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
335 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be
336 correctly configured.
341 (EFIAPI
*EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR
) (
342 IN EFI_USB_IO_PROTOCOL
*This
,
343 IN UINT8 EndpointIndex
,
344 OUT EFI_USB_ENDPOINT_DESCRIPTOR
*EndpointDescriptor
348 Retrieves a Unicode string stored in a USB Device.
350 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
351 @param LangID The Language ID for the string being retrieved.
352 @param StringID The ID of the string being retrieved.
353 @param String A pointer to a buffer allocated by this function with
354 AllocatePool() to store the string.
356 @retval EFI_SUCCESS The string was retrieved successfully.
357 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.
358 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.
363 (EFIAPI
*EFI_USB_IO_GET_STRING_DESCRIPTOR
) (
364 IN EFI_USB_IO_PROTOCOL
*This
,
371 Retrieves all the language ID codes that the USB device supports.
373 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
374 @param LangIDTable Language ID for the string the caller wants to get.
375 @param TableSize The size, in bytes, of the table LangIDTable.
377 @retval EFI_SUCCESS The support languages were retrieved successfully.
382 (EFIAPI
*EFI_USB_IO_GET_SUPPORTED_LANGUAGE
) (
383 IN EFI_USB_IO_PROTOCOL
*This
,
384 OUT UINT16
**LangIDTable
,
385 OUT UINT16
*TableSize
389 // Protocol Interface Structure
391 struct _EFI_USB_IO_PROTOCOL
{
395 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer
;
396 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer
;
397 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer
;
398 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer
;
399 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer
;
400 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer
;
403 // Common device request
405 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor
;
406 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor
;
407 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor
;
408 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor
;
409 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor
;
410 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages
;
413 // Reset controller's parent port
415 EFI_USB_IO_PORT_RESET UsbPortReset
;
418 extern EFI_GUID gEfiUsbIoProtocolGuid
;