MdeModulePkg/Bus/Usb/UsbBusDxe/UsbUtility.h

   1 /** @file
   2
   3     Manage Usb Port/Hc/Etc.
   4
   5 Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>
   6 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 /**
  41   Get the root hub port state.
  42
  43   @param  UsbBus           The USB bus driver.
  44   @param  PortIndex        The index of port.
  45   @param  PortStatus       The variable to save port state.
  46
  47   @retval EFI_SUCCESS      The root port state is returned in.
  48   @retval Others           Failed to get the root hub port state.
  49
  50 **/
  51 EFI_STATUS
  52 UsbHcGetRootHubPortStatus (
  53   IN  USB_BUS             *UsbBus,
  54   IN  UINT8               PortIndex,
  55   OUT EFI_USB_PORT_STATUS *PortStatus
  56   );
  57
  58 /**
  59   Set the root hub port feature.
  60
  61   @param  UsbBus           The USB bus driver.
  62   @param  PortIndex        The port index.
  63   @param  Feature          The port feature to set.
  64
  65   @retval EFI_SUCCESS      The port feature is set.
  66   @retval Others           Failed to set port feature.
  67
  68 **/
  69 EFI_STATUS
  70 UsbHcSetRootHubPortFeature (
  71   IN USB_BUS              *UsbBus,
  72   IN UINT8                PortIndex,
  73   IN EFI_USB_PORT_FEATURE Feature
  74   );
  75
  76 /**
  77   Clear the root hub port feature.
  78
  79   @param  UsbBus           The USB bus driver.
  80   @param  PortIndex        The port index.
  81   @param  Feature          The port feature to clear.
  82
  83   @retval EFI_SUCCESS      The port feature is clear.
  84   @retval Others           Failed to clear port feature.
  85
  86 **/
  87 EFI_STATUS
  88 UsbHcClearRootHubPortFeature (
  89   IN USB_BUS              *UsbBus,
  90   IN UINT8                PortIndex,
  91   IN EFI_USB_PORT_FEATURE Feature
  92   );
  93
  94 /**
  95   Execute a control transfer to the device.
  96
  97   @param  UsbBus           The USB bus driver.
  98   @param  DevAddr          The device address.
  99   @param  DevSpeed         The device speed.
 100   @param  MaxPacket        Maximum packet size of endpoint 0.
 101   @param  Request          The control transfer request.
 102   @param  Direction        The direction of data stage.
 103   @param  Data             The buffer holding data.
 104   @param  DataLength       The length of the data.
 105   @param  TimeOut          Timeout (in ms) to wait until timeout.
 106   @param  Translator       The transaction translator for low/full speed device.
 107   @param  UsbResult        The result of transfer.
 108
 109   @retval EFI_SUCCESS      The control transfer finished without error.
 110   @retval Others           The control transfer failed, reason returned in UsbReslt.
 111
 112 **/
 113 EFI_STATUS
 114 UsbHcControlTransfer (
 115   IN  USB_BUS                             *UsbBus,
 116   IN  UINT8                               DevAddr,
 117   IN  UINT8                               DevSpeed,
 118   IN  UINTN                               MaxPacket,
 119   IN  EFI_USB_DEVICE_REQUEST              *Request,
 120   IN  EFI_USB_DATA_DIRECTION              Direction,
 121   IN  OUT VOID                            *Data,
 122   IN  OUT UINTN                           *DataLength,
 123   IN  UINTN                               TimeOut,
 124   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 125   OUT UINT32                              *UsbResult
 126   );
 127
 128 /**
 129   Execute a bulk transfer to the device's endpoint.
 130
 131   @param  UsbBus           The USB bus driver.
 132   @param  DevAddr          The target device address.
 133   @param  EpAddr           The target endpoint address, with direction encoded in
 134                            bit 7.
 135   @param  DevSpeed         The device's speed.
 136   @param  MaxPacket        The endpoint's max packet size.
 137   @param  BufferNum        The number of data buffer.
 138   @param  Data             Array of pointers to data buffer.
 139   @param  DataLength       The length of data buffer.
 140   @param  DataToggle       On input, the initial data toggle to use, also  return
 141                            the next toggle on output.
 142   @param  TimeOut          The time to wait until timeout.
 143   @param  Translator       The transaction translator for low/full speed device.
 144   @param  UsbResult        The result of USB execution.
 145
 146   @retval EFI_SUCCESS      The bulk transfer is finished without error.
 147   @retval Others           Failed to execute bulk transfer, result in UsbResult.
 148
 149 **/
 150 EFI_STATUS
 151 UsbHcBulkTransfer (
 152   IN  USB_BUS                             *UsbBus,
 153   IN  UINT8                               DevAddr,
 154   IN  UINT8                               EpAddr,
 155   IN  UINT8                               DevSpeed,
 156   IN  UINTN                               MaxPacket,
 157   IN  UINT8                               BufferNum,
 158   IN  OUT VOID                            *Data[EFI_USB_MAX_BULK_BUFFER_NUM],
 159   IN  OUT UINTN                           *DataLength,
 160   IN  OUT UINT8                           *DataToggle,
 161   IN  UINTN                               TimeOut,
 162   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 163   OUT UINT32                              *UsbResult
 164   );
 165
 166 /**
 167   Queue or cancel an asynchronous interrupt transfer.
 168
 169   @param  UsbBus           The USB bus driver.
 170   @param  DevAddr          The target device address.
 171   @param  EpAddr           The target endpoint address, with direction encoded in
 172                            bit 7.
 173   @param  DevSpeed         The device's speed.
 174   @param  MaxPacket        The endpoint's max packet size.
 175   @param  IsNewTransfer    Whether this is a new request. If not, cancel the old
 176                            request.
 177   @param  DataToggle       Data toggle to use on input, next toggle on output.
 178   @param  PollingInterval  The interval to poll the interrupt transfer (in ms).
 179   @param  DataLength       The length of periodical data receive.
 180   @param  Translator       The transaction translator for low/full speed device.
 181   @param  Callback         Function to call when data is received.
 182   @param  Context          The context to the callback.
 183
 184   @retval EFI_SUCCESS      The asynchronous transfer is queued.
 185   @retval Others           Failed to queue the transfer.
 186
 187 **/
 188 EFI_STATUS
 189 UsbHcAsyncInterruptTransfer (
 190   IN  USB_BUS                             *UsbBus,
 191   IN  UINT8                               DevAddr,
 192   IN  UINT8                               EpAddr,
 193   IN  UINT8                               DevSpeed,
 194   IN  UINTN                               MaxPacket,
 195   IN  BOOLEAN                             IsNewTransfer,
 196   IN OUT UINT8                            *DataToggle,
 197   IN  UINTN                               PollingInterval,
 198   IN  UINTN                               DataLength,
 199   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 200   IN  EFI_ASYNC_USB_TRANSFER_CALLBACK     Callback,
 201   IN  VOID                                *Context OPTIONAL
 202   );
 203
 204 /**
 205   Execute a synchronous interrupt transfer to the target endpoint.
 206
 207   @param  UsbBus           The USB bus driver.
 208   @param  DevAddr          The target device address.
 209   @param  EpAddr           The target endpoint address, with direction encoded in
 210                            bit 7.
 211   @param  DevSpeed         The device's speed.
 212   @param  MaxPacket        The endpoint's max packet size.
 213   @param  Data             Pointer to data buffer.
 214   @param  DataLength       The length of data buffer.
 215   @param  DataToggle       On input, the initial data toggle to use, also  return
 216                            the next toggle on output.
 217   @param  TimeOut          The time to wait until timeout.
 218   @param  Translator       The transaction translator for low/full speed device.
 219   @param  UsbResult        The result of USB execution.
 220
 221   @retval EFI_SUCCESS      The synchronous interrupt transfer is OK.
 222   @retval Others           Failed to execute the synchronous interrupt transfer.
 223
 224 **/
 225 EFI_STATUS
 226 UsbHcSyncInterruptTransfer (
 227   IN  USB_BUS                             *UsbBus,
 228   IN  UINT8                               DevAddr,
 229   IN  UINT8                               EpAddr,
 230   IN  UINT8                               DevSpeed,
 231   IN  UINTN                               MaxPacket,
 232   IN OUT VOID                             *Data,
 233   IN OUT UINTN                            *DataLength,
 234   IN OUT UINT8                            *DataToggle,
 235   IN  UINTN                               TimeOut,
 236   IN  EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 237   OUT UINT32                              *UsbResult
 238   );
 239
 240
 241 /**
 242   Open the USB host controller protocol BY_CHILD.
 243
 244   @param  Bus              The USB bus driver.
 245   @param  Child            The child handle.
 246
 247   @return The open protocol return.
 248
 249 **/
 250 EFI_STATUS
 251 UsbOpenHostProtoByChild (
 252   IN USB_BUS              *Bus,
 253   IN EFI_HANDLE           Child
 254   );
 255
 256 /**
 257   Close the USB host controller protocol BY_CHILD.
 258
 259   @param  Bus              The USB bus driver.
 260   @param  Child            The child handle.
 261
 262   @return None.
 263
 264 **/
 265 VOID
 266 UsbCloseHostProtoByChild (
 267   IN USB_BUS              *Bus,
 268   IN EFI_HANDLE           Child
 269   );
 270
 271 /**
 272   return the current TPL, copied from the EDKII glue lib.
 273
 274   @param  VOID.
 275
 276   @return Current TPL.
 277
 278 **/
 279 EFI_TPL
 280 UsbGetCurrentTpl (
 281   VOID
 282   );
 283
 284 #endif