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