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