1 /** @file 2 EFI_USB_HC_PROTOCOL as defined in EFI 1.10. 3 4 The USB Host Controller Protocol is used by code, typically USB bus drivers, 5 running in the EFI boot services environment, to perform data transactions 6 over a USB bus. In addition, it provides an abstraction for the root hub of the USB bus. 7 8 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> 9 This program and the accompanying materials 10 are licensed and made available under the terms and conditions of the BSD License 11 which accompanies this distribution. The full text of the license may be found at 12 http://opensource.org/licenses/bsd-license.php 13 14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 16 17 **/ 18 19 #ifndef _USB_HOSTCONTROLLER_H_ 20 #define _USB_HOSTCONTROLLER_H_ 21 22 #include <Protocol/Usb2HostController.h> 23 24 #define EFI_USB_HC_PROTOCOL_GUID \ 25 { \ 26 0xf5089266, 0x1aa0, 0x4953, {0x97, 0xd8, 0x56, 0x2f, 0x8a, 0x73, 0xb5, 0x19 } \ 27 } 28 29 /// 30 /// Forward reference for pure ANSI compatability 31 /// 32 typedef struct _EFI_USB_HC_PROTOCOL EFI_USB_HC_PROTOCOL; 33 34 // 35 // Protocol definitions 36 // 37 38 /** 39 Provides software reset for the USB host controller. 40 41 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 42 @param Attributes A bit mask of the reset operation to perform. 43 44 @retval EFI_SUCCESS The reset operation succeeded. 45 @retval EFI_UNSUPPORTED The type of reset specified by Attributes is not currently supported 46 by the host controller hardware. 47 @retval EFI_INVALID_PARAMETER Attributes is not valid. 48 @retval EFI_DEVICE_ERROR An error was encountered while attempting to perform the reset operation. 49 50 **/ 51 typedef 52 EFI_STATUS 53 (EFIAPI *EFI_USB_HC_PROTOCOL_RESET)( 54 IN EFI_USB_HC_PROTOCOL *This, 55 IN UINT16 Attributes 56 ); 57 58 /** 59 Retrieves current state of the USB host controller. 60 61 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 62 @param State A pointer to the EFI_USB_HC_STATE data structure that 63 indicates current state of the USB host controller. 64 65 @retval EFI_SUCCESS The state information of the host controller was returned in State. 66 @retval EFI_INVALID_PARAMETER State is NULL. 67 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the host controller's 68 current state. 69 70 **/ 71 typedef 72 EFI_STATUS 73 (EFIAPI *EFI_USB_HC_PROTOCOL_GET_STATE)( 74 IN EFI_USB_HC_PROTOCOL *This, 75 OUT EFI_USB_HC_STATE *State 76 ); 77 78 /** 79 Sets the USB host controller to a specific state. 80 81 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 82 @param State Indicates the state of the host controller that will be set. 83 84 @retval EFI_SUCCESS The USB host controller was successfully placed in the state specified by 85 State. 86 @retval EFI_INVALID_PARAMETER State is NULL. 87 @retval EFI_DEVICE_ERROR Failed to set the state specified by State due to device error. 88 89 **/ 90 typedef 91 EFI_STATUS 92 (EFIAPI *EFI_USB_HC_PROTOCOL_SET_STATE)( 93 IN EFI_USB_HC_PROTOCOL *This, 94 IN EFI_USB_HC_STATE State 95 ); 96 97 /** 98 Submits control transfer to a target USB device. 99 100 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 101 @param DeviceAddress Represents the address of the target device on the USB, which is 102 assigned during USB enumeration. 103 @param IsSlowDevice Indicates whether the target device is slow device or full-speed 104 device. 105 @param MaximumPacketLength Indicates the maximum packet size that the default control 106 transfer endpoint is capable of sending or receiving. 107 @param Request A pointer to the USB device request that will be sent to the USB 108 device. 109 @param TransferDirection Specifies the data direction for the transfer. There are three 110 values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. 111 @param Data A pointer to the buffer of data that will be transmitted to USB 112 device or received from USB device. 113 @param DataLength On input, indicates the size, in bytes, of the data buffer specified 114 by Data. On output, indicates the amount of data actually 115 transferred. 116 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer 117 is allowed to complete. 118 @param TransferResult A pointer to the detailed result information generated by this 119 control transfer. 120 121 @retval EFI_SUCCESS The control transfer was completed successfully. 122 @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources. 123 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 124 @retval EFI_TIMEOUT The control transfer failed due to timeout. 125 @retval EFI_DEVICE_ERROR The control transfer failed due to host controller or device error. 126 127 **/ 128 typedef 129 EFI_STATUS 130 (EFIAPI *EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER)( 131 IN EFI_USB_HC_PROTOCOL *This, 132 IN UINT8 DeviceAddress, 133 IN BOOLEAN IsSlowDevice, 134 IN UINT8 MaximumPacketLength, 135 IN EFI_USB_DEVICE_REQUEST *Request, 136 IN EFI_USB_DATA_DIRECTION TransferDirection, 137 IN OUT VOID *Data OPTIONAL, 138 IN OUT UINTN *DataLength OPTIONAL, 139 IN UINTN TimeOut, 140 OUT UINT32 *TransferResult 141 ); 142 143 /** 144 Submits bulk transfer to a bulk endpoint of a USB device. 145 146 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 147 @param DeviceAddress Represents the address of the target device on the USB, which is 148 assigned during USB enumeration. 149 @param EndPointAddress The combination of an endpoint number and an endpoint 150 direction of the target USB device. Each endpoint address 151 supports data transfer in one direction except the control 152 endpoint (whose default endpoint address is 0). It is the 153 caller's responsibility to make sure that the EndPointAddress 154 represents a bulk endpoint. 155 @param MaximumPacketLength Indicates the maximum packet size that the default control 156 transfer endpoint is capable of sending or receiving. 157 @param Data A pointer to the buffer of data that will be transmitted to USB 158 device or received from USB device. 159 @param DataLength On input, indicates the size, in bytes, of the data buffer specified 160 by Data. On output, indicates the amount of data actually 161 transferred. 162 @param DataToggle A pointer to the data toggle value. 163 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer 164 is allowed to complete. 165 @param TransferResult A pointer to the detailed result information of the bulk transfer. 166 167 @retval EFI_SUCCESS The bulk transfer was completed successfully. 168 @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to a lack of resources. 169 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 170 @retval EFI_TIMEOUT The bulk transfer failed due to timeout. 171 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. 172 173 **/ 174 typedef 175 EFI_STATUS 176 (EFIAPI *EFI_USB_HC_PROTOCOL_BULK_TRANSFER)( 177 IN EFI_USB_HC_PROTOCOL *This, 178 IN UINT8 DeviceAddress, 179 IN UINT8 EndPointAddress, 180 IN UINT8 MaximumPacketLength, 181 IN OUT VOID *Data, 182 IN OUT UINTN *DataLength, 183 IN OUT UINT8 *DataToggle, 184 IN UINTN TimeOut, 185 OUT UINT32 *TransferResult 186 ); 187 188 /** 189 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device. 190 191 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 192 @param DeviceAddress Represents the address of the target device on the USB, which is 193 assigned during USB enumeration. 194 @param EndPointAddress The combination of an endpoint number and an endpoint 195 direction of the target USB device. Each endpoint address 196 supports data transfer in one direction except the control 197 endpoint (whose default endpoint address is zero). It is the 198 caller's responsibility to make sure that the 199 EndPointAddress represents an interrupt endpoint. 200 @param IsSlowDevice Indicates whether the target device is slow device or full-speed 201 device. 202 @param MaximumPacketLength Indicates the maximum packet size that the default control 203 transfer endpoint is capable of sending or receiving. 204 @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host 205 and the target interrupt endpoint. If FALSE, the specified asynchronous 206 interrupt pipe is canceled. If TRUE, and an interrupt transfer exists 207 for the target end point, then EFI_INVALID_PARAMETER is returned. 208 @param DataToggle A pointer to the data toggle value. On input, it is valid when 209 IsNewTransfer is TRUE, and it indicates the initial data toggle 210 value the asynchronous interrupt transfer should adopt. On output, 211 it is valid when IsNewTransfer is FALSE, and it is updated to indicate 212 the data toggle value of the subsequent asynchronous interrupt transfer. 213 @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous 214 interrupt transfer is polled. 215 @param DataLength Indicates the length of data to be received at the rate specified by 216 PollingInterval from the target asynchronous interrupt 217 endpoint. This parameter is only required when IsNewTransfer is TRUE. 218 @param CallBackFunction The Callback function. This function is called at the rate specified by 219 PollingInterval. This parameter is only required when IsNewTransfer is TRUE. 220 @param Context The context that is passed to the CallBackFunction. 221 222 @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully 223 submitted or canceled. 224 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 225 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 226 @retval EFI_TIMEOUT The bulk transfer failed due to timeout. 227 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. 228 229 **/ 230 typedef 231 EFI_STATUS 232 (EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER)( 233 IN EFI_USB_HC_PROTOCOL *This, 234 IN UINT8 DeviceAddress, 235 IN UINT8 EndPointAddress, 236 IN BOOLEAN IsSlowDevice, 237 IN UINT8 MaxiumPacketLength, 238 IN BOOLEAN IsNewTransfer, 239 IN OUT UINT8 *DataToggle, 240 IN UINTN PollingInterval OPTIONAL, 241 IN UINTN DataLength OPTIONAL, 242 IN EFI_ASYNC_USB_TRANSFER_CALLBACK CallBackFunction OPTIONAL, 243 IN VOID *Context OPTIONAL 244 ); 245 246 /** 247 Submits synchronous interrupt transfer to an interrupt endpoint of a USB device. 248 249 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 250 @param DeviceAddress Represents the address of the target device on the USB, which is 251 assigned during USB enumeration. 252 @param EndPointAddress The combination of an endpoint number and an endpoint 253 direction of the target USB device. Each endpoint address 254 supports data transfer in one direction except the control 255 endpoint (whose default endpoint address is zero). It is the 256 caller's responsibility to make sure that the 257 EndPointAddress represents an interrupt endpoint. 258 @param IsSlowDevice Indicates whether the target device is slow device or full-speed 259 device. 260 @param MaximumPacketLength Indicates the maximum packet size that the default control 261 transfer endpoint is capable of sending or receiving. 262 @param Data A pointer to the buffer of data that will be transmitted to USB 263 device or received from USB device. asynchronous interrupt pipe is canceled. 264 @param DataLength On input, the size, in bytes, of the data buffer specified by Data. 265 On output, the number of bytes transferred. 266 @param DataToggle A pointer to the data toggle value. On input, it indicates the initial 267 data toggle value the synchronous interrupt transfer should adopt; 268 on output, it is updated to indicate the data toggle value of the 269 subsequent synchronous interrupt transfer. 270 @param TimeOut Indicates the maximum time, in milliseconds, which the transfer 271 is allowed to complete. 272 @param TransferResult A pointer to the detailed result information from the synchronous 273 interrupt transfer. 274 275 @retval EFI_SUCCESS The synchronous interrupt transfer was completed successfully. 276 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 277 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 278 @retval EFI_TIMEOUT The synchronous interrupt transfer failed due to timeout. 279 @retval EFI_DEVICE_ERROR The synchronous interrupt transfer failed due to host controller or device error. 280 281 **/ 282 typedef 283 EFI_STATUS 284 (EFIAPI *EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER)( 285 IN EFI_USB_HC_PROTOCOL *This, 286 IN UINT8 DeviceAddress, 287 IN UINT8 EndPointAddress, 288 IN BOOLEAN IsSlowDevice, 289 IN UINT8 MaximumPacketLength, 290 IN OUT VOID *Data, 291 IN OUT UINTN *DataLength, 292 IN OUT UINT8 *DataToggle, 293 IN UINTN TimeOut, 294 OUT UINT32 *TransferResult 295 ); 296 297 /** 298 Submits isochronous transfer to an isochronous endpoint of a USB device. 299 300 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 301 @param DeviceAddress Represents the address of the target device on the USB, which is 302 assigned during USB enumeration. 303 @param EndPointAddress The combination of an endpoint number and an endpoint 304 direction of the target USB device. Each endpoint address 305 supports data transfer in one direction except the control 306 endpoint (whose default endpoint address is 0). It is the caller's 307 responsibility to make sure that the EndPointAddress 308 represents an isochronous endpoint. 309 @param MaximumPacketLength Indicates the maximum packet size that the default control 310 transfer endpoint is capable of sending or receiving. 311 @param Data A pointer to the buffer of data that will be transmitted to USB 312 device or received from USB device. asynchronous interrupt pipe is canceled. 313 @param DataLength Specifies the length, in bytes, of the data to be sent to or received 314 from the USB device. 315 @param TransferResult A pointer to the detailed result information from the isochronous 316 transfer. 317 318 @retval EFI_SUCCESS The isochronous transfer was completed successfully. 319 @retval EFI_OUT_OF_RESOURCES The isochronous could not be completed due to a lack of resources. 320 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 321 @retval EFI_TIMEOUT The isochronous transfer failed due to timeout. 322 @retval EFI_DEVICE_ERROR The isochronous transfer failed due to host controller or device error. 323 324 **/ 325 typedef 326 EFI_STATUS 327 (EFIAPI *EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER)( 328 IN EFI_USB_HC_PROTOCOL *This, 329 IN UINT8 DeviceAddress, 330 IN UINT8 EndPointAddress, 331 IN UINT8 MaximumPacketLength, 332 IN OUT VOID *Data, 333 IN UINTN DataLength, 334 OUT UINT32 *TransferResult 335 ); 336 337 /** 338 Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device. 339 340 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 341 @param DeviceAddress Represents the address of the target device on the USB, which is 342 assigned during USB enumeration. 343 @param EndPointAddress The combination of an endpoint number and an endpoint 344 direction of the target USB device. Each endpoint address 345 supports data transfer in one direction except the control 346 endpoint (whose default endpoint address is zero). It is the 347 caller's responsibility to make sure that the 348 EndPointAddress represents an isochronous endpoint. 349 @param MaximumPacketLength Indicates the maximum packet size that the default control 350 transfer endpoint is capable of sending or receiving. For isochronous 351 endpoints, this value is used to reserve the bus time in the schedule, 352 required for the perframe data payloads. The pipe may, on an ongoing basis, 353 actually use less bandwidth than that reserved. 354 @param Data A pointer to the buffer of data that will be transmitted to USB 355 device or received from USB device. asynchronous interrupt pipe is canceled. 356 @param DataLength Specifies the length, in bytes, of the data to be sent to or received 357 from the USB device. 358 @param IsochronousCallback The Callback function.This function is called if the requested 359 isochronous transfer is completed. 360 @param Context Data passed to the IsochronousCallback function. This is 361 an optional parameter and may be NULL. 362 363 @retval EFI_SUCCESS The asynchronous isochronous transfer was completed successfully. 364 @retval EFI_OUT_OF_RESOURCES The asynchronous isochronous could not be completed due to a lack of resources. 365 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 366 367 **/ 368 typedef 369 EFI_STATUS 370 (EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER)( 371 IN EFI_USB_HC_PROTOCOL *This, 372 IN UINT8 DeviceAddress, 373 IN UINT8 EndPointAddress, 374 IN UINT8 MaximumPacketLength, 375 IN OUT VOID *Data, 376 IN UINTN DataLength, 377 IN EFI_ASYNC_USB_TRANSFER_CALLBACK IsochronousCallBack, 378 IN VOID *Context OPTIONAL 379 ); 380 381 /** 382 Retrieves the number of root hub ports. 383 384 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 385 @param PortNumber A pointer to the number of the root hub ports. 386 387 @retval EFI_SUCCESS The port number was retrieved successfully. 388 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve the port number. 389 @retval EFI_INVALID_PARAMETER PortNumber is NULL. 390 391 **/ 392 typedef 393 EFI_STATUS 394 (EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER)( 395 IN EFI_USB_HC_PROTOCOL *This, 396 OUT UINT8 *PortNumber 397 ); 398 399 /** 400 Retrieves the current status of a USB root hub port. 401 402 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 403 @param PortNumber Specifies the root hub port from which the status is to be retrieved. 404 This value is zero based. For example, if a root hub has two ports, 405 then the first port is numbered 0, and the second port is 406 numbered 1. 407 @param PortStatus A pointer to the current port status bits and port status change bits. 408 409 @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber 410 was returned in PortStatus. 411 @retval EFI_INVALID_PARAMETER PortNumber is invalid. 412 413 **/ 414 typedef 415 EFI_STATUS 416 (EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)( 417 IN EFI_USB_HC_PROTOCOL *This, 418 IN UINT8 PortNumber, 419 OUT EFI_USB_PORT_STATUS *PortStatus 420 ); 421 422 /** 423 Sets a feature for the specified root hub port. 424 425 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 426 @param PortNumber Specifies the root hub port from which the status is to be retrieved. 427 This value is zero based. For example, if a root hub has two ports, 428 then the first port is numbered 0, and the second port is 429 numbered 1. 430 @param PortFeature Indicates the feature selector associated with the feature set 431 request. 432 433 @retval EFI_SUCCESS The feature specified by PortFeature was set for the USB 434 root hub port specified by PortNumber. 435 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. 436 437 **/ 438 typedef 439 EFI_STATUS 440 (EFIAPI *EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE)( 441 IN EFI_USB_HC_PROTOCOL *This, 442 IN UINT8 PortNumber, 443 IN EFI_USB_PORT_FEATURE PortFeature 444 ); 445 446 /** 447 Clears a feature for the specified root hub port. 448 449 @param This A pointer to the EFI_USB_HC_PROTOCOL instance. 450 @param PortNumber Specifies the root hub port from which the status is to be retrieved. 451 This value is zero based. For example, if a root hub has two ports, 452 then the first port is numbered 0, and the second port is 453 numbered 1. 454 @param PortFeature Indicates the feature selector associated with the feature clear 455 request. 456 457 @retval EFI_SUCCESS The feature specified by PortFeature was cleared for the USB 458 root hub port specified by PortNumber. 459 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function. 460 461 **/ 462 typedef 463 EFI_STATUS 464 (EFIAPI *EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE)( 465 IN EFI_USB_HC_PROTOCOL *This, 466 IN UINT8 PortNumber, 467 IN EFI_USB_PORT_FEATURE PortFeature 468 ); 469 470 471 /// 472 /// The EFI_USB_HC_PROTOCOL provides USB host controller management, basic data transactions 473 /// over a USB bus, and USB root hub access. A device driver that wishes to manage a USB bus in a 474 /// system retrieves the EFI_USB_HC_PROTOCOL instance that is associated with the USB bus to be 475 /// managed. A device handle for a USB host controller will minimally contain an 476 /// EFI_DEVICE_PATH_PROTOCOL instance, and an EFI_USB_HC_PROTOCOL instance. 477 /// 478 struct _EFI_USB_HC_PROTOCOL { 479 EFI_USB_HC_PROTOCOL_RESET Reset; 480 EFI_USB_HC_PROTOCOL_GET_STATE GetState; 481 EFI_USB_HC_PROTOCOL_SET_STATE SetState; 482 EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER ControlTransfer; 483 EFI_USB_HC_PROTOCOL_BULK_TRANSFER BulkTransfer; 484 EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER AsyncInterruptTransfer; 485 EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER SyncInterruptTransfer; 486 EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER IsochronousTransfer; 487 EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER AsyncIsochronousTransfer; 488 EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber; 489 EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; 490 EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; 491 EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; 492 /// 493 /// The major revision number of the USB host controller. The revision information 494 /// indicates the release of the Universal Serial Bus Specification with which the 495 /// host controller is compliant. 496 /// 497 UINT16 MajorRevision; 498 /// 499 /// The minor revision number of the USB host controller. The revision information 500 /// indicates the release of the Universal Serial Bus Specification with which the 501 /// host controller is compliant. 502 /// 503 UINT16 MinorRevision; 504 }; 505 506 extern EFI_GUID gEfiUsbHcProtocolGuid; 507 508 #endif 509