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