Tools/Source/TianoTools/Include/Protocol/UsbIo.h

   1 /** @file
   2   EFI Usb I/O Protocol
   3
   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
   9
  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.
  12
  13   Module Name:  UsbIo.h
  14
  15 **/
  16
  17 #ifndef __USB_IO_H__
  18 #define __USB_IO_H__
  19
  20 //
  21 // Global ID for the USB I/O Protocol
  22 //
  23 #define EFI_USB_IO_PROTOCOL_GUID \
  24   { \
  25     0x2B2F68D6, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75 } \
  26   }
  27
  28 typedef struct _EFI_USB_IO_PROTOCOL   EFI_USB_IO_PROTOCOL;
  29
  30 /**
  31   Async USB transfer callback routine.
  32
  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.
  39
  40   @retval EFI_SUCCESS           The asynchronous USB transfer request has been successfully executed.
  41   @retval EFI_DEVICE_ERROR      The asynchronous USB transfer request failed.
  42
  43 **/
  44 typedef
  45 EFI_STATUS
  46 (EFIAPI *EFI_ASYNC_USB_TRANSFER_CALLBACK) (
  47   IN VOID         *Data,
  48   IN UINTN        DataLength,
  49   IN VOID         *Context,
  50   IN UINT32       Status
  51   );
  52
  53 //
  54 // Prototype for EFI USB I/O protocol
  55 //
  56
  57
  58 /**
  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.
  61
  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
  64                                 device.
  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.
  72
  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.
  78
  79 **/
  80 typedef
  81 EFI_STATUS
  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,
  86   IN UINT32                                     Timeout,
  87   IN OUT VOID                                   *Data OPTIONAL,
  88   IN UINTN                                      DataLength  OPTIONAL,
  89   OUT UINT32                                    *Status
  90   );
  91
  92 /**
  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.
  95
  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
  98                                 device.
  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.
 105
 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.
 111
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *EFI_USB_IO_BULK_TRANSFER) (
 116   IN EFI_USB_IO_PROTOCOL            *This,
 117   IN UINT8                          DeviceEndpoint,
 118   IN OUT VOID                       *Data,
 119   IN OUT UINTN                      *DataLength,
 120   IN UINTN                          Timeout,
 121   OUT UINT32                        *Status
 122   );
 123
 124 /**
 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
 128   a fixed rate.
 129
 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
 132                                 device.
 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
 135                                 transfer queue.
 136   @param  PollingInterval       Indicates the periodic rate, in milliseconds, that the transfer is to be
 137                                 executed.
 138   @param  DataLength            Specifies the length, in bytes, of the data to be received from the
 139                                 USB device.
 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.
 143
 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.
 146
 147 **/
 148 typedef
 149 EFI_STATUS
 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
 158   );
 159
 160 /**
 161   This function is used to manage a USB device with an interrupt transfer pipe.
 162
 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
 165                                 device.
 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.
 172
 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.
 178 **/
 179 typedef
 180 EFI_STATUS
 181 (EFIAPI *EFI_USB_IO_SYNC_INTERRUPT_TRANSFER) (
 182   IN EFI_USB_IO_PROTOCOL            *This,
 183   IN     UINT8                      DeviceEndpoint,
 184   IN OUT VOID                       *Data,
 185   IN OUT UINTN                      *DataLength,
 186   IN     UINTN                      Timeout,
 187   OUT    UINT32                     *Status
 188   );
 189
 190 /**
 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.
 193
 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
 196                                 device.
 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.
 201
 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.
 208 **/
 209 typedef
 210 EFI_STATUS
 211 (EFIAPI *EFI_USB_IO_ISOCHRONOUS_TRANSFER) (
 212   IN EFI_USB_IO_PROTOCOL            *This,
 213   IN     UINT8                      DeviceEndpoint,
 214   IN OUT VOID                       *Data,
 215   IN     UINTN                      DataLength,
 216   OUT    UINT32                     *Status
 217   );
 218
 219 /**
 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.
 222
 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
 225                                 device.
 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.
 231
 232   @retval EFI_SUCCESS           The asynchronous isochronous transfer has been successfully submitted
 233                                 to the system.
 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.
 236
 237 **/
 238 typedef
 239 EFI_STATUS
 240 (EFIAPI *EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER) (
 241   IN EFI_USB_IO_PROTOCOL              *This,
 242   IN UINT8                            DeviceEndpoint,
 243   IN OUT VOID                         *Data,
 244   IN     UINTN                        DataLength,
 245   IN EFI_ASYNC_USB_TRANSFER_CALLBACK  IsochronousCallBack,
 246   IN VOID                             *Context OPTIONAL
 247   );
 248
 249 /**
 250   Resets and reconfigures the USB controller. This function will work for all USB devices except
 251   USB Hub Controllers.
 252
 253   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
 254
 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.
 258
 259 **/
 260 typedef
 261 EFI_STATUS
 262 (EFIAPI *EFI_USB_IO_PORT_RESET) (
 263   IN EFI_USB_IO_PROTOCOL    *This
 264   );
 265
 266 /**
 267   Retrieves the USB Device Descriptor.
 268
 269   @param  This                  A pointer to the EFI_USB_IO_PROTOCOL instance.
 270   @param  DeviceDescriptor      A pointer to the caller allocated USB Device Descriptor.
 271
 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.
 275
 276 **/
 277 typedef
 278 EFI_STATUS
 279 (EFIAPI *EFI_USB_IO_GET_DEVICE_DESCRIPTOR) (
 280   IN EFI_USB_IO_PROTOCOL            *This,
 281   OUT EFI_USB_DEVICE_DESCRIPTOR     *DeviceDescriptor
 282   );
 283
 284 /**
 285   Retrieves the USB Device Descriptor.
 286
 287   @param  This                    A pointer to the EFI_USB_IO_PROTOCOL instance.
 288   @param  ConfigurationDescriptor A pointer to the caller allocated USB Active Configuration
 289                                   Descriptor.
 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
 293                                   be configured.
 294
 295 **/
 296 typedef
 297 EFI_STATUS
 298 (EFIAPI *EFI_USB_IO_GET_CONFIG_DESCRIPTOR) (
 299   IN EFI_USB_IO_PROTOCOL            *This,
 300   OUT EFI_USB_CONFIG_DESCRIPTOR     *ConfigurationDescriptor
 301   );
 302
 303 /**
 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.
 306
 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.
 314
 315 **/
 316 typedef
 317 EFI_STATUS
 318 (EFIAPI *EFI_USB_IO_GET_INTERFACE_DESCRIPTOR) (
 319   IN EFI_USB_IO_PROTOCOL            *This,
 320   OUT EFI_USB_INTERFACE_DESCRIPTOR  *InterfaceDescriptor
 321   );
 322
 323 /**
 324   Retrieves an Endpoint Descriptor within a USB Controller.
 325
 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
 329                                   a USB controller.
 330
 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.
 335
 336 **/
 337 typedef
 338 EFI_STATUS
 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
 343   );
 344
 345 /**
 346   Retrieves a Unicode string stored in a USB Device.
 347
 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.
 353
 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.
 357
 358 **/
 359 typedef
 360 EFI_STATUS
 361 (EFIAPI *EFI_USB_IO_GET_STRING_DESCRIPTOR) (
 362   IN EFI_USB_IO_PROTOCOL            *This,
 363   IN  UINT16                        LangID,
 364   IN  UINT8                         StringID,
 365   OUT CHAR16                        **String
 366   );
 367
 368 /**
 369   Retrieves all the language ID codes that the USB device supports.
 370
 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.
 374
 375   @retval EFI_SUCCESS             The support languages were retrieved successfully.
 376
 377 **/
 378 typedef
 379 EFI_STATUS
 380 (EFIAPI *EFI_USB_IO_GET_SUPPORTED_LANGUAGE) (
 381   IN EFI_USB_IO_PROTOCOL            *This,
 382   OUT UINT16                        **LangIDTable,
 383   OUT UINT16                        *TableSize
 384   );
 385
 386 //
 387 //  Protocol Interface Structure
 388 //
 389 struct _EFI_USB_IO_PROTOCOL {
 390   //
 391   // IO transfer
 392   //
 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;
 399
 400   //
 401   // Common device request
 402   //
 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;
 409
 410   //
 411   // Reset controller's parent port
 412   //
 413   EFI_USB_IO_PORT_RESET                 UsbPortReset;
 414 };
 415
 416 extern EFI_GUID gEfiUsbIoProtocolGuid;
 417
 418 #endif