Introduction

DWC3 Xilinx Linux USB driver supports Zynq Ultrascale USB 3.0 IP and Versal Adaptive SoCs USB IPs.

ZynqMP USB 3.0 Controller implements a 5.0 Gbit/s raw transfer rate using 8b/10b encoding. USB 2.0 implements the Hi-Speed mode (HS – 480 Mbit/s), while USB 1.1 implements Low Speed (LS) – 1.5 Mbit/s and Full Speed (FS) – 12 Mbit/s). The USB 3.0 Controller provides one 5.0Gbit/s USB channel using the PS internal GT as PHY.

The Versal adaptive SoC USB controller is based on newer Synopsys IP and is implemented as a USB 2.0 controller.

The Versal Gen 2 SOC has two USB 2.0 controllers and one MMI USB3 DRD IP. MMI USB DRD IP is usb3.1 Gen2 controller which supports SSP (10-Gbps), SuperSpeed(5-Gbps), high-speed(480-Mbps), full-speed(12-Mbps), and low-speed(1.5-Mbps) operation modes.

Table of Contents

HW/IP Features

The ZynqMP USB 3.0 Controller shall provide one 5.0 Gbit/s USB channel using the PS internal GT as the PHY. Refer to the Zynq UltraScale+ Device Technical Reference Manual (UG1085) for USB IP details.

The Versal USB 2.0 controller is compliant with the USB 2.0 specification to support high, full, and low-speed modes in all configurations. It can be configured as a host, a device, or in on-the-go (OTG). Refer to the Versal Adaptive SoC Technical Reference Manual (AM011) for USB IP details.

Features supported in the driver

• The Linux DWC3 driver supports all standard USB controller features.

• For the MMI USB Controller, host mode is validated using a Kingston DataTraveler Max SSP pendrive, and device mode is validated with the mass storage driver. DRD role switching and Type-C flip are not supported.

Missing Features, Known Issues and Limitations

• ZynqMP USB 3.0 controller doesn't support USB 3.0 OTG (On The Go) host/device selection

Important AR links

• USB core reset in Linux can cause issues with USB device connected if it was previously powered in U-boot - AR-72376

• USB3.0 device mode does not work when booting through USB boot mode - AR-72409

• USB 3.0 standalone device driver does not send STALL response for every unsupported command - AR-71925

• USB 3.0 port hangs after plug-in and plug-out cable in gadget mode - AR-76696

• USB DWC3-core getting the clock error message "Failed to get clk 'ref': -2“ - AR-72764

• USB Remote wake-up feature support (2020 release) - AR-76750

• USB Remote wake-up feature support (2021.1 and later release) - AR-76949

Host Mode

ZCU102 board jumper settings for Host mode
J7 - ON
J113 - 1-2
J110 - 2-3

Please refer the below image for jumper settings on ZCU102 board

Open

USB 3.0 Host mode setup snapshot

Open

Kernel Configuration

By enabling the above we need to see the below mentioned Kconfig parameter enabled
CONFIG_USB_DWC3 = y
CONFIG_USB_DWC3_DUAL_ROLE = y
CONFIG_USB_SUPPORT=y
CONFIG_USB_COMMON=y
CONFIG_USB_ARCH_HAS_HCD=y
CONFIG_USB=y
CONFIG_USB_XHCI_HCD=y
CONFIG_USB_XHCI_PLATFORM=y

Devicetree

usb@ff9d0000 {
#address-cells = <0x02>;
#size-cells = <0x02>;
status = "okay";
compatible = "xlnx,zynqmp-dwc3";
reg = <0x00 0xff9d0000 0x00 0x100>;
clock-names = "bus_clk\\0ref_clk";
power-domains = <0x84 0x16>;
resets = <0x03 0x3b 0x03 0x3d 0x03 0x3f>;
reset-names = "usb_crst\\0usb_hibrst\\0usb_apbrst";
reset-gpios = <0xaf 0x01 0x01>;
ranges;
clocks = <0x7b 0x20 0x7b 0x22>;
assigned-clocks = <0x7b 0x20 0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,usb-polarity = <0x00>;
xlnx,ip-name = "psu_usb";
xlnx,usb-reset-mode = <0x00>;
xlnx,usb-board-interface = "custom";
xlnx,tz-nonsecure = <0x01>;
pinctrl-names = "default";
pinctrl-0 = <0xb0>;
phy-names = "usb3-phy";
phys = <0x6a 0x02 0x04 0x00 0x02>;
phandle = <0x74>;

usb@fe200000 {
compatible = "snps,dwc3";
status = "okay";
reg = <0x00 0xfe200000 0x00 0x40000>;
interrupt-parent = <0x0e>;
interrupt-names = "host\\0peripheral\\0otg\\0wakeup";
interrupts = <0x00 0x41 0x04 0x00 0x41 0x04 0x00 0x45 0x04 0x00 0x4b 0x04>;
clock-names = "ref";
snps,quirk-frame-length-adjustment = <0x20>;
snps,resume-hs-terminations;
clocks = <0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,ip-name = "psu_usb_xhci";
xlnx,enable-superspeed = <0x01>;
xlnx,usb-board-interface = "custom";
dr_mode = "host";
snps,usb3_lpm_capable;
maximum-speed = "super-speed";
phandle = <0x75>;
};
};

Test Procedure

Connect the USB 3.0/2.0 pendrive to USB 3.0 capable board and see it getting detected in /dev/sd<x>.

Expected Output

Once Linux boots the below highlighted prints should be visible when we connect the mass storage device

Performance

When Mass Storage device is connected
Device used :
USB 3.0 : HP USB 3.0 16 GB pendrive (idVendor=03f0, idProduct=4840)
USB 3.0 - UASP capable drive - Transcend Storjet 128GB
USB 2.0 : Sandisk Cruzer Blade USB 2.0 8 GB Pendrive (idVendor=0781, idProduct=5567)

Using HDPARM tool

Note : Above results may vary from device to device

When Ethernet device is connected
Device used :
USB 3.0/2.0 : Xilinx ZynqMP RNDIS/Ethernet Gadget

Using Iperf tool (TCP)

Using Iperf tool (UDP)

Note : The above results are taken with LPM mode disabled

Peripheral Mode

ZCU102 jumper settings for Peripheral mode
J7 - OFF
J113 - 1-2
J110 - 1-2

J109- No jumper

Please refer the image below for jumper settings required for peripheral mode on ZCU102 board

Open

USB 3.0 peripheral mode setup snapshot

Open

This document only explains the USB 3.0 peripheral mode configurations for MASS STORAGE gadget or ETHERNET Gadget profiles.

Mass Storage

Kernel Configuration

By enabling the above we need to see the below mentioned Kconfig parameter enabled

CONFIG_CONFIGFS_FS=y
CONFIG_USB_MASS_STORAGE=m

Please find the required .ko files in the paths mentioned below:
linux-xlnx/drivers/usb/gadget/legacy/g_mass_storage.ko

Devicetree :

Example Device tree node:
usb@ff9d0000 {
#address-cells = <0x02>;
#size-cells = <0x02>;
status = "okay";
compatible = "xlnx,zynqmp-dwc3";
reg = <0x00 0xff9d0000 0x00 0x100>;
clock-names = "bus_clk\\0ref_clk";
power-domains = <0x84 0x16>;
resets = <0x03 0x3b 0x03 0x3d 0x03 0x3f>;
reset-names = "usb_crst\\0usb_hibrst\\0usb_apbrst";
reset-gpios = <0xaf 0x01 0x01>;
ranges;
clocks = <0x7b 0x20 0x7b 0x22>;
assigned-clocks = <0x7b 0x20 0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,usb-polarity = <0x00>;
xlnx,ip-name = "psu_usb";
xlnx,usb-reset-mode = <0x00>;
xlnx,usb-board-interface = "custom";
xlnx,tz-nonsecure = <0x01>;
pinctrl-names = "default";
pinctrl-0 = <0xb0>;
phy-names = "usb3-phy";
phys = <0x6a 0x02 0x04 0x00 0x02>;
phandle = <0x74>;

usb@fe200000 {
compatible = "snps,dwc3";
status = "okay";
reg = <0x00 0xfe200000 0x00 0x40000>;
interrupt-parent = <0x0e>;
interrupt-names = "host\\0peripheral\\0otg\\0wakeup";
interrupts = <0x00 0x41 0x04 0x00 0x41 0x04 0x00 0x45 0x04 0x00 0x4b 0x04>;
clock-names = "ref";
snps,quirk-frame-length-adjustment = <0x20>;
snps,resume-hs-terminations;
clocks = <0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,ip-name = "psu_usb_xhci";
xlnx,enable-superspeed = <0x01>;
xlnx,usb-board-interface = "custom";
dr_mode = "peripheral";
snps,usb3_lpm_capable;
maximum-speed = "super-speed";
phandle = <0x75>;
};
};

Performance

Using HDPARM tool (Linux Host)
Link Power Management (LPM) mode Enable

Link Power Management (LPM) mode Disable

Testing Procedure

Please use the below settings for configuring USB as MASS STORAGE profile in device mode:

Testing the mass storage functionality by connecting the board to host using the below steps:

1. Connect the cable from board to windows host machine

2. Format the mass storage device that got detected in windows

3. The windows screen shot when we the device gets detected should be as below
   
   

   Open

   

4. The board will be detected as mass storage drive with size 256 MB.

5. Copy some files into the mass storage drive, remove the cable, and then reconnect it. We should be able to see the files that we copied into the drive.

Ethernet Gadget

Kernel Configuration

For the xilinx-v2016.2 and prior tags, apply the following patch.

Open

By enabling the above we need to see the below mentioned Kconfig parameter enabled

CONFIG_CONFIGFS_FS=y
CONFIG_USB_ETH=m
CONFIG_USB_ETH_RNDIS=y

Please find the required .ko files in the paths mentioned below:
linux-xlnx/drivers/usb/gadget/function/g_ether.ko
linux-xlnx/drivers/usb/gadget/function/usb_f_rndis.ko

Devicetree

usb@ff9d0000 {
#address-cells = <0x02>;
#size-cells = <0x02>;
status = "okay";
compatible = "xlnx,zynqmp-dwc3";
reg = <0x00 0xff9d0000 0x00 0x100>;
clock-names = "bus_clk\\0ref_clk";
power-domains = <0x84 0x16>;
resets = <0x03 0x3b 0x03 0x3d 0x03 0x3f>;
reset-names = "usb_crst\\0usb_hibrst\\0usb_apbrst";
reset-gpios = <0xaf 0x01 0x01>;
ranges;
clocks = <0x7b 0x20 0x7b 0x22>;
assigned-clocks = <0x7b 0x20 0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,usb-polarity = <0x00>;
xlnx,ip-name = "psu_usb";
xlnx,usb-reset-mode = <0x00>;
xlnx,usb-board-interface = "custom";
xlnx,tz-nonsecure = <0x01>;
pinctrl-names = "default";
pinctrl-0 = <0xb0>;
phy-names = "usb3-phy";
phys = <0x6a 0x02 0x04 0x00 0x02>;
phandle = <0x74>;

usb@fe200000 {
compatible = "snps,dwc3";
status = "okay";
reg = <0x00 0xfe200000 0x00 0x40000>;
interrupt-parent = <0x0e>;
interrupt-names = "host\\0peripheral\\0otg\\0wakeup";
interrupts = <0x00 0x41 0x04 0x00 0x41 0x04 0x00 0x45 0x04 0x00 0x4b 0x04>;
clock-names = "ref";
snps,quirk-frame-length-adjustment = <0x20>;
snps,resume-hs-terminations;
clocks = <0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,ip-name = "psu_usb_xhci";
xlnx,enable-superspeed = <0x01>;
xlnx,usb-board-interface = "custom";
dr_mode = "peripheral";
snps,usb3_lpm_capable;
maximum-speed = "super-speed";
phandle = <0x75>;
};
};

Performance

Iperf tool (TCP)

Iperf tool (UDP)

Testing Procedure

Please use the below settings for configuring USB as an ETHERNET gadget profile in device mode:

Testing the ethernet gadget by connecting to linux/windows machine:

1. Connect the cable from board to windows/linux host machine

2. Set the ipaddress on device side
   systest# ifconfig usb0 192.168.1.200

3. Set the ipaddress on host side

4. ping host address from device side and the result should be as below mentioned
   ping <host address>

Expected Output:

Open

USB Attached SCSI Protocol(UASP)

Limitation
TCM MODULE USED FOR UASP does not support ATA_12 commands. so user needs to change VID and PID in file drivers/usb/gadget/legacy/tcm_usb_gadget.c as below
#define UAS_VENDOR_ID 0x0bc2
#define UAS_PRODUCT_ID 0xa013

Kernel Configuration

KCONFIG options for UASP profile
CONFIG_TARGET_CORE=y
CONFIG_TCM_FILEIO=y
CONFIG_USB_GADGET=y
CONFIG_USB_LIBCOMPOSITE=y
CONFIG_USB_F_TCM=y
CONFIG_USB_GADGET_TARGET=y
CONFIG_CONFIGFS_FS=y

Devicetree

usb@ff9d0000 {
#address-cells = <0x02>;
#size-cells = <0x02>;
status = "okay";
compatible = "xlnx,zynqmp-dwc3";
reg = <0x00 0xff9d0000 0x00 0x100>;
clock-names = "bus_clk\\0ref_clk";
power-domains = <0x84 0x16>;
resets = <0x03 0x3b 0x03 0x3d 0x03 0x3f>;
reset-names = "usb_crst\\0usb_hibrst\\0usb_apbrst";
reset-gpios = <0xaf 0x01 0x01>;
ranges;
clocks = <0x7b 0x20 0x7b 0x22>;
assigned-clocks = <0x7b 0x20 0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,usb-polarity = <0x00>;
xlnx,ip-name = "psu_usb";
xlnx,usb-reset-mode = <0x00>;
xlnx,usb-board-interface = "custom";
xlnx,tz-nonsecure = <0x01>;
pinctrl-names = "default";
pinctrl-0 = <0xb0>;
phy-names = "usb3-phy";
phys = <0x6a 0x02 0x04 0x00 0x02>;
phandle = <0x74>;

usb@fe200000 {
compatible = "snps,dwc3";
status = "okay";
reg = <0x00 0xfe200000 0x00 0x40000>;
interrupt-parent = <0x0e>;
interrupt-names = "host\\0peripheral\\0otg\\0wakeup";
interrupts = <0x00 0x41 0x04 0x00 0x41 0x04 0x00 0x45 0x04 0x00 0x4b 0x04>;
clock-names = "ref";
snps,quirk-frame-length-adjustment = <0x20>;
snps,resume-hs-terminations;
clocks = <0x7b 0x22>;
xlnx,is-cache-coherent = <0x00>;
xlnx,ip-name = "psu_usb_xhci";
xlnx,enable-superspeed = <0x01>;
xlnx,usb-board-interface = "custom";
dr_mode = "peripheral";
snps,usb3_lpm_capable;
maximum-speed = "super-speed";
phandle = <0x75>;
};
};

Example Device tree node:

Performance

HDPARM Tool (UBUNTU Host)

Test procedure

Connect the USB 3.0 cable to linux PC and perform the steps given below on the device side

Mount the configfs

Create a memory that will be assigned to gadget (here creating memory of 750MB)

Format the memory that just has been created

Assign memory to gadget module

Change max busrt to get maximum performance

Connect device to Host

UbuntuOn performing the steps given above, below prints should be shown on host side on typing "dmesg"