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