ZynqMp USB Stadalone Driver

This page gives an overview of the bare-metal driver support for the Xilinx® LogiCORE™ IP Zynq Ultrascale+ MPSoC USB soft IP. 

Table of Contents

Introduction

This page gives an overview of the Zynq Ultrascale+ MPSoC usbpsu driver which is available as part of the Xilinx Vivado and SDK distribution.
This document explains USB 2.0 & 3.0 peripheral mode standalone configurations for MASS STORAGE and DFU gadgets

For more information,

Please refer to Chapter 31: USB3.0 Controller in ZynqMp TRM which includes links to the official documentation and resource utilization.

Please refer to Chapter 72: USB2.0 Controller in Versal TRM which includes links to the official documentation and resource utilization.

Driver Sources

The source code for the driver is included with the Vitis Unified Software Platform installation and being available in the Xilinx Github repository. 

Driver Name

Path in Vitis

Path in Github

usbpsu

<Vitis Install Directory>/data/embedded/XilinxProcessorIPLib/drivers/usbpsu

https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/usbpsu

Note: To view the sources for a particular release, use the rel-version tag in github.  For example, for the 2020.1 release, the proper version of the code is: https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/usbpsu


The driver source code is organized into different folders.  The table below shows the usbpsu driver source organization. 

Directory
Description

doc

Provides the API and data structure details

data

Driver .tcl and .mdd file

examples

Example applications that show how to use the driver features

src

Driver source files

Driver Implementation

For a full list of features supported by this IP,

ZynqMp: Please refer to Chapter 31: USB3.0 Controller in ZynqMp TRM

Versal: Please refer to Chapter 72: USB2.0 Controller in Versal TRM

Features

Features Controller Support

The ZynqMP USB 3.0 Controller shall provide one 5.0Gbit/s USB channel using the PS internal GT as PHY.

  • Two USB 2.0/3.0 controllers
  • Compliant with USB 3.0 specs
  • Compliant with xHCI standard
  • Supports 5.0 Gbps data rate
  • Support host and device modes
  • Support On The Go (OTG) host/device selection
  • Provide simultaneous operation of the USB2.0 and USB3.0 interfaces where applicable
    • In host mode, as required by the standard for speed negotiation and switching
    • In device mode, statically configured as USB2.0 or USB3.0
  • 64-bit AXI master port with built-in DMA
  • Register programming via AXI and/or APB slave ports
  • Power management features: hibernation mode
  • Support 44-bit address space
  • Supports Link Power Management (LPM) transfers to save power when the bus is idle

Features Driver support

  • Supports device mode only
  • Supports LPM transfers

Known Issues and Limitations

  • Host mode is not supported by the standalone driver
  • Doesn't support hibernation
  • Can't operate simultaneous USB 3.0/ 2.0 modes, need to restart example before changing modes

Example Applications

Refer to the driver examples directory for various example applications that exercise the different features of the driver. Each application is linked in the table below. The following sections describe the usage and expected output of the various applications.  These example applications can be imported into the Vitis IDE from the Board Support Package settings tab. 

Links to Examples

Examples Path:
https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/usbpsu/examples

Test Name

Example Source

Description
USB Mass-Storage Gadget - Poll Mode 

xusb_poll_example.c

This example does a basic read and writes test from the USB drive in polled mode.
USB Mass-Storage Gadget - Interrupt Mode

xusb_intr_example.c

This example does a basic read and writes test from the USB drive in interrupt mode.
USB Dfu: Only ZynqMpxusb_dfu_example.cThis example does firmware download in dfu mode when USB boot mode set. This is a reference example.
USB Composite Gadgetxusb_composite_example.cThis example shows mass storage and hid (keyboard) gadget features in USB composite mode.
ExampleDepandent source files (https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/usbpsu/examples)
xusb_intr_example.cxusb_class_storage.c,xusb_class_storage.h,xusb_ch9_storage.c,xusb_ch9_storage.h,xusb_ch9.c,xusb_ch9.h,xusb_wrapper.c,xusb_wrapper.h
xusb_poll_example.cxusb_class_storage.c,xusb_class_storage.h,xusb_ch9_storage.c,xusb_ch9_storage.h,xusb_ch9.c,xusb_ch9.h,xusb_wrapper.c,xusb_wrapper.h
xusb_dfu_example.cxusb_class_dfu.c,xusb_class_dfu.h,xusb_ch9_dfu.c,xusb_ch9_dfu.h,xusb_ch9.c,xusb_ch9.h,xusb_wrapper.c,xusb_wrapper.h
xusb_composite_example.cxusb_ch9_composite.c,xusb_ch9_composite.h,xusb_class_composite.c,xusb_class_composite.h,xusb_ch9.c,xusb_ch9.h,xusb_wrapper.c,xusb_wrapper.h

Example Application Usage

Mass-Storage: USB Polled/Interrupt mode example

Mass storage profile can be tested by compiling xusbpsu_ch9_storage.c , xusbpsu_ch9_storage.h , xusbpsu_ch9.c , xusbpsu_ch9.h , xusbpsu_class_storage.c , xusbpsu_class_storage.h , xusbpsu_intr_example.c/xusbpsu_poll_example.c 
files together

USB 2.0 Peripheral Mode

The below gives the testing procedure of zynqmp USB standalone example which operates as a mass storage gadget

Testing procedure
  • Download and run the generated USB 2.0 example ELF on board
  • Debug prints you can see on com port(Teraterm/putty)
    the below prints should be seen on com port
  • Connect board to standard host(Windows/Linux)machine USB 2.0 port.
Expected Output
  • You will get a pop-up window on the Window machine for formatting the size 256MB
    After the format complete you can copy a file to the USB device

USB 3.0 Peripheral Mode

The below gives the testing procedure of zynqmp USB standalone example which operates as a mass storage gadget

Testing procedure
  • Download and run the generated USB 3.0 example ELF on board
  • Debug prints you can see on com port(Teraterm/putty)
    the below points should be seen on com port


  • Connect board to standard host(Windows/Linux)machine USB 3.0 port.
Expected Output
  • You will get a pop-up window on the Window machine for formatting the size 256MB
    After the format complete you can copy a file to the USB device

USB Composite Testing

Testing procedure
  • Download and run the generated USB 3.0 example ELF on board
  • Debug prints you can see on com port(Teraterm/putty)
Expected Output

Device Log:

USB Composite Device Start...
Keyboard Unknown class request 0x9
Keyboard Unknown class request 0x9
  • Connect the board to a standard host(Windows/Linux) machine USB port.

Host Log (Linux):

[13539.237627] usb 1-3.3: new high-speed USB device number 14 using xhci_hcd
[13539.254059] usb 1-3.3: config 1 contains an unexpected descriptor of type 0x2, skipping
[13539.254085] usb 1-3.3: config 1 interface 2 altsetting 0 has 1 endpoint descriptor, different from the interface descriptor's value: 0
[13539.254571] usb 1-3.3: New USB device found, idVendor=03fd, idProduct=0200
[13539.254585] usb 1-3.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[13539.254594] usb 1-3.3: Product: USB 2.0 COMPOSITE DEVICE
[13539.254603] usb 1-3.3: Manufacturer: XILINX INC
[13539.254612] usb 1-3.3: SerialNumber: 2A49876D9CC1AA4
[13539.256799] usb-storage 1-3.3:1.4: USB Mass Storage device detected
[13539.257130] scsi6 : usb-storage 1-3.3:1.4
[13539.259039] input: XILINX INC USB 2.0 COMPOSITE DEVICE as /devices/pci0000:00/0000:00:14.0/usb1/1-3/1-3.3/1-3.3:1.5/input/input12
[13539.259621] hid-generic 0003:03FD:0200.0002: input,hidraw0: USB HID v10.01 Keyboard [XILINX INC USB 2.0 COMPOSITE DEVICE] on usb-0000:00:14.0-3.3/input5
[13539.317317] usbcore: registered new interface driver snd-usb-audio
[13540.254219] scsi 6:0:0:0: Direct-Access Xilinx PS USB VirtDisk 1.00 PQ: 0 ANSI: 0 CCS
[13540.255509] sd 6:0:0:0: Attached scsi generic sg1 type 0
[13540.255974] sd 6:0:0:0: [sdc] 204800 512-byte logical blocks: (104 MB/100 MiB)
[13540.256155] sd 6:0:0:0: [sdc] Write Protect is off
[13540.256164] sd 6:0:0:0: [sdc] Mode Sense: 03 00 00 00
[13540.256321] sd 6:0:0:0: [sdc] No Caching mode page found
[13540.256336] sd 6:0:0:0: [sdc] Assuming drive cache: write through
[13540.257404] sd 6:0:0:0: [sdc] No Caching mode page found
[13540.257416] sd 6:0:0:0: [sdc] Assuming drive cache: write through
[13540.258264] sdc: unknown partition table
[13540.259277] sd 6:0:0:0: [sdc] No Caching mode page found
[13540.259290] sd 6:0:0:0: [sdc] Assuming drive cache: write through
[13540.259301] sd 6:0:0:0: [sdc] Attached SCSI removable disk

root@xhdbfarmrkx4:/home/piyushm# mkfs.vfat -I /dev/sdc
mkfs.fat 3.0.26 (2014-03-07)

root@xhdbfarmrkx4:/home/piyushm# mount /dev/sdc /mnt/
root@xhdbfarmrkx4:/home/piyushm# df -h
Filesystem Size Used Avail Use% Mounted on
/dev/sdc 100M 0 100M 0% /mnt
root@xhdbfarmrkx4:/home/piyushm#

USB DFU Testing

The below gives the testing procedure of zynqmp USB DFU example

Testing procedure


On ZCU102 board side

  • Download and run the generated dfu example


On HOST side
On Linux

  • Install dfu-util binaries in linux host. Please refer http://dfu-util.sourceforge.net/build.html
  • Connect DFU device (Alto device running DFU example)
  • dfu-util –l (check our DFU Boot Image downloader)
  • dfu-util –D boot.bin


On Windows
Install Windows driver for DFU devices in host machine

  • Download Zadig tool from http://zadig.akeo.ie/ and install
  • Connect DFU device (Alto device running DFU example)
  • Open zadig and select DFU device and install WinUSB driver




Running dfu-util and downloading files

  • Install DFU utils
  • Launch 'cmd' (make sure your path is that where dfu-util.exe is)
  • dfu-util –l (check our DFU Boot Image downloader)
  • dfu-util –D boot.bin –t 1024
Expected Output

Example Design Architecture

Default Petalinux Design

Performance

The below performance results are observed using CrystalDiskMark tool on windows

USB 2.0:

USB 3.0:

Change Log

2021.2

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2021.2/doc/ChangeLog#L221

2021.1

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2021.1/doc/ChangeLog#L494

2020.2

https://github.com/Xilinx/embeddedsw/blob/xilinx-v2020.2/doc/ChangeLog#L350

2020.1

https://github.com/Xilinx/embeddedsw/blob/xilinx-v2020.1/doc/ChangeLog#L238

2019.2

https://github.com/Xilinx/embeddedsw/blob/xilinx-v2019.2/doc/ChangeLog#L90

2019.1

https://github.com/Xilinx/embeddedsw/blob/xilinx-v2019.1/doc/ChangeLog#L267

2018.3

https://github.com/Xilinx/embeddedsw/blob/release-2018.3/doc/ChangeLog#L307

2018.2

https://github.com/Xilinx/embeddedsw/blob/release-2018.2/doc/ChangeLog#L441

2018.1

https://github.com/Xilinx/embeddedsw/blob/release-2018.1/doc/ChangeLog#L332

2017.3

https://github.com/Xilinx/embeddedsw/blob/release-2017.3/doc/ChangeLog#L881

2017.1

https://github.com/Xilinx/embeddedsw/blob/xilinx-v2017.1/doc/ChangeLog#L406

2016.4

https://github.com/Xilinx/embeddedsw/blob/xilinx-v2016.4/doc/ChangeLog#L1049

2015.4

https://github.com/Xilinx/embeddedsw/blob/xilinx-v2015.4/doc/ChangeLog#L258


Related Links