2 Private Header file for Usb Host Controller PEIM
4 Copyright (c) 2014 - 2016, Intel Corporation. All rights reserved.<BR>
6 SPDX-License-Identifier: BSD-2-Clause-Patent
10 #ifndef _RECOVERY_XHC_H_
11 #define _RECOVERY_XHC_H_
15 #include <Ppi/UsbController.h>
16 #include <Ppi/Usb2HostController.h>
17 #include <Ppi/IoMmu.h>
18 #include <Ppi/EndOfPeiPhase.h>
20 #include <Library/DebugLib.h>
21 #include <Library/PeimEntryPoint.h>
22 #include <Library/PeiServicesLib.h>
23 #include <Library/BaseMemoryLib.h>
24 #include <Library/TimerLib.h>
25 #include <Library/IoLib.h>
26 #include <Library/MemoryAllocationLib.h>
28 typedef struct _PEI_XHC_DEV PEI_XHC_DEV
;
29 typedef struct _USB_DEV_CONTEXT USB_DEV_CONTEXT
;
33 #include "XhciSched.h"
35 #define CMD_RING_TRB_NUMBER 0x100
36 #define TR_RING_TRB_NUMBER 0x100
37 #define ERST_NUMBER 0x01
38 #define EVENT_RING_TRB_NUMBER 0x200
40 #define XHC_1_MICROSECOND 1
41 #define XHC_1_MILLISECOND (1000 * XHC_1_MICROSECOND)
42 #define XHC_1_SECOND (1000 * XHC_1_MILLISECOND)
45 // XHC reset timeout experience values.
46 // The unit is millisecond, setting it as 1s.
48 #define XHC_RESET_TIMEOUT (1000)
51 // TRSTRCY delay requirement in usb 2.0 spec chapter 7.1.7.5.
52 // The unit is microsecond, setting it as 10ms.
54 #define XHC_RESET_RECOVERY_DELAY (10 * 1000)
57 // Wait for root port state stable.
59 #define XHC_ROOT_PORT_STATE_STABLE (200 * XHC_1_MILLISECOND)
62 // XHC generic timeout experience values.
63 // The unit is millisecond, setting it as 10s.
65 #define XHC_GENERIC_TIMEOUT (10 * 1000)
67 #define XHC_LOW_32BIT(Addr64) ((UINT32)(((UINTN)(Addr64)) & 0XFFFFFFFF))
68 #define XHC_HIGH_32BIT(Addr64) ((UINT32)(RShiftU64((UINTN)(Addr64), 32) & 0XFFFFFFFF))
69 #define XHC_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
71 #define XHC_REG_BIT_IS_SET(XHC, Offset, Bit) \
72 (XHC_BIT_IS_SET(XhcPeiReadOpReg ((XHC), (Offset)), (Bit)))
74 #define USB_DESC_TYPE_HUB 0x29
75 #define USB_DESC_TYPE_HUB_SUPER_SPEED 0x2a
78 // The RequestType in EFI_USB_DEVICE_REQUEST is composed of
79 // three fields: One bit direction, 2 bit type, and 5 bit
82 #define USB_REQUEST_TYPE(Dir, Type, Target) \
83 ((UINT8)((((Dir) == EfiUsbDataIn ? 0x01 : 0) << 7) | (Type) | (Target)))
85 struct _USB_DEV_CONTEXT
{
87 // Whether this entry in UsbDevContext array is used or not.
91 // The slot id assigned to the new device through XHCI's Enable_Slot cmd.
95 // The route string presented an attached usb device.
97 USB_DEV_ROUTE RouteString
;
99 // The route string of parent device if it exists. Otherwise it's zero.
101 USB_DEV_ROUTE ParentRouteString
;
103 // The actual device address assigned by XHCI through Address_Device command.
107 // The requested device address from UsbBus driver through Set_Address standard usb request.
108 // As XHCI spec replaces this request with Address_Device command, we have to record the
109 // requested device address and establish a mapping relationship with the actual device address.
110 // Then UsbBus driver just need to be aware of the requested device address to access usb device
111 // through EFI_USB2_HC_PROTOCOL. Xhci driver would be responsible for translating it to actual
112 // device address and access the actual device.
116 // The pointer to the input device context.
120 // The pointer to the output device context.
124 // The transfer queue for every endpoint.
126 VOID
*EndpointTransferRing
[31];
128 // The device descriptor which is stored to support XHCI's Evaluate_Context cmd.
130 EFI_USB_DEVICE_DESCRIPTOR DevDesc
;
132 // As a usb device may include multiple configuration descriptors, we dynamically allocate an array
134 // Note that every configuration descriptor stored here includes those lower level descriptors,
135 // such as Interface descriptor, Endpoint descriptor, and so on.
136 // These information is used to support XHCI's Config_Endpoint cmd.
138 EFI_USB_CONFIG_DESCRIPTOR
**ConfDesc
;
141 #define USB_XHC_DEV_SIGNATURE SIGNATURE_32 ('x', 'h', 'c', 'i')
143 struct _PEI_XHC_DEV
{
145 PEI_USB2_HOST_CONTROLLER_PPI Usb2HostControllerPpi
;
146 EFI_PEI_PPI_DESCRIPTOR PpiDescriptor
;
147 UINT32 UsbHostControllerBaseAddress
;
148 USBHC_MEM_POOL
*MemPool
;
151 // EndOfPei callback is used to stop the XHC DMA operation
152 // after exit PEI phase.
154 EFI_PEI_NOTIFY_DESCRIPTOR EndOfPeiNotifyList
;
157 // XHCI configuration data
159 UINT8 CapLength
; ///< Capability Register Length
160 XHC_HCSPARAMS1 HcSParams1
; ///< Structural Parameters 1
161 XHC_HCSPARAMS2 HcSParams2
; ///< Structural Parameters 2
162 XHC_HCCPARAMS HcCParams
; ///< Capability Parameters
163 UINT32 DBOff
; ///< Doorbell Offset
164 UINT32 RTSOff
; ///< Runtime Register Space Offset
166 UINT32 MaxScratchpadBufs
;
169 UINT64
*ScratchEntry
;
170 UINTN
*ScratchEntryMap
;
176 TRANSFER_RING CmdRing
;
180 EVENT_RING EventRing
;
183 // Store device contexts managed by XHCI device
184 // The array supports up to 255 devices, entry 0 is reserved and should not be used.
186 USB_DEV_CONTEXT UsbDevContext
[256];
189 #define PEI_RECOVERY_USB_XHC_DEV_FROM_THIS(a) CR (a, PEI_XHC_DEV, Usb2HostControllerPpi, USB_XHC_DEV_SIGNATURE)
190 #define PEI_RECOVERY_USB_XHC_DEV_FROM_THIS_NOTIFY(a) CR (a, PEI_XHC_DEV, EndOfPeiNotifyList, USB_XHC_DEV_SIGNATURE)
193 Initialize the memory management pool for the host controller.
195 @return Pointer to the allocated memory pool or NULL if failed.
205 Release the memory management pool.
207 @param Pool The USB memory pool to free.
212 IN USBHC_MEM_POOL
*Pool
217 Allocate some memory from the host controller's memory pool
218 which can be used to communicate with host controller.
220 @param Pool The host controller's memory pool.
221 @param Size Size of the memory to allocate.
223 @return The allocated memory or NULL.
228 IN USBHC_MEM_POOL
*Pool
,
234 Free the allocated memory back to the memory pool.
236 @param Pool The memory pool of the host controller.
237 @param Mem The memory to free.
238 @param Size The size of the memory to free.
243 IN USBHC_MEM_POOL
*Pool
,
259 Provides the controller-specific addresses required to access system memory from a
262 @param Operation Indicates if the bus master is going to read or write to system memory.
263 @param HostAddress The system memory address to map to the PCI controller.
264 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes
266 @param DeviceAddress The resulting map address for the bus master PCI controller to use to
267 access the hosts HostAddress.
268 @param Mapping A resulting value to pass to Unmap().
270 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes.
271 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer.
272 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
273 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
274 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address.
279 IN EDKII_IOMMU_OPERATION Operation
,
280 IN VOID
*HostAddress
,
281 IN OUT UINTN
*NumberOfBytes
,
282 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
287 Completes the Map() operation and releases any corresponding resources.
289 @param Mapping The mapping value returned from Map().
291 @retval EFI_SUCCESS The range was unmapped.
292 @retval EFI_INVALID_PARAMETER Mapping is not a value that was returned by Map().
293 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory.
301 Allocates pages that are suitable for an OperationBusMasterCommonBuffer or
302 OperationBusMasterCommonBuffer64 mapping.
304 @param Pages The number of pages to allocate.
305 @param HostAddress A pointer to store the base system memory address of the
307 @param DeviceAddress The resulting map address for the bus master PCI controller to use to
308 access the hosts HostAddress.
309 @param Mapping A resulting value to pass to Unmap().
311 @retval EFI_SUCCESS The requested memory pages were allocated.
312 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are
313 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
314 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
315 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated.
319 IoMmuAllocateBuffer (
321 OUT VOID
**HostAddress
,
322 OUT EFI_PHYSICAL_ADDRESS
*DeviceAddress
,
327 Frees memory that was allocated with AllocateBuffer().
329 @param Pages The number of pages to free.
330 @param HostAddress The base system memory address of the allocated range.
331 @param Mapping The mapping value returned from Map().
333 @retval EFI_SUCCESS The requested memory pages were freed.
334 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
335 was not allocated with AllocateBuffer().
341 IN VOID
*HostAddress
,