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