1 /** @file 2 3 The definition for UHCI driver model and HC protocol routines. 4 5 Copyright (c) 2004 - 2015, 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 222