SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h - edk2 - Git at Google

 /** @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__