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