MdeModulePkg/Bus/Usb/UsbBusPei/UsbPeim.h

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