MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.h

   1 /** @file
   2
   3     Manage Usb Port/Hc/Etc.
   4
   5 Copyright (c) 2007, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _EFI_USB_UTILITY_H_
  17 #define _EFI_USB_UTILITY_H_
  18
  19 /**
  20   Get the capability of the host controller.
  21
  22   @param  UsbBus           The usb driver.
  23   @param  MaxSpeed         The maximum speed this host controller supports.
  24   @param  NumOfPort        The number of the root hub port.
  25   @param  Is64BitCapable   Whether this controller support 64 bit addressing.
  26
  27   @retval EFI_SUCCESS      The host controller capability is returned.
  28   @retval Others           Failed to retrieve the host controller capability.
  29
  30 **/
  31 EFI_STATUS
  32 UsbHcGetCapability (
  33   IN  USB_BUS             *UsbBus,
  34   OUT UINT8               *MaxSpeed,
  35   OUT UINT8               *NumOfPort,
  36   OUT UINT8               *Is64BitCapable
  37   );
  38
  39 /**
  40   Reset the host controller.
  41
  42   @param  UsbBus                The usb bus driver.
  43   @param  Attributes            The reset type, only global reset is used by this driver.
  44
  45   @retval EFI_SUCCESS           The reset operation succeeded.
  46   @retval EFI_INVALID_PARAMETER Attributes is not valid.
  47   @retval EFI_UNSUPPOURTED      The type of reset specified by Attributes is
  48                                 not currently supported by the host controller.
  49   @retval EFI_DEVICE_ERROR      Host controller isn't halted to reset.
  50 **/
  51 EFI_STATUS
  52 UsbHcReset (
  53   IN USB_BUS              *UsbBus,
  54   IN UINT16               Attributes
  55   );
  56
  57 /**
  58   Get the current operation state of the host controller.
  59
  60   @param  UsbBus           The USB bus driver.
  61   @param  State            The host controller operation state.
  62
  63   @retval EFI_SUCCESS      The operation state is returned in State.
  64   @retval Others           Failed to get the host controller state.
  65
  66 **/
  67 EFI_STATUS
  68 UsbHcGetState (
  69   IN  USB_BUS             *UsbBus,
  70   OUT EFI_USB_HC_STATE    *State
  71   );
  72
  73 /**
  74   Set the host controller operation state.
  75
  76   @param  UsbBus           The USB bus driver.
  77   @param  State            The state to set.
  78
  79   @retval EFI_SUCCESS      The host controller is now working at State.
  80   @retval Others           Failed to set operation state.
  81
  82 **/
  83 EFI_STATUS
  84 UsbHcSetState (
  85   IN  USB_BUS             *UsbBus,
  86   IN EFI_USB_HC_STATE     State
  87   );
  88
  89 /**
  90   Get the root hub port state.
  91
  92   @param  UsbBus           The USB bus driver.
  93   @param  PortIndex        The index of port.
  94   @param  PortStatus       The variable to save port state.
  95
  96   @retval EFI_SUCCESS      The root port state is returned in.
  97   @retval Others           Failed to get the root hub port state.
  98
  99 **/
 100 EFI_STATUS
 101 UsbHcGetRootHubPortStatus (
 102   IN  USB_BUS             *UsbBus,
 103   IN  UINT8               PortIndex,
 104   OUT EFI_USB_PORT_STATUS *PortStatus
 105   );
 106
 107 /**
 108   Set the root hub port feature.
 109
 110   @param  UsbBus           The USB bus driver.
 111   @param  PortIndex        The port index.
 112   @param  Feature          The port feature to set.
 113
 114   @retval EFI_SUCCESS      The port feature is set.
 115   @retval Others           Failed to set port feature.
 116
 117 **/
 118 EFI_STATUS
 119 UsbHcSetRootHubPortFeature (
 120   IN USB_BUS              *UsbBus,
 121   IN UINT8                PortIndex,
 122   IN EFI_USB_PORT_FEATURE Feature
 123   );
 124
 125 /**
 126   Clear the root hub port feature.
 127
 128   @param  UsbBus           The USB bus driver.
 129   @param  PortIndex        The port index.
 130   @param  Feature          The port feature to clear.
 131
 132   @retval EFI_SUCCESS      The port feature is clear.
 133   @retval Others           Failed to clear port feature.
 134
 135 **/
 136 EFI_STATUS
 137 UsbHcClearRootHubPortFeature (
 138   IN USB_BUS              *UsbBus,
 139   IN UINT8                PortIndex,
 140   IN EFI_USB_PORT_FEATURE Feature
 141   );
 142
 143 /**
 144   Execute a control transfer to the device.
 145
 146   @param  UsbBus           The USB bus driver.
 147   @param  DevAddr          The device address.
 148   @param  DevSpeed         The device speed.
 149   @param  MaxPacket        Maximum packet size of endpoint 0.
 150   @param  Request          The control transfer request.
 151   @param  Direction        The direction of data stage.
 152   @param  Data             The buffer holding data.
 153   @param  DataLength       The length of the data.
 154   @param  TimeOut          Timeout (in ms) to wait until timeout.
 155   @param  Translator       The transaction translator for low/full speed device.
 156   @param  UsbResult        The result of transfer.
 157
 158   @retval EFI_SUCCESS      The control transfer finished without error.
 159   @retval Others           The control transfer failed, reason returned in UsbReslt.
 160
 161 **/
 162 EFI_STATUS
 163 UsbHcControlTransfer (
 164   IN  USB_BUS                             *UsbBus,
 165   IN  UINT8                               DevAddr,
 166   IN  UINT8                               DevSpeed,
 167   IN  UINTN                               MaxPacket,
 168   IN  EFI_USB_DEVICE_REQUEST              *Request,
 169   IN  EFI_USB_DATA_DIRECTION              Direction,
 170   IN  OUT VOID                            *Data,
 171   IN  OUT UINTN                           *DataLength,
 172   IN  UINTN                               TimeOut,
 173   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 174   OUT UINT32                              *UsbResult
 175   );
 176
 177 /**
 178   Execute a bulk transfer to the device's endpoint.
 179
 180   @param  UsbBus           The USB bus driver.
 181   @param  DevAddr          The target device address.
 182   @param  EpAddr           The target endpoint address, with direction encoded in
 183                            bit 7.
 184   @param  DevSpeed         The device's speed.
 185   @param  MaxPacket        The endpoint's max packet size.
 186   @param  BufferNum        The number of data buffer.
 187   @param  Data             Array of pointers to data buffer.
 188   @param  DataLength       The length of data buffer.
 189   @param  DataToggle       On input, the initial data toggle to use, also  return
 190                            the next toggle on output.
 191   @param  TimeOut          The time to wait until timeout.
 192   @param  Translator       The transaction translator for low/full speed device.
 193   @param  UsbResult        The result of USB execution.
 194
 195   @retval EFI_SUCCESS      The bulk transfer is finished without error.
 196   @retval Others           Failed to execute bulk transfer, result in UsbResult.
 197
 198 **/
 199 EFI_STATUS
 200 UsbHcBulkTransfer (
 201   IN  USB_BUS                             *UsbBus,
 202   IN  UINT8                               DevAddr,
 203   IN  UINT8                               EpAddr,
 204   IN  UINT8                               DevSpeed,
 205   IN  UINTN                               MaxPacket,
 206   IN  UINT8                               BufferNum,
 207   IN  OUT VOID                            *Data[EFI_USB_MAX_BULK_BUFFER_NUM],
 208   IN  OUT UINTN                           *DataLength,
 209   IN  OUT UINT8                           *DataToggle,
 210   IN  UINTN                               TimeOut,
 211   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 212   OUT UINT32                              *UsbResult
 213   );
 214
 215 /**
 216   Queue or cancel an asynchronous interrupt transfer.
 217
 218   @param  UsbBus           The USB bus driver.
 219   @param  DevAddr          The target device address.
 220   @param  EpAddr           The target endpoint address, with direction encoded in
 221                            bit 7.
 222   @param  DevSpeed         The device's speed.
 223   @param  MaxPacket        The endpoint's max packet size.
 224   @param  IsNewTransfer    Whether this is a new request. If not, cancel the old
 225                            request.
 226   @param  DataToggle       Data toggle to use on input, next toggle on output.
 227   @param  PollingInterval  The interval to poll the interrupt transfer (in ms).
 228   @param  DataLength       The length of periodical data receive.
 229   @param  Translator       The transaction translator for low/full speed device.
 230   @param  Callback         Function to call when data is received.
 231   @param  Context          The context to the callback.
 232
 233   @retval EFI_SUCCESS      The asynchronous transfer is queued.
 234   @retval Others           Failed to queue the transfer.
 235
 236 **/
 237 EFI_STATUS
 238 UsbHcAsyncInterruptTransfer (
 239   IN  USB_BUS                             *UsbBus,
 240   IN  UINT8                               DevAddr,
 241   IN  UINT8                               EpAddr,
 242   IN  UINT8                               DevSpeed,
 243   IN  UINTN                               MaxPacket,
 244   IN  BOOLEAN                             IsNewTransfer,
 245   IN OUT UINT8                            *DataToggle,
 246   IN  UINTN                               PollingInterval,
 247   IN  UINTN                               DataLength,
 248   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 249   IN  EFI_ASYNC_USB_TRANSFER_CALLBACK     Callback,
 250   IN  VOID                                *Context OPTIONAL
 251   );
 252
 253 /**
 254   Execute a synchronous interrupt transfer to the target endpoint.
 255
 256   @param  UsbBus           The USB bus driver.
 257   @param  DevAddr          The target device address.
 258   @param  EpAddr           The target endpoint address, with direction encoded in
 259                            bit 7.
 260   @param  DevSpeed         The device's speed.
 261   @param  MaxPacket        The endpoint's max packet size.
 262   @param  Data             Pointer to data buffer.
 263   @param  DataLength       The length of data buffer.
 264   @param  DataToggle       On input, the initial data toggle to use, also  return
 265                            the next toggle on output.
 266   @param  TimeOut          The time to wait until timeout.
 267   @param  Translator       The transaction translator for low/full speed device.
 268   @param  UsbResult        The result of USB execution.
 269
 270   @retval EFI_SUCCESS      The synchronous interrupt transfer is OK.
 271   @retval Others           Failed to execute the synchronous interrupt transfer.
 272
 273 **/
 274 EFI_STATUS
 275 UsbHcSyncInterruptTransfer (
 276   IN  USB_BUS                             *UsbBus,
 277   IN  UINT8                               DevAddr,
 278   IN  UINT8                               EpAddr,
 279   IN  UINT8                               DevSpeed,
 280   IN  UINTN                               MaxPacket,
 281   IN OUT VOID                             *Data,
 282   IN OUT UINTN                            *DataLength,
 283   IN OUT UINT8                            *DataToggle,
 284   IN  UINTN                               TimeOut,
 285   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 286   OUT UINT32                              *UsbResult
 287   );
 288
 289 /**
 290   Execute a synchronous Isochronous USB transfer.
 291
 292   @param  UsbBus           The USB bus driver.
 293   @param  DevAddr          The target device address.
 294   @param  EpAddr           The target endpoint address, with direction encoded in
 295                            bit 7.
 296   @param  DevSpeed         The device's speed.
 297   @param  MaxPacket        The endpoint's max packet size.
 298   @param  BufferNum        The number of data buffer.
 299   @param  Data             Array of pointers to data buffer.
 300   @param  DataLength       The length of data buffer.
 301   @param  Translator       The transaction translator for low/full speed device.
 302   @param  UsbResult        The result of USB execution.
 303
 304   @retval EFI_UNSUPPORTED  The isochronous transfer isn't supported now.
 305
 306 **/
 307 EFI_STATUS
 308 UsbHcIsochronousTransfer (
 309   IN  USB_BUS                             *UsbBus,
 310   IN  UINT8                               DevAddr,
 311   IN  UINT8                               EpAddr,
 312   IN  UINT8                               DevSpeed,
 313   IN  UINTN                               MaxPacket,
 314   IN  UINT8                               BufferNum,
 315   IN  OUT VOID                            *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
 316   IN  UINTN                               DataLength,
 317   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 318   OUT UINT32                              *UsbResult
 319   );
 320
 321 /**
 322   Queue an asynchronous isochronous transfer.
 323
 324   @param  UsbBus           The USB bus driver.
 325   @param  DevAddr          The target device address.
 326   @param  EpAddr           The target endpoint address, with direction encoded in
 327                            bit 7.
 328   @param  DevSpeed         The device's speed.
 329   @param  MaxPacket        The endpoint's max packet size.
 330   @param  BufferNum        The number of data buffer.
 331   @param  Data             Array of pointers to data buffer.
 332   @param  DataLength       The length of data buffer.
 333   @param  Translator       The transaction translator for low/full speed device.
 334   @param  Callback         The function to call when data is transferred.
 335   @param  Context          The context to the callback function.
 336
 337   @retval EFI_UNSUPPORTED  The asynchronous isochronous transfer isn't supported.
 338
 339 **/
 340 EFI_STATUS
 341 UsbHcAsyncIsochronousTransfer (
 342   IN  USB_BUS                             *UsbBus,
 343   IN  UINT8                               DevAddr,
 344   IN  UINT8                               EpAddr,
 345   IN  UINT8                               DevSpeed,
 346   IN  UINTN                               MaxPacket,
 347   IN  UINT8                               BufferNum,
 348   IN OUT VOID                             *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
 349   IN  UINTN                               DataLength,
 350   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 351   IN  EFI_ASYNC_USB_TRANSFER_CALLBACK     Callback,
 352   IN  VOID                                *Context
 353   );
 354
 355 /**
 356   Open the USB host controller protocol BY_CHILD.
 357
 358   @param  Bus              The USB bus driver.
 359   @param  Child            The child handle.
 360
 361   @return The open protocol return.
 362
 363 **/
 364 EFI_STATUS
 365 UsbOpenHostProtoByChild (
 366   IN USB_BUS              *Bus,
 367   IN EFI_HANDLE           Child
 368   );
 369
 370 /**
 371   Close the USB host controller protocol BY_CHILD.
 372
 373   @param  Bus              The USB bus driver.
 374   @param  Child            The child handle.
 375
 376   @return None.
 377
 378 **/
 379 VOID
 380 UsbCloseHostProtoByChild (
 381   IN USB_BUS              *Bus,
 382   IN EFI_HANDLE           Child
 383   );
 384
 385 /**
 386   return the current TPL, copied from the EDKII glue lib.
 387
 388   @param  VOID.
 389
 390   @return Current TPL.
 391
 392 **/
 393 EFI_TPL
 394 UsbGetCurrentTpl (
 395   VOID
 396   );
 397
 398 #endif