]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Protocol/UsbIo.h
Import Pal.h and Sal.h.
[mirror_edk2.git] / MdePkg / Include / Protocol / UsbIo.h
CommitLineData
d1f95000 1/** @file\r
2 EFI Usb I/O Protocol\r
3\r
4 Copyright (c) 2006, Intel Corporation \r
5 All rights reserved. This program and the accompanying materials \r
6 are licensed and made available under the terms and conditions of the BSD License \r
7 which accompanies this distribution. The full text of the license may be found at \r
8 http://opensource.org/licenses/bsd-license.php \r
9\r
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
12\r
13 Module Name: UsbIo.h\r
14\r
15**/\r
16\r
17#ifndef __USB_IO_H__\r
18#define __USB_IO_H__\r
19\r
20#include <IndustryStandard/Usb.h>\r
21\r
22//\r
23// Global ID for the USB I/O Protocol\r
24//\r
25#define EFI_USB_IO_PROTOCOL_GUID \\r
26 { \\r
27 0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \\r
28 }\r
29\r
30typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL;\r
31\r
32/** \r
33 Async USB transfer callback routine.\r
34 \r
35 @param Data Data received or sent via the USB Asynchronous Transfer, if the\r
36 transfer completed successfully. \r
37 @param DataLength The length of Data received or sent via the Asynchronous\r
38 Transfer, if transfer successfully completes. \r
39 @param Context Data passed from UsbAsyncInterruptTransfer() request.\r
40 @param Status Indicates the result of the asynchronous transfer.\r
41 \r
42 @retval EFI_SUCCESS The asynchronous USB transfer request has been successfully executed. \r
43 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed.\r
44 \r
45**/\r
46typedef\r
47EFI_STATUS\r
48(EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK) (\r
49 IN VOID *Data,\r
50 IN UINTN DataLength,\r
51 IN VOID *Context,\r
52 IN UINT32 Status\r
53 );\r
54\r
55//\r
56// Prototype for EFI USB I/O protocol\r
57//\r
58\r
59\r
60/** \r
61 This function is used to manage a USB device with a control transfer pipe. A control transfer is\r
62 typically used to perform device initialization and configuration. \r
63 \r
64 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
65 @param Request A pointer to the USB device request that will be sent to the USB\r
66 device. \r
67 @param Direction Indicates the data direction.\r
68 @param Data A pointer to the buffer of data that will be transmitted to USB\r
69 device or received from USB device. \r
70 @param Timeout Indicating the transfer should be completed within this time frame.\r
71 The units are in milliseconds. \r
72 @param DataLength The size, in bytes, of the data buffer specified by Data.\r
73 @param Status A pointer to the result of the USB transfer.\r
74 \r
75 @retval EFI_SUCCESS The control transfer has been successfully executed.\r
76 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.\r
77 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.\r
78 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
79 @retval EFI_TIMEOUT The control transfer fails due to timeout.\r
80 \r
81**/\r
82typedef\r
83EFI_STATUS\r
84(EFIAPI *EFI_USB_IO_CONTROL_TRANSFER) (\r
85 IN EFI_USB_IO_PROTOCOL *This,\r
86 IN EFI_USB_DEVICE_REQUEST *Request,\r
87 IN EFI_USB_DATA_DIRECTION Direction,\r
88 IN UINT32 Timeout,\r
89 IN OUT VOID *Data OPTIONAL,\r
90 IN UINTN DataLength OPTIONAL,\r
91 OUT UINT32 *Status\r
92 );\r
93\r
94/** \r
95 This function is used to manage a USB device with the bulk transfer pipe. Bulk Transfers are\r
96 typically used to transfer large amounts of data to/from USB devices.\r
97 \r
98 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
99 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
100 device. \r
101 @param Data A pointer to the buffer of data that will be transmitted to USB\r
102 device or received from USB device. \r
103 @param DataLength The size, in bytes, of the data buffer specified by Data.\r
104 @param Timeout Indicating the transfer should be completed within this time frame.\r
105 The units are in milliseconds. \r
106 @param Status This parameter indicates the USB transfer status.\r
107 \r
108 @retval EFI_SUCCESS The bulk transfer has been successfully executed.\r
109 @retval EFI_DEVICE_ERROR The transfer failed. The transfer status is returned in Status.\r
110 @retval EFI_INVALID_PARAMETE One or more parameters are invalid.\r
111 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
112 @retval EFI_TIMEOUT The control transfer fails due to timeout.\r
113 \r
114**/\r
115typedef\r
116EFI_STATUS\r
117(EFIAPI *EFI_USB_IO_BULK_TRANSFER) (\r
118 IN EFI_USB_IO_PROTOCOL *This,\r
119 IN UINT8 DeviceEndpoint,\r
120 IN OUT VOID *Data,\r
121 IN OUT UINTN *DataLength,\r
122 IN UINTN Timeout,\r
123 OUT UINT32 *Status\r
124 );\r
125\r
126/** \r
127 This function is used to manage a USB device with an interrupt transfer pipe. An Asynchronous \r
128 Interrupt Transfer is typically used to query a device's status at a fixed rate. For example, \r
129 keyboard, mouse, and hub devices use this type of transfer to query their interrupt endpoints at\r
130 a fixed rate. \r
131 \r
132 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
133 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
134 device. \r
135 @param IsNewTransfer If TRUE, a new transfer will be submitted to USB controller. If \r
136 FALSE, the interrupt transfer is deleted from the device's interrupt\r
137 transfer queue. \r
138 @param PollingInterval Indicates the periodic rate, in milliseconds, that the transfer is to be \r
139 executed. \r
140 @param DataLength Specifies the length, in bytes, of the data to be received from the\r
141 USB device. \r
142 @param Context Data passed to the InterruptCallback function.\r
143 @param InterruptCallback The Callback function. This function is called if the asynchronous\r
144 interrupt transfer is completed.\r
145 \r
146 @retval EFI_SUCCESS The asynchronous USB transfer request transfer has been successfully executed.\r
147 @retval EFI_DEVICE_ERROR The asynchronous USB transfer request failed. \r
148 \r
149**/\r
150typedef\r
151EFI_STATUS\r
152(EFIAPI *EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER) (\r
153 IN EFI_USB_IO_PROTOCOL *This,\r
154 IN UINT8 DeviceEndpoint,\r
155 IN BOOLEAN IsNewTransfer,\r
156 IN UINTN PollingInterval OPTIONAL,\r
157 IN UINTN DataLength OPTIONAL,\r
158 IN EFI_ASYNC_USB_TRANSFER_CALLBACK InterruptCallBack OPTIONAL,\r
159 IN VOID *Context OPTIONAL\r
160 );\r
161\r
162/** \r
163 This function is used to manage a USB device with an interrupt transfer pipe.\r
164 \r
165 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
166 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
167 device. \r
168 @param Data A pointer to the buffer of data that will be transmitted to USB\r
169 device or received from USB device. \r
170 @param DataLength On input, then size, in bytes, of the buffer Data. On output, the\r
171 amount of data actually transferred. \r
172 @param Timeout The time out, in seconds, for this transfer.\r
173 @param Status This parameter indicates the USB transfer status. \r
174 \r
175 @retval EFI_SUCCESS The sync interrupt transfer has been successfully executed.\r
176 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
177 @retval EFI_DEVICE_ERROR The sync interrupt transfer request failed. \r
178 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
179 @retval EFI_TIMEOUT The transfer fails due to timeout. \r
180**/\r
181typedef\r
182EFI_STATUS\r
183(EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER) (\r
184 IN EFI_USB_IO_PROTOCOL *This,\r
185 IN UINT8 DeviceEndpoint,\r
186 IN OUT VOID *Data,\r
187 IN OUT UINTN *DataLength,\r
188 IN UINTN Timeout,\r
189 OUT UINT32 *Status\r
190 );\r
191\r
192/** \r
193 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous\r
194 transfer is typically used to transfer streaming data.\r
195 \r
196 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
197 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
198 device. \r
199 @param Data A pointer to the buffer of data that will be transmitted to USB\r
200 device or received from USB device. \r
201 @param DataLength The size, in bytes, of the data buffer specified by Data. \r
202 @param Status This parameter indicates the USB transfer status. \r
203 \r
204 @retval EFI_SUCCESS The isochronous transfer has been successfully executed.\r
205 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.\r
206 @retval EFI_DEVICE_ERROR The transfer failed due to the reason other than timeout, The error status\r
207 is returned in Status. \r
208 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
209 @retval EFI_TIMEOUT The transfer fails due to timeout. \r
210**/\r
211typedef\r
212EFI_STATUS\r
213(EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER) (\r
214 IN EFI_USB_IO_PROTOCOL *This,\r
215 IN UINT8 DeviceEndpoint,\r
216 IN OUT VOID *Data,\r
217 IN UINTN DataLength,\r
218 OUT UINT32 *Status\r
219 );\r
220\r
221/** \r
222 This function is used to manage a USB device with an isochronous transfer pipe. An Isochronous\r
223 transfer is typically used to transfer streaming data. \r
224 \r
225 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
226 @param DeviceEndpoint A pointer to the USB device request that will be sent to the USB\r
227 device. \r
228 @param Data A pointer to the buffer of data that will be transmitted to USB\r
229 device or received from USB device. \r
230 @param DataLength The size, in bytes, of the data buffer specified by Data. \r
231 @param Context Data passed to the IsochronousCallback() function.\r
232 @param IsochronousCallback The IsochronousCallback() function.\r
233 \r
234 @retval EFI_SUCCESS The asynchronous isochronous transfer has been successfully submitted\r
235 to the system.\r
236 @retval EFI_INVALID_PARAMETER The parameter DeviceEndpoint is not valid.\r
237 @retval EFI_OUT_OF_RESOURCES The request could not be submitted due to a lack of resources.\r
238 \r
239**/\r
240typedef\r
241EFI_STATUS\r
242(EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER) (\r
243 IN EFI_USB_IO_PROTOCOL *This,\r
244 IN UINT8 DeviceEndpoint,\r
245 IN OUT VOID *Data,\r
246 IN UINTN DataLength,\r
247 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack,\r
248 IN VOID *Context OPTIONAL\r
249 );\r
250\r
251/** \r
252 Resets and reconfigures the USB controller. This function will work for all USB devices except\r
253 USB Hub Controllers. \r
254 \r
255 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
256 \r
257 @retval EFI_SUCCESS The USB controller was reset. \r
258 @retval EFI_INVALID_PARAMETER If the controller specified by This is a USB hub.\r
259 @retval EFI_DEVICE_ERROR An error occurred during the reconfiguration process.\r
260 \r
261**/\r
262typedef\r
263EFI_STATUS\r
264(EFIAPI *EFI_USB_IO_PORT_RESET) (\r
265 IN EFI_USB_IO_PROTOCOL *This\r
266 );\r
267\r
268/** \r
269 Retrieves the USB Device Descriptor.\r
270 \r
271 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
272 @param DeviceDescriptor A pointer to the caller allocated USB Device Descriptor.\r
273 \r
274 @retval EFI_SUCCESS The device descriptor was retrieved successfully.\r
275 @retval EFI_INVALID_PARAMETER DeviceDescriptor is NULL.\r
276 @retval EFI_NOT_FOUND The device descriptor was not found. The device may not be configured.\r
277 \r
278**/\r
279typedef\r
280EFI_STATUS\r
281(EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR) (\r
282 IN EFI_USB_IO_PROTOCOL *This,\r
283 OUT EFI_USB_DEVICE_DESCRIPTOR *DeviceDescriptor\r
284 );\r
285\r
286/** \r
287 Retrieves the USB Device Descriptor.\r
288 \r
289 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
290 @param ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration\r
291 Descriptor. \r
292 @retval EFI_SUCCESS The active configuration descriptor was retrieved successfully.\r
293 @retval EFI_INVALID_PARAMETER ConfigurationDescriptor is NULL.\r
294 @retval EFI_NOT_FOUND An active configuration descriptor cannot be found. The device may not\r
295 be configured. \r
296 \r
297**/\r
298typedef\r
299EFI_STATUS\r
300(EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR) (\r
301 IN EFI_USB_IO_PROTOCOL *This,\r
302 OUT EFI_USB_CONFIG_DESCRIPTOR *ConfigurationDescriptor\r
303 );\r
304\r
305/** \r
306 Retrieves the Interface Descriptor for a USB Device Controller. As stated earlier, an interface\r
307 within a USB device is equivalently to a USB Controller within the current configuration. \r
308 \r
309 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
310 @param InterfaceDescriptor A pointer to the caller allocated USB Interface Descriptor within\r
311 the configuration setting. \r
312 @retval EFI_SUCCESS The interface descriptor retrieved successfully.\r
313 @retval EFI_INVALID_PARAMETER InterfaceDescriptor is NULL.\r
314 @retval EFI_NOT_FOUND The interface descriptor cannot be found. The device may not be\r
315 correctly configured. \r
316 \r
317**/\r
318typedef\r
319EFI_STATUS\r
320(EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR) (\r
321 IN EFI_USB_IO_PROTOCOL *This,\r
322 OUT EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor\r
323 );\r
324\r
325/** \r
326 Retrieves an Endpoint Descriptor within a USB Controller.\r
327 \r
328 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
329 @param EndpointIndex Indicates which endpoint descriptor to retrieve.\r
330 @param EndpointDescriptor A pointer to the caller allocated USB Endpoint Descriptor of\r
331 a USB controller. \r
332 \r
333 @retval EFI_SUCCESS The endpoint descriptor was retrieved successfully.\r
334 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
335 @retval EFI_NOT_FOUND The endpoint descriptor cannot be found. The device may not be\r
336 correctly configured. \r
337 \r
338**/\r
339typedef\r
340EFI_STATUS\r
341(EFIAPI *EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR) (\r
342 IN EFI_USB_IO_PROTOCOL *This,\r
343 IN UINT8 EndpointIndex,\r
344 OUT EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescriptor\r
345 );\r
346\r
347/** \r
348 Retrieves a Unicode string stored in a USB Device.\r
349 \r
350 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
351 @param LangID The Language ID for the string being retrieved.\r
352 @param StringID The ID of the string being retrieved. \r
353 @param String A pointer to a buffer allocated by this function with \r
354 AllocatePool() to store the string.\r
355 \r
356 @retval EFI_SUCCESS The string was retrieved successfully. \r
357 @retval EFI_NOT_FOUND The string specified by LangID and StringID was not found. \r
358 @retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the return buffer String.\r
359 \r
360**/\r
361typedef\r
362EFI_STATUS\r
363(EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR) (\r
364 IN EFI_USB_IO_PROTOCOL *This,\r
365 IN UINT16 LangID,\r
366 IN UINT8 StringID,\r
367 OUT CHAR16 **String\r
368 );\r
369\r
370/** \r
371 Retrieves all the language ID codes that the USB device supports.\r
372 \r
373 @param This A pointer to the EFI_USB_IO_PROTOCOL instance. \r
374 @param LangIDTable Language ID for the string the caller wants to get.\r
375 @param TableSize The size, in bytes, of the table LangIDTable.\r
376 \r
377 @retval EFI_SUCCESS The support languages were retrieved successfully. \r
378 \r
379**/\r
380typedef\r
381EFI_STATUS\r
382(EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE) (\r
383 IN EFI_USB_IO_PROTOCOL *This,\r
384 OUT UINT16 **LangIDTable,\r
385 OUT UINT16 *TableSize\r
386 );\r
387\r
388//\r
389// Protocol Interface Structure\r
390//\r
391struct _EFI_USB_IO_PROTOCOL {\r
392 //\r
393 // IO transfer\r
394 //\r
395 EFI_USB_IO_CONTROL_TRANSFER UsbControlTransfer;\r
396 EFI_USB_IO_BULK_TRANSFER UsbBulkTransfer;\r
397 EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER UsbAsyncInterruptTransfer;\r
398 EFI_USB_IO_SYNC_INTERRUPT_TRANSFER UsbSyncInterruptTransfer;\r
399 EFI_USB_IO_ISOCHRONOUS_TRANSFER UsbIsochronousTransfer;\r
400 EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER UsbAsyncIsochronousTransfer;\r
401\r
402 //\r
403 // Common device request\r
404 //\r
405 EFI_USB_IO_GET_DEVICE_DESCRIPTOR UsbGetDeviceDescriptor;\r
406 EFI_USB_IO_GET_CONFIG_DESCRIPTOR UsbGetConfigDescriptor;\r
407 EFI_USB_IO_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor;\r
408 EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor;\r
409 EFI_USB_IO_GET_STRING_DESCRIPTOR UsbGetStringDescriptor;\r
410 EFI_USB_IO_GET_SUPPORTED_LANGUAGE UsbGetSupportedLanguages;\r
411\r
412 //\r
413 // Reset controller's parent port\r
414 //\r
415 EFI_USB_IO_PORT_RESET UsbPortReset;\r
416};\r
417\r
418extern EFI_GUID gEfiUsbIoProtocolGuid;\r
419\r
420#endif\r