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