MdeModulePkg/Include/Ppi/UsbHostController.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) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   9
  10 SPDX-License-Identifier: BSD-2-Clause-Patent
  11
  12 **/
  13
  14 #ifndef _PEI_USB_HOST_CONTROLLER_PPI_H_
  15 #define _PEI_USB_HOST_CONTROLLER_PPI_H_
  16
  17 #include <Protocol/Usb2HostController.h>
  18
  19 ///
  20 /// Global ID for the PEI_USB_HOST_CONTROLLER_PPI.
  21 ///
  22 #define PEI_USB_HOST_CONTROLLER_PPI_GUID \
  23   { \
  24     0x652b38a9, 0x77f4, 0x453f, { 0x89, 0xd5, 0xe7, 0xbd, 0xc3, 0x52, 0xfc, 0x53} \
  25   }
  26
  27 ///
  28 /// Forward declaration for the PEI_USB_HOST_CONTROLLER_PPI.
  29 ///
  30 typedef struct _PEI_USB_HOST_CONTROLLER_PPI PEI_USB_HOST_CONTROLLER_PPI;
  31
  32 /**
  33   Initiate a USB control transfer using a specific USB Host controller on the USB bus.
  34
  35   @param[in]     PeiServices           The pointer to the PEI Services Table.
  36   @param[in]     This                  The pointer to this instance of the
  37                                        PEI_USB_HOST_CONTROLLER_PPI.
  38   @param[in]     DeviceAddress         Represents the address of the target device
  39                                        on the USB.
  40   @param[in]     DeviceSpeed           Indicates device speed.
  41   @param[in]     MaximumPacketLength   Indicates the maximum packet size that the
  42                                        default control transfer
  43                                        endpoint is capable of sending or receiving.
  44   @param[in]     Request               A pointer to the USB device request that
  45                                        will be sent to the USB device.
  46   @param[in]     TransferDirection     Specifies the data direction for the transfer.
  47                                        There are three values available:
  48                                        EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData.
  49   @param[in,out] Data                  A pointer to the buffer of data that will
  50                                        be transmitted to USB device or
  51                                        received from USB device.
  52   @param[in,out] DataLength            On input, indicates the size, in bytes, of
  53                                        the data buffer specified by Data.
  54                                        On output, indicates the amount of data
  55                                        actually transferred.
  56   @param[in]     TimeOut               Indicates the maximum time, in milliseconds,
  57                                        that the transfer is allowed to complete.
  58                                        If Timeout is 0, then the caller must wait for
  59                                        the function to be completed until EFI_SUCCESS
  60                                        or EFI_DEVICE_ERROR is returned.
  61   @param[out]    TransferResult        A pointer to the detailed result information
  62                                        generated by this control transfer.
  63
  64   @retval EFI_DEVICE_ERROR   The control transfer failed due to host controller
  65                              or device error.
  66   @retval EFI_SUCCESS        The control transfer was completed successfully.
  67
  68 **/
  69 typedef
  70 EFI_STATUS
  71 (EFIAPI *PEI_USB_HOST_CONTROLLER_CONTROL_TRANSFER)(
  72   IN EFI_PEI_SERVICES             **PeiServices,
  73   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
  74   IN     UINT8                    DeviceAddress,
  75   IN     UINT8                    DeviceSpeed,
  76   IN     UINT8                    MaximumPacketLength,
  77   IN     USB_DEVICE_REQUEST       *Request,
  78   IN     EFI_USB_DATA_DIRECTION   TransferDirection,
  79   IN OUT VOID                     *Data OPTIONAL,
  80   IN OUT UINTN                    *DataLength OPTIONAL,
  81   IN     UINTN                    TimeOut,
  82   OUT    UINT32                   *TransferResult
  83   );
  84
  85 /**
  86   Initiate a USB bulk transfer using a specific USB Host controller on the USB bus.
  87
  88   @param[in]     PeiServices           The pointer to the PEI Services Table.
  89   @param[in]     This                  The pointer to this instance of the
  90                                        PEI_USB_HOST_CONTROLLER_PPI.
  91   @param[in]     DeviceAddress         Represents the address of the target device
  92                                        on the USB.
  93   @param[in]     EndPointAddress       The combination of an endpoint number and
  94                                        an endpoint direction of the target USB device.
  95   @param[in]     MaximumPacketLength   Indicates the maximum packet size the target
  96                                        endpoint is capable of sending or receiving.
  97   @param[in,out] Data                  Array of pointers to the buffers of data
  98                                        that will be transmitted to USB device or
  99                                        received from USB device.
 100   @param[in,out] DataLength            When input, indicates the size, in bytes, of
 101                                        the data buffers specified by Data. When output,
 102                                        indicates the data size actually transferred.
 103   @param[in,out] DataToggle            A pointer to the data toggle value.
 104   @param[in]     TimeOut               Indicates the maximum time, in milliseconds,
 105                                        in which the transfer is allowed to complete.
 106                                        If Timeout is 0, then the caller must wait for
 107                                        the function to be completed until EFI_SUCCESS
 108                                        or EFI_DEVICE_ERROR is returned.
 109   @param[out]    TransferResult        A pointer to the detailed result information
 110                                        of the bulk transfer.
 111
 112   @retval EFI_SUCCESS           The bulk transfer was completed successfully.
 113   @retval EFI_DEVICE_ERROR      The bulk transfer failed due to host controller or device error.
 114                                 Caller should check TransferResult for detailed error information.
 115
 116 **/
 117 typedef
 118 EFI_STATUS
 119 (EFIAPI *PEI_USB_HOST_CONTROLLER_BULK_TRANSFER)(
 120   IN     EFI_PEI_SERVICES             **PeiServices,
 121   IN     PEI_USB_HOST_CONTROLLER_PPI  *This,
 122   IN     UINT8                        DeviceAddress,
 123   IN     UINT8                        EndPointAddress,
 124   IN     UINT8                        MaximumPacketLength,
 125   IN OUT VOID                         *Data,
 126   IN OUT UINTN                        *DataLength,
 127   IN OUT UINT8                        *DataToggle,
 128   IN     UINTN                        TimeOut,
 129   OUT    UINT32                       *TransferResult
 130   );
 131
 132 /**
 133   Retrieves the number of root hub ports.
 134
 135   @param[in]  PeiServices   The pointer to the PEI Services Table.
 136   @param[in]  This          The pointer to this instance of the
 137                             PEI_USB_HOST_CONTROLLER_PPI.
 138   @param[out] PortNumber    The pointer to the number of the root hub ports.
 139
 140   @retval EFI_SUCCESS           The port number was retrieved successfully.
 141   @retval EFI_DEVICE_ERROR      An error was encountered while attempting to retrieve
 142                                 the port number.
 143   @retval EFI_INVALID_PARAMETER PortNumber is NULL.
 144
 145 **/
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER)(
 149   IN  EFI_PEI_SERVICES             **PeiServices,
 150   IN  PEI_USB_HOST_CONTROLLER_PPI  *This,
 151   OUT UINT8                        *PortNumber
 152   );
 153
 154 /**
 155   Retrieves the current status of a USB root hub port.
 156
 157   @param[in]  PeiServices   The pointer to the PEI Services Table.
 158   @param[in]  This          The pointer to this instance of the
 159                             PEI_USB_HOST_CONTROLLER_PPI.
 160   @param[in]  PortNumber    Specifies the root hub port from which the status is
 161                             to be retrieved.
 162                             This value is zero based.
 163   @param[out] PortStatus    A pointer to the current port status bits and port
 164                             status change bits.
 165
 166   @retval EFI_SUCCESS           The status of the USB root hub port specified by
 167                                 PortNumber was returned in PortStatus.
 168   @retval EFI_INVALID_PARAMETER PortNumber is invalid.
 169
 170 **/
 171 typedef
 172 EFI_STATUS
 173 (EFIAPI *PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS)(
 174   IN  EFI_PEI_SERVICES             **PeiServices,
 175   IN  PEI_USB_HOST_CONTROLLER_PPI  *This,
 176   IN  UINT8                        PortNumber,
 177   OUT EFI_USB_PORT_STATUS          *PortStatus
 178   );
 179
 180 /**
 181   Sets a feature for the specified root hub port.
 182
 183   @param[in] PeiServices   The pointer to the PEI Services Table.
 184   @param[in] This          The pointer to this instance of the
 185                            PEI_USB_HOST_CONTROLLER_PPI.
 186   @param[in] PortNumber    Specifies the root hub port whose feature is requested
 187                            to be set. This value is zero based.
 188   @param[in] PortFeature   Indicates the feature selector associated with the feature
 189                            set request.
 190
 191   @retval EFI_SUCCESS           The feature specified by PortFeature was set for
 192                                 the USB root hub port specified by PortNumber.
 193   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid
 194                                 for this function.
 195
 196 **/
 197 typedef
 198 EFI_STATUS
 199 (EFIAPI *PEI_USB_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE)(
 200   IN EFI_PEI_SERVICES             **PeiServices,
 201   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 202   IN UINT8                        PortNumber,
 203   IN EFI_USB_PORT_FEATURE         PortFeature
 204   );
 205
 206 /**
 207   Clears a feature for the specified root hub port.
 208
 209   @param[in] PeiServices   The pointer to the PEI Services Table.
 210   @param[in] This          The pointer to this instance of the
 211                            PEI_USB_HOST_CONTROLLER_PPI.
 212   @param[in] PortNumber    Specifies the root hub port whose feature is
 213                            requested to be cleared.
 214   @param[in] PortFeature   Indicates the feature selector associated with the
 215                            feature clear request.
 216
 217   @return EFI_SUCCESS             The feature specified by PortFeature was cleared
 218                                   for the USB root hub port specified by PortNumber.
 219   @return EFI_INVALID_PARAMETER   PortNumber is invalid or PortFeature is invalid.
 220   @return EFI_DEVICE_ERROR        Can't read the register.
 221
 222 **/
 223 typedef
 224 EFI_STATUS
 225 (EFIAPI *PEI_USB_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE)(
 226   IN EFI_PEI_SERVICES             **PeiServices,
 227   IN PEI_USB_HOST_CONTROLLER_PPI  *This,
 228   IN UINT8                        PortNumber,
 229   IN EFI_USB_PORT_FEATURE         PortFeature
 230   );
 231
 232 ///
 233 /// This PPI contains a set of services to interact with the USB host controller.
 234 /// These interfaces are modeled on the UEFI 2.3 specification protocol
 235 /// EFI_USB2_HOST_CONTROLLER_PROTOCOL.  Refer to section 16.1 of the UEFI 2.3
 236 /// Specification for more information on these interfaces.
 237 ///
 238 struct _PEI_USB_HOST_CONTROLLER_PPI {
 239   PEI_USB_HOST_CONTROLLER_CONTROL_TRANSFER            ControlTransfer;
 240   PEI_USB_HOST_CONTROLLER_BULK_TRANSFER               BulkTransfer;
 241   PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER     GetRootHubPortNumber;
 242   PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS     GetRootHubPortStatus;
 243   PEI_USB_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE    SetRootHubPortFeature;
 244   PEI_USB_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE  ClearRootHubPortFeature;
 245 };
 246
 247 extern EFI_GUID gPeiUsbHostControllerPpiGuid;
 248
 249 #endif
 250