MdeModulePkg/Bus/Pci/UhciDxe/Uhci.h

   1 /** @file
   2
   3   The definition for UHCI driver model and HC protocol routines.
   4
   5 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _EFI_UHCI_H_
  11 #define _EFI_UHCI_H_
  12
  13 #include <Uefi.h>
  14
  15 #include <Protocol/Usb2HostController.h>
  16 #include <Protocol/UsbHostController.h>
  17 #include <Protocol/PciIo.h>
  18
  19 #include <Guid/EventGroup.h>
  20
  21 #include <Library/DebugLib.h>
  22 #include <Library/BaseMemoryLib.h>
  23 #include <Library/UefiDriverEntryPoint.h>
  24 #include <Library/UefiBootServicesTableLib.h>
  25 #include <Library/UefiLib.h>
  26 #include <Library/BaseLib.h>
  27 #include <Library/MemoryAllocationLib.h>
  28 #include <Library/PcdLib.h>
  29 #include <Library/ReportStatusCodeLib.h>
  30
  31 #include <IndustryStandard/Pci.h>
  32
  33 typedef struct _USB_HC_DEV USB_HC_DEV;
  34
  35 #include "UsbHcMem.h"
  36 #include "UhciQueue.h"
  37 #include "UhciReg.h"
  38 #include "UhciSched.h"
  39 #include "UhciDebug.h"
  40 #include "ComponentName.h"
  41
  42 //
  43 // UHC timeout experience values
  44 //
  45
  46 #define UHC_1_MICROSECOND  1
  47 #define UHC_1_MILLISECOND  (1000 * UHC_1_MICROSECOND)
  48 #define UHC_1_SECOND       (1000 * UHC_1_MILLISECOND)
  49
  50 //
  51 // UHCI register operation timeout, set by experience
  52 //
  53 #define UHC_GENERIC_TIMEOUT  UHC_1_SECOND
  54
  55 //
  56 // Wait for force global resume(FGR) complete, refers to
  57 // specification[UHCI11-2.1.1]
  58 //
  59 #define UHC_FORCE_GLOBAL_RESUME_STALL  (20 * UHC_1_MILLISECOND)
  60
  61 //
  62 // Wait for roothub port reset and recovery, reset stall
  63 // is set by experience, and recovery stall refers to
  64 // specification[UHCI11-2.1.1]
  65 //
  66 #define UHC_ROOT_PORT_RESET_STALL     (50 * UHC_1_MILLISECOND)
  67 #define UHC_ROOT_PORT_RECOVERY_STALL  (10 * UHC_1_MILLISECOND)
  68
  69 //
  70 // Sync and Async transfer polling interval, set by experience,
  71 // and the unit of Async is 100us.
  72 //
  73 #define UHC_SYNC_POLL_INTERVAL   (1 * UHC_1_MILLISECOND)
  74 #define UHC_ASYNC_POLL_INTERVAL  EFI_TIMER_PERIOD_MILLISECONDS(1)
  75
  76 //
  77 // UHC raises TPL to TPL_NOTIFY to serialize all its operations
  78 // to protect shared data structures.
  79 //
  80 #define  UHCI_TPL  TPL_NOTIFY
  81
  82 #define  USB_HC_DEV_SIGNATURE  SIGNATURE_32 ('u', 'h', 'c', 'i')
  83
  84 #pragma pack(1)
  85 typedef struct {
  86   UINT8    ProgInterface;
  87   UINT8    SubClassCode;
  88   UINT8    BaseCode;
  89 } USB_CLASSC;
  90 #pragma pack()
  91
  92 #define UHC_FROM_USB2_HC_PROTO(This)  CR(This, USB_HC_DEV, Usb2Hc, USB_HC_DEV_SIGNATURE)
  93
  94 //
  95 // USB_HC_DEV support the UHCI hardware controller. It schedules
  96 // the asynchronous interrupt transfer with the same method as
  97 // EHCI: a reversed tree structure. For synchronous interrupt,
  98 // control and bulk transfer, it uses three static queue head to
  99 // schedule them. SyncIntQh is for interrupt transfer. LsCtrlQh is
 100 // for LOW speed control transfer, and FsCtrlBulkQh is for FULL
 101 // speed control or bulk transfer. This is because FULL speed contrl
 102 // or bulk transfer can reclaim the unused bandwidth. Some USB
 103 // device requires this bandwidth reclamation capability.
 104 //
 105 struct _USB_HC_DEV {
 106   UINT32                      Signature;
 107   EFI_USB2_HC_PROTOCOL        Usb2Hc;
 108   EFI_PCI_IO_PROTOCOL         *PciIo;
 109   EFI_DEVICE_PATH_PROTOCOL    *DevicePath;
 110   UINT64                      OriginalPciAttributes;
 111
 112   //
 113   // Schedule data structures
 114   //
 115   UINT32                      *FrameBase;         // the buffer pointed by this pointer is used to store pci bus address of the QH descriptor.
 116   UINT32                      *FrameBaseHostAddr; // the buffer pointed by this pointer is used to store host memory address of the QH descriptor.
 117   UHCI_QH_SW                  *SyncIntQh;
 118   UHCI_QH_SW                  *CtrlQh;
 119   UHCI_QH_SW                  *BulkQh;
 120
 121   //
 122   // Structures to maintain asynchronus interrupt transfers.
 123   // When asynchronous interrutp transfer is unlinked from
 124   // the frame list, the hardware may still hold a pointer
 125   // to it. To synchronize with hardware, its resoureces are
 126   // released in two steps using Recycle and RecycleWait.
 127   // Check the asynchronous interrupt management routines.
 128   //
 129   LIST_ENTRY                  AsyncIntList;
 130   EFI_EVENT                   AsyncIntMonitor;
 131   UHCI_ASYNC_REQUEST          *Recycle;
 132   UHCI_ASYNC_REQUEST          *RecycleWait;
 133
 134   UINTN                       RootPorts;
 135   USBHC_MEM_POOL              *MemPool;
 136   EFI_UNICODE_STRING_TABLE    *CtrlNameTable;
 137   VOID                        *FrameMapping;
 138
 139   //
 140   // ExitBootServicesEvent is used to stop the EHC DMA operation
 141   // after exit boot service.
 142   //
 143   EFI_EVENT                   ExitBootServiceEvent;
 144 };
 145
 146 extern EFI_DRIVER_BINDING_PROTOCOL   gUhciDriverBinding;
 147 extern EFI_COMPONENT_NAME_PROTOCOL   gUhciComponentName;
 148 extern EFI_COMPONENT_NAME2_PROTOCOL  gUhciComponentName2;
 149
 150 /**
 151   Test to see if this driver supports ControllerHandle. Any
 152   ControllerHandle that has UsbHcProtocol installed will be supported.
 153
 154   @param  This                 Protocol instance pointer.
 155   @param  Controller           Handle of device to test.
 156   @param  RemainingDevicePath  Not used.
 157
 158   @return EFI_SUCCESS          This driver supports this device.
 159   @return EFI_UNSUPPORTED      This driver does not support this device.
 160
 161 **/
 162 EFI_STATUS
 163 EFIAPI
 164 UhciDriverBindingSupported (
 165   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 166   IN EFI_HANDLE                   Controller,
 167   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 168   );
 169
 170 /**
 171   Starting the Usb UHCI Driver.
 172
 173   @param  This                 Protocol instance pointer.
 174   @param  Controller           Handle of device to test.
 175   @param  RemainingDevicePath  Not used.
 176
 177   @retval EFI_SUCCESS          This driver supports this device.
 178   @retval EFI_UNSUPPORTED      This driver does not support this device.
 179   @retval EFI_DEVICE_ERROR     This driver cannot be started due to device Error.
 180                                EFI_OUT_OF_RESOURCES- Failed due to resource shortage.
 181
 182 **/
 183 EFI_STATUS
 184 EFIAPI
 185 UhciDriverBindingStart (
 186   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 187   IN EFI_HANDLE                   Controller,
 188   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 189   );
 190
 191 /**
 192   Stop this driver on ControllerHandle. Support stopping any child handles
 193   created by this driver.
 194
 195   @param  This                 Protocol instance pointer.
 196   @param  Controller           Handle of device to stop driver on.
 197   @param  NumberOfChildren     Number of Children in the ChildHandleBuffer.
 198   @param  ChildHandleBuffer    List of handles for the children we need to stop.
 199
 200   @return EFI_SUCCESS
 201   @return others
 202
 203 **/
 204 EFI_STATUS
 205 EFIAPI
 206 UhciDriverBindingStop (
 207   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 208   IN EFI_HANDLE                   Controller,
 209   IN UINTN                        NumberOfChildren,
 210   IN EFI_HANDLE                   *ChildHandleBuffer
 211   );
 212
 213 #endif