Tools/Source/TianoTools/Include/Protocol/UsbHostController.h

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