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