#include <Base.h>
#include <IndustryStandard/Pci.h>
#include <IndustryStandard/Usb.h>
#include <Library/IoLib.h>
#include <Library/PciLib.h>
#include <Library/PcdLib.h>
#include <Library/TimerLib.h>
#include <Library/DebugCommunicationLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/BaseLib.h>
#include <Library/DebugLib.h>

Data Structures
struct	_USB_DEBUG_PORT_DESCRIPTOR

struct	_USB_DEBUG_PORT_REGISTER

struct	_USB_DEBUG_PORT_HANDLE

Macros
#define	SETUP_PID 0x2D

#define	INPUT_PID 0x69

#define	OUTPUT_PID 0xE1

#define	ERROR_PID 0x55

#define	DATA0_PID 0xC3

#define	DATA1_PID 0x4B

#define	DATA2_PID 0x87

#define	MDATA_PID 0x0F

#define	ACK_PID 0xD2

#define	NAK_PID 0x5A

#define	STALL_PID 0x1E

#define	NYET_PID 0x96

#define	PCI_CAPABILITY_ID_DEBUG_PORT 0x0A

#define	USB_DEBUG_PORT_MAX_PACKET_SIZE 0x08

#define	USB_DEBUG_PORT_IN_USE BIT10

#define	USB_DEBUG_PORT_ENABLE BIT28

#define	USB_DEBUG_PORT_OWNER BIT30

#define	USB_PORT_LINE_STATUS_LS 0x400

#define	USB_PORT_LINE_STATUS_MASK 0xC00

#define	USBDBG_NO_DEV 0

#define	USBDBG_NO_DBG_CAB 1

#define	USBDBG_DBG_CAB 2

#define	USBDBG_INIT_DONE 4

#define	USBDBG_RESET 8

Typedefs
typedef struct _USB_DEBUG_PORT_DESCRIPTOR	USB_DEBUG_PORT_DESCRIPTOR

typedef struct _USB_DEBUG_PORT_REGISTER	USB_DEBUG_PORT_REGISTER

typedef struct _USB_DEBUG_PORT_HANDLE	USB_DEBUG_PORT_HANDLE

Functions
RETURN_STATUS EFIAPI	CalculateUsbDebugPortBar (OUT UINT16 DebugPortOffset, OUT UINT8 DebugPortBarNumbar)

RETURN_STATUS EFIAPI	UsbDebugPortIn (IN USB_DEBUG_PORT_REGISTER DebugPortRegister, IN OUT UINT8 Buffer, OUT UINT8 *Length, IN UINT8 Token, IN UINT8 Addr, IN UINT8 Ep, IN UINT8 DataToggle)

RETURN_STATUS EFIAPI	UsbDebugPortOut (IN USB_DEBUG_PORT_REGISTER DebugPortRegister, IN UINT8 Buffer, IN UINT8 Length, IN UINT8 Token, IN UINT8 Addr, IN UINT8 Ep, IN UINT8 DataToggle)

RETURN_STATUS EFIAPI	UsbDebugPortControlTransfer (IN USB_DEBUG_PORT_REGISTER DebugPortRegister, IN USB_DEVICE_REQUEST SetupPacket, IN UINT8 Addr, IN UINT8 Ep, OUT UINT8 Data, IN OUT UINT8 DataLength)

BOOLEAN EFIAPI	NeedReinitializeHardware (IN USB_DEBUG_PORT_HANDLE *Handle)

RETURN_STATUS EFIAPI	InitializeUsbDebugHardware (IN USB_DEBUG_PORT_HANDLE *Handle)

UINTN EFIAPI	DebugPortReadBuffer (IN DEBUG_PORT_HANDLE Handle, IN UINT8 *Buffer, IN UINTN NumberOfBytes, IN UINTN Timeout)

UINTN EFIAPI	DebugPortWriteBuffer (IN DEBUG_PORT_HANDLE Handle, IN UINT8 *Buffer, IN UINTN NumberOfBytes)

BOOLEAN EFIAPI	DebugPortPollBuffer (IN DEBUG_PORT_HANDLE Handle)

DEBUG_PORT_HANDLE EFIAPI	DebugPortInitialize (IN VOID *Context, IN DEBUG_PORT_CONTINUE Function)

Variables
USB_DEVICE_REQUEST	mDebugCommunicationLibUsbGetDebugDescriptor

USB_DEVICE_REQUEST	mDebugCommunicationLibUsbSetDebugFeature

USB_DEVICE_REQUEST	mDebugCommunicationLibUsbSetDebugAddress

USB_DEBUG_PORT_HANDLE	mDebugCommunicationLibUsbDebugPortHandle

Detailed Description

Debug Port Library implementation based on usb debug port.

Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file DebugCommunicationLibUsb.c.

Macro Definition Documentation

◆ ACK_PID

#define ACK_PID 0xD2

Definition at line 29 of file DebugCommunicationLibUsb.c.

◆ DATA0_PID

#define DATA0_PID 0xC3

Definition at line 25 of file DebugCommunicationLibUsb.c.

◆ DATA1_PID

#define DATA1_PID 0x4B

Definition at line 26 of file DebugCommunicationLibUsb.c.

◆ DATA2_PID

#define DATA2_PID 0x87

Definition at line 27 of file DebugCommunicationLibUsb.c.

◆ ERROR_PID

#define ERROR_PID 0x55

Definition at line 24 of file DebugCommunicationLibUsb.c.

◆ INPUT_PID

#define INPUT_PID 0x69

Definition at line 22 of file DebugCommunicationLibUsb.c.

◆ MDATA_PID

#define MDATA_PID 0x0F

Definition at line 28 of file DebugCommunicationLibUsb.c.

◆ NAK_PID

#define NAK_PID 0x5A

Definition at line 30 of file DebugCommunicationLibUsb.c.

◆ NYET_PID

#define NYET_PID 0x96

Definition at line 32 of file DebugCommunicationLibUsb.c.

◆ OUTPUT_PID

#define OUTPUT_PID 0xE1

Definition at line 23 of file DebugCommunicationLibUsb.c.

◆ PCI_CAPABILITY_ID_DEBUG_PORT

#define PCI_CAPABILITY_ID_DEBUG_PORT 0x0A

Definition at line 34 of file DebugCommunicationLibUsb.c.

◆ SETUP_PID

#define SETUP_PID 0x2D

Definition at line 21 of file DebugCommunicationLibUsb.c.

◆ STALL_PID

#define STALL_PID 0x1E

Definition at line 31 of file DebugCommunicationLibUsb.c.

◆ USB_DEBUG_PORT_ENABLE

#define USB_DEBUG_PORT_ENABLE BIT28

Definition at line 38 of file DebugCommunicationLibUsb.c.

◆ USB_DEBUG_PORT_IN_USE

#define USB_DEBUG_PORT_IN_USE BIT10

Definition at line 37 of file DebugCommunicationLibUsb.c.

◆ USB_DEBUG_PORT_MAX_PACKET_SIZE

#define USB_DEBUG_PORT_MAX_PACKET_SIZE 0x08

Definition at line 35 of file DebugCommunicationLibUsb.c.

◆ USB_DEBUG_PORT_OWNER

#define USB_DEBUG_PORT_OWNER BIT30

Definition at line 39 of file DebugCommunicationLibUsb.c.

◆ USB_PORT_LINE_STATUS_LS

#define USB_PORT_LINE_STATUS_LS 0x400

Definition at line 41 of file DebugCommunicationLibUsb.c.

◆ USB_PORT_LINE_STATUS_MASK

#define USB_PORT_LINE_STATUS_MASK 0xC00

Definition at line 42 of file DebugCommunicationLibUsb.c.

◆ USBDBG_DBG_CAB

#define USBDBG_DBG_CAB 2

Definition at line 101 of file DebugCommunicationLibUsb.c.

◆ USBDBG_INIT_DONE

#define USBDBG_INIT_DONE 4

Definition at line 102 of file DebugCommunicationLibUsb.c.

◆ USBDBG_NO_DBG_CAB

#define USBDBG_NO_DBG_CAB 1

Definition at line 100 of file DebugCommunicationLibUsb.c.

◆ USBDBG_NO_DEV

#define USBDBG_NO_DEV 0

Definition at line 99 of file DebugCommunicationLibUsb.c.

◆ USBDBG_RESET

#define USBDBG_RESET 8

Definition at line 103 of file DebugCommunicationLibUsb.c.

Function Documentation

◆ CalculateUsbDebugPortBar()

RETURN_STATUS EFIAPI CalculateUsbDebugPortBar	(	OUT UINT16 *	DebugPortOffset,
		OUT UINT8 *	DebugPortBarNumbar
	)

Calculate the usb debug port bar address.

Parameters

DebugPortOffset	Get usb debug port offset in the usb debug port memory space.
DebugPortBarNumbar	Get the bar number at which usb debug port is located.

Return values

RETURN_UNSUPPORTED	The usb host controller does not supported usb debug port capability.
RETURN_SUCCESS	Get bar and offset successfully.

Definition at line 172 of file DebugCommunicationLibUsb.c.

◆ DebugPortInitialize()

DEBUG_PORT_HANDLE EFIAPI DebugPortInitialize	(	IN VOID *	Context,
		IN DEBUG_PORT_CONTINUE	Function
	)

Initialize the debug port.

If Function is not NULL, Debug Communication Library will call this function by passing in the Context to be the first parameter. If needed, Debug Communication Library will create one debug port handle to be the second argument passing in calling the Function, otherwise it will pass NULL to be the second argument of Function.

If Function is NULL, and Context is not NULL, the Debug Communication Library could a) Return the same handle as passed in (as Context parameter). b) Ignore the input Context parameter and create new handle to be returned.

If parameter Function is NULL and Context is NULL, Debug Communication Library could created a new handle if needed and return it, otherwise it will return NULL.

Parameters

[in]	Context	Context needed by callback function; it was optional.
[in]	Function	Continue function called by Debug Communication library; it was optional.

Returns: The debug port handle created by Debug Communication Library if Function is not NULL.

Definition at line 1062 of file DebugCommunicationLibUsb.c.

◆ DebugPortPollBuffer()

BOOLEAN EFIAPI DebugPortPollBuffer ( IN DEBUG_PORT_HANDLE Handle )

Polls a debug device to see if there is any data waiting to be read.

Polls a debug device to see if there is any data waiting to be read. If there is data waiting to be read from the debug device, then TRUE is returned. If there is no data waiting to be read from the debug device, then FALSE is returned.

Parameters

Handle Debug port handle.

Return values

TRUE	Data is waiting to be read from the debug device.
FALSE	There is no data waiting to be read from the serial device.

Definition at line 944 of file DebugCommunicationLibUsb.c.

◆ DebugPortReadBuffer()

UINTN EFIAPI DebugPortReadBuffer	(	IN DEBUG_PORT_HANDLE	Handle,
		IN UINT8 *	Buffer,
		IN UINTN	NumberOfBytes,
		IN UINTN	Timeout
	)

Read data from debug device and save the data in a buffer.

Reads NumberOfBytes data bytes from a debug device into the buffer specified by Buffer. The number of bytes actually read is returned. If the return value is less than NumberOfBytes, then the rest operation failed. If NumberOfBytes is zero, then return 0.

Parameters

Handle	Debug port handle.
Buffer	Pointer to the data buffer to store the data read from the debug device.
NumberOfBytes	Number of bytes which will be read.
Timeout	Timeout value for reading from debug device. It unit is Microsecond.

Return values

0	Read data failed, no data is to be read.
>0	Actual number of bytes read from debug device.

Definition at line 789 of file DebugCommunicationLibUsb.c.

◆ DebugPortWriteBuffer()

UINTN EFIAPI DebugPortWriteBuffer	(	IN DEBUG_PORT_HANDLE	Handle,
		IN UINT8 *	Buffer,
		IN UINTN	NumberOfBytes
	)

Write data from buffer to debug device.

Writes NumberOfBytes data bytes from Buffer to the debug device. The number of bytes actually written to the debug device is returned. If the return value is less than NumberOfBytes, then the write operation failed. If NumberOfBytes is zero, then return 0.

Parameters

Handle	Debug port handle.
Buffer	Pointer to the data buffer to be written.
NumberOfBytes	Number of bytes to written to the debug device.

Return values

0	NumberOfBytes is 0.
>0	The number of bytes written to the debug device. If this value is less than NumberOfBytes, then the read operation failed.

Definition at line 860 of file DebugCommunicationLibUsb.c.

◆ InitializeUsbDebugHardware()

RETURN_STATUS EFIAPI InitializeUsbDebugHardware ( IN USB_DEBUG_PORT_HANDLE * Handle )

Initialize usb debug port hardware.

reset ehci host controller.
set right port to debug port.
find a usb debug device is attached by getting debug device descriptor.
set address for the usb debug device.
configure the usb debug device to debug mode.

Parameters

Handle Debug port handle.

Return values

TRUE	The usb debug port hardware configuration is changed.
FALSE	The usb debug port hardware configuration is not changed.

Definition at line 603 of file DebugCommunicationLibUsb.c.

◆ NeedReinitializeHardware()

BOOLEAN EFIAPI NeedReinitializeHardware ( IN USB_DEBUG_PORT_HANDLE * Handle )

Check if it needs to re-initialize usb debug port hardware.

During different phases switch, such as SEC to PEI or PEI to DXE or DXE to SMM, we should check whether the usb debug port hardware configuration is changed. Such case can be triggered by Pci bus resource allocation and so on.

Parameters

Handle Debug port handle.

Return values

TRUE	The usb debug port hardware configuration is changed.
FALSE	The usb debug port hardware configuration is not changed.

Definition at line 533 of file DebugCommunicationLibUsb.c.

◆ UsbDebugPortControlTransfer()

RETURN_STATUS EFIAPI UsbDebugPortControlTransfer	(	IN USB_DEBUG_PORT_REGISTER *	DebugPortRegister,
		IN USB_DEVICE_REQUEST *	SetupPacket,
		IN UINT8	Addr,
		IN UINT8	Ep,
		OUT UINT8 *	Data,
		IN OUT UINT8 *	DataLength
	)

Do a usb control transfer by usb debug port.

Parameters

DebugPortRegister	Pointer to the base address of usb debug port register interface.
SetupPacket	The token PID for each USB transaction.
Addr	The usb device address for usb transaction.
Ep	The endpoint for usb transaction.
Data	Pointer to the buffer receiving data.
DataLength	Number of bytes of the received data.

Return values

RETURN_SUCCESS	The IN transaction is executed successfully.
RETURN_INVALID_PARAMETER	The parameters passed in are invalid.
RETURN_DEVICE_ERROR	The IN transaction comes across error.

Definition at line 456 of file DebugCommunicationLibUsb.c.

◆ UsbDebugPortIn()

RETURN_STATUS EFIAPI UsbDebugPortIn	(	IN USB_DEBUG_PORT_REGISTER *	DebugPortRegister,
		IN OUT UINT8 *	Buffer,
		OUT UINT8 *	Length,
		IN UINT8	Token,
		IN UINT8	Addr,
		IN UINT8	Ep,
		IN UINT8	DataToggle
	)

Do a usb IN transaction by usb debug port.

Parameters

DebugPortRegister	Pointer to the base address of usb debug port register interface.
Buffer	Pointer to the buffer receiving data.
Length	Number of bytes of the received data.
Token	The token PID for each USB transaction.
Addr	The usb device address for usb transaction.
Ep	The endpoint for usb transaction.
DataToggle	The toggle bit used at usb transaction.

Return values

RETURN_SUCCESS	The IN transaction is executed successfully.
RETURN_INVALID_PARAMETER	The parameters passed in are invalid.
RETURN_DEVICE_ERROR	The IN transaction comes across error.

Definition at line 264 of file DebugCommunicationLibUsb.c.

◆ UsbDebugPortOut()

RETURN_STATUS EFIAPI UsbDebugPortOut	(	IN USB_DEBUG_PORT_REGISTER *	DebugPortRegister,
		IN UINT8 *	Buffer,
		IN UINT8	Length,
		IN UINT8	Token,
		IN UINT8	Addr,
		IN UINT8	Ep,
		IN UINT8	DataToggle
	)

Do a usb SETUP/OUT transaction by usb debug port.

Parameters

DebugPortRegister	Pointer to the base address of usb debug port register interface.
Buffer	Pointer to the buffer receiving data.
Length	Number of bytes of the received data.
Token	The token PID for each USB transaction.
Addr	The usb device address for usb transaction.
Ep	The endpoint for usb transaction.
DataToggle	The toggle bit used at usb transaction.

Return values

RETURN_SUCCESS	The IN transaction is executed successfully.
RETURN_INVALID_PARAMETER	The parameters passed in are invalid.
RETURN_DEVICE_ERROR	The IN transaction comes across error.

Definition at line 362 of file DebugCommunicationLibUsb.c.

Variable Documentation

◆ mDebugCommunicationLibUsbDebugPortHandle

USB_DEBUG_PORT_HANDLE mDebugCommunicationLibUsbDebugPortHandle

Definition at line 158 of file DebugCommunicationLibUsb.c.

◆ mDebugCommunicationLibUsbGetDebugDescriptor

USB_DEVICE_REQUEST mDebugCommunicationLibUsbGetDebugDescriptor

Initial value:

= {
  0x80,
  USB_REQ_GET_DESCRIPTOR,
  (UINT16)(0x0A << 8),
  0x0000,
  sizeof (USB_DEBUG_PORT_DESCRIPTOR)
}

Definition at line 55 of file DebugCommunicationLibUsb.c.

◆ mDebugCommunicationLibUsbSetDebugAddress

USB_DEVICE_REQUEST mDebugCommunicationLibUsbSetDebugAddress

Initial value:

= {
  0x0,
  USB_REQ_SET_ADDRESS,
  (UINT16)(0x7F),
  0x0000,
  0x0
}

Definition at line 71 of file DebugCommunicationLibUsb.c.

◆ mDebugCommunicationLibUsbSetDebugFeature

USB_DEVICE_REQUEST mDebugCommunicationLibUsbSetDebugFeature

Initial value:

= {
  0x0,
  USB_REQ_SET_FEATURE,
  (UINT16)(0x06),
  0x0000,
  0x0
}

Definition at line 63 of file DebugCommunicationLibUsb.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ACK_PID

◆ DATA0_PID

◆ DATA1_PID

◆ DATA2_PID

◆ ERROR_PID

◆ INPUT_PID

◆ MDATA_PID

◆ NAK_PID

◆ NYET_PID

◆ OUTPUT_PID

◆ PCI_CAPABILITY_ID_DEBUG_PORT

◆ SETUP_PID

◆ STALL_PID

◆ USB_DEBUG_PORT_ENABLE

◆ USB_DEBUG_PORT_IN_USE

◆ USB_DEBUG_PORT_MAX_PACKET_SIZE

◆ USB_DEBUG_PORT_OWNER

◆ USB_PORT_LINE_STATUS_LS

◆ USB_PORT_LINE_STATUS_MASK

◆ USBDBG_DBG_CAB

◆ USBDBG_INIT_DONE

◆ USBDBG_NO_DBG_CAB

◆ USBDBG_NO_DEV

◆ USBDBG_RESET

Function Documentation

◆ CalculateUsbDebugPortBar()

◆ DebugPortInitialize()

◆ DebugPortPollBuffer()

◆ DebugPortReadBuffer()

◆ DebugPortWriteBuffer()

◆ InitializeUsbDebugHardware()

◆ NeedReinitializeHardware()

◆ UsbDebugPortControlTransfer()

◆ UsbDebugPortIn()

◆ UsbDebugPortOut()

Variable Documentation

◆ mDebugCommunicationLibUsbDebugPortHandle

◆ mDebugCommunicationLibUsbGetDebugDescriptor

◆ mDebugCommunicationLibUsbSetDebugAddress

◆ mDebugCommunicationLibUsbSetDebugFeature