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 stoping 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