Table of Contents

Document History

Summary

The Zynq® UltraScale+™ MPSoC USB 3.0 controller consists of two independent dual-role device (DRD) controllers. Both can be individually configured to work as host or device at any given time. The USB 3.0 DRD controller provides an eXtensible host controller interface (xHCI) to the system software through the advanced eXtensible interface (AXI) slave interface. An internal DMA engine is present in the controller and it utilizes the AXI master interface to transfer data. There are four primary types of communication defined by the USB protocol, based on which any required application can be built without changing the firmware or underlying hardware for different applications. These transfer types are Control Transfer, Bulk Transfer, Isochronous transfer and Interrupt transfer. Zynq® UltraScale+™ MPSoC USB3.0 controller supports all four types of transfers.This Tech Tip explains how to enable all the configuration options, step by step procedure to use the Zynq® UltraScale+™ MPSoC USB 3.0 controller in device mode and make use of bulk transfer type for mass storage device using the USB 3.0. For complete specifications of USB protocol and class specific specifications refer: http://www.usb.org/developers/docs/
This design covers:

• The USB mass storage device example block diagram and overview
• How to configure all the Zynq® ultrascale +™ MPSoC Linux kernel and dependent files for the mass storage class reference2-16
• Setup to test Zynq® UltraScale+™ MPSoC USB 3.0 mass storage class functionality with Windows as well as Linux host machine

Implementation

Block Diagram

• The design explained in the below figure shows how use Zynq® UltraScale+™ MPSoC USB 3.0 controller (targeted board- ZCU102 running Linux OS) as a mass storage device and it's connection with host machine. Here windows/Linux PC/laptop USB host controller is used for all host functionality.

Figure 1: Zynq ultrascale + MPSoC USB 3.0 mass storage device reference block diagram

Linux:Zynq® UltraScale+™ MPSoC USB 3.0 controller's mass storage device class functionality

This section explains Linux gadget driver support for Zynq® UltraScale+™ MPSoC USB 3.0 controller and how to use these drivers for configuring the Zynq® UltraScale+™ MPSoC USB 3.0 controller as a mass storage device. This section also explains the steps in PetaLinux SDK to configure the Linux kernel, source tree and also steps to build Linux image and Linux kernel modules.
Configuring and building the Linux for Mass storage gadget driver support using PetaLinux SDK:

• Follow the PetaLinux SDK installation user guide in this document to install and configure Petalinux SDK. Execute the steps till the PetaLinux Working Environment Setup section for installing PetaLinux SDK to your Linux machine.

Note:This Tech Tip is developed based on PetaLinux version 2018.1. It recommend to download the PetaLinux installer version 2018.1 from Xilinx website. This example uses the ZCU102 PetaLinux BSP to create a PetaLinux project. For Rev1 board download ZCU102,ES2,Rev1.0 BSP and for Rev B/C/D boards, download ZCU102 BSP from xilinx website.

• After installing PetaLinux SDK create a project in the PetaLinux installed directory by executing $ petalinux-create –t project –n <project_name> -s <path-to-bsp> command
• Above command will create a project with the user provided name under the PetaLinux installed directory. Change the directory to project directory which is created above. $ cd <project_name>
• Configure the Linux source to support USB mass storage gadget driver by executing PetaLinux command $ petalinux-config -c kernel
• Go to Device Drivers -->
  • USB Support -->
    • USB Gadget Support --> enable mass storage and mass storage gadget as shown in figure below.

Figure 2: Linux kernel configuration enable USB for mass storage mode

• Go to File Systems -->
  • Pseudo filesystems --> enable Userspace-driven configuration filesystems as shown in figure below.

Figure 3: Linux kernel configuration to enable userspace driven configuration

• Ensure that parameters shown in the above figures are selected in the kernel source tree. Save and exit the configuration file.
• As this Tech Tip is intends to configure the Zynq® ultraScale+™ MPSoC USB 3.0 controller in device mode. Add below mentioned node at end of system-user.dtsi file present at "<project_name>/project-spec/meta-user/recipes-dt/device-tree/files directory
  "&dwc3_0 {
  dr_mode = "peripheral";
  status = "okay";
  };
• With the above changes in kernel configuration, build petalinux using command "$ petalinux-build". This builds the image.ub executable and some other USB mass storage gadget driver support modules.
• Create BOOT.BIN using petalinux SDK tool, change directory to images/linux (cd images/linux) directory and run below command.
  • $ petalinux-package --boot --fsbl zynqmp_fsbl.elf --pmufw pmufw.elf --atf bl31.elf --u-boot u-boot.elf. This will create BOOT.BIN under images/linux

Preparing SD card:

copy the following files into the SD card

• BOOT.BIN which is created in the above section and present at “<project_name>/images/linux”
• configfs.ko file from following path "libcomposite.ko file from following path “<project_name>/build/tmp/work/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.14-xilinx-v2018.1+gitAUTOINC+4ac76ffacb-r0/image/lib/modules/4.14.0-xilinx-v2018.1/kernel/fs/configfs/"
• libcomposite.ko file from following path “<project_name>/build/tmp/work/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.14-xilinx-v2018.1+gitAUTOINC+4ac76ffacb-r0/image/lib/modules/4.14.0-xilinx-v2018.1/kernel/drivers/usb/gadget/"
• g_mass_storage.ko file from following path “<project_name>/build/tmp/work/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.14-xilinx-v2018.1+gitAUTOINC+4ac76ffacb-r0/image/lib/modules/4.14.0-xilinx-v2018.1/kernel/drivers/usb/gadget/legacy/"
• usb_f_mass_storage.ko from following path “<project_name>/build/tmp/work/zcu102_zynqmp-xilinx-linux/linux-xlnx/4.14-xilinx-v2018.1+gitAUTOINC+4ac76ffacb-r0/image/lib/modules/4.14.0-xilinx-v2018.1/kernel/drivers/usb/gadget/function/"
• Image.ub from “<project_name>/images/linux”.

Note:For user convenience SD card images are provided along with this Tech Tip. Download the design files archive released with this Tech Tip and extract it under the convenient location of host machine. Find the SD card images under the path Zynqmp_mass_storage_design_files_2018_1/ of your extracted directory. For Rev1.0 board copy files from Zynqmp_mass_storage_design_files_2018_1/Rev_1_0_prebuilt_images on to SD card and for Rev B/C/D boards, copy files from Zynqmp_mass_storage_design_files_2018_1/Rev_BCD_prebuilt_images on to SD card. Refer to appendix A for more information about design files.

ZCU102 Board Setup:

• Connect the power supply to the ZCU102 board(Rev1.0 /B/C/D). Do not switch the power on.
• Connect the Micro USB cable into the ZCU102 Board Micro USB port J83, and the other end into an open USB 3.0 port on the host Machine as shown in figure below.

Figure 4: ZCU102 board setup in device mode

• Make sure the switches (SW6) are set as shown in figure below which allows the ZCU102 board to boot from the SD-MMC card.
• Figure 6 shows SD boot mode settings for ZCU102 Rev-B/C/D board

Figure 5: SD boot mode switch setting for ZCU102 board

• Figure 6 shows SD boot mode settings for ZCU102 Rev1.0 baord

Figure 6: SD boot mode switch setting for ZCU102 Rev1.0 board

• To operate board in device mode, OFF J7 jumper as shown in board figure 4 (ZCU102 board setup in device mode).

Testing Linux Zynq® UltraScale+™ MPSoC USB 3.0 mass storage device functionality on Windows host PC:

• Load the SD card into the ZCU102 board, in the J100 connector
• Power on the board.
• Start the installed UART terminal program on your host PC (e.g.. Tera Term on a Windows PC).
• Use the following UART configuration: Baud rate = 115200, bits=8, parity=none, and stop bits =1. For UART-0, select COM port with interface-0
• Board will start booting with Linux and after few seconds Linux prompt will be appeared on the UART terminal program running on your host PC.
• Petalinux console login details.
  • user : root
  • password: root
• Use below command to mount the SD card onto target board.
  • $mount /dev/mmcblk0p1 /mnt/
  • cd /mnt/
• Insert the following modules in the Linux kernel which enables mass storage gadget support in the Linux and create disk image of 256MB by executing following commands as shown.
  • Insert the "insmod configfs.ko" module incase if you are using Rev-B/Rev-C/Rev-D boards.
  • insmod libcomposite.ko
  • insmod usb_f_mass_storage.ko
  • dd if=/dev/zero of=/tmp/test.img bs=1M count=256
  • insmod g_mass_storage.ko file=/tmp/test.img removable=1
• Now connect USB3.0 cable between ZCU102 board and host machine. USB 3.0 type A male side end to host machine USB3.0 port and Micro B male cable end to USB3.0 connector (J96) on ZCU102 board as shown in figure 4.
• Above inserted modules configures the Zynq® UltraScale+™ MPSoC USB 3.0 as a mass storage device. When it is detected as mass storage device, host PC will install all the required drivers on the host side(make sure that you are connected to network). A 256MB size of disk image will be mounted on the host pc.
• In case of windows host PC a Microsoft windows disk formatting wizard gets popped up. Click on Format disk and start formatting the disk. After completion of formatting disk perform the read and write operations like file copy, update and open etc from host PC to disk pace created vice versa.

Figure 7: Windows disk format wizard

• In case of Linux (Ubuntu) host PC the Zynq® UltraScale+™ MPSoC USB 3.0 appears as a mass storage device of 256MB. Perform read and write operations from Linux PC to the disk space created vice versa.

Appendix A: Design File structure

Zynqmp_mass_storage_design_files_2018_1.zip

• Zynqmp_mass_storage_design_files_2018_1
  Rev_1_0_prebuilt_images
  • BOOT.BIN
  • image.ub
  • configfs.ko
  • libcomposite.ko
  • g_mass_storage.ko
  • usb_f_mass_storage.ko
• Rev_BCD_prebuilt_images : Image for Rev-B/Rev-C/Rev-D Prod silicon boards
  • BOOT.BIN
  • image.ub
  • configfs.ko
  • libcomposite.ko
  • g_mass_storage.ko
  • usb_f_mass_storage.ko