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 // Wait for set device address, refers to specification
 104 // [USB20-9.2.6.3, it says 2ms]
 105 //
 106 #define USB_SET_DEVICE_ADDRESS_STALL    (2 * USB_BUS_1_MILLISECOND)
 107
 108 //
 109 // Wait for get configuration descriptor, set by experience
 110 //
 111 #define USB_GET_CONFIG_DESCRIPTOR_STALL (1 * USB_BUS_1_MILLISECOND)
 112
 113 /**
 114   Submits control transfer to a target USB device.
 115
 116   @param  PeiServices            The pointer of EFI_PEI_SERVICES.
 117   @param  This                   The pointer of PEI_USB_IO_PPI.
 118   @param  Request                USB device request to send.
 119   @param  Direction              Specifies the data direction for the data stage.
 120   @param  Timeout                Indicates the maximum timeout, in millisecond. If Timeout
 121                                  is 0, then the caller must wait for the function to be
 122                                  completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 123   @param  Data                   Data buffer to be transmitted or received from USB device.
 124   @param  DataLength             The size (in bytes) of the data buffer.
 125
 126   @retval EFI_SUCCESS            Transfer was completed successfully.
 127   @retval EFI_OUT_OF_RESOURCES   The transfer failed due to lack of resources.
 128   @retval EFI_INVALID_PARAMETER  Some parameters are invalid.
 129   @retval EFI_TIMEOUT            Transfer failed due to timeout.
 130   @retval EFI_DEVICE_ERROR       Transfer failed due to host controller or device error.
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 PeiUsbControlTransfer (
 136   IN     EFI_PEI_SERVICES          **PeiServices,
 137   IN     PEI_USB_IO_PPI            *This,
 138   IN     EFI_USB_DEVICE_REQUEST    *Request,
 139   IN     EFI_USB_DATA_DIRECTION    Direction,
 140   IN     UINT32                    Timeout,
 141   IN OUT VOID                      *Data,      OPTIONAL
 142   IN     UINTN                     DataLength  OPTIONAL
 143   );
 144
 145 /**
 146   Submits bulk transfer to a bulk endpoint of a USB device.
 147
 148   @param  PeiServices           The pointer of EFI_PEI_SERVICES.
 149   @param  This                  The pointer of PEI_USB_IO_PPI.
 150   @param  DeviceEndpoint        Endpoint number and its direction in bit 7.
 151   @param  Data                  A pointer to the buffer of data to transmit
 152                                 from or receive into.
 153   @param  DataLength            The lenght of the data buffer.
 154   @param  Timeout               Indicates the maximum time, in millisecond, which the
 155                                 transfer is allowed to complete. If Timeout is 0, then
 156                                 the caller must wait for the function to be completed
 157                                 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned.
 158
 159   @retval EFI_SUCCESS           The transfer was completed successfully.
 160   @retval EFI_OUT_OF_RESOURCES  The transfer failed due to lack of resource.
 161   @retval EFI_INVALID_PARAMETER Parameters are invalid.
 162   @retval EFI_TIMEOUT           The transfer failed due to timeout.
 163   @retval EFI_DEVICE_ERROR      The transfer failed due to host controller error.
 164
 165 **/
 166 EFI_STATUS
 167 EFIAPI
 168 PeiUsbBulkTransfer (
 169   IN     EFI_PEI_SERVICES    **PeiServices,
 170   IN     PEI_USB_IO_PPI      *This,
 171   IN     UINT8               DeviceEndpoint,
 172   IN OUT VOID                *Data,
 173   IN OUT UINTN               *DataLength,
 174   IN     UINTN               Timeout
 175   );
 176
 177 /**
 178   Get the usb interface descriptor.
 179
 180   @param  PeiServices          General-purpose services that are available to every PEIM.
 181   @param  This                 Indicates the PEI_USB_IO_PPI instance.
 182   @param  InterfaceDescriptor  Request interface descriptor.
 183
 184
 185   @retval EFI_SUCCESS          Usb interface descriptor is obtained successfully.
 186
 187 **/
 188 EFI_STATUS
 189 EFIAPI
 190 PeiUsbGetInterfaceDescriptor (
 191   IN  EFI_PEI_SERVICES                **PeiServices,
 192   IN  PEI_USB_IO_PPI                  *This,
 193   OUT EFI_USB_INTERFACE_DESCRIPTOR    **InterfaceDescriptor
 194   );
 195
 196 /**
 197   Get the usb endpoint descriptor.
 198
 199   @param  PeiServices          General-purpose services that are available to every PEIM.
 200   @param  This                 Indicates the PEI_USB_IO_PPI instance.
 201   @param  EndpointIndex        The valid index of the specified endpoint.
 202   @param  EndpointDescriptor   Request endpoint descriptor.
 203
 204   @retval EFI_SUCCESS       Usb endpoint descriptor is obtained successfully.
 205   @retval EFI_NOT_FOUND     Usb endpoint descriptor is NOT found.
 206
 207 **/
 208 EFI_STATUS
 209 EFIAPI
 210 PeiUsbGetEndpointDescriptor (
 211   IN  EFI_PEI_SERVICES               **PeiServices,
 212   IN  PEI_USB_IO_PPI                 *This,
 213   IN  UINT8                          EndpointIndex,
 214   OUT EFI_USB_ENDPOINT_DESCRIPTOR    **EndpointDescriptor
 215   );
 216
 217 /**
 218   Reset the port and re-configure the usb device.
 219
 220   @param  PeiServices    General-purpose services that are available to every PEIM.
 221   @param  This           Indicates the PEI_USB_IO_PPI instance.
 222
 223   @retval EFI_SUCCESS    Usb device is reset and configured successfully.
 224   @retval Others         Other failure occurs.
 225
 226 **/
 227 EFI_STATUS
 228 EFIAPI
 229 PeiUsbPortReset (
 230   IN EFI_PEI_SERVICES    **PeiServices,
 231   IN PEI_USB_IO_PPI      *This
 232   );
 233
 234 /**
 235   Send reset signal over the given root hub port.
 236
 237   @param  PeiServices       Describes the list of possible PEI Services.
 238   @param  UsbHcPpi          The pointer of PEI_USB_HOST_CONTROLLER_PPI instance.
 239   @param  Usb2HcPpi         The pointer of PEI_USB2_HOST_CONTROLLER_PPI instance.
 240   @param  PortNum           The port to be reset.
 241   @param  RetryIndex        The retry times.
 242
 243 **/
 244 VOID
 245 ResetRootPort (
 246   IN EFI_PEI_SERVICES               **PeiServices,
 247   IN PEI_USB_HOST_CONTROLLER_PPI    *UsbHcPpi,
 248   IN PEI_USB2_HOST_CONTROLLER_PPI   *Usb2HcPpi,
 249   IN UINT8                          PortNum,
 250   IN UINT8                          RetryIndex
 251   );
 252
 253 #endif