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