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.
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 Async USB transfer callback routine.
33 @param Data Data received or sent via the USB Asynchronous Transfer, if the
34 transfer completed successfully.
35 @param DataLength The length of Data received or sent via the Asynchronous
36 Transfer, if transfer successfully completes.
37 @param Context Data passed from UsbAsyncInterruptTransfer() request.
38 @param Status Indicates the result of the asynchronous transfer.
40 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed.
41 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
46 (EFIAPI
*EFI_ASYNC_USB_TRANSFER_CALLBACK
) (
54 // Prototype for EFI USB I/O protocol
59 This function is used to manage a USB device with a control transfer pipe. A control transfer is
60 typically used to perform device initialization and configuration.
62 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
63 @param Request A pointer to the USB device request that will be sent to the USB
65 @param Direction Indicates the data direction.
66 @param Data A pointer to the buffer of data that will be transmitted to USB
67 device or received from USB device.
68 @param Timeout Indicating the transfer should be completed within this time frame.
69 The units are in milliseconds.
70 @param DataLength The size, in bytes, of the data buffer specified by Data.
71 @param Status A pointer to the result of the USB transfer.
73 @retval EFI_SUCCESS The control transfer has been successfully executed.
74 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
75 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
76 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
77 @retval EFI_TIMEOUT The control transfer fails due to timeout.
82 (EFIAPI
*EFI_USB_IO_CONTROL_TRANSFER
) (
83 IN EFI_USB_IO_PROTOCOL
*This
,
84 IN EFI_USB_DEVICE_REQUEST
*Request
,
85 IN EFI_USB_DATA_DIRECTION Direction
,
87 IN OUT VOID
*Data OPTIONAL
,
88 IN UINTN DataLength OPTIONAL
,
93 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are
94 typically used to transfer large amounts of data to/from USB devices.
96 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
97 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
99 @param Data A pointer to the buffer of data that will be transmitted to USB
100 device or received from USB device.
101 @param DataLength The size, in bytes, of the data buffer specified by Data.
102 @param Timeout Indicating the transfer should be completed within this time frame.
103 The units are in milliseconds.
104 @param Status This parameter indicates the USB transfer status.
106 @retval EFI_SUCCESS The bulk transfer has been successfully executed.
107 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.
108 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.
109 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
110 @retval EFI_TIMEOUT The control transfer fails due to timeout.
115 (EFIAPI
*EFI_USB_IO_BULK_TRANSFER
) (
116 IN EFI_USB_IO_PROTOCOL
*This
,
117 IN UINT8 DeviceEndpoint
,
119 IN OUT UINTN
*DataLength
,
125 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous
126 Interrupt Transfer is typically used to query a device¡¯s status at a fixed rate. For example,
127 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at
130 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
131 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
133 @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If
134 FALSE, the interrupt transfer is deleted from the device¡¯s interrupt
136 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be
138 @param DataLength Specifies the length, in bytes, of the data to be received from the
140 @param Context Data passed to the InterruptCallback function.
141 @param InterruptCallback The Callback function. This function is called if the asynchronous
142 interrupt transfer is completed.
144 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.
145 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.
150 (EFIAPI
*EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER
) (
151 IN EFI_USB_IO_PROTOCOL
*This
,
152 IN UINT8 DeviceEndpoint
,
153 IN BOOLEAN IsNewTransfer
,
154 IN UINTN PollingInterval OPTIONAL
,
155 IN UINTN DataLength OPTIONAL
,
156 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL
,
157 IN VOID
*Context OPTIONAL
161 This function is used to manage a USB device with an interrupt transfer pipe.
163 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
164 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
166 @param Data A pointer to the buffer of data that will be transmitted to USB
167 device or received from USB device.
168 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the
169 amount of data actually transferred.
170 @param Timeout The time out, in seconds, for this transfer.
171 @param Status This parameter indicates the USB transfer status.
173 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.
174 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
175 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed.
176 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
177 @retval EFI_TIMEOUT The transfer fails due to timeout.
181 (EFIAPI
*EFI_USB_IO_SYNC_INTERRUPT_TRANSFER
) (
182 IN EFI_USB_IO_PROTOCOL
*This
,
183 IN UINT8 DeviceEndpoint
,
185 IN OUT UINTN
*DataLength
,
191 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
192 transfer is typically used to transfer streaming data.
194 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
195 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
197 @param Data A pointer to the buffer of data that will be transmitted to USB
198 device or received from USB device.
199 @param DataLength The size, in bytes, of the data buffer specified by Data.
200 @param Status This parameter indicates the USB transfer status.
202 @retval EFI_SUCCESS The isochronous transfer has been successfully executed.
203 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
204 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status
205 is returned in Status.
206 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
207 @retval EFI_TIMEOUT The transfer fails due to timeout.
211 (EFIAPI
*EFI_USB_IO_ISOCHRONOUS_TRANSFER
) (
212 IN EFI_USB_IO_PROTOCOL
*This
,
213 IN UINT8 DeviceEndpoint
,
220 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous
221 transfer is typically used to transfer streaming data.
223 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
224 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB
226 @param Data A pointer to the buffer of data that will be transmitted to USB
227 device or received from USB device.
228 @param DataLength The size, in bytes, of the data buffer specified by Data.
229 @param Context Data passed to the IsochronousCallback() function.
230 @param IsochronousCallback The IsochronousCallback() function.
232 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted
234 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.
235 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.
240 (EFIAPI
*EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER
) (
241 IN EFI_USB_IO_PROTOCOL
*This
,
242 IN UINT8 DeviceEndpoint
,
245 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack
,
246 IN VOID
*Context OPTIONAL
250 Resets and reconfigures the USB controller. This function will work for all USB devices except
253 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
255 @retval EFI_SUCCESS The USB controller was reset.
256 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.
257 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.
262 (EFIAPI
*EFI_USB_IO_PORT_RESET
) (
263 IN EFI_USB_IO_PROTOCOL
*This
267 Retrieves the USB Device Descriptor.
269 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
270 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.
272 @retval EFI_SUCCESS The device descriptor was retrieved successfully.
273 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.
274 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.
279 (EFIAPI
*EFI_USB_IO_GET_DEVICE_DESCRIPTOR
) (
280 IN EFI_USB_IO_PROTOCOL
*This
,
281 OUT EFI_USB_DEVICE_DESCRIPTOR
*DeviceDescriptor
285 Retrieves the USB Device Descriptor.
287 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
288 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
290 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.
291 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.
292 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not
298 (EFIAPI
*EFI_USB_IO_GET_CONFIG_DESCRIPTOR
) (
299 IN EFI_USB_IO_PROTOCOL
*This
,
300 OUT EFI_USB_CONFIG_DESCRIPTOR
*ConfigurationDescriptor
304 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface
305 within a USB device is equivalently to a USB Controller within the current configuration.
307 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
308 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within
309 the configuration setting.
310 @retval EFI_SUCCESS The interface descriptor retrieved successfully.
311 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.
312 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be
313 correctly configured.
318 (EFIAPI
*EFI_USB_IO_GET_INTERFACE_DESCRIPTOR
) (
319 IN EFI_USB_IO_PROTOCOL
*This
,
320 OUT EFI_USB_INTERFACE_DESCRIPTOR
*InterfaceDescriptor
324 Retrieves an Endpoint Descriptor within a USB Controller.
326 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
327 @param EndpointIndex Indicates which endpoint descriptor to retrieve.
328 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of
331 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.
332 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
333 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be
334 correctly configured.
339 (EFIAPI
*EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR
) (
340 IN EFI_USB_IO_PROTOCOL
*This
,
341 IN UINT8 EndpointIndex
,
342 OUT EFI_USB_ENDPOINT_DESCRIPTOR
*EndpointDescriptor
346 Retrieves a Unicode string stored in a USB Device.
348 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
349 @param LangID The Language ID for the string being retrieved.
350 @param StringID The ID of the string being retrieved.
351 @param String A pointer to a buffer allocated by this function with
352 AllocatePool() to store the string.
354 @retval EFI_SUCCESS The string was retrieved successfully.
355 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found.
356 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.
361 (EFIAPI
*EFI_USB_IO_GET_STRING_DESCRIPTOR
) (
362 IN EFI_USB_IO_PROTOCOL
*This
,
369 Retrieves all the language ID codes that the USB device supports.
371 @param This A pointer to the EFI_USB_IO_PROTOCOL instance.
372 @param LangIDTable Language ID for the string the caller wants to get.
373 @param TableSize The size, in bytes, of the table LangIDTable.
375 @retval EFI_SUCCESS The support languages were retrieved successfully.
380 (EFIAPI
*EFI_USB_IO_GET_SUPPORTED_LANGUAGE
) (
381 IN EFI_USB_IO_PROTOCOL
*This
,
382 OUT UINT16
**LangIDTable
,
383 OUT UINT16
*TableSize
387 // Protocol Interface Structure
389 struct _EFI_USB_IO_PROTOCOL
{
393 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer
;
394 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer
;
395 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer
;
396 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer
;
397 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer
;
398 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer
;
401 // Common device request
403 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor
;
404 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor
;
405 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor
;
406 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor
;
407 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor
;
408 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages
;
411 // Reset controller's parent port
413 EFI_USB_IO_PORT_RESET UsbPortReset
;
416 extern EFI_GUID gEfiUsbIoProtocolGuid
;