MdeModulePkg/Bus/Usb/UsbBusPei/UsbPeim.h

   1 /** @file
   2 Usb Peim definition.
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved. <BR>
   5
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _PEI_USB_PEIM_H_
  11 #define _PEI_USB_PEIM_H_
  12
  13
  14 #include <PiPei.h>
  15
  16 #include <Ppi/UsbHostController.h>
  17 #include <Ppi/Usb2HostController.h>
  18 #include <Ppi/UsbIo.h>
  19
  20 #include <Library/DebugLib.h>
  21 #include <Library/PeimEntryPoint.h>
  22 #include <Library/PeiServicesLib.h>
  23 #include <Library/BaseMemoryLib.h>
  24 #include <Library/TimerLib.h>
  25 #include <Library/PcdLib.h>
  26
  27 #include <IndustryStandard/Usb.h>
  28
  29 //
  30 // A common header for usb standard descriptor.
  31 // Each stand descriptor has a length and type.
  32 //
  33 #pragma pack(1)
  34 typedef struct {
  35   UINT8                   Len;
  36   UINT8                   Type;
  37 } USB_DESC_HEAD;
  38 #pragma pack()
  39
  40 #define MAX_INTERFACE             8
  41 #define MAX_ENDPOINT              16
  42
  43 #define PEI_USB_DEVICE_SIGNATURE  SIGNATURE_32 ('U', 's', 'b', 'D')
  44 typedef struct {
  45   UINTN                         Signature;
  46   PEI_USB_IO_PPI                UsbIoPpi;
  47   EFI_PEI_PPI_DESCRIPTOR        UsbIoPpiList;
  48   UINT16                        MaxPacketSize0;
  49   UINT16                        DataToggle;
  50   UINT8                         DeviceAddress;
  51   UINT8                         DeviceSpeed;
  52   UINT8                         IsHub;
  53   UINT8                         DownStreamPortNo;
  54   UINTN                         AllocateAddress;
  55   PEI_USB_HOST_CONTROLLER_PPI   *UsbHcPpi;
  56   PEI_USB2_HOST_CONTROLLER_PPI  *Usb2HcPpi;
  57   UINT8                         ConfigurationData[1024];
  58   EFI_USB_CONFIG_DESCRIPTOR     *ConfigDesc;
  59   EFI_USB_INTERFACE_DESCRIPTOR  *InterfaceDesc;
  60   EFI_USB_INTERFACE_DESCRIPTOR  *InterfaceDescList[MAX_INTERFACE];
  61   EFI_USB_ENDPOINT_DESCRIPTOR   *EndpointDesc[MAX_ENDPOINT];
  62   EFI_USB_ENDPOINT_DESCRIPTOR   *EndpointDescList[MAX_INTERFACE][MAX_ENDPOINT];
  63   EFI_USB2_HC_TRANSACTION_TRANSLATOR Translator;
  64   UINT8                          Tier;
  65 } PEI_USB_DEVICE;
  66
  67 #define PEI_USB_DEVICE_FROM_THIS(a) CR (a, PEI_USB_DEVICE, UsbIoPpi, PEI_USB_DEVICE_SIGNATURE)
  68
  69 #define USB_BIT_IS_SET(Data, Bit)   ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
  70
  71 #define USB_BUS_1_MILLISECOND       1000
  72
  73 //
  74 // Wait for port reset, refers to specification
  75 // [USB20-7.1.7.5, it says 10ms for hub and 50ms for
  76 // root hub]
  77 //
  78 // According to USB2.0, Chapter 11.5.1.5 Resetting,
  79 // the worst case for TDRST is 20ms
  80 //
  81 #define USB_SET_PORT_RESET_STALL        (20 * USB_BUS_1_MILLISECOND)
  82 #define USB_SET_ROOT_PORT_RESET_STALL   (50 * USB_BUS_1_MILLISECOND)
  83
  84 //
  85 // Wait for clear roothub port reset, set by experience
  86 //
  87 #define USB_CLR_ROOT_PORT_RESET_STALL   (20 * USB_BUS_1_MILLISECOND)
  88
  89 //
  90 // Wait for port statue reg change, set by experience
  91 //
  92 #define USB_WAIT_PORT_STS_CHANGE_STALL  (100)
  93
  94 //
  95 // Host software return timeout if port status doesn't change
  96 // after 500ms(LOOP * STALL = 5000 * 0.1ms), set by experience
  97 //
  98 #define USB_WAIT_PORT_STS_CHANGE_LOOP   5000
  99
 100 //
 101 // Wait for hub port power-on, refers to specification
 102 // [USB20-11.23.2]
 103 //
 104 #define USB_SET_PORT_POWER_STALL        (2 * USB_BUS_1_MILLISECOND)
 105
 106 //
 107 // Wait for set device address, refers to specification
 108 // [USB20-9.2.6.3, it says 2ms]
 109 //
 110 #define USB_SET_DEVICE_ADDRESS_STALL    (2 * USB_BUS_1_MILLISECOND)
 111
 112 //
 113 // Wait for get configuration descriptor, set by experience
 114 //
 115 #define USB_GET_CONFIG_DESCRIPTOR_STALL (1 * USB_BUS_1_MILLISECOND)
 116
 117 /**
 118   Submits control transfer to a target USB device.
 119
 120   @param  PeiServices            The pointer of EFI_PEI_SERVICES.
 121   @param  This                   The pointer of PEI_USB_IO_PPI.
 122   @param  Request                USB device request to send.
 123   @param  Direction              Specifies the data direction for the data stage.
 124   @param  Timeout                Indicates the maximum timeout, in millisecond. If Timeout
 125                                  is 0, then the caller must wait for the function to be
 126                                  completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 127   @param  Data                   Data buffer to be transmitted or received from USB device.
 128   @param  DataLength             The size (in bytes) of the data buffer.
 129
 130   @retval EFI_SUCCESS            Transfer was completed successfully.
 131   @retval EFI_OUT_OF_RESOURCES   The transfer failed due to lack of resources.
 132   @retval EFI_INVALID_PARAMETER  Some parameters are invalid.
 133   @retval EFI_TIMEOUT            Transfer failed due to timeout.
 134   @retval EFI_DEVICE_ERROR       Transfer failed due to host controller or device error.
 135
 136 **/
 137 EFI_STATUS
 138 EFIAPI
 139 PeiUsbControlTransfer (
 140   IN     EFI_PEI_SERVICES          **PeiServices,
 141   IN     PEI_USB_IO_PPI            *This,
 142   IN     EFI_USB_DEVICE_REQUEST    *Request,
 143   IN     EFI_USB_DATA_DIRECTION    Direction,
 144   IN     UINT32                    Timeout,
 145   IN OUT VOID                      *Data,      OPTIONAL
 146   IN     UINTN                     DataLength  OPTIONAL
 147   );
 148
 149 /**
 150   Submits bulk transfer to a bulk endpoint of a USB device.
 151
 152   @param  PeiServices           The pointer of EFI_PEI_SERVICES.
 153   @param  This                  The pointer of PEI_USB_IO_PPI.
 154   @param  DeviceEndpoint        Endpoint number and its direction in bit 7.
 155   @param  Data                  A pointer to the buffer of data to transmit
 156                                 from or receive into.
 157   @param  DataLength            The lenght of the data buffer.
 158   @param  Timeout               Indicates the maximum time, in millisecond, which the
 159                                 transfer is allowed to complete. If Timeout is 0, then
 160                                 the caller must wait for the function to be completed
 161                                 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 162
 163   @retval EFI_SUCCESS           The transfer was completed successfully.
 164   @retval EFI_OUT_OF_RESOURCES  The transfer failed due to lack of resource.
 165   @retval EFI_INVALID_PARAMETER Parameters are invalid.
 166   @retval EFI_TIMEOUT           The transfer failed due to timeout.
 167   @retval EFI_DEVICE_ERROR      The transfer failed due to host controller error.
 168
 169 **/
 170 EFI_STATUS
 171 EFIAPI
 172 PeiUsbBulkTransfer (
 173   IN     EFI_PEI_SERVICES    **PeiServices,
 174   IN     PEI_USB_IO_PPI      *This,
 175   IN     UINT8               DeviceEndpoint,
 176   IN OUT VOID                *Data,
 177   IN OUT UINTN               *DataLength,
 178   IN     UINTN               Timeout
 179   );
 180
 181 /**
 182   Get the usb interface descriptor.
 183
 184   @param  PeiServices          General-purpose services that are available to every PEIM.
 185   @param  This                 Indicates the PEI_USB_IO_PPI instance.
 186   @param  InterfaceDescriptor  Request interface descriptor.
 187
 188
 189   @retval EFI_SUCCESS          Usb interface descriptor is obtained successfully.
 190
 191 **/
 192 EFI_STATUS
 193 EFIAPI
 194 PeiUsbGetInterfaceDescriptor (
 195   IN  EFI_PEI_SERVICES                **PeiServices,
 196   IN  PEI_USB_IO_PPI                  *This,
 197   OUT EFI_USB_INTERFACE_DESCRIPTOR    **InterfaceDescriptor
 198   );
 199
 200 /**
 201   Get the usb endpoint descriptor.
 202
 203   @param  PeiServices          General-purpose services that are available to every PEIM.
 204   @param  This                 Indicates the PEI_USB_IO_PPI instance.
 205   @param  EndpointIndex        The valid index of the specified endpoint.
 206   @param  EndpointDescriptor   Request endpoint descriptor.
 207
 208   @retval EFI_SUCCESS       Usb endpoint descriptor is obtained successfully.
 209   @retval EFI_NOT_FOUND     Usb endpoint descriptor is NOT found.
 210
 211 **/
 212 EFI_STATUS
 213 EFIAPI
 214 PeiUsbGetEndpointDescriptor (
 215   IN  EFI_PEI_SERVICES               **PeiServices,
 216   IN  PEI_USB_IO_PPI                 *This,
 217   IN  UINT8                          EndpointIndex,
 218   OUT EFI_USB_ENDPOINT_DESCRIPTOR    **EndpointDescriptor
 219   );
 220
 221 /**
 222   Reset the port and re-configure the usb device.
 223
 224   @param  PeiServices    General-purpose services that are available to every PEIM.
 225   @param  This           Indicates the PEI_USB_IO_PPI instance.
 226
 227   @retval EFI_SUCCESS    Usb device is reset and configured successfully.
 228   @retval Others         Other failure occurs.
 229
 230 **/
 231 EFI_STATUS
 232 EFIAPI
 233 PeiUsbPortReset (
 234   IN EFI_PEI_SERVICES    **PeiServices,
 235   IN PEI_USB_IO_PPI      *This
 236   );
 237
 238 /**
 239   Send reset signal over the given root hub port.
 240
 241   @param  PeiServices       Describes the list of possible PEI Services.
 242   @param  UsbHcPpi          The pointer of PEI_USB_HOST_CONTROLLER_PPI instance.
 243   @param  Usb2HcPpi         The pointer of PEI_USB2_HOST_CONTROLLER_PPI instance.
 244   @param  PortNum           The port to be reset.
 245   @param  RetryIndex        The retry times.
 246
 247 **/
 248 VOID
 249 ResetRootPort (
 250   IN EFI_PEI_SERVICES               **PeiServices,
 251   IN PEI_USB_HOST_CONTROLLER_PPI    *UsbHcPpi,
 252   IN PEI_USB2_HOST_CONTROLLER_PPI   *Usb2HcPpi,
 253   IN UINT8                          PortNum,
 254   IN UINT8                          RetryIndex
 255   );
 256
 257 #endif