diff options
Diffstat (limited to 'SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h')
| -rw-r--r-- | SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h | 1474 |
1 files changed, 737 insertions, 737 deletions
diff --git a/SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h b/SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h index cc5f294f33..8fd9105b88 100644 --- a/SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h +++ b/SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h @@ -1,737 +1,737 @@ -/** @file
- Debug Port Library implementation based on usb3 debug port.
-
- Copyright (c) 2014 - 2018, Intel Corporation. All rights reserved.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
-
-**/
-
-#ifndef __USB3_DEBUG_PORT_LIB_INTERNAL__
-#define __USB3_DEBUG_PORT_LIB_INTERNAL__
-
-#include <Uefi.h>
-#include <Base.h>
-#include <IndustryStandard/Usb.h>
-#include <Library/IoLib.h>
-#include <IndustryStandard/Pci.h>
-#include <Library/PcdLib.h>
-#include <Library/UefiLib.h>
-#include <Library/UefiBootServicesTableLib.h>
-#include <Library/MemoryAllocationLib.h>
-#include <Library/DebugLib.h>
-#include <Library/BaseMemoryLib.h>
-#include <Library/BaseLib.h>
-#include <Library/TimerLib.h>
-#include <Library/DebugCommunicationLib.h>
-#include <Library/PciLib.h>
-
-//
-// USB Debug GUID value
-//
-#define USB3_DBG_GUID \
- { \
- 0xb2a56f4d, 0x9177, 0x4fc8, { 0xa6, 0x77, 0xdd, 0x96, 0x3e, 0xb4, 0xcb, 0x1b } \
- }
-
-//
-// The state machine of usb debug port
-//
-#define USB3DBG_NO_DBG_CAB 0 // The XHCI host controller does not support debug capability
-#define USB3DBG_DBG_CAB 1 // The XHCI host controller supports debug capability
-#define USB3DBG_ENABLED 2 // The XHCI debug device is enabled
-#define USB3DBG_NOT_ENABLED 4 // The XHCI debug device is not enabled
-#define USB3DBG_UNINITIALIZED 255 // The XHCI debug device is uninitialized
-
-#define USB3_DEBUG_PORT_WRITE_MAX_PACKET_SIZE 0x08
-
-//
-// MaxPacketSize for DbC Endpoint Descriptor IN and OUT
-//
-#define XHCI_DEBUG_DEVICE_MAX_PACKET_SIZE 0x400
-
-#define XHCI_DEBUG_DEVICE_VENDOR_ID 0x0525
-#define XHCI_DEBUG_DEVICE_PRODUCT_ID 0x127A
-#define XHCI_DEBUG_DEVICE_PROTOCOL 0xFF
-#define XHCI_DEBUG_DEVICE_REVISION 0x00
-
-#define XHCI_BASE_ADDRESS_64_BIT_MASK 0xFFFFFFFFFFFF0000ULL
-#define XHCI_BASE_ADDRESS_32_BIT_MASK 0xFFFF0000
-
-#define PCI_CAPABILITY_ID_DEBUG_PORT 0x0A
-#define XHC_HCCPARAMS_OFFSET 0x10
-#define XHC_CAPABILITY_ID_MASK 0xFF
-#define XHC_NEXT_CAPABILITY_MASK 0xFF00
-
-#define XHC_HCSPARAMS1_OFFSET 0x4 // Structural Parameters 1
-#define XHC_USBCMD_OFFSET 0x0 // USB Command Register Offset
-#define XHC_USBSTS_OFFSET 0x4 // USB Status Register Offset
-#define XHC_PORTSC_OFFSET 0x400 // Port Status and Control Register Offset
-
-#define XHC_USBCMD_RUN BIT0 // Run/Stop
-#define XHC_USBCMD_RESET BIT1 // Host Controller Reset
-
-#define XHC_USBSTS_HALT BIT0
-
-//
-// Indicate the timeout when data is transferred in microsecond. 0 means infinite timeout.
-//
-#define DATA_TRANSFER_WRITE_TIMEOUT 0
-#define DATA_TRANSFER_READ_TIMEOUT 50000
-#define DATA_TRANSFER_POLL_TIMEOUT 1000
-#define XHC_DEBUG_PORT_1_MILLISECOND 1000
-//
-// XHCI port power off/on delay
-//
-#define XHC_DEBUG_PORT_ON_OFF_DELAY 100000
-
-//
-// USB debug device string descriptor (header size + unicode string length)
-//
-#define STRING0_DESC_LEN 4
-#define MANU_DESC_LEN 12
-#define PRODUCT_DESC_LEN 40
-#define SERIAL_DESC_LEN 4
-
-//
-// Debug Capability Register Offset
-//
-#define XHC_DC_DCID 0x0
-#define XHC_DC_DCDB 0x4
-#define XHC_DC_DCERSTSZ 0x8
-#define XHC_DC_DCERSTBA 0x10
-#define XHC_DC_DCERDP 0x18
-#define XHC_DC_DCCTRL 0x20
-#define XHC_DC_DCST 0x24
-#define XHC_DC_DCPORTSC 0x28
-#define XHC_DC_DCCP 0x30
-#define XHC_DC_DCDDI1 0x38
-#define XHC_DC_DCDDI2 0x3C
-
-#define TRB_TYPE_LINK 6
-
-#define ERST_NUMBER 0x01
-#define TR_RING_TRB_NUMBER 0x100
-#define EVENT_RING_TRB_NUMBER 0x200
-
-#define ED_BULK_OUT 2
-#define ED_BULK_IN 6
-
-#define XHC_LOW_32BIT(Addr64) ((UINT32)(((UINTN)(Addr64)) & 0xFFFFFFFF))
-#define XHC_HIGH_32BIT(Addr64) ((UINT32)(RShiftU64((UINT64)(UINTN)(Addr64), 32) & 0xFFFFFFFF))
-#define XHC_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
-
-//
-// Endpoint Type (EP Type).
-//
-#define ED_NOT_VALID 0
-#define ED_ISOCH_OUT 1
-#define ED_BULK_OUT 2
-#define ED_INTERRUPT_OUT 3
-#define ED_CONTROL_BIDIR 4
-#define ED_ISOCH_IN 5
-#define ED_BULK_IN 6
-#define ED_INTERRUPT_IN 7
-
-//
-// 6.4.5 TRB Completion Codes
-//
-#define TRB_COMPLETION_INVALID 0
-#define TRB_COMPLETION_SUCCESS 1
-#define TRB_COMPLETION_DATA_BUFFER_ERROR 2
-#define TRB_COMPLETION_BABBLE_ERROR 3
-#define TRB_COMPLETION_USB_TRANSACTION_ERROR 4
-#define TRB_COMPLETION_TRB_ERROR 5
-#define TRB_COMPLETION_STALL_ERROR 6
-#define TRB_COMPLETION_SHORT_PACKET 13
-
-//
-// 6.4.6 TRB Types
-//
-#define TRB_TYPE_NORMAL 1
-#define TRB_TYPE_SETUP_STAGE 2
-#define TRB_TYPE_DATA_STAGE 3
-#define TRB_TYPE_STATUS_STAGE 4
-#define TRB_TYPE_ISOCH 5
-#define TRB_TYPE_LINK 6
-#define TRB_TYPE_EVENT_DATA 7
-#define TRB_TYPE_NO_OP 8
-#define TRB_TYPE_EN_SLOT 9
-#define TRB_TYPE_DIS_SLOT 10
-#define TRB_TYPE_ADDRESS_DEV 11
-#define TRB_TYPE_CON_ENDPOINT 12
-#define TRB_TYPE_EVALU_CONTXT 13
-#define TRB_TYPE_RESET_ENDPOINT 14
-#define TRB_TYPE_STOP_ENDPOINT 15
-#define TRB_TYPE_SET_TR_DEQUE 16
-#define TRB_TYPE_RESET_DEV 17
-#define TRB_TYPE_GET_PORT_BANW 21
-#define TRB_TYPE_FORCE_HEADER 22
-#define TRB_TYPE_NO_OP_COMMAND 23
-#define TRB_TYPE_TRANS_EVENT 32
-#define TRB_TYPE_COMMAND_COMPLT_EVENT 33
-#define TRB_TYPE_PORT_STATUS_CHANGE_EVENT 34
-#define TRB_TYPE_HOST_CONTROLLER_EVENT 37
-#define TRB_TYPE_DEVICE_NOTIFI_EVENT 38
-#define TRB_TYPE_MFINDEX_WRAP_EVENT 39
-
-//
-// Convert millisecond to microsecond.
-//
-#define XHC_1_MILLISECOND (1000)
-#define XHC_POLL_DELAY (1000)
-#define XHC_GENERIC_TIMEOUT (10 * 1000)
-
-#define EFI_USB_SPEED_FULL 0x0000 ///< 12 Mb/s, USB 1.1 OHCI and UHCI HC.
-#define EFI_USB_SPEED_LOW 0x0001 ///< 1 Mb/s, USB 1.1 OHCI and UHCI HC.
-#define EFI_USB_SPEED_HIGH 0x0002 ///< 480 Mb/s, USB 2.0 EHCI HC.
-#define EFI_USB_SPEED_SUPER 0x0003 ///< 4.8 Gb/s, USB 3.0 XHCI HC.
-
-//
-// Transfer types, used in URB to identify the transfer type
-//
-#define XHC_CTRL_TRANSFER 0x01
-#define XHC_BULK_TRANSFER 0x02
-#define XHC_INT_TRANSFER_SYNC 0x04
-#define XHC_INT_TRANSFER_ASYNC 0x08
-#define XHC_INT_ONLY_TRANSFER_ASYNC 0x10
-
-//
-// USB Transfer Results
-//
-#define EFI_USB_NOERROR 0x00
-#define EFI_USB_ERR_NOTEXECUTE 0x01
-#define EFI_USB_ERR_STALL 0x02
-#define EFI_USB_ERR_BUFFER 0x04
-#define EFI_USB_ERR_BABBLE 0x08
-#define EFI_USB_ERR_NAK 0x10
-#define EFI_USB_ERR_CRC 0x20
-#define EFI_USB_ERR_TIMEOUT 0x40
-#define EFI_USB_ERR_BITSTUFF 0x80
-#define EFI_USB_ERR_SYSTEM 0x100
-
-#pragma pack(1)
-
-//
-// 7.6.9 OUT/IN EP Context: 64 bytes
-// 7.6.9.2 When used by the DbC it is always a 64 byte data structure
-//
-typedef struct _ENDPOINT_CONTEXT_64 {
- UINT32 EPState : 3;
- UINT32 RsvdZ1 : 5;
- UINT32 Mult : 2; // set to 0
- UINT32 MaxPStreams : 5; // set to 0
- UINT32 LSA : 1; // set to 0
- UINT32 Interval : 8; // set to 0
- UINT32 RsvdZ2 : 8;
-
- UINT32 RsvdZ3 : 1;
- UINT32 CErr : 2;
- UINT32 EPType : 3;
- UINT32 RsvdZ4 : 1;
- UINT32 HID : 1; // set to 0
- UINT32 MaxBurstSize : 8;
- UINT32 MaxPacketSize : 16;
-
- UINT32 PtrLo;
-
- UINT32 PtrHi;
-
- UINT32 AverageTRBLength : 16;
- UINT32 MaxESITPayload : 16; // set to 0
-
- UINT32 RsvdZ5; // Reserved
- UINT32 RsvdZ6;
- UINT32 RsvdZ7;
-
- UINT32 RsvdZ8;
- UINT32 RsvdZ9;
- UINT32 RsvdZ10;
- UINT32 RsvdZ11;
-
- UINT32 RsvdZ12;
- UINT32 RsvdZ13;
- UINT32 RsvdZ14;
- UINT32 RsvdZ15;
-} ENDPOINT_CONTEXT_64;
-
-//
-// 6.4.1.1 Normal TRB: 16 bytes
-// A Normal TRB is used in several ways; exclusively on Bulk and Interrupt Transfer Rings for normal and
-// Scatter/Gather operations, to define additional data buffers for Scatter/Gather operations on Isoch Transfer
-// Rings, and to define the Data stage information for Control Transfer Rings.
-//
-typedef struct _TRANSFER_TRB_NORMAL {
- UINT32 TRBPtrLo;
-
- UINT32 TRBPtrHi;
-
- UINT32 Length : 17;
- UINT32 TDSize : 5;
- UINT32 IntTarget : 10;
-
- UINT32 CycleBit : 1;
- UINT32 ENT : 1;
- UINT32 ISP : 1;
- UINT32 NS : 1;
- UINT32 CH : 1;
- UINT32 IOC : 1;
- UINT32 IDT : 1;
- UINT32 RsvdZ1 : 2;
- UINT32 BEI : 1;
- UINT32 Type : 6;
- UINT32 RsvdZ2 : 16;
-} TRANSFER_TRB_NORMAL;
-
-//
-// 6.4.2.1 Transfer Event TRB: 16 bytes
-// A Transfer Event provides the completion status associated with a Transfer TRB. Refer to section 4.11.3.1
-// for more information on the use and operation of Transfer Events.
-//
-typedef struct _EVT_TRB_TRANSFER {
- UINT32 TRBPtrLo;
-
- UINT32 TRBPtrHi;
-
- UINT32 Length : 24;
- UINT32 Completecode : 8;
-
- UINT32 CycleBit : 1;
- UINT32 RsvdZ1 : 1;
- UINT32 ED : 1;
- UINT32 RsvdZ2 : 7;
- UINT32 Type : 6;
- UINT32 EndpointId : 5;
- UINT32 RsvdZ3 : 3;
- UINT32 SlotId : 8;
-} EVT_TRB_TRANSFER;
-
-//
-// 6.4.4.1 Link TRB: 16 bytes
-// A Link TRB provides support for non-contiguous TRB Rings.
-//
-typedef struct _LINK_TRB {
- UINT32 PtrLo;
-
- UINT32 PtrHi;
-
- UINT32 RsvdZ1 : 22;
- UINT32 InterTarget : 10;
-
- UINT32 CycleBit : 1;
- UINT32 TC : 1;
- UINT32 RsvdZ2 : 2;
- UINT32 CH : 1;
- UINT32 IOC : 1;
- UINT32 RsvdZ3 : 4;
- UINT32 Type : 6;
- UINT32 RsvdZ4 : 16;
-} LINK_TRB;
-
-//
-// TRB Template: 16 bytes
-//
-typedef struct _TRB_TEMPLATE {
- UINT32 Parameter1;
-
- UINT32 Parameter2;
-
- UINT32 Status;
-
- UINT32 CycleBit : 1;
- UINT32 RsvdZ1 : 9;
- UINT32 Type : 6;
- UINT32 Control : 16;
-} TRB_TEMPLATE;
-
-//
-// Refer to XHCI 6.5 Event Ring Segment Table: 16 bytes
-//
-typedef struct _EVENT_RING_SEG_TABLE_ENTRY {
- UINT32 PtrLo;
- UINT32 PtrHi;
- UINT32 RingTrbSize : 16;
- UINT32 RsvdZ1 : 16;
- UINT32 RsvdZ2;
-} EVENT_RING_SEG_TABLE_ENTRY;
-
-//
-// Size: 40 bytes
-//
-typedef struct _EVENT_RING {
- EFI_PHYSICAL_ADDRESS ERSTBase;
- EFI_PHYSICAL_ADDRESS EventRingSeg0;
- UINT32 TrbNumber;
- EFI_PHYSICAL_ADDRESS EventRingEnqueue;
- EFI_PHYSICAL_ADDRESS EventRingDequeue;
- UINT32 EventRingCCS;
-} EVENT_RING;
-
-// Size: 32 bytes
-typedef struct _TRANSFER_RING {
- EFI_PHYSICAL_ADDRESS RingSeg0;
- UINT32 TrbNumber;
- EFI_PHYSICAL_ADDRESS RingEnqueue;
- EFI_PHYSICAL_ADDRESS RingDequeue;
- UINT32 RingPCS;
-} TRANSFER_RING;
-
-//
-// Size: 64 bytes
-//
-typedef struct _DBC_INFO_CONTEXT {
- UINT64 String0DescAddress;
- UINT64 ManufacturerStrDescAddress;
- UINT64 ProductStrDescAddress;
- UINT64 SerialNumberStrDescAddress;
- UINT64 String0Length : 8;
- UINT64 ManufacturerStrLength : 8;
- UINT64 ProductStrLength : 8;
- UINT64 SerialNumberStrLength : 8;
- UINT64 RsvdZ1 : 32;
- UINT64 RsvdZ2;
- UINT64 RsvdZ3;
- UINT64 RsvdZ4;
-} DBC_INFO_CONTEXT;
-
-//
-// Debug Capability Context Data Structure: 192 bytes
-//
-typedef struct _XHC_DC_CONTEXT {
- DBC_INFO_CONTEXT DbcInfoContext;
- ENDPOINT_CONTEXT_64 EpOutContext;
- ENDPOINT_CONTEXT_64 EpInContext;
-} XHC_DC_CONTEXT;
-
-//
-// Size: 16 bytes
-//
-typedef union _TRB {
- TRB_TEMPLATE TrbTemplate;
- TRANSFER_TRB_NORMAL TrbNormal;
-} TRB;
-
-///
-/// USB data transfer direction
-///
-typedef enum {
- EfiUsbDataIn,
- EfiUsbDataOut,
- EfiUsbNoData
-} EFI_USB_DATA_DIRECTION;
-
-//
-// URB (Usb Request Block) contains information for all kinds of
-// usb requests.
-//
-typedef struct _URB {
- //
- // Transfer data buffer
- //
- EFI_PHYSICAL_ADDRESS Data;
- UINT32 DataLen;
-
- //
- // Execute result
- //
- UINT32 Result;
- //
- // Completed data length
- //
- UINT32 Completed;
- //
- // Tranfer Ring info
- //
- EFI_PHYSICAL_ADDRESS Ring;
- EFI_PHYSICAL_ADDRESS Trb;
- BOOLEAN Finished;
- EFI_USB_DATA_DIRECTION Direction;
-} URB;
-
-typedef struct _USB3_DEBUG_PORT_INSTANCE {
- UINT8 Initialized;
-
- //
- // The flag indicates debug capability is supported
- //
- BOOLEAN DebugSupport;
-
- //
- // The flag indicates debug device is ready
- //
- BOOLEAN Ready;
-
- //
- // The flag indicates the instance is from HOB
- //
- BOOLEAN FromHob;
-
- //
- // Prevent notification being interrupted by debug timer
- //
- BOOLEAN InNotify;
-
- //
- // PciIo protocol event
- //
- EFI_PHYSICAL_ADDRESS PciIoEvent;
-
- //
- // The flag indicates if USB 3.0 ports has been turn off/on power
- //
- BOOLEAN ChangePortPower;
-
- //
- // XHCI MMIO Base address
- //
- EFI_PHYSICAL_ADDRESS XhciMmioBase;
-
- //
- // XHCI OP RegisterBase address
- //
- EFI_PHYSICAL_ADDRESS XhciOpRegister;
-
- //
- // XHCI Debug Register Base Address
- //
- EFI_PHYSICAL_ADDRESS DebugCapabilityBase;
-
- //
- // XHCI Debug Capability offset
- //
- UINT64 DebugCapabilityOffset;
-
- //
- // XHCI Debug Context Address
- //
- EFI_PHYSICAL_ADDRESS DebugCapabilityContext;
-
- //
- // Transfer Ring
- //
- TRANSFER_RING TransferRingOut;
- TRANSFER_RING TransferRingIn;
-
- //
- // EventRing
- //
- EVENT_RING EventRing;
-
- //
- // URB - Read
- //
- URB UrbOut;
-
- //
- // URB - Write
- //
- URB UrbIn;
-
- //
- // The available data length in the following data buffer.
- //
- UINT8 DataCount;
- //
- // The data buffer address for data read and poll.
- //
- EFI_PHYSICAL_ADDRESS Data;
-} USB3_DEBUG_PORT_HANDLE;
-
-#pragma pack()
-
-/**
- Read XHCI debug register.
-
- @param Handle Debug port handle.
- @param Offset The offset of the debug register.
-
- @return The register content read
-
-**/
-UINT32
-XhcReadDebugReg (
- IN USB3_DEBUG_PORT_HANDLE *Handle,
- IN UINT32 Offset
- );
-
-/**
- Set one bit of the debug register while keeping other bits.
-
- @param Handle Debug port handle.
- @param Offset The offset of the debug register.
- @param Bit The bit mask of the register to set.
-
-**/
-VOID
-XhcSetDebugRegBit (
- IN USB3_DEBUG_PORT_HANDLE *Handle,
- IN UINT32 Offset,
- IN UINT32 Bit
- );
-
-/**
- Write the data to the debug register.
-
- @param Handle Debug port handle.
- @param Offset The offset of the debug register.
- @param Data The data to write.
-
-**/
-VOID
-XhcWriteDebugReg (
- IN USB3_DEBUG_PORT_HANDLE *Handle,
- IN UINT32 Offset,
- IN UINT32 Data
- );
-
-/**
- Verifies if the bit positions specified by a mask are set in a register.
-
- @param[in, out] Register UINTN register
- @param[in] BitMask 32-bit mask
-
- @return BOOLEAN - TRUE if all bits specified by the mask are enabled.
- - FALSE even if one of the bits specified by the mask
- is not enabled.
-**/
-BOOLEAN
-XhcIsBitSet (
- UINTN Register,
- UINT32 BitMask
- );
-
-/**
- Sets bits as per the enabled bit positions in the mask.
-
- @param[in, out] Register UINTN register
- @param[in] BitMask 32-bit mask
-**/
-VOID
-XhcSetR32Bit (
- UINTN Register,
- UINT32 BitMask
- );
-
-/**
- Clears bits as per the enabled bit positions in the mask.
-
- @param[in, out] Register UINTN register
- @param[in] BitMask 32-bit mask
-**/
-VOID
-XhcClearR32Bit (
- IN OUT UINTN Register,
- IN UINT32 BitMask
- );
-
-/**
- Initialize USB3 debug port.
-
- This method invokes various internal functions to facilitate
- detection and initialization of USB3 debug port.
-
- @retval RETURN_SUCCESS The serial device was initialized.
-**/
-RETURN_STATUS
-EFIAPI
-USB3Initialize (
- VOID
- );
-
-/**
- Return command register value in XHCI controller.
-
-**/
-UINT16
-GetXhciPciCommand (
- VOID
- );
-
-/**
- Allocate aligned memory for XHC's usage.
-
- @param BufferSize The size, in bytes, of the Buffer.
-
- @return A pointer to the allocated buffer or NULL if allocation fails.
-
-**/
-VOID *
-AllocateAlignBuffer (
- IN UINTN BufferSize
- );
-
-/**
- The real function to initialize USB3 debug port.
-
- This method invokes various internal functions to facilitate
- detection and initialization of USB3 debug port.
-
- @retval RETURN_SUCCESS The serial device was initialized.
-**/
-RETURN_STATUS
-EFIAPI
-USB3InitializeReal (
- VOID
- );
-
-/**
- Submits bulk transfer to a bulk endpoint of a USB device.
-
- @param Handle The instance of debug device.
- @param Direction The direction of data transfer.
- @param Data Array of pointers to the buffers of data to transmit
- from or receive into.
- @param DataLength The length of the data buffer.
- @param Timeout Indicates the maximum time, in millisecond, which
- the transfer is allowed to complete.
-
- @retval EFI_SUCCESS The transfer was completed successfully.
- @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource.
- @retval EFI_INVALID_PARAMETER Some parameters are invalid.
- @retval EFI_TIMEOUT The transfer failed due to timeout.
- @retval EFI_DEVICE_ERROR The transfer failed due to host controller error.
-
-**/
-EFI_STATUS
-EFIAPI
-XhcDataTransfer (
- IN USB3_DEBUG_PORT_HANDLE *Handle,
- IN EFI_USB_DATA_DIRECTION Direction,
- IN OUT VOID *Data,
- IN OUT UINTN *DataLength,
- IN UINTN Timeout
- );
-
-/**
- Initialize usb debug port hardware.
-
- @param Handle Debug port handle.
-
- @retval TRUE The usb debug port hardware configuration is changed.
- @retval FALSE The usb debug port hardware configuration is not changed.
-
-**/
-RETURN_STATUS
-EFIAPI
-InitializeUsbDebugHardware (
- IN USB3_DEBUG_PORT_HANDLE *Handle
- );
-
-/**
- Return USB3 debug instance address pointer.
-
-**/
-EFI_PHYSICAL_ADDRESS *
-GetUsb3DebugPortInstanceAddrPtr (
- VOID
- );
-
-/**
- Return USB3 debug instance address.
-
-**/
-USB3_DEBUG_PORT_HANDLE *
-GetUsb3DebugPortInstance (
- VOID
- );
-
-#endif //__SERIAL_PORT_LIB_USB__
+/** @file + Debug Port Library implementation based on usb3 debug port. + + Copyright (c) 2014 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __USB3_DEBUG_PORT_LIB_INTERNAL__ +#define __USB3_DEBUG_PORT_LIB_INTERNAL__ + +#include <Uefi.h> +#include <Base.h> +#include <IndustryStandard/Usb.h> +#include <Library/IoLib.h> +#include <IndustryStandard/Pci.h> +#include <Library/PcdLib.h> +#include <Library/UefiLib.h> +#include <Library/UefiBootServicesTableLib.h> +#include <Library/MemoryAllocationLib.h> +#include <Library/DebugLib.h> +#include <Library/BaseMemoryLib.h> +#include <Library/BaseLib.h> +#include <Library/TimerLib.h> +#include <Library/DebugCommunicationLib.h> +#include <Library/PciLib.h> + +// +// USB Debug GUID value +// +#define USB3_DBG_GUID \ + { \ + 0xb2a56f4d, 0x9177, 0x4fc8, { 0xa6, 0x77, 0xdd, 0x96, 0x3e, 0xb4, 0xcb, 0x1b } \ + } + +// +// The state machine of usb debug port +// +#define USB3DBG_NO_DBG_CAB 0 // The XHCI host controller does not support debug capability +#define USB3DBG_DBG_CAB 1 // The XHCI host controller supports debug capability +#define USB3DBG_ENABLED 2 // The XHCI debug device is enabled +#define USB3DBG_NOT_ENABLED 4 // The XHCI debug device is not enabled +#define USB3DBG_UNINITIALIZED 255 // The XHCI debug device is uninitialized + +#define USB3_DEBUG_PORT_WRITE_MAX_PACKET_SIZE 0x08 + +// +// MaxPacketSize for DbC Endpoint Descriptor IN and OUT +// +#define XHCI_DEBUG_DEVICE_MAX_PACKET_SIZE 0x400 + +#define XHCI_DEBUG_DEVICE_VENDOR_ID 0x0525 +#define XHCI_DEBUG_DEVICE_PRODUCT_ID 0x127A +#define XHCI_DEBUG_DEVICE_PROTOCOL 0xFF +#define XHCI_DEBUG_DEVICE_REVISION 0x00 + +#define XHCI_BASE_ADDRESS_64_BIT_MASK 0xFFFFFFFFFFFF0000ULL +#define XHCI_BASE_ADDRESS_32_BIT_MASK 0xFFFF0000 + +#define PCI_CAPABILITY_ID_DEBUG_PORT 0x0A +#define XHC_HCCPARAMS_OFFSET 0x10 +#define XHC_CAPABILITY_ID_MASK 0xFF +#define XHC_NEXT_CAPABILITY_MASK 0xFF00 + +#define XHC_HCSPARAMS1_OFFSET 0x4 // Structural Parameters 1 +#define XHC_USBCMD_OFFSET 0x0 // USB Command Register Offset +#define XHC_USBSTS_OFFSET 0x4 // USB Status Register Offset +#define XHC_PORTSC_OFFSET 0x400 // Port Status and Control Register Offset + +#define XHC_USBCMD_RUN BIT0 // Run/Stop +#define XHC_USBCMD_RESET BIT1 // Host Controller Reset + +#define XHC_USBSTS_HALT BIT0 + +// +// Indicate the timeout when data is transferred in microsecond. 0 means infinite timeout. +// +#define DATA_TRANSFER_WRITE_TIMEOUT 0 +#define DATA_TRANSFER_READ_TIMEOUT 50000 +#define DATA_TRANSFER_POLL_TIMEOUT 1000 +#define XHC_DEBUG_PORT_1_MILLISECOND 1000 +// +// XHCI port power off/on delay +// +#define XHC_DEBUG_PORT_ON_OFF_DELAY 100000 + +// +// USB debug device string descriptor (header size + unicode string length) +// +#define STRING0_DESC_LEN 4 +#define MANU_DESC_LEN 12 +#define PRODUCT_DESC_LEN 40 +#define SERIAL_DESC_LEN 4 + +// +// Debug Capability Register Offset +// +#define XHC_DC_DCID 0x0 +#define XHC_DC_DCDB 0x4 +#define XHC_DC_DCERSTSZ 0x8 +#define XHC_DC_DCERSTBA 0x10 +#define XHC_DC_DCERDP 0x18 +#define XHC_DC_DCCTRL 0x20 +#define XHC_DC_DCST 0x24 +#define XHC_DC_DCPORTSC 0x28 +#define XHC_DC_DCCP 0x30 +#define XHC_DC_DCDDI1 0x38 +#define XHC_DC_DCDDI2 0x3C + +#define TRB_TYPE_LINK 6 + +#define ERST_NUMBER 0x01 +#define TR_RING_TRB_NUMBER 0x100 +#define EVENT_RING_TRB_NUMBER 0x200 + +#define ED_BULK_OUT 2 +#define ED_BULK_IN 6 + +#define XHC_LOW_32BIT(Addr64) ((UINT32)(((UINTN)(Addr64)) & 0xFFFFFFFF)) +#define XHC_HIGH_32BIT(Addr64) ((UINT32)(RShiftU64((UINT64)(UINTN)(Addr64), 32) & 0xFFFFFFFF)) +#define XHC_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit))) + +// +// Endpoint Type (EP Type). +// +#define ED_NOT_VALID 0 +#define ED_ISOCH_OUT 1 +#define ED_BULK_OUT 2 +#define ED_INTERRUPT_OUT 3 +#define ED_CONTROL_BIDIR 4 +#define ED_ISOCH_IN 5 +#define ED_BULK_IN 6 +#define ED_INTERRUPT_IN 7 + +// +// 6.4.5 TRB Completion Codes +// +#define TRB_COMPLETION_INVALID 0 +#define TRB_COMPLETION_SUCCESS 1 +#define TRB_COMPLETION_DATA_BUFFER_ERROR 2 +#define TRB_COMPLETION_BABBLE_ERROR 3 +#define TRB_COMPLETION_USB_TRANSACTION_ERROR 4 +#define TRB_COMPLETION_TRB_ERROR 5 +#define TRB_COMPLETION_STALL_ERROR 6 +#define TRB_COMPLETION_SHORT_PACKET 13 + +// +// 6.4.6 TRB Types +// +#define TRB_TYPE_NORMAL 1 +#define TRB_TYPE_SETUP_STAGE 2 +#define TRB_TYPE_DATA_STAGE 3 +#define TRB_TYPE_STATUS_STAGE 4 +#define TRB_TYPE_ISOCH 5 +#define TRB_TYPE_LINK 6 +#define TRB_TYPE_EVENT_DATA 7 +#define TRB_TYPE_NO_OP 8 +#define TRB_TYPE_EN_SLOT 9 +#define TRB_TYPE_DIS_SLOT 10 +#define TRB_TYPE_ADDRESS_DEV 11 +#define TRB_TYPE_CON_ENDPOINT 12 +#define TRB_TYPE_EVALU_CONTXT 13 +#define TRB_TYPE_RESET_ENDPOINT 14 +#define TRB_TYPE_STOP_ENDPOINT 15 +#define TRB_TYPE_SET_TR_DEQUE 16 +#define TRB_TYPE_RESET_DEV 17 +#define TRB_TYPE_GET_PORT_BANW 21 +#define TRB_TYPE_FORCE_HEADER 22 +#define TRB_TYPE_NO_OP_COMMAND 23 +#define TRB_TYPE_TRANS_EVENT 32 +#define TRB_TYPE_COMMAND_COMPLT_EVENT 33 +#define TRB_TYPE_PORT_STATUS_CHANGE_EVENT 34 +#define TRB_TYPE_HOST_CONTROLLER_EVENT 37 +#define TRB_TYPE_DEVICE_NOTIFI_EVENT 38 +#define TRB_TYPE_MFINDEX_WRAP_EVENT 39 + +// +// Convert millisecond to microsecond. +// +#define XHC_1_MILLISECOND (1000) +#define XHC_POLL_DELAY (1000) +#define XHC_GENERIC_TIMEOUT (10 * 1000) + +#define EFI_USB_SPEED_FULL 0x0000 ///< 12 Mb/s, USB 1.1 OHCI and UHCI HC. +#define EFI_USB_SPEED_LOW 0x0001 ///< 1 Mb/s, USB 1.1 OHCI and UHCI HC. +#define EFI_USB_SPEED_HIGH 0x0002 ///< 480 Mb/s, USB 2.0 EHCI HC. +#define EFI_USB_SPEED_SUPER 0x0003 ///< 4.8 Gb/s, USB 3.0 XHCI HC. + +// +// Transfer types, used in URB to identify the transfer type +// +#define XHC_CTRL_TRANSFER 0x01 +#define XHC_BULK_TRANSFER 0x02 +#define XHC_INT_TRANSFER_SYNC 0x04 +#define XHC_INT_TRANSFER_ASYNC 0x08 +#define XHC_INT_ONLY_TRANSFER_ASYNC 0x10 + +// +// USB Transfer Results +// +#define EFI_USB_NOERROR 0x00 +#define EFI_USB_ERR_NOTEXECUTE 0x01 +#define EFI_USB_ERR_STALL 0x02 +#define EFI_USB_ERR_BUFFER 0x04 +#define EFI_USB_ERR_BABBLE 0x08 +#define EFI_USB_ERR_NAK 0x10 +#define EFI_USB_ERR_CRC 0x20 +#define EFI_USB_ERR_TIMEOUT 0x40 +#define EFI_USB_ERR_BITSTUFF 0x80 +#define EFI_USB_ERR_SYSTEM 0x100 + +#pragma pack(1) + +// +// 7.6.9 OUT/IN EP Context: 64 bytes +// 7.6.9.2 When used by the DbC it is always a 64 byte data structure +// +typedef struct _ENDPOINT_CONTEXT_64 { + UINT32 EPState : 3; + UINT32 RsvdZ1 : 5; + UINT32 Mult : 2; // set to 0 + UINT32 MaxPStreams : 5; // set to 0 + UINT32 LSA : 1; // set to 0 + UINT32 Interval : 8; // set to 0 + UINT32 RsvdZ2 : 8; + + UINT32 RsvdZ3 : 1; + UINT32 CErr : 2; + UINT32 EPType : 3; + UINT32 RsvdZ4 : 1; + UINT32 HID : 1; // set to 0 + UINT32 MaxBurstSize : 8; + UINT32 MaxPacketSize : 16; + + UINT32 PtrLo; + + UINT32 PtrHi; + + UINT32 AverageTRBLength : 16; + UINT32 MaxESITPayload : 16; // set to 0 + + UINT32 RsvdZ5; // Reserved + UINT32 RsvdZ6; + UINT32 RsvdZ7; + + UINT32 RsvdZ8; + UINT32 RsvdZ9; + UINT32 RsvdZ10; + UINT32 RsvdZ11; + + UINT32 RsvdZ12; + UINT32 RsvdZ13; + UINT32 RsvdZ14; + UINT32 RsvdZ15; +} ENDPOINT_CONTEXT_64; + +// +// 6.4.1.1 Normal TRB: 16 bytes +// A Normal TRB is used in several ways; exclusively on Bulk and Interrupt Transfer Rings for normal and +// Scatter/Gather operations, to define additional data buffers for Scatter/Gather operations on Isoch Transfer +// Rings, and to define the Data stage information for Control Transfer Rings. +// +typedef struct _TRANSFER_TRB_NORMAL { + UINT32 TRBPtrLo; + + UINT32 TRBPtrHi; + + UINT32 Length : 17; + UINT32 TDSize : 5; + UINT32 IntTarget : 10; + + UINT32 CycleBit : 1; + UINT32 ENT : 1; + UINT32 ISP : 1; + UINT32 NS : 1; + UINT32 CH : 1; + UINT32 IOC : 1; + UINT32 IDT : 1; + UINT32 RsvdZ1 : 2; + UINT32 BEI : 1; + UINT32 Type : 6; + UINT32 RsvdZ2 : 16; +} TRANSFER_TRB_NORMAL; + +// +// 6.4.2.1 Transfer Event TRB: 16 bytes +// A Transfer Event provides the completion status associated with a Transfer TRB. Refer to section 4.11.3.1 +// for more information on the use and operation of Transfer Events. +// +typedef struct _EVT_TRB_TRANSFER { + UINT32 TRBPtrLo; + + UINT32 TRBPtrHi; + + UINT32 Length : 24; + UINT32 Completecode : 8; + + UINT32 CycleBit : 1; + UINT32 RsvdZ1 : 1; + UINT32 ED : 1; + UINT32 RsvdZ2 : 7; + UINT32 Type : 6; + UINT32 EndpointId : 5; + UINT32 RsvdZ3 : 3; + UINT32 SlotId : 8; +} EVT_TRB_TRANSFER; + +// +// 6.4.4.1 Link TRB: 16 bytes +// A Link TRB provides support for non-contiguous TRB Rings. +// +typedef struct _LINK_TRB { + UINT32 PtrLo; + + UINT32 PtrHi; + + UINT32 RsvdZ1 : 22; + UINT32 InterTarget : 10; + + UINT32 CycleBit : 1; + UINT32 TC : 1; + UINT32 RsvdZ2 : 2; + UINT32 CH : 1; + UINT32 IOC : 1; + UINT32 RsvdZ3 : 4; + UINT32 Type : 6; + UINT32 RsvdZ4 : 16; +} LINK_TRB; + +// +// TRB Template: 16 bytes +// +typedef struct _TRB_TEMPLATE { + UINT32 Parameter1; + + UINT32 Parameter2; + + UINT32 Status; + + UINT32 CycleBit : 1; + UINT32 RsvdZ1 : 9; + UINT32 Type : 6; + UINT32 Control : 16; +} TRB_TEMPLATE; + +// +// Refer to XHCI 6.5 Event Ring Segment Table: 16 bytes +// +typedef struct _EVENT_RING_SEG_TABLE_ENTRY { + UINT32 PtrLo; + UINT32 PtrHi; + UINT32 RingTrbSize : 16; + UINT32 RsvdZ1 : 16; + UINT32 RsvdZ2; +} EVENT_RING_SEG_TABLE_ENTRY; + +// +// Size: 40 bytes +// +typedef struct _EVENT_RING { + EFI_PHYSICAL_ADDRESS ERSTBase; + EFI_PHYSICAL_ADDRESS EventRingSeg0; + UINT32 TrbNumber; + EFI_PHYSICAL_ADDRESS EventRingEnqueue; + EFI_PHYSICAL_ADDRESS EventRingDequeue; + UINT32 EventRingCCS; +} EVENT_RING; + +// Size: 32 bytes +typedef struct _TRANSFER_RING { + EFI_PHYSICAL_ADDRESS RingSeg0; + UINT32 TrbNumber; + EFI_PHYSICAL_ADDRESS RingEnqueue; + EFI_PHYSICAL_ADDRESS RingDequeue; + UINT32 RingPCS; +} TRANSFER_RING; + +// +// Size: 64 bytes +// +typedef struct _DBC_INFO_CONTEXT { + UINT64 String0DescAddress; + UINT64 ManufacturerStrDescAddress; + UINT64 ProductStrDescAddress; + UINT64 SerialNumberStrDescAddress; + UINT64 String0Length : 8; + UINT64 ManufacturerStrLength : 8; + UINT64 ProductStrLength : 8; + UINT64 SerialNumberStrLength : 8; + UINT64 RsvdZ1 : 32; + UINT64 RsvdZ2; + UINT64 RsvdZ3; + UINT64 RsvdZ4; +} DBC_INFO_CONTEXT; + +// +// Debug Capability Context Data Structure: 192 bytes +// +typedef struct _XHC_DC_CONTEXT { + DBC_INFO_CONTEXT DbcInfoContext; + ENDPOINT_CONTEXT_64 EpOutContext; + ENDPOINT_CONTEXT_64 EpInContext; +} XHC_DC_CONTEXT; + +// +// Size: 16 bytes +// +typedef union _TRB { + TRB_TEMPLATE TrbTemplate; + TRANSFER_TRB_NORMAL TrbNormal; +} TRB; + +/// +/// USB data transfer direction +/// +typedef enum { + EfiUsbDataIn, + EfiUsbDataOut, + EfiUsbNoData +} EFI_USB_DATA_DIRECTION; + +// +// URB (Usb Request Block) contains information for all kinds of +// usb requests. +// +typedef struct _URB { + // + // Transfer data buffer + // + EFI_PHYSICAL_ADDRESS Data; + UINT32 DataLen; + + // + // Execute result + // + UINT32 Result; + // + // Completed data length + // + UINT32 Completed; + // + // Tranfer Ring info + // + EFI_PHYSICAL_ADDRESS Ring; + EFI_PHYSICAL_ADDRESS Trb; + BOOLEAN Finished; + EFI_USB_DATA_DIRECTION Direction; +} URB; + +typedef struct _USB3_DEBUG_PORT_INSTANCE { + UINT8 Initialized; + + // + // The flag indicates debug capability is supported + // + BOOLEAN DebugSupport; + + // + // The flag indicates debug device is ready + // + BOOLEAN Ready; + + // + // The flag indicates the instance is from HOB + // + BOOLEAN FromHob; + + // + // Prevent notification being interrupted by debug timer + // + BOOLEAN InNotify; + + // + // PciIo protocol event + // + EFI_PHYSICAL_ADDRESS PciIoEvent; + + // + // The flag indicates if USB 3.0 ports has been turn off/on power + // + BOOLEAN ChangePortPower; + + // + // XHCI MMIO Base address + // + EFI_PHYSICAL_ADDRESS XhciMmioBase; + + // + // XHCI OP RegisterBase address + // + EFI_PHYSICAL_ADDRESS XhciOpRegister; + + // + // XHCI Debug Register Base Address + // + EFI_PHYSICAL_ADDRESS DebugCapabilityBase; + + // + // XHCI Debug Capability offset + // + UINT64 DebugCapabilityOffset; + + // + // XHCI Debug Context Address + // + EFI_PHYSICAL_ADDRESS DebugCapabilityContext; + + // + // Transfer Ring + // + TRANSFER_RING TransferRingOut; + TRANSFER_RING TransferRingIn; + + // + // EventRing + // + EVENT_RING EventRing; + + // + // URB - Read + // + URB UrbOut; + + // + // URB - Write + // + URB UrbIn; + + // + // The available data length in the following data buffer. + // + UINT8 DataCount; + // + // The data buffer address for data read and poll. + // + EFI_PHYSICAL_ADDRESS Data; +} USB3_DEBUG_PORT_HANDLE; + +#pragma pack() + +/** + Read XHCI debug register. + + @param Handle Debug port handle. + @param Offset The offset of the debug register. + + @return The register content read + +**/ +UINT32 +XhcReadDebugReg ( + IN USB3_DEBUG_PORT_HANDLE *Handle, + IN UINT32 Offset + ); + +/** + Set one bit of the debug register while keeping other bits. + + @param Handle Debug port handle. + @param Offset The offset of the debug register. + @param Bit The bit mask of the register to set. + +**/ +VOID +XhcSetDebugRegBit ( + IN USB3_DEBUG_PORT_HANDLE *Handle, + IN UINT32 Offset, + IN UINT32 Bit + ); + +/** + Write the data to the debug register. + + @param Handle Debug port handle. + @param Offset The offset of the debug register. + @param Data The data to write. + +**/ +VOID +XhcWriteDebugReg ( + IN USB3_DEBUG_PORT_HANDLE *Handle, + IN UINT32 Offset, + IN UINT32 Data + ); + +/** + Verifies if the bit positions specified by a mask are set in a register. + + @param[in, out] Register UINTN register + @param[in] BitMask 32-bit mask + + @return BOOLEAN - TRUE if all bits specified by the mask are enabled. + - FALSE even if one of the bits specified by the mask + is not enabled. +**/ +BOOLEAN +XhcIsBitSet ( + UINTN Register, + UINT32 BitMask + ); + +/** + Sets bits as per the enabled bit positions in the mask. + + @param[in, out] Register UINTN register + @param[in] BitMask 32-bit mask +**/ +VOID +XhcSetR32Bit ( + UINTN Register, + UINT32 BitMask + ); + +/** + Clears bits as per the enabled bit positions in the mask. + + @param[in, out] Register UINTN register + @param[in] BitMask 32-bit mask +**/ +VOID +XhcClearR32Bit ( + IN OUT UINTN Register, + IN UINT32 BitMask + ); + +/** + Initialize USB3 debug port. + + This method invokes various internal functions to facilitate + detection and initialization of USB3 debug port. + + @retval RETURN_SUCCESS The serial device was initialized. +**/ +RETURN_STATUS +EFIAPI +USB3Initialize ( + VOID + ); + +/** + Return command register value in XHCI controller. + +**/ +UINT16 +GetXhciPciCommand ( + VOID + ); + +/** + Allocate aligned memory for XHC's usage. + + @param BufferSize The size, in bytes, of the Buffer. + + @return A pointer to the allocated buffer or NULL if allocation fails. + +**/ +VOID * +AllocateAlignBuffer ( + IN UINTN BufferSize + ); + +/** + The real function to initialize USB3 debug port. + + This method invokes various internal functions to facilitate + detection and initialization of USB3 debug port. + + @retval RETURN_SUCCESS The serial device was initialized. +**/ +RETURN_STATUS +EFIAPI +USB3InitializeReal ( + VOID + ); + +/** + Submits bulk transfer to a bulk endpoint of a USB device. + + @param Handle The instance of debug device. + @param Direction The direction of data transfer. + @param Data Array of pointers to the buffers of data to transmit + from or receive into. + @param DataLength The length of the data buffer. + @param Timeout Indicates the maximum time, in millisecond, which + the transfer is allowed to complete. + + @retval EFI_SUCCESS The transfer was completed successfully. + @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource. + @retval EFI_INVALID_PARAMETER Some parameters are invalid. + @retval EFI_TIMEOUT The transfer failed due to timeout. + @retval EFI_DEVICE_ERROR The transfer failed due to host controller error. + +**/ +EFI_STATUS +EFIAPI +XhcDataTransfer ( + IN USB3_DEBUG_PORT_HANDLE *Handle, + IN EFI_USB_DATA_DIRECTION Direction, + IN OUT VOID *Data, + IN OUT UINTN *DataLength, + IN UINTN Timeout + ); + +/** + Initialize usb debug port hardware. + + @param Handle Debug port handle. + + @retval TRUE The usb debug port hardware configuration is changed. + @retval FALSE The usb debug port hardware configuration is not changed. + +**/ +RETURN_STATUS +EFIAPI +InitializeUsbDebugHardware ( + IN USB3_DEBUG_PORT_HANDLE *Handle + ); + +/** + Return USB3 debug instance address pointer. + +**/ +EFI_PHYSICAL_ADDRESS * +GetUsb3DebugPortInstanceAddrPtr ( + VOID + ); + +/** + Return USB3 debug instance address. + +**/ +USB3_DEBUG_PORT_HANDLE * +GetUsb3DebugPortInstance ( + VOID + ); + +#endif //__SERIAL_PORT_LIB_USB__ |