OldMdePkg/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   @param  DataToggle            A pointer to the data toggle value.
 194   @param  PollingInterval       Indicates the interval, in milliseconds, that the asynchronous
 195                                 interrupt transfer is polled.                                                                                                      asynchronous interrupt pipe is canceled.
 196   @param  DataLength            Indicates the length of data to be received at the rate specified by
 197                                 PollingInterval from the target asynchronous interrupt
 198                                 endpoint.
 199   @param  CallBackFunction      The Callback function.
 200   @param  Context               The context that is passed to the CallBackFunction.
 201
 202   @retval EFI_SUCCESS           The asynchronous interrupt transfer request has been successfully
 203                                 submitted or canceled.
 204   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 205   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 206   @retval EFI_TIMEOUT           The bulk transfer failed due to timeout.
 207   @retval EFI_DEVICE_ERROR      The bulk transfer failed due to host controller or device error.
 208
 209 **/
 210 typedef
 211 EFI_STATUS
 212 (EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER) (
 213   IN     EFI_USB_HC_PROTOCOL                                 *This,
 214   IN     UINT8                                               DeviceAddress,
 215   IN     UINT8                                               EndPointAddress,
 216   IN     BOOLEAN                                             IsSlowDevice,
 217   IN     UINT8                                               MaxiumPacketLength,
 218   IN     BOOLEAN                                             IsNewTransfer,
 219   IN OUT UINT8                                               *DataToggle,
 220   IN     UINTN                                               PollingInterval  OPTIONAL,
 221   IN     UINTN                                               DataLength       OPTIONAL,
 222   IN     EFI_ASYNC_USB_TRANSFER_CALLBACK                     CallBackFunction OPTIONAL,
 223   IN     VOID                                                *Context         OPTIONAL
 224   );
 225
 226 /**
 227   Submits synchronous interrupt transfer to an interrupt endpoint of a USB device.
 228
 229   @param  This                  A pointer to the EFI_USB_HC_PROTOCOL instance.
 230   @param  DeviceAddress         Represents the address of the target device on the USB, which is
 231                                 assigned during USB enumeration.
 232   @param  EndPointAddress       The combination of an endpoint number and an endpoint
 233                                 direction of the target USB device.
 234   @param  IsSlowDevice          Indicates whether the target device is slow device or full-speed
 235                                 device.
 236   @param  MaximumPacketLength   Indicates the maximum packet size that the default control
 237                                 transfer endpoint is capable of sending or receiving.
 238   @param  Data                  A pointer to the buffer of data that will be transmitted to USB
 239                                 device or received from USB device.                                                                                            asynchronous interrupt pipe is canceled.
 240   @param  DataLength            On input, the size, in bytes, of the data buffer specified by Data.
 241                                 On output, the number of bytes transferred.
 242   @param  DataToggle            A pointer to the data toggle value.
 243   @param  TimeOut               Indicates the maximum time, in milliseconds, which the transfer
 244                                 is allowed to complete.
 245   @param  TransferResult        A pointer to the detailed result information from the synchronous
 246                                 interrupt transfer.
 247
 248   @retval EFI_SUCCESS           The synchronous interrupt transfer was completed successfully.
 249   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 250   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 251   @retval EFI_TIMEOUT           The synchronous interrupt transfer failed due to timeout.
 252   @retval EFI_DEVICE_ERROR      The synchronous interrupt transfer failed due to host controller or device error.
 253
 254 **/
 255 typedef
 256 EFI_STATUS
 257 (EFIAPI *EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER) (
 258   IN     EFI_USB_HC_PROTOCOL    *This,
 259   IN     UINT8                  DeviceAddress,
 260   IN     UINT8                  EndPointAddress,
 261   IN     BOOLEAN                IsSlowDevice,
 262   IN     UINT8                  MaximumPacketLength,
 263   IN OUT VOID                   *Data,
 264   IN OUT UINTN                  *DataLength,
 265   IN OUT UINT8                  *DataToggle,
 266   IN     UINTN                  TimeOut,
 267   OUT    UINT32                 *TransferResult
 268   );
 269
 270 /**
 271   Submits isochronous transfer to an isochronous endpoint of a USB device.
 272
 273   @param  This                  A pointer to the EFI_USB_HC_PROTOCOL instance.
 274   @param  DeviceAddress         Represents the address of the target device on the USB, which is
 275                                 assigned during USB enumeration.
 276   @param  EndPointAddress       The combination of an endpoint number and an endpoint
 277                                 direction of the target USB device.
 278   @param  MaximumPacketLength   Indicates the maximum packet size that the default control
 279                                 transfer endpoint is capable of sending or receiving.
 280   @param  Data                  A pointer to the buffer of data that will be transmitted to USB
 281                                 device or received from USB device.                                                                                            asynchronous interrupt pipe is canceled.
 282   @param  DataLength            Specifies the length, in bytes, of the data to be sent to or received
 283                                 from the USB device.
 284   @param  TransferResult        A pointer to the detailed result information from the isochronous
 285                                 transfer.
 286
 287   @retval EFI_SUCCESS           The isochronous transfer was completed successfully.
 288   @retval EFI_OUT_OF_RESOURCES  The isochronous could not be completed due to a lack of resources.
 289   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 290   @retval EFI_TIMEOUT           The isochronous transfer failed due to timeout.
 291   @retval EFI_DEVICE_ERROR      The isochronous transfer failed due to host controller or device error.
 292
 293 **/
 294 typedef
 295 EFI_STATUS
 296 (EFIAPI *EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER) (
 297   IN     EFI_USB_HC_PROTOCOL    *This,
 298   IN     UINT8                  DeviceAddress,
 299   IN     UINT8                  EndPointAddress,
 300   IN     UINT8                  MaximumPacketLength,
 301   IN OUT VOID                   *Data,
 302   IN     UINTN                  DataLength,
 303   OUT    UINT32                 *TransferResult
 304   );
 305
 306 /**
 307   Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device.
 308
 309   @param  This                  A pointer to the EFI_USB_HC_PROTOCOL instance.
 310   @param  DeviceAddress         Represents the address of the target device on the USB, which is
 311                                 assigned during USB enumeration.
 312   @param  EndPointAddress       The combination of an endpoint number and an endpoint
 313                                 direction of the target USB device.
 314   @param  MaximumPacketLength   Indicates the maximum packet size that the default control
 315                                 transfer endpoint is capable of sending or receiving.
 316   @param  Data                  A pointer to the buffer of data that will be transmitted to USB
 317                                 device or received from USB device.                                                                                            asynchronous interrupt pipe is canceled.
 318   @param  DataLength            Specifies the length, in bytes, of the data to be sent to or received
 319                                 from the USB device.
 320   @param  IsochronousCallback   The Callback function.
 321   @param  Context               Data passed to the IsochronousCallback function. This is
 322                                 an optional parameter and may be NULL.
 323
 324   @retval EFI_SUCCESS           The asynchronous isochronous transfer was completed successfully.
 325   @retval EFI_OUT_OF_RESOURCES  The asynchronous isochronous could not be completed due to a lack of resources.
 326   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 327
 328 **/
 329 typedef
 330 EFI_STATUS
 331 (EFIAPI *EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER) (
 332   IN     EFI_USB_HC_PROTOCOL                *This,
 333   IN     UINT8                              DeviceAddress,
 334   IN     UINT8                              EndPointAddress,
 335   IN     UINT8                              MaximumPacketLength,
 336   IN OUT VOID                               *Data,
 337   IN     UINTN                              DataLength,
 338   IN     EFI_ASYNC_USB_TRANSFER_CALLBACK    IsochronousCallBack,
 339   IN     VOID                               *Context OPTIONAL
 340   );
 341
 342 /**
 343   Retrieves the number of root hub ports.
 344
 345   @param  This                  A pointer to the EFI_USB_HC_PROTOCOL instance.
 346   @param  PortNumber            A pointer to the number of the root hub ports.
 347
 348   @retval EFI_SUCCESS           The port number was retrieved successfully.
 349   @retval EFI_DEVICE_ERROR      An error was encountered while attempting to retrieve the port number.
 350   @retval EFI_INVALID_PARAMETER PortNumber is NULL.
 351
 352 **/
 353 typedef
 354 EFI_STATUS
 355 (EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER) (
 356   IN EFI_USB_HC_PROTOCOL    *This,
 357   OUT UINT8                 *PortNumber
 358   );
 359
 360 /**
 361   Retrieves the current status of a USB root hub port.
 362
 363   @param  This                  A pointer to the EFI_USB_HC_PROTOCOL instance.
 364   @param  PortNumber            Specifies the root hub port from which the status is to be retrieved.
 365                                 This value is zero based.
 366   @param  PortStatus            A pointer to the current port status bits and port status change bits.
 367
 368   @retval EFI_SUCCESS           The status of the USB root hub port specified by PortNumber
 369                                 was returned in PortStatus.
 370   @retval EFI_INVALID_PARAMETER PortNumber is invalid.
 371
 372 **/
 373 typedef
 374 EFI_STATUS
 375 (EFIAPI *EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS) (
 376   IN EFI_USB_HC_PROTOCOL     *This,
 377   IN  UINT8                  PortNumber,
 378   OUT EFI_USB_PORT_STATUS    *PortStatus
 379   );
 380
 381 /**
 382   Sets a feature for the specified root hub port.
 383
 384   @param  This                  A pointer to the EFI_USB_HC_PROTOCOL instance.
 385   @param  PortNumber            Specifies the root hub port from which the status is to be retrieved.
 386                                 This value is zero based.
 387   @param  PortFeature           Indicates the feature selector associated with the feature set
 388                                 request.
 389
 390   @retval EFI_SUCCESS           The feature specified by PortFeature was set for the USB
 391                                 root hub port specified by PortNumber.
 392   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
 393
 394 **/
 395 typedef
 396 EFI_STATUS
 397 (EFIAPI *EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE) (
 398   IN EFI_USB_HC_PROTOCOL     *This,
 399   IN UINT8                   PortNumber,
 400   IN EFI_USB_PORT_FEATURE    PortFeature
 401   );
 402
 403 /**
 404   Clears a feature for the specified root hub port.
 405
 406   @param  This                  A pointer to the EFI_USB_HC_PROTOCOL instance.
 407   @param  PortNumber            Specifies the root hub port from which the status is to be cleared.
 408                                 This value is zero based.
 409   @param  PortFeature           Indicates the feature selector associated with the feature clear
 410                                 request.
 411
 412   @retval EFI_SUCCESS           The feature specified by PortFeature was cleared for the USB
 413                                 root hub port specified by PortNumber.
 414   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
 415
 416 **/
 417 typedef
 418 EFI_STATUS
 419 (EFIAPI *EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE) (
 420   IN EFI_USB_HC_PROTOCOL     *This,
 421   IN UINT8                   PortNumber,
 422   IN EFI_USB_PORT_FEATURE    PortFeature
 423   );
 424
 425 struct _EFI_USB_HC_PROTOCOL {
 426   EFI_USB_HC_PROTOCOL_RESET                       Reset;
 427   EFI_USB_HC_PROTOCOL_GET_STATE                   GetState;
 428   EFI_USB_HC_PROTOCOL_SET_STATE                   SetState;
 429   EFI_USB_HC_PROTOCOL_CONTROL_TRANSFER            ControlTransfer;
 430   EFI_USB_HC_PROTOCOL_BULK_TRANSFER               BulkTransfer;
 431   EFI_USB_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER    AsyncInterruptTransfer;
 432   EFI_USB_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER     SyncInterruptTransfer;
 433   EFI_USB_HC_PROTOCOL_ISOCHRONOUS_TRANSFER        IsochronousTransfer;
 434   EFI_USB_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER  AsyncIsochronousTransfer;
 435   EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_NUMBER     GetRootHubPortNumber;
 436   EFI_USB_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS     GetRootHubPortStatus;
 437   EFI_USB_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE    SetRootHubPortFeature;
 438   EFI_USB_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE  ClearRootHubPortFeature;
 439   UINT16                                          MajorRevision;
 440   UINT16                                          MinorRevision;
 441 };
 442
 443 extern EFI_GUID gEfiUsbHcProtocolGuid;
 444
 445 #endif