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

Table of Contents

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 : https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2069987899

• Device Tree -- Check the corresponding Device tree changes for USB mode : https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2069987899

• Check the USB jumper settings -- Check the corresponding USB mode jumper settings : https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2069987899

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

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

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

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

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

1. REGADDR = 0x00 (Vendor ID offset of the ULPI phy)

2. REGWR = 0 (Since we are reading the vendor id)

3. 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

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

1. Ensure that the ULPI phy RESETN pin got RESET toggle sequence before proceeding with the below steps

2. 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.

3. 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.

4. 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

5. Some Phys like TIUSB1210 may require ULPI regs OTG CTRL.DrvVbusExternal andOTG CTRL.DrvVbus to operate properly

6. Check if CPEN ping is getting driven properly

7. 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,

1. Check USB ref clock = 250MHz

2. Check GT lane config

3. Probe ref clock = 26MHz

4. Check vbus status

5. Read GCTRL register for operation mode, got connect event , TD config, SOF is fine(not ok timer issue),
   read error register.

6. Read the port states PORTSC_20(0xFE200420)

7. Get the USB phy dump.

8. USB phy details.

9. USB hot-plug is working or not

10. 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

1. Enter into Host mode

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

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

1. 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

1. Set DCTL.RUN_STOP = 0

2. DCTL. ULSTCHNGREQ = 10

3. Set  DCTL.RUN_STOP = 1  here the link should go to compliance mode

4. Once in compliance ,

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