This page demonstrate the overview of how to debug PS USB controller on Versal & ZynqMP platforms.

Basic checks before debugging further

Observing the failure:

Host mode - Run the below command to check whether pendrive detected or not.

lsusb

Device mode - Need to check this below node is created or not

/sys/class/udc/*/uevent

Diagnosis:

Kernel boot log -- Check the kernel boot logs is there any suspicious logs (dumps) are there or not.
Kernel Config -- Check the corresponding kernel configs for USB mode : Versal Linux USB Device Driver Examples
Device Tree -- Check the corresponding Device tree changes for USB mode : Versal Linux USB Device Driver Examples
Check the USB jumper settings -- Check the corresponding USB mode jumper settings : Versal Linux USB Device Driver Examples

Guidelines on debugging USB runtime failures

Check hardware design
USB driver logs
Dynamic debug
ftrace (function tracer)
USB register dump
USB protocol analyzer trace

USB Hardware Design

Review schematics
Review PCB layout - Refer to Xilinx pcb guidelines recommendations

ZynqMP - https://www.xilinx.com/support/documentation/user_guides/ug583-ultrascale-pcb-design.pdf#USB 2.0

Versal - https://www.xilinx.com/support/documentation/user_guides/ug863-versal-pcb-design.pdf#USB 2.0

USB driver logs

Kernel USB drivers print error messages when USB behaves abnormally:

Error messages
Kernel crash dump

These messages might be the first hint of an issue, it can be cross checked.

Dynamic debug

Another useful debugging method is with dynamic debugging. By default driver stack has a lot of dynamic debug prints added . The prints are added using dev_dbg(). These prints are not enabled by default. They needs to be enabled using the below for dynamic debug

Dynamically enable/disable kernel debug code at runtime to obtain kernel debug log:

pr_debug()/dev_dbg0()

print_hex_dump_debug()/print_hex_dump_bytes()

Benefits:

Almost no overhead when log code is not enabled.
Turn on/off debug log at runtime.
No need to recompile the kernel.

Debugfs control example

mount -t debugfs none /sys/kernel/debug/
echo 8 > /proc/sys/kernel/printk
echo -n 'file drivers/usb/dwc3/otg.c +p' > /sys/kernel/debug/dynamic_debug/control
echo -n 'file drivers/usb/core/hub.c +p' > /sys/kernel/debug/dynamic_debug/control
echo -n 'file drivers/usb/dwc3/core.c +p' > /sys/kernel/debug/dynamic_debug/control
echo “file xxx.c +p” >  /sys/kernel/debug/dynamic_debug/control
echo “file dwc3.c line 1603 +p” >  /sys/kernel/debug/dynamic_debug/control
echo “file drivers/usb/core/* +p” >  /sys/kernel/debug/dynamic_debug/control
echo “file xxx.c -p” >  /sys/kernel/debug/dynamic_debug/control

The below method can also be used for enabling dynamic debug for a range of files present in a folder

echo 8 > /proc/sys/kernel/printk
echo -n "file drivers/usb/* +p" > /sys/kernel/debug/dynamic_debug/control

Ftrace

It is quite common for USB to enter into issues. The easiest way of debugging the host and Gadget mode drivers is using the trace. Using tracers we can capture the live debug data.

Below Kernel configurations need to be enabled for ftrace usage

CONFIG_FUNCTION_TRACER=y
CONFIG_DYNAMIC_FTRACE=y
CONFIG_FUNCTION_GRAPH_TRACER=y
CONFIG_HAVE_FUNCTION_TRACER=y
CONFIG_HAVE_DYNAMIC_FTRACE=y
CONFIG_HAVE_FUNCTION_GRAPH_TRACER=y

Ftrace usage:

Please run this below commands after booting the board

HOST Mode:

GADGET Mode:

Capturing the Trace:

The enabled trace can be captured using the below command

Deleting the trace:

Register dump

Guidelines to Debug USB PHY issues (ULPI PHY validation)

In ZynqMP/Versal platforms, GUSB2PHYACC_ULPI (0xfe20c280) is provided to send TX CMDs to the ULPI phy from Dwc3 controller. This below is the details of the register

EXAMPLE:

The below is the sequence to read the Vendor/Product ID from the attached ULPI phy.

Write 0xFE20C280 with the below information

REGADDR = 0x00 (Vendor ID offset of the ULPI phy)
REGWR = 0 (Since we are reading the vendor id)
NEWREGREQ = 1 (Always 1 for read/write

Now read the register and see the REGDATA field for the returned information. For SMSC3320 0x01000024 is returned. Decoding the returned value.

REGDATA = Returned information from ULPI phy (0x24)
VSTSDONE =1 (this should be set to 1 if properly read)

GUSB2PHYCFG (Global USB2 PHY Configuration Register)

This register is used for controlling the ULPI phy from DWC3 controller

Register Name(GUSB2PHYCFG )	Description

Register Name(GUSB2PHYCFG )	Description
GUSB2PHYCFG.PHYSOFTRST	This bit is used to drive ULPI phy reset signal in Versal. For ZynqMp this is dummy.
GUSB2PHYCFG.ULPIEXTVBUSDRV	this bit is used to update ULPI OTG Control register[bit 6] bit. Some of the ULPI Phys like USB3340 requires this bit to be set for normal USB operation
GUSB2PHYCFG. ULPIAUTORES	This bit updates the ULPI InterfaceConrtol Register[bit 4]. This enables the ULPI phy to auto-resume when suspended.
GUSB2PHYCFG.XCVRDLY	This bit is used in both ZynqMp/Versal platforms to add delay between the assertion of the ULPI Transceiver Select signal (for HS) and the assertion of the TxValid signal during a HS Chirp. This delay is useful for some ULPI Phys like USB3340. The delay is inserted after selecting ULPI transceiver selection (like FS/HS) and requesting TXValid signal to the ULPI phy for starting a HS Chirp reset sequence.
GUSB2PHYCFG.SUSPENDUSB20	This bit enables the USB2.0 PHY to enter Suspend mode if Suspend conditions are valid. This bit updates the ULPI phy Function Ctrl[bit 6].

Significance of usb2_phy_reset (Available only in Versal platforms)

usb3_phy_reset is a part of USB vendor registers available in versal platform. This bit masks the ULPI phy reset signal coming out from DWC3 controller from reaching the ULPI phy. By default, this mask is set to "1" allowing the ULPI reset signal reaching the ULPI phy.

usb2_phy_reset → "1" . Allows the ULPI phy reset signal reaching the ULPI phy

usb2_phy_reset → "0". Masks the ULPI phy reset signal from reaching to the ULPI phy.

Common Issues with ULPI phy

It is quite common for many clients to modify the schematic based on the reference design provided by Xilinx. Most clients tend to use different ULPI Phys other than SMSC3320 (which is recommended by Xilinx) like USB3340/TIUSB1210.

Each ULPI phy has there own configuration requirements. Missing in these configuration steps may cause behaviour incorrect problems.

The below are the basic steps to identify any issue with ULPI phy

Ensure that the ULPI phy RESETN pin got RESET toggle sequence before proceeding with the below steps
In Host/Gadget mode, the very first step is to check if able to access ULPI registers. Please follow the steps mentioned in "How ZynqMp/Versal Dwc3 controller controls the ULPI phy?" section above and see if able to read the ULPI phy registers.
If not able to read the ULPI phy registers then there can be clocking issue. ULPI phy requires 24MHZ crystal oscillator, check if the clock is proper. Also check if the clock out coming from ULPI phy is 60 MHZ.
Some of the ULPI Phys has a configuration to operate in CLK OUT or CLK IN mode. Need to check datasheet and need to properly configure the phy to operate in CLK OUT mode
Some Phys like TIUSB1210 may require ULPI regs OTG CTRL.DrvVbusExternal andOTG CTRL.DrvVbus to operate properly
Check if CPEN ping is getting driven properly
Some of ULPI PHY like USB 3340 may need some delay between dwc3 link selecting the ULPI PHY transceiver(to full/high speed) and dwc3 link issuing command to send HS CHIRP sequence (for Detection of HS device by host). This can be done by setting XCVRDLY.

Disabling Low Power Mode entries in USB 3.0 mode

By default USB 3.0 supports U1/U2 Low Power Mode. The device communicates to the host about the low power mode timeouts (U1timeout and U2timeout) values using the LPM transfers. Allowing LPM modes may be useful when power saving is needed but may be useless if performance is needed.

The LPM entries can be disabled by updating the below

In Gadget mode

Disable the DCTL.INITU2ENA, DCTL.INITU1ENA,DCTL.ACCEPTU2ENA, DCTL.ACCEPTU2ENA

In Host Mode:
Update the PORTPMSC_30.U2_TIMEOUT andPORTPMSC_30.U1_TIMEOUT values to 0xF

USB Register Dumps for all the USB modes

For Host mode

Need to cross check the below details if the device not detected by host,

Check USB ref clock = 250MHz
Check GT lane config
Probe ref clock = 26MHz
Check vbus status
Read GCTRL register for operation mode, got connect event , TD config, SOF is fine(not ok timer issue),
read error register.
Read the port states PORTSC_20(0xFE200420)
Get the USB phy dump.
USB phy details.
USB hot-plug is working or not
Get Serdes lane dump if USB-3.0 is used.

Host_mode_reg_dump

Device_mode_reg_dump

Otg_mode_register_dump

Serdes Lane check registers

USB PHY reset

On ZCU102, USB PHY ULPI reset is connected to the PS_MODE1 pin. ULPI reset are done twice, once in FSBL and then in Linux as part of Serdes driver during PHY initialization.
both resets is done by writing to the PS_MODE register directly.

For custom board, if USB doesn't work, they can try to issue the reset again in the Linux.
If customer uses EMIO 0 as reset pin GPIO, then we can try to do the following sequence on Linux prompt

USB Gadget scripts

MASS STORAGE

RNDIS Gadget

HID gadget

UVC GADGET

UVC_YUV_FORMAT

UVC_MJPEG_FORMAT

COMPOSITE GADGET

AUDIO GADGET

USB compliance mode test procedure

For usb compliance mode test, FSBL is used to bring controller out of reset.

Host mode

Enter into Host mode

a. Bring the core out of reset
b. Set GCTL.PRTCAPDIR = 1

Enter into compliance mode

a.      Put the host controller into compliance mode using the commands below
PORTSC &= 0xFFFEFE1F
PORTSC |= 0x10140
b.      Wait for some time
c.       Set GUSB3PIPECTL.HstPrtCmpl = 1
// This will transmit CP0 pattern

Enter into next compliance pattern

a. Set GUSB3PIPECTL.HstPrtCmpl = 0
b. Set GUSB3PIPECTL.HstPrtCmpl = 1
// This will transmit the next compliance pattern

Device mode

In device mode SS Compliance mode is normally entered and controlled by the remote link partner.

The SS port link enters compliance after failing the first polling sequence after power on. But this can be forcefully tried using the below steps Set DCTL.RUN_STOP = 0

Set DCTL.RUN_STOP = 0
DCTL. ULSTCHNGREQ = 10
Set DCTL.RUN_STOP = 1 here the link should go to compliance mode
Once in compliance ,

alternatively write DCTL. ULSTCHNGREQ = 0 & DCTL. ULSTCHNGREQ = 10 to enter into next compliance mode

Xilinx Wiki

USB Debug Guide for Zynq UltraScale+ and Versal Devices

Table of Contents