1/** @file
2
3  The definition for UHCI driver model and HC protocol routines.
4
5Copyright (c) 2004 - 2015, Intel Corporation. All rights reserved.<BR>
6This program and the accompanying materials
7are licensed and made available under the terms and conditions of the BSD License
8which accompanies this distribution.  The full text of the license may be found at
9http://opensource.org/licenses/bsd-license.php
10
11THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12WITHOUT 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
40typedef 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)
92typedef 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//
112struct _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
154extern EFI_DRIVER_BINDING_PROTOCOL   gUhciDriverBinding;
155extern EFI_COMPONENT_NAME_PROTOCOL   gUhciComponentName;
156extern 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**/
170EFI_STATUS
171EFIAPI
172UhciDriverBindingSupported (
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**/
191EFI_STATUS
192EFIAPI
193UhciDriverBindingStart (
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**/
212EFI_STATUS
213EFIAPI
214UhciDriverBindingStop (
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