MdeModulePkg/Include/Ppi/Usb2HostController.h

   1 /** @file
   2   Defines the USB Host Controller PPI that provides I/O services for a USB Host
   3   Controller that may be used to access recovery devices.  These interfaces are
   4   modeled on the UEFI 2.3 specification EFI_USB2_HOST_CONTROLLER_PROTOCOL.
   5   Refer to section 16.1 of the UEFI 2.3 Specification for more information on
   6   these interfaces.
   7
   8 Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved. <BR>
   9
  10 This program and the accompanying materials
  11 are licensed and made available under the terms and conditions
  12 of the BSD License which accompanies this distribution.  The
  13 full text of the license may be found at
  14 http://opensource.org/licenses/bsd-license.php
  15
  16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  17 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  18
  19 **/
  20
  21 #ifndef _PEI_USB2_HOST_CONTROLLER_PPI_H_
  22 #define _PEI_USB2_HOST_CONTROLLER_PPI_H_
  23
  24 #include <Protocol/Usb2HostController.h>
  25
  26 ///
  27 /// Global ID for the PEI_USB2_HOST_CONTROLLER_PPI.
  28 ///
  29 #define PEI_USB2_HOST_CONTROLLER_PPI_GUID \
  30   { \
  31     0xa7d09fe1, 0x74d4, 0x4ba5, { 0x84, 0x7c, 0x12, 0xed, 0x5b, 0x19, 0xad, 0xe4 } \
  32   }
  33
  34 ///
  35 /// Forward declaration for the PEI_USB2_HOST_CONTROLLER_PPI.
  36 ///
  37 typedef struct _PEI_USB2_HOST_CONTROLLER_PPI PEI_USB2_HOST_CONTROLLER_PPI;
  38
  39 /**
  40   Initiate a USB control transfer using a specific USB Host controller on the USB bus.
  41
  42   @param[in]     PeiServices           The pointer to the PEI Services Table.
  43   @param[in]     This                  The pointer to this instance of the
  44                                        PEI_USB2_HOST_CONTROLLER_PPI.
  45   @param[in]     DeviceAddress         Represents the address of the target device
  46                                        on the USB.
  47   @param[in]     DeviceSpeed           Indicates device speed.
  48   @param[in]     MaximumPacketLength   Indicates the maximum packet size that the
  49                                        default control transfer
  50                                        endpoint is capable of sending or receiving.
  51   @param[in]     Request               A pointer to the USB device request that
  52                                        will be sent to the USB device.
  53   @param[in]     TransferDirection     Specifies the data direction for the transfer.
  54                                        There are three values available:
  55                                        EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData.
  56   @param[in,out] Data                  A pointer to the buffer of data that will
  57                                        be transmitted to USB device or
  58                                        received from USB device.
  59   @param[in,out] DataLength            On input, indicates the size, in bytes, of
  60                                        the data buffer specified by Data.
  61                                        On output, indicates the amount of data
  62                                        actually transferred.
  63   @param[in]     TimeOut               Indicates the maximum time, in milliseconds,
  64                                        that the transfer is allowed to complete.
  65                                        If Timeout is 0, then the caller must wait for
  66                                        the function to be completed until EFI_SUCCESS
  67                                        or EFI_DEVICE_ERROR is returned.
  68   @param[in]     Translator            A pointer to the transaction translator data.
  69   @param[out]    TransferResult        A pointer to the detailed result information
  70                                        generated by this control transfer.
  71
  72   @retval EFI_SUCCESS           The control transfer was completed successfully.
  73   @retval EFI_DEVICE_ERROR      The control transfer failed due to host controller
  74                                 or device error.
  75   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
  76   @retval EFI_OUT_OF_RESOURCES  The control transfer could not be completed due to a lack of resources.
  77   @retval EFI_TIMEOUT           The control transfer failed due to timeout.
  78
  79
  80 **/
  81 typedef
  82 EFI_STATUS
  83 (EFIAPI *PEI_USB2_HOST_CONTROLLER_CONTROL_TRANSFER)(
  84   IN EFI_PEI_SERVICES                         **PeiServices,
  85   IN PEI_USB2_HOST_CONTROLLER_PPI             *This,
  86   IN     UINT8                                DeviceAddress,
  87   IN     UINT8                                DeviceSpeed,
  88   IN     UINTN                                MaximumPacketLength,
  89   IN     USB_DEVICE_REQUEST                   *Request,
  90   IN     EFI_USB_DATA_DIRECTION               TransferDirection,
  91   IN OUT VOID                                 *Data OPTIONAL,
  92   IN OUT UINTN                                *DataLength OPTIONAL,
  93   IN     UINTN                                TimeOut,
  94   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR   *Translator,
  95   OUT    UINT32                               *TransferResult
  96   );
  97
  98 /**
  99   Initiate a USB bulk transfer using a specific USB Host controller on the USB bus.
 100
 101   @param[in]     PeiServices           The pointer to the PEI Services Table.
 102   @param[in]     This                  The pointer to this instance of the
 103                                        PEI_USB2_HOST_CONTROLLER_PPI.
 104   @param[in]     DeviceAddress         Represents the address of the target device
 105                                        on the USB.
 106   @param[in]     EndPointAddress       The combination of an endpoint number and
 107                                        an endpoint direction of the target USB device.
 108   @param[in]     DeviceSpeed           Indicates device speed.
 109   @param[in]     MaximumPacketLength   Indicates the maximum packet size the target
 110                                        endpoint is capable of sending or receiving.
 111   @param[in,out] Data                  Array of pointers to the buffers of data
 112                                        that will be transmitted to USB device or
 113                                        received from USB device.
 114   @param[in,out] DataLength            When input, indicates the size, in bytes, of
 115                                        the data buffers specified by Data. When output,
 116                                        indicates the data size actually transferred.
 117   @param[in,out] DataToggle            A pointer to the data toggle value.
 118   @param[in]     TimeOut               Indicates the maximum time, in milliseconds,
 119                                        in which the transfer is allowed to complete.
 120                                        If Timeout is 0, then the caller must wait for
 121                                        the function to be completed until EFI_SUCCESS
 122                                        or EFI_DEVICE_ERROR is returned.
 123   @param[in]     Translator            A pointer to the transaction translator data.
 124   @param[out]    TransferResult        A pointer to the detailed result information
 125                                        of the bulk transfer.
 126
 127   @retval EFI_SUCCESS           The bulk transfer was completed successfully.
 128   @retval EFI_DEVICE_ERROR      The bulk transfer failed due to host controller or device error.
 129                                 Caller should check TransferResult for detailed error information.
 130   @retval EFI_INVALID_PARAMETER Some parameters are invalid.
 131   @retval EFI_OUT_OF_RESOURCES  The bulk transfer could not be submitted due to a lack of resources.
 132   @retval EFI_TIMEOUT           The bulk transfer failed due to timeout.
 133
 134
 135 **/
 136 typedef
 137 EFI_STATUS
 138 (EFIAPI *PEI_USB2_HOST_CONTROLLER_BULK_TRANSFER)(
 139   IN     EFI_PEI_SERVICES                    **PeiServices,
 140   IN     PEI_USB2_HOST_CONTROLLER_PPI        *This,
 141   IN     UINT8                               DeviceAddress,
 142   IN     UINT8                               EndPointAddress,
 143   IN     UINT8                               DeviceSpeed,
 144   IN     UINTN                               MaximumPacketLength,
 145   IN OUT VOID                                *Data[EFI_USB_MAX_BULK_BUFFER_NUM],
 146   IN OUT UINTN                               *DataLength,
 147   IN OUT UINT8                               *DataToggle,
 148   IN     UINTN                               TimeOut,
 149   IN     EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Translator,
 150   OUT    UINT32                              *TransferResult
 151   );
 152
 153 /**
 154   Retrieves the number of root hub ports.
 155
 156   @param[in]  PeiServices       The pointer to the PEI Services Table.
 157   @param[in]  This              The pointer to this instance of the
 158                                 PEI_USB2_HOST_CONTROLLER_PPI.
 159   @param[out] PortNumber        The pointer to the number of the root hub ports.
 160
 161   @retval EFI_SUCCESS           The port number was retrieved successfully.
 162   @retval EFI_INVALID_PARAMETER PortNumber is NULL.
 163
 164 **/
 165 typedef
 166 EFI_STATUS
 167 (EFIAPI *PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER)(
 168   IN  EFI_PEI_SERVICES              **PeiServices,
 169   IN  PEI_USB2_HOST_CONTROLLER_PPI  *This,
 170   OUT UINT8                         *PortNumber
 171   );
 172
 173 /**
 174   Retrieves the current status of a USB root hub port.
 175
 176   @param[in]  PeiServices       The pointer to the PEI Services Table.
 177   @param[in]  This              The pointer to this instance of the
 178                                 PEI_USB2_HOST_CONTROLLER_PPI.
 179   @param[in]  PortNumber        Specifies the root hub port from which the status is
 180                                 to be retrieved.
 181                                 This value is zero based.
 182   @param[out] PortStatus        A pointer to the current port status bits and port
 183                                 status change bits.
 184
 185   @retval EFI_SUCCESS           The status of the USB root hub port specified by
 186                                 PortNumber was returned in PortStatus.
 187   @retval EFI_INVALID_PARAMETER PortNumber is invalid.
 188
 189 **/
 190 typedef
 191 EFI_STATUS
 192 (EFIAPI *PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS)(
 193   IN  EFI_PEI_SERVICES              **PeiServices,
 194   IN  PEI_USB2_HOST_CONTROLLER_PPI  *This,
 195   IN  UINT8                         PortNumber,
 196   OUT EFI_USB_PORT_STATUS           *PortStatus
 197   );
 198
 199 /**
 200   Sets a feature for the specified root hub port.
 201
 202   @param[in] PeiServices        The pointer to the PEI Services Table.
 203   @param[in] This               The pointer to this instance of the
 204                                 PEI_USB2_HOST_CONTROLLER_PPI.
 205   @param[in] PortNumber         Specifies the root hub port whose feature is requested
 206                                 to be set. This value is zero based.
 207   @param[in] PortFeature        Indicates the feature selector associated with the feature
 208                                 set request.
 209
 210   @retval EFI_SUCCESS           The feature specified by PortFeature was set for
 211                                 the USB root hub port specified by PortNumber.
 212   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid
 213                                 for this function.
 214   @retval EFI_TIMEOUT           The time out occurred
 215
 216 **/
 217 typedef
 218 EFI_STATUS
 219 (EFIAPI *PEI_USB2_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE)(
 220   IN EFI_PEI_SERVICES               **PeiServices,
 221   IN PEI_USB2_HOST_CONTROLLER_PPI   *This,
 222   IN UINT8                          PortNumber,
 223   IN EFI_USB_PORT_FEATURE           PortFeature
 224   );
 225
 226 /**
 227   Clears a feature for the specified root hub port.
 228
 229   @param[in] PeiServices          The pointer to the PEI Services Table.
 230   @param[in] This                 The pointer to this instance of the
 231                                   PEI_USB2_HOST_CONTROLLER_PPI.
 232   @param[in] PortNumber           Specifies the root hub port whose feature is
 233                                   requested to be cleared.
 234   @param[in] PortFeature          Indicates the feature selector associated with the
 235                                   feature clear request.
 236
 237   @return EFI_SUCCESS             The feature specified by PortFeature was cleared
 238                                   for the USB root hub port specified by PortNumber.
 239   @return EFI_INVALID_PARAMETER   PortNumber is invalid or PortFeature is invalid.
 240
 241 **/
 242 typedef
 243 EFI_STATUS
 244 (EFIAPI *PEI_USB2_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE)(
 245   IN EFI_PEI_SERVICES               **PeiServices,
 246   IN PEI_USB2_HOST_CONTROLLER_PPI   *This,
 247   IN UINT8                          PortNumber,
 248   IN EFI_USB_PORT_FEATURE           PortFeature
 249   );
 250
 251 ///
 252 /// This PPI contains a set of services to interact with the USB host controller.
 253 /// These interfaces are modeled on the UEFI 2.3 specification protocol
 254 /// EFI_USB2_HOST_CONTROLLER_PROTOCOL.  Refer to section 16.1 of the UEFI 2.3
 255 /// Specification for more information on these interfaces.
 256 ///
 257 struct _PEI_USB2_HOST_CONTROLLER_PPI {
 258   PEI_USB2_HOST_CONTROLLER_CONTROL_TRANSFER            ControlTransfer;
 259   PEI_USB2_HOST_CONTROLLER_BULK_TRANSFER               BulkTransfer;
 260   PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER     GetRootHubPortNumber;
 261   PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS     GetRootHubPortStatus;
 262   PEI_USB2_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE    SetRootHubPortFeature;
 263   PEI_USB2_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE  ClearRootHubPortFeature;
 264 };
 265
 266 extern EFI_GUID gPeiUsb2HostControllerPpiGuid;
 267
 268 #endif
 269