path: root/SourceLevelDebugPkg/Library/DebugCommunicationLibUsb3/DebugCommunicationLibUsb3Internal.h

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