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 UsbResult. 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 279