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 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 399