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