Updated headers to follow coding standard
[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   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