iPXE
Usb2HostController.h
Go to the documentation of this file.
00001 /** @file
00002   EFI_USB2_HC_PROTOCOL as defined in UEFI 2.0.
00003   The USB Host Controller Protocol is used by code, typically USB bus drivers,
00004   running in the EFI boot services environment, to perform data transactions over
00005   a USB bus. In addition, it provides an abstraction for the root hub of the USB bus.
00006 
00007   Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>
00008   This program and the accompanying materials
00009   are licensed and made available under the terms and conditions of the BSD License
00010   which accompanies this distribution.  The full text of the license may be found at
00011   http://opensource.org/licenses/bsd-license.php
00012 
00013   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00014   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00015 
00016 **/
00017 
00018 #ifndef _USB2_HOSTCONTROLLER_H_
00019 #define _USB2_HOSTCONTROLLER_H_
00020 
00021 FILE_LICENCE ( BSD3 );
00022 
00023 #include <ipxe/efi/Protocol/UsbIo.h>
00024 
00025 #define EFI_USB2_HC_PROTOCOL_GUID \
00026   { \
00027     0x3e745226, 0x9818, 0x45b6, {0xa2, 0xac, 0xd7, 0xcd, 0xe, 0x8b, 0xa2, 0xbc } \
00028   }
00029 
00030 ///
00031 /// Forward reference for pure ANSI compatability
00032 ///
00033 typedef struct _EFI_USB2_HC_PROTOCOL EFI_USB2_HC_PROTOCOL;
00034 
00035 
00036 typedef struct {
00037   UINT16          PortStatus;        ///< Contains current port status bitmap.
00038   UINT16          PortChangeStatus;  ///< Contains current port status change bitmap.
00039 } EFI_USB_PORT_STATUS;
00040 
00041 ///
00042 /// EFI_USB_PORT_STATUS.PortStatus bit definition
00043 ///
00044 #define USB_PORT_STAT_CONNECTION    0x0001
00045 #define USB_PORT_STAT_ENABLE        0x0002
00046 #define USB_PORT_STAT_SUSPEND       0x0004
00047 #define USB_PORT_STAT_OVERCURRENT   0x0008
00048 #define USB_PORT_STAT_RESET         0x0010
00049 #define USB_PORT_STAT_POWER         0x0100
00050 #define USB_PORT_STAT_LOW_SPEED     0x0200
00051 #define USB_PORT_STAT_HIGH_SPEED    0x0400
00052 #define USB_PORT_STAT_SUPER_SPEED   0x0800
00053 #define USB_PORT_STAT_OWNER         0x2000
00054 
00055 ///
00056 /// EFI_USB_PORT_STATUS.PortChangeStatus bit definition
00057 ///
00058 #define USB_PORT_STAT_C_CONNECTION  0x0001
00059 #define USB_PORT_STAT_C_ENABLE      0x0002
00060 #define USB_PORT_STAT_C_SUSPEND     0x0004
00061 #define USB_PORT_STAT_C_OVERCURRENT 0x0008
00062 #define USB_PORT_STAT_C_RESET       0x0010
00063 
00064 
00065 ///
00066 /// Usb port features value
00067 /// Each value indicates its bit index in the port status and status change bitmaps,
00068 /// if combines these two bitmaps into a 32-bit bitmap.
00069 ///
00070 typedef enum {
00071   EfiUsbPortEnable            = 1,
00072   EfiUsbPortSuspend           = 2,
00073   EfiUsbPortReset             = 4,
00074   EfiUsbPortPower             = 8,
00075   EfiUsbPortOwner             = 13,
00076   EfiUsbPortConnectChange     = 16,
00077   EfiUsbPortEnableChange      = 17,
00078   EfiUsbPortSuspendChange     = 18,
00079   EfiUsbPortOverCurrentChange = 19,
00080   EfiUsbPortResetChange       = 20
00081 } EFI_USB_PORT_FEATURE;
00082 
00083 #define EFI_USB_SPEED_FULL      0x0000  ///< 12 Mb/s, USB 1.1 OHCI and UHCI HC.
00084 #define EFI_USB_SPEED_LOW       0x0001  ///< 1 Mb/s, USB 1.1 OHCI and UHCI HC.
00085 #define EFI_USB_SPEED_HIGH      0x0002  ///< 480 Mb/s, USB 2.0 EHCI HC.
00086 #define EFI_USB_SPEED_SUPER     0x0003  ///< 4.8 Gb/s, USB 3.0 XHCI HC.
00087 
00088 typedef struct {
00089   UINT8      TranslatorHubAddress; ///< device address
00090   UINT8      TranslatorPortNumber; ///< the port number of the hub that device is connected to.
00091 } EFI_USB2_HC_TRANSACTION_TRANSLATOR;
00092 
00093 //
00094 // Protocol definitions
00095 //
00096 
00097 /**
00098   Retrieves the Host Controller capabilities.
00099 
00100   @param  This           A pointer to the EFI_USB2_HC_PROTOCOL instance.
00101   @param  MaxSpeed       Host controller data transfer speed.
00102   @param  PortNumber     Number of the root hub ports.
00103   @param  Is64BitCapable TRUE if controller supports 64-bit memory addressing,
00104                          FALSE otherwise.
00105 
00106   @retval EFI_SUCCESS           The host controller capabilities were retrieved successfully.
00107   @retval EFI_INVALID_PARAMETER One of the input args was NULL.
00108   @retval EFI_DEVICE_ERROR      An error was encountered while attempting to
00109                                 retrieve the capabilities.
00110 
00111 **/
00112 typedef
00113 EFI_STATUS
00114 (EFIAPI *EFI_USB2_HC_PROTOCOL_GET_CAPABILITY)(
00115   IN  EFI_USB2_HC_PROTOCOL  *This,
00116   OUT UINT8                 *MaxSpeed,
00117   OUT UINT8                 *PortNumber,
00118   OUT UINT8                 *Is64BitCapable
00119   );
00120 
00121 #define EFI_USB_HC_RESET_GLOBAL             0x0001
00122 #define EFI_USB_HC_RESET_HOST_CONTROLLER    0x0002
00123 #define EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG  0x0004
00124 #define EFI_USB_HC_RESET_HOST_WITH_DEBUG    0x0008
00125 /**
00126   Provides software reset for the USB host controller.
00127 
00128   @param  This       A pointer to the EFI_USB2_HC_PROTOCOL instance.
00129   @param  Attributes A bit mask of the reset operation to perform.
00130 
00131   @retval EFI_SUCCESS           The reset operation succeeded.
00132   @retval EFI_INVALID_PARAMETER Attributes is not valid.
00133   @retval EFI_UNSUPPORTED       The type of reset specified by Attributes is not currently
00134                                 supported by the host controller hardware.
00135   @retval EFI_ACCESS_DENIED     Reset operation is rejected due to the debug port being configured
00136                                 and active; only EFI_USB_HC_RESET_GLOBAL_WITH_DEBUG or
00137                                 EFI_USB_HC_RESET_HOST_WITH_DEBUG reset Attributes can be used to
00138                                 perform reset operation for this host controller.
00139   @retval EFI_DEVICE_ERROR      An error was encountered while attempting to
00140                                 retrieve the capabilities.
00141 
00142 **/
00143 typedef
00144 EFI_STATUS
00145 (EFIAPI *EFI_USB2_HC_PROTOCOL_RESET)(
00146   IN EFI_USB2_HC_PROTOCOL   *This,
00147   IN UINT16                 Attributes
00148   );
00149 
00150 /**
00151   Enumration value for status of USB HC.
00152 **/
00153 typedef enum {
00154   EfiUsbHcStateHalt,                ///< The host controller is in halt
00155                                     ///< state. No USB transactions can occur
00156                                     ///< while in this state. The host
00157                                     ///< controller can enter this state for
00158                                     ///< three reasons: 1) After host
00159                                     ///< controller hardware reset. 2)
00160                                     ///< Explicitly set by software. 3)
00161                                     ///< Triggered by a fatal error such as
00162                                     ///< consistency check failure.
00163 
00164   EfiUsbHcStateOperational,         ///< The host controller is in an
00165                                     ///< operational state. When in
00166                                     ///< this state, the host
00167                                     ///< controller can execute bus
00168                                     ///< traffic. This state must be
00169                                     ///< explicitly set to enable the
00170                                     ///< USB bus traffic.
00171 
00172   EfiUsbHcStateSuspend,             ///< The host controller is in the
00173                                     ///< suspend state. No USB
00174                                     ///< transactions can occur while in
00175                                     ///< this state. The host controller
00176                                     ///< enters this state for the
00177                                     ///< following reasons: 1) Explicitly
00178                                     ///< set by software. 2) Triggered
00179                                     ///< when there is no bus traffic for
00180                                     ///< 3 microseconds.
00181 
00182   EfiUsbHcStateMaximum              ///< Maximum value for enumration value of HC status.
00183 } EFI_USB_HC_STATE;
00184 
00185 /**
00186   Retrieves current state of the USB host controller.
00187 
00188   @param  This  A pointer to the EFI_USB2_HC_PROTOCOL instance.
00189   @param  State A pointer to the EFI_USB_HC_STATE data structure that
00190                 indicates current state of the USB host controller.
00191 
00192   @retval EFI_SUCCESS           The state information of the host controller was returned in State.
00193   @retval EFI_INVALID_PARAMETER State is NULL.
00194   @retval EFI_DEVICE_ERROR      An error was encountered while attempting to retrieve the
00195                                 host controller's current state.
00196 
00197 **/
00198 typedef
00199 EFI_STATUS
00200 (EFIAPI *EFI_USB2_HC_PROTOCOL_GET_STATE)(
00201   IN        EFI_USB2_HC_PROTOCOL    *This,
00202   OUT       EFI_USB_HC_STATE        *State
00203 );
00204 
00205 /**
00206   Sets the USB host controller to a specific state.
00207 
00208   @param  This  A pointer to the EFI_USB2_HC_PROTOCOL instance.
00209   @param  State Indicates the state of the host controller that will be set.
00210 
00211   @retval EFI_SUCCESS           The USB host controller was successfully placed in the state
00212                                 specified by State.
00213   @retval EFI_INVALID_PARAMETER State is not valid.
00214   @retval EFI_DEVICE_ERROR      Failed to set the state specified by State due to device error.
00215 
00216 **/
00217 typedef
00218 EFI_STATUS
00219 (EFIAPI *EFI_USB2_HC_PROTOCOL_SET_STATE)(
00220   IN EFI_USB2_HC_PROTOCOL    *This,
00221   IN EFI_USB_HC_STATE        State
00222   );
00223 
00224 /**
00225   Submits control transfer to a target USB device.
00226 
00227   @param  This                A pointer to the EFI_USB2_HC_PROTOCOL instance.
00228   @param  DeviceAddress       Represents the address of the target device on the USB.
00229   @param  DeviceSpeed         Indicates device speed.
00230   @param  MaximumPacketLength Indicates the maximum packet size that the default control transfer
00231                               endpoint is capable of sending or receiving.
00232   @param  Request             A pointer to the USB device request that will be sent to the USB device.
00233   @param  TransferDirection   Specifies the data direction for the transfer. There are three values
00234                               available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData.
00235   @param  Data                A pointer to the buffer of data that will be transmitted to USB device or
00236                               received from USB device.
00237   @param  DataLength          On input, indicates the size, in bytes, of the data buffer specified by Data.
00238                               On output, indicates the amount of data actually transferred.
00239   @param  TimeOut             Indicates the maximum time, in milliseconds, which the transfer is
00240                               allowed to complete.
00241   @param  Translator          A pointer to the transaction translator data.
00242   @param  TransferResult      A pointer to the detailed result information generated by this control
00243                               transfer.
00244 
00245   @retval EFI_SUCCESS           The control transfer was completed successfully.
00246   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
00247   @retval EFI_OUT_OF_RESOURCES  The control transfer could not be completed due to a lack of resources.
00248   @retval EFI_TIMEOUT           The control transfer failed due to timeout.
00249   @retval EFI_DEVICE_ERROR      The control transfer failed due to host controller or device error.
00250                                 Caller should check TransferResult for detailed error information.
00251 
00252 **/
00253 typedef
00254 EFI_STATUS
00255 (EFIAPI *EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER)(
00256   IN     EFI_USB2_HC_PROTOCOL               *This,
00257   IN     UINT8                              DeviceAddress,
00258   IN     UINT8                              DeviceSpeed,
00259   IN     UINTN                              MaximumPacketLength,
00260   IN     EFI_USB_DEVICE_REQUEST             *Request,
00261   IN     EFI_USB_DATA_DIRECTION             TransferDirection,
00262   IN OUT VOID                               *Data       OPTIONAL,
00263   IN OUT UINTN                              *DataLength OPTIONAL,
00264   IN     UINTN                              TimeOut,
00265   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
00266   OUT    UINT32                             *TransferResult
00267   );
00268 
00269 #define EFI_USB_MAX_BULK_BUFFER_NUM 10
00270 
00271 /**
00272   Submits bulk transfer to a bulk endpoint of a USB device.
00273 
00274   @param  This                A pointer to the EFI_USB2_HC_PROTOCOL instance.
00275   @param  DeviceAddress       Represents the address of the target device on the USB.
00276   @param  EndPointAddress     The combination of an endpoint number and an endpoint direction of the
00277                               target USB device.
00278   @param  DeviceSpeed         Indicates device speed.
00279   @param  MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of
00280                               sending or receiving.
00281   @param  DataBuffersNumber   Number of data buffers prepared for the transfer.
00282   @param  Data                Array of pointers to the buffers of data that will be transmitted to USB
00283                               device or received from USB device.
00284   @param  DataLength          When input, indicates the size, in bytes, of the data buffers specified by
00285                               Data. When output, indicates the actually transferred data size.
00286   @param  DataToggle          A pointer to the data toggle value.
00287   @param  TimeOut             Indicates the maximum time, in milliseconds, which the transfer is
00288                               allowed to complete.
00289   @param  Translator          A pointer to the transaction translator data.
00290   @param  TransferResult      A pointer to the detailed result information of the bulk transfer.
00291 
00292   @retval EFI_SUCCESS           The bulk transfer was completed successfully.
00293   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
00294   @retval EFI_OUT_OF_RESOURCES  The bulk transfer could not be submitted due to a lack of resources.
00295   @retval EFI_TIMEOUT           The bulk transfer failed due to timeout.
00296   @retval EFI_DEVICE_ERROR      The bulk transfer failed due to host controller or device error.
00297                                 Caller should check TransferResult for detailed error information.
00298 
00299 **/
00300 typedef
00301 EFI_STATUS
00302 (EFIAPI *EFI_USB2_HC_PROTOCOL_BULK_TRANSFER)(
00303   IN     EFI_USB2_HC_PROTOCOL               *This,
00304   IN     UINT8                              DeviceAddress,
00305   IN     UINT8                              EndPointAddress,
00306   IN     UINT8                              DeviceSpeed,
00307   IN     UINTN                              MaximumPacketLength,
00308   IN     UINT8                              DataBuffersNumber,
00309   IN OUT VOID                               *Data[EFI_USB_MAX_BULK_BUFFER_NUM],
00310   IN OUT UINTN                              *DataLength,
00311   IN OUT UINT8                              *DataToggle,
00312   IN     UINTN                              TimeOut,
00313   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
00314   OUT    UINT32                             *TransferResult
00315   );
00316 
00317 /**
00318   Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
00319   Translator parameter doesn't exist in UEFI2.0 spec, but it will be updated in the following specification version.
00320 
00321   @param  This                A pointer to the EFI_USB2_HC_PROTOCOL instance.
00322   @param  DeviceAddress       Represents the address of the target device on the USB.
00323   @param  EndPointAddress     The combination of an endpoint number and an endpoint direction of the
00324                               target USB device.
00325   @param  DeviceSpeed         Indicates device speed.
00326   @param  MaximumPacketLength Indicates the maximum packet size the target endpoint is capable of
00327                               sending or receiving.
00328   @param  IsNewTransfer       If TRUE, an asynchronous interrupt pipe is built between the host and the
00329                               target interrupt endpoint. If FALSE, the specified asynchronous interrupt
00330                               pipe is canceled. If TRUE, and an interrupt transfer exists for the target
00331                               end point, then EFI_INVALID_PARAMETER is returned.
00332   @param  DataToggle          A pointer to the data toggle value.
00333   @param  PollingInterval     Indicates the interval, in milliseconds, that the asynchronous interrupt
00334                               transfer is polled.
00335   @param  DataLength          Indicates the length of data to be received at the rate specified by
00336                               PollingInterval from the target asynchronous interrupt endpoint.
00337   @param  Translator          A pointr to the transaction translator data.
00338   @param  CallBackFunction    The Callback function. This function is called at the rate specified by
00339                               PollingInterval.
00340   @param  Context             The context that is passed to the CallBackFunction. This is an
00341                               optional parameter and may be NULL.
00342 
00343   @retval EFI_SUCCESS           The asynchronous interrupt transfer request has been successfully
00344                                 submitted or canceled.
00345   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
00346   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
00347 
00348 **/
00349 typedef
00350 EFI_STATUS
00351 (EFIAPI *EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER)(
00352   IN     EFI_USB2_HC_PROTOCOL                                *This,
00353   IN     UINT8                                               DeviceAddress,
00354   IN     UINT8                                               EndPointAddress,
00355   IN     UINT8                                               DeviceSpeed,
00356   IN     UINTN                                               MaxiumPacketLength,
00357   IN     BOOLEAN                                             IsNewTransfer,
00358   IN OUT UINT8                                               *DataToggle,
00359   IN     UINTN                                               PollingInterval  OPTIONAL,
00360   IN     UINTN                                               DataLength       OPTIONAL,
00361   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR                  *Translator      OPTIONAL,
00362   IN     EFI_ASYNC_USB_TRANSFER_CALLBACK                     CallBackFunction OPTIONAL,
00363   IN     VOID                                                *Context         OPTIONAL
00364   );
00365 
00366 /**
00367   Submits synchronous interrupt transfer to an interrupt endpoint of a USB device.
00368   Translator parameter doesn't exist in UEFI2.0 spec, but it will be updated in the following specification version.
00369 
00370   @param  This                  A pointer to the EFI_USB2_HC_PROTOCOL instance.
00371   @param  DeviceAddress         Represents the address of the target device on the USB.
00372   @param  EndPointAddress       The combination of an endpoint number and an endpoint direction of the
00373                                 target USB device.
00374   @param  DeviceSpeed           Indicates device speed.
00375   @param  MaximumPacketLength   Indicates the maximum packet size the target endpoint is capable of
00376                                 sending or receiving.
00377   @param  Data                  A pointer to the buffer of data that will be transmitted to USB device or
00378                                 received from USB device.
00379   @param  DataLength            On input, the size, in bytes, of the data buffer specified by Data. On
00380                                 output, the number of bytes transferred.
00381   @param  DataToggle            A pointer to the data toggle value.
00382   @param  TimeOut               Indicates the maximum time, in milliseconds, which the transfer is
00383                                 allowed to complete.
00384   @param  Translator            A pointr to the transaction translator data.
00385   @param  TransferResult        A pointer to the detailed result information from the synchronous
00386                                 interrupt transfer.
00387 
00388   @retval EFI_SUCCESS           The synchronous interrupt transfer was completed successfully.
00389   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
00390   @retval EFI_OUT_OF_RESOURCES  The synchronous interrupt transfer could not be submitted due to a lack of resources.
00391   @retval EFI_TIMEOUT           The synchronous interrupt transfer failed due to timeout.
00392   @retval EFI_DEVICE_ERROR      The synchronous interrupt transfer failed due to host controller or device error.
00393                                 Caller should check TransferResult for detailed error information.
00394 
00395 **/
00396 typedef
00397 EFI_STATUS
00398 (EFIAPI *EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER)(
00399   IN     EFI_USB2_HC_PROTOCOL                        *This,
00400   IN     UINT8                                       DeviceAddress,
00401   IN     UINT8                                       EndPointAddress,
00402   IN     UINT8                                       DeviceSpeed,
00403   IN     UINTN                                       MaximumPacketLength,
00404   IN OUT VOID                                        *Data,
00405   IN OUT UINTN                                       *DataLength,
00406   IN OUT UINT8                                       *DataToggle,
00407   IN     UINTN                                       TimeOut,
00408   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR          *Translator,
00409   OUT    UINT32                                      *TransferResult
00410   );
00411 
00412 #define EFI_USB_MAX_ISO_BUFFER_NUM  7
00413 #define EFI_USB_MAX_ISO_BUFFER_NUM1 2
00414 
00415 /**
00416   Submits isochronous transfer to an isochronous endpoint of a USB device.
00417 
00418   This function is used to submit isochronous transfer to a target endpoint of a USB device.
00419   The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers are
00420   used when working with isochronous date. It provides periodic, continuous communication between
00421   the host and a device. Isochronous transfers can beused only by full-speed, high-speed, and
00422   super-speed devices.
00423 
00424   High-speed isochronous transfers can be performed using multiple data buffers. The number of
00425   buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For
00426   full-speed isochronous transfers this value is ignored.
00427 
00428   Data represents a list of pointers to the data buffers. For full-speed isochronous transfers
00429   only the data pointed by Data[0]shall be used. For high-speed isochronous transfers and for
00430   the split transactions depending on DataLengththere several data buffers canbe used. For the
00431   high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM.
00432 
00433   For split transactions performed on full-speed device by high-speed host controller the total
00434   number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1.
00435   If the isochronous transfer is successful, then EFI_SUCCESSis returned. The isochronous transfer
00436   is designed to be completed within one USB frame time, if it cannot be completed, EFI_TIMEOUT
00437   is returned. If an error other than timeout occurs during the USB transfer, then EFI_DEVICE_ERROR
00438   is returned and the detailed status code will be returned in TransferResult.
00439 
00440   EFI_INVALID_PARAMETERis returned if one of the following conditionsis satisfied:
00441     - Data is NULL.
00442     - DataLength is 0.
00443     - DeviceSpeed is not one of the supported values listed above.
00444     - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed devices,
00445       and 1024 or less for high-speed and super-speed devices.
00446     - TransferResult is NULL.
00447 
00448   @param  This                  A pointer to the EFI_USB2_HC_PROTOCOL instance.
00449   @param  DeviceAddress         Represents the address of the target device on the USB.
00450   @param  EndPointAddress       The combination of an endpoint number and an endpoint direction of the
00451                                 target USB device.
00452   @param  DeviceSpeed           Indicates device speed. The supported values are EFI_USB_SPEED_FULL,
00453                                 EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER.
00454   @param  MaximumPacketLength   Indicates the maximum packet size the target endpoint is capable of
00455                                 sending or receiving.
00456   @param  DataBuffersNumber     Number of data buffers prepared for the transfer.
00457   @param  Data                  Array of pointers to the buffers of data that will be transmitted to USB
00458                                 device or received from USB device.
00459   @param  DataLength            Specifies the length, in bytes, of the data to be sent to or received from
00460                                 the USB device.
00461   @param  Translator            A pointer to the transaction translator data.
00462   @param  TransferResult        A pointer to the detailed result information of the isochronous transfer.
00463 
00464   @retval EFI_SUCCESS           The isochronous transfer was completed successfully.
00465   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
00466   @retval EFI_OUT_OF_RESOURCES  The isochronous transfer could not be submitted due to a lack of resources.
00467   @retval EFI_TIMEOUT           The isochronous transfer cannot be completed within the one USB frame time.
00468   @retval EFI_DEVICE_ERROR      The isochronous transfer failed due to host controller or device error.
00469                                 Caller should check TransferResult for detailed error information.
00470 
00471 **/
00472 typedef
00473 EFI_STATUS
00474 (EFIAPI *EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER)(
00475   IN     EFI_USB2_HC_PROTOCOL               *This,
00476   IN     UINT8                              DeviceAddress,
00477   IN     UINT8                              EndPointAddress,
00478   IN     UINT8                              DeviceSpeed,
00479   IN     UINTN                              MaximumPacketLength,
00480   IN     UINT8                              DataBuffersNumber,
00481   IN OUT VOID                               *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
00482   IN     UINTN                              DataLength,
00483   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
00484   OUT    UINT32                             *TransferResult
00485   );
00486 
00487 /**
00488   Submits nonblocking isochronous transfer to an isochronous endpoint of a USB device.
00489 
00490   This is an asynchronous type of USB isochronous transfer. If the caller submits a USB
00491   isochronous transfer request through this function, this function will return immediately.
00492 
00493   When the isochronous transfer completes, the IsochronousCallbackfunction will be triggered,
00494   the caller can know the transfer results. If the transfer is successful, the caller can get
00495   the data received or sent in this callback function.
00496 
00497   The target endpoint is specified by DeviceAddressand EndpointAddress. Isochronous transfers
00498   are used when working with isochronous date. It provides periodic, continuous communication
00499   between the host and a device. Isochronous transfers can be used only by full-speed, high-speed,
00500   and super-speed devices.
00501 
00502   High-speed isochronous transfers can be performed using multiple data buffers. The number of
00503   buffers that are actually prepared for the transfer is specified by DataBuffersNumber. For
00504   full-speed isochronous transfers this value is ignored.
00505 
00506   Data represents a list of pointers to the data buffers. For full-speed isochronous transfers
00507   only the data pointed by Data[0] shall be used. For high-speed isochronous transfers and for
00508   the split transactions depending on DataLength there several data buffers can be used. For
00509   the high-speed isochronous transfers the total number of buffers must not exceed EFI_USB_MAX_ISO_BUFFER_NUM.
00510 
00511   For split transactions performed on full-speed device by high-speed host controller the total
00512   number of buffers is limited to EFI_USB_MAX_ISO_BUFFER_NUM1.
00513 
00514   EFI_INVALID_PARAMETER is returned if one of the following conditionsis satisfied:
00515     - Data is NULL.
00516     - DataLength is 0.
00517     - DeviceSpeed is not one of the supported values listed above.
00518     - MaximumPacketLength is invalid. MaximumPacketLength must be 1023 or less for full-speed
00519       devices and 1024 or less for high-speed and super-speed devices.
00520 
00521   @param  This                  A pointer to the EFI_USB2_HC_PROTOCOL instance.
00522   @param  DeviceAddress         Represents the address of the target device on the USB.
00523   @param  EndPointAddress       The combination of an endpoint number and an endpoint direction of the
00524                                 target USB device.
00525   @param  DeviceSpeed           Indicates device speed. The supported values are EFI_USB_SPEED_FULL,
00526                                 EFI_USB_SPEED_HIGH, or EFI_USB_SPEED_SUPER.
00527   @param  MaximumPacketLength   Indicates the maximum packet size the target endpoint is capable of
00528                                 sending or receiving.
00529   @param  DataBuffersNumber     Number of data buffers prepared for the transfer.
00530   @param  Data                  Array of pointers to the buffers of data that will be transmitted to USB
00531                                 device or received from USB device.
00532   @param  DataLength            Specifies the length, in bytes, of the data to be sent to or received from
00533                                 the USB device.
00534   @param  Translator            A pointer to the transaction translator data.
00535   @param  IsochronousCallback   The Callback function. This function is called if the requested
00536                                 isochronous transfer is completed.
00537   @param  Context               Data passed to the IsochronousCallback function. This is an
00538                                 optional parameter and may be NULL.
00539 
00540   @retval EFI_SUCCESS           The asynchronous isochronous transfer request has been successfully
00541                                 submitted or canceled.
00542   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
00543   @retval EFI_OUT_OF_RESOURCES  The asynchronous isochronous transfer could not be submitted due to
00544                                 a lack of resources.
00545 
00546 **/
00547 typedef
00548 EFI_STATUS
00549 (EFIAPI *EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER)(
00550   IN     EFI_USB2_HC_PROTOCOL               *This,
00551   IN     UINT8                              DeviceAddress,
00552   IN     UINT8                              EndPointAddress,
00553   IN     UINT8                              DeviceSpeed,
00554   IN     UINTN                              MaximumPacketLength,
00555   IN     UINT8                              DataBuffersNumber,
00556   IN OUT VOID                               *Data[EFI_USB_MAX_ISO_BUFFER_NUM],
00557   IN     UINTN                              DataLength,
00558   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator,
00559   IN     EFI_ASYNC_USB_TRANSFER_CALLBACK    IsochronousCallBack,
00560   IN     VOID                               *Context OPTIONAL
00561   );
00562 
00563 /**
00564   Retrieves the current status of a USB root hub port.
00565 
00566   @param  This       A pointer to the EFI_USB2_HC_PROTOCOL instance.
00567   @param  PortNumber Specifies the root hub port from which the status is to be retrieved.
00568                      This value is zero based.
00569   @param  PortStatus A pointer to the current port status bits and port status change bits.
00570 
00571   @retval EFI_SUCCESS           The status of the USB root hub port specified by PortNumber
00572                                 was returned in PortStatus.
00573   @retval EFI_INVALID_PARAMETER PortNumber is invalid.
00574 
00575 **/
00576 typedef
00577 EFI_STATUS
00578 (EFIAPI *EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS)(
00579   IN        EFI_USB2_HC_PROTOCOL    *This,
00580   IN        UINT8                   PortNumber,
00581   OUT       EFI_USB_PORT_STATUS     *PortStatus
00582   );
00583 
00584 /**
00585   Sets a feature for the specified root hub port.
00586 
00587   @param  This        A pointer to the EFI_USB2_HC_PROTOCOL instance.
00588   @param  PortNumber  Specifies the root hub port whose feature is requested to be set. This
00589                       value is zero based.
00590   @param  PortFeature Indicates the feature selector associated with the feature set request.
00591 
00592   @retval EFI_SUCCESS           The feature specified by PortFeature was set for the USB
00593                                 root hub port specified by PortNumber.
00594   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
00595 
00596 **/
00597 typedef
00598 EFI_STATUS
00599 (EFIAPI *EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE)(
00600   IN EFI_USB2_HC_PROTOCOL    *This,
00601   IN UINT8                   PortNumber,
00602   IN EFI_USB_PORT_FEATURE    PortFeature
00603   );
00604 
00605 /**
00606   Clears a feature for the specified root hub port.
00607 
00608   @param  This        A pointer to the EFI_USB2_HC_PROTOCOL instance.
00609   @param  PortNumber  Specifies the root hub port whose feature is requested to be cleared. This
00610                       value is zero based.
00611   @param  PortFeature Indicates the feature selector associated with the feature clear request.
00612 
00613   @retval EFI_SUCCESS           The feature specified by PortFeature was cleared for the USB
00614                                 root hub port specified by PortNumber.
00615   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid for this function.
00616 
00617 **/
00618 typedef
00619 EFI_STATUS
00620 (EFIAPI *EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE)(
00621   IN EFI_USB2_HC_PROTOCOL    *This,
00622   IN UINT8                   PortNumber,
00623   IN EFI_USB_PORT_FEATURE    PortFeature
00624   );
00625 
00626 ///
00627 /// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic
00628 /// data transactions over a USB bus, and USB root hub access. A device driver
00629 /// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL
00630 /// instance that is associated with the USB bus to be managed. A device handle
00631 /// for a USB host controller will minimally contain an EFI_DEVICE_PATH_PROTOCOL
00632 /// instance, and an EFI_USB2_HC_PROTOCOL instance.
00633 ///
00634 struct _EFI_USB2_HC_PROTOCOL {
00635   EFI_USB2_HC_PROTOCOL_GET_CAPABILITY              GetCapability;
00636   EFI_USB2_HC_PROTOCOL_RESET                       Reset;
00637   EFI_USB2_HC_PROTOCOL_GET_STATE                   GetState;
00638   EFI_USB2_HC_PROTOCOL_SET_STATE                   SetState;
00639   EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER            ControlTransfer;
00640   EFI_USB2_HC_PROTOCOL_BULK_TRANSFER               BulkTransfer;
00641   EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER    AsyncInterruptTransfer;
00642   EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER     SyncInterruptTransfer;
00643   EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER        IsochronousTransfer;
00644   EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER  AsyncIsochronousTransfer;
00645   EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS     GetRootHubPortStatus;
00646   EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE    SetRootHubPortFeature;
00647   EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE  ClearRootHubPortFeature;
00648 
00649   ///
00650   /// The major revision number of the USB host controller. The revision information
00651   /// indicates the release of the Universal Serial Bus Specification with which the
00652   /// host controller is compliant.
00653   ///
00654   UINT16                                           MajorRevision;
00655 
00656   ///
00657   /// The minor revision number of the USB host controller. The revision information
00658   /// indicates the release of the Universal Serial Bus Specification with which the
00659   /// host controller is compliant.
00660   ///
00661   UINT16                                           MinorRevision;
00662 };
00663 
00664 extern EFI_GUID gEfiUsb2HcProtocolGuid;
00665 
00666 #endif