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