Table of Contents

Date	Version	Author	Description of Revisions
4/15/2015	0.1	Rajesh Gugulothu & Upender Cherukupally	Release 1.0

Summary

The Zynq-7000 AP SoC has two USB2.0 On-The-Go (OTG) controllers in the Processing System. The OTG controllers can act as USB host or USB Device or dynamically changing roles between host and device. 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 transfers types are Control Transfer, Bulk Transfer, Isochronous transfer and Interrupt transfer. These transfers types are the key abstractions for different applications development on USB with same hardware. The OTG controllers in Zynq-7000 AP SoC supports all the four types of transfers. This techtip explains how to enable all the configuration options, step by step procedure to use the Zynq-7000 AP SoC OTG controller in device mode and make use of bulk transfer type for a serial communication device abstraction using the USB. For application specific commands there are specific commands defined in the form of USB classes. The serial communication device commands are explained in the USB Communication Device Class (CDC) reference.
For complete specifications of USB protocol, class specific specifications refer: http://www.usb.org/developers/docs/

This design example covers:

1. The CDC design example internals
2. How to get and configure all the Zynq-7000 AP SoC Linux kernel and dependent files for the CDC class reference
3. Bare metal CDC solution on Zynq-7000 AP SoC
4. Demonstrating the CDC functionality with Windows as well as Linux host machine

Implementation

Implementation Details
Design Type	PS only
SW Type	Zynq-7000 AP SoC Linux & Zynq-7000 AP SoC Baremetal
CPUs	2 ARM Cortex-A9: SMP Linux and Baremetal configurations
PS Features	DDR3 Cache L1 and L2 Cache OCM Generic Interrupt Controller USB 2.0 OTG Controller
Boards/Tools	ZC702 kit
Xilinx Tools Version	SDK 2015.1 or latest
Other Details	-

Files Provided
Zynq USB CDC Class	Contain folders: Source, SD Card Images and Windows drivers required to follow the procedure below

Design overview:

The design explained in the below steps shows how to develop a USB system and building corresponding executable files for configuring Zynq-7000 AP SoC USB 2.0 OTG controller as a communication class device. This design shows both bare metal software running on the Zynq-7000 target as well as Linux running on Zynq-7000 AP SoC target system. Windows/Linux PC/laptop USB host controller is used for all host functionality.
The following sections describes step by step procedure to configure, develop and build the USB CDC example design using the baremetal and Linux SW running on Zynq-7000 AP SoC.

Figure 1: Zynq-7000 AP SoC USB CDC reference design block diagram

Linux: Step by Step procedure for creating Zynq-7000 AP SoC USB 2.0 controller’s communication device class functionality

This section explains the CDC Abstract Control Model (ACM) Linux gadget driver details, how to configure the Linux source to support serial gadget driver for Zynq-7000 AP SoC USB 2.0. and, also gives step by step procedure to test the Zynq-7000 AP SoC USB 2.0 communication device class functionality on windows and Linux host machines.

CDC ACM Linux gadget driver:

USB CDC ACM is a vendor-independent publicly documented protocol that can be used for emulating serial ports over USB. This allows the device to be registered on a host computer as a serial port (e.g. /dev/ttyACM0 or COM1). Linux has a generic CDC ACM host-side implementation in the kernel module __cdc_acm.ko.This protocol requires two USB interfaces: a data interface which consists of two endpoints (bulk in + bulk out) and a control interface which consists of one interrupt in endpoint. Furthermore, on EP0 the device must implement the class-specific requests defined by the CDC specification. Because this USB protocol is compliant to the CDC/ACM standard on some other operating systems (e.g. Linux, MacOS) the device can work with the default drivers if available/installed.

Configuring and building the Linux Operating System for Zynq-7000 AP SoC

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

Note: This tech tip is developed based on PetaLinux version 2014.4.

• After installing PetaLinux SDK create a project in the PetaLinux installed directory by executing below command
  • “$ petaLinux-create –t project –n <project_name>”.
  Project is created with the user provided name under the PetaLinux installed directory.
• Change the directory to project created directory, which is created above.
• Configure the Linux source with default configuration, by executing following PetaLinux command.
  • “$ petalinux-config -c kernel --defconfig”
• Configure the Linux source to support USB communication device class driver by executing PetaLinux command “$ petalinux-config -c kernel ” and ensure that parameters shown in the below figure are selected in the kernel source tree and save & exit the configuration file.

Figure 2: Linux kernel configuration for the USB device mode CDC ACM support

Figure 3: Linux kernel configuration for the User space driven configuration

• Change the USB device tree node property “dr_mode“ in the device tree source code as “peripheral which controls the mode of the device driver”. Because this tech-tip is intends to configure the Zynq-7000 USB 2.0 controller in device mode. The respective device tree file named as pcw.dtsi can be found under the path “<petalinux_installed_path>/<project_name>/subsystems/linux/configs/device-tree”.

Figure 4: Device Tree entries specific to this design

• With the above changes build the PetaLinux by executing following command
  • “$ petalinux-build”
  which builds the image.ub executable and some other USB communication device class gadget driver support modules.
• Take the u-boot.elf and zynq-fsbl.elf executables from the directory“<petalinux_installed_directory>/<project_name>/images/linux” and create BOOT.BIN using Xilinx SDK 2015.1 or later tool.

SD card images:

copy the following files on to the SD card

• BOOT.BIN which is created in the above section.
• libcomposite.ko file from following path “<petalinux_installed_directory>/<project_name>/build/linux/kernel/xlnx-3.17/drivers/usb/gadget”.
• u_serial.ko file from following path “<petalinux_installed_directory>/<project_name>/build/linux/kernel/xlnx-3.17/drivers/usb/gadget/function".
• usb_f_serial.ko from following path “<petalinux_installed_directory>/<project_name>/build/linux/kernel/xlnx-3.17/drivers/usb/gadget/function".
• usb_f_acm.ko from following path “<petalinux_installed_directory>/<project_name>/build/linux/kernel/xlnx-3.17/drivers/usb/gadget/function".
• g_serial.ko from following path “<petalinux_installed_directory>/<project_name>/build/linux/kernel/xlnx-3.17/drivers/usb/gadget/legacy".
• Image.ub from “<petalinux_installed_directory>/<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 for Linux under the path CDC_Design_files/sd_card_images/Linux of your extracted directory. User can use these images for quick test .

ZC702 board setup:

Follow the below steps to make the test setup.

• Connect the power supply to the ZC702 board. Do not switch the power on.
• Connect an USB Mini-B cable into the Mini USB port J17 labeled USB UART on the ZC702 board and the USB Type-A cable end into an open USB port on the host PC for UART communications.
• Make sure the switches are set as shown in figure below which allows the ZC702 board to boot from the SD-MMC card.

• 
  

  Figure 5: SW16 configuration

  
  

Testing Linux Zynq-7000 AP SoC USB 2.0 Communication device class functionality on Windows host PC:

Follow the below procedure to test the Zynq-7000 AP SoC USB 2.0 OTG controller communication device class functionality when Linux is running on the target board and windows PC as a host.

• Copy the files listed in the SD card images section on to the SD-MMC card.
• Put the SD Card in the SD card slot of the ZC702 board.
• 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.
  Note: This step is required to view debug information or to run the UART Menu-Based Demonstration application.
• Wait until ZC702 board is booted up with u-boot and stop the auto boot process by clicking enter key.
• Type the command "run sdboot" at the u-boot prompt and click enter. 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
• Mount SD card on by typing following command on the Linux prompt

Figure 6: Mounting the SD card

• Insert the following modules in the Linux kernel which enables Communication class device gadget support in the Linux kernel and configures Zynq-7000 AP SoC USB 2.0 as serial communication device.

Figure 7: insmod all the dependent kernel objects

• Now the Zynq-7000 AP SoC USB 2.0 gadget serial device is ready.

Figure 8: Zynq-7000 AP SoC Linux Console after successful installation

• Now connect the USB to micro USB cable to the ZC702 board Micro-B USB connector as shown in the below figure.

Fig 9: ZC702 board setup with micro-USB cable connected

• Host PC tries to enumerates the Zynq-7000 AP SoC USB 2.0 as a communication class device and try to install the appropriate windows driver but it will fails because windows don't have aware of driver for this device and shows a popup windows of Device driver software was not successfully installed. So Install the windows driver for Zynq-7000 AP SoC USB 2.0 device on host machine by following the below procedure.

Installation steps for windows CDC ACM driver

• In the windows host machine, click on the start button.
• Right click on the computer option and select the manage option as show in the below figure 10.

Figure 10: Opening device manager

• In the administrator confirmation wizard, click yes on that then a computer management wizard will opens
• Select the Device Manager option, as highlighted in the below figure 11.

Figure 11: Selecting device manager

• It will lists all the device connected to the system.

• Now Expand the Others tab, and right click on the CDC ACM device, select install/update driver as show in the below figure 12. It will opens How do you want to search for driver software? Page.

Figure 12: Install driver

• Click on the Browse my computer for driver software option and provide the path for CDC ACM driver software folder <working_directory>\CDC_Design_files\Windows_driver and click next.
  Once the driver installation done, a popup of successful installation comes.
• After installing the driver software successfully the Zynq-7000 AP SoC USB 2.0 device is detected as a virtual communication port at the host PC side and on the other side i.e. target side. USB serial gadget driver is registered as /dev/ttyGS0.
• Start the installed UART terminal program on your host PC (e.g.. Tera Term on a Windows PC) with this newly detected virtual COM port.
• Use the UART configuration as: Baud rate = 115200, bits = 8=, parity =none, and stop bits =1.
• In order to send data from the target device we need to use the USB serial gadget drive device file ‘/dev/ttyGS0’. We can use echo command to send the data from the > > device to the windows PC.

Figure 13: command to send the data

• After that you should see the Hello on the virtual communication port (ex: COM21) as shown below figure.

Figure 14: Serial terminal shows the transfer of data successful

• In the similar way if we want to send data from the host computer to the device write some string (ex: Hello) on the virtual terminal (ex: COM21) opened on the host computer.

Note: If entered data in the virtual terminal is not visible then enable the local echo option in the Tera Term settings.

• Read the data at the device side by opening the serial gadget driver device file using following command.

Figure 15: Serial terminal showing the data transfer

Testing Linux Zynq-7000 USB 2.0 Communication device class functionality on Linux host PC:

• The CDC ACM only driver that comes with the Linux kernel is supported on Linux host PC.

• Once the device is attached inspect the log to obtain the device file names used on the host by entering the following command on the terminal window of Linux (Ubuntu) machine.

Figure 16: Inspecting the Log for successful device connection

• The serial communication port get registered as 'ttyACM0' meaning it will show up as '/dev/ttyACM0'.
• In order to send data from the target device we need to use the USB serial gadget driver device file '/dev/ttyGS0'. We can echo command to send data from the device to the Ubuntu host computer.

Figure 17: Serial terminal with test data

• Use the following command to display data received over the USB serial connection from the USB device on the Ubuntu host machine.

Figure 18: Checking the data on ttyACM0

• In the similar way if we want to send data from the host computer to the device we should first send the data on the host by running following command

Figure 19: Sending the data back to target serial port

• read it on the device using following command.

Figure 20: Checking the data on the target

Baremetal software for designing Zynq-7000 AP SoC USB 2.0 controller’s communication device class functionality

Application software development

This section explains about the bare-metal software development and also step by step procedure to build the system to create binaries for Zynq-7000 AP SoC CDC class device.

Application software:

It is a bare-metal software application which configures the Zynq-7000 AP SoC USB 2.0 as CDC class device and Zynq-7000 AP SoC USB 2.0 device appears as virtual serial communication port at the host side system.Whenever host sends some data to Zynq-7000 AP SoC USB 2.0 device through virtual serial communication port the application responds back to host machine with the received data.

Building Application:

After SDK launch the projects can be imported from the design files provided along with this techtip as shown below

• Select File->Import to open an import wizard.
• Select General > Existing Projects into Workspace in the import wizard.
• Select Achieve file and specify the location <working_directory>/CDC_Design_files/source/Bare-metal/Design_files.zip

Note: Download the Design files archive released with this tech tip and extract it under the convenient working directory of your host machine

• The import wizard displays a list of projects that are available to import. This list Includes
  • cdc_application.
  • cdc_application_bsp
  • fsbl
  • fsbl_bsp
  • ZC702_hw_platform
• Select all above project files and click finish.

Figure 21: Importing the SDK projects

• Build the both fsbl and cdc_application projects by right click and selecting Build project option for each project.

Generating Boot File:

This tech-tip contains the cdc_application. elf and fsbl.elf binaries.Below are the steps to create BOOT.bin file.

• Select Xilinx Tools > Create Zynq Boot Image in the SDK menu.

The Create Zynq Boot Image wizard opens.

• Provide the path in the Output BIF file path tab where output.bif file has to be created.
• Provide the fsbl.elf and cdc_application.elf files which are built in the above steps.

Note: Find the fsbl.elf in <SDK Workspace >\fsbl\Debug\fsbl.elf.

• Find the mass_storage.elf in <SDK Workspace>\cdc_application\Debug\cdc_application.elf.

• Provide the output folder path in the Output path tab and Click on Create Image.
• BOOT.bin file will be crated under the path specified in the output path tab.

Note: For quick testing user may use the BOOT.bin file which is provided along with this tech-tip can be found under the path
<working_directory>/CDC_Design_files/sd_card_images/Bare-metal.

Application execution :

Follow the below procedure to test the baremetal Zynq-7000 AP SoC USB 2.0 OTG controller CDC functionality with windows/Linux (Ubuntu) as a host PC.

• Copy the BOOT.bin file which is created in the Generating boot files section on to the SD card.
• Insert the SD on SD card slot of Zynq ZC702 development board.
• Connect the power supply to the ZC702 board. Do not switch power on.
• Connect the USB cable into the Micro-B USB connector on the ZC702 board to windows host PC.
• Make sure the switches are set as shown in figure below which allows the ZC702 board to boot from the SD-MMC card

Figure 22: SW16 configuration

• Switch on the board power.
• After board is booted up with Zynq_fsbl it will handoff the execution control to application present in the next partition of boot image. Then application software configures the Zynq-7000 AP SoC USB 2.0 as a serial communication device. As micro-USB cable is already being connected to the host PC it will enumerates the Zynq-7000 AP SoC USB 2.0 device as a serial communication device and loads appropriate driver for that.

Note: If appropriate drivers are not found then the Zynq-7000 AP SoC USB device will get failed to connect to the host PC.

Testing baremetal Zynq-7000 AP SoC USB 2.0 Communication device class functionality on Windows host PC:

• On the windows host PC side the Zynq-7000 AP SoC USB 2.0 device is detected as serial communication port.
• Start the installed UART terminal program on your host PC (e.g.. Tera Term on a Windows PC) with that newly detected virtual COM port.
• Use the following UART configuration: Baud rate = 115200, bits =8, parity =none, and stop bits =1.

• To send the data from host to target device write a character on the serial terminal (ex: COM20 as shown in the below figure). As soon as the data is received at the Zynq-7000 AP SoC USB device the application running on Zynq-7000 AP SoC will replay back with the entered character.

Figure 23: Testing the data transfer

Testing baremetal Zynq-7000 AP SoC USB 2.0 Communication device class functionality on Linux host PC:

• The CDC ACM only driver that comes with the Linux kernel is supported on Linux host PC.

• Once you attached the device inspect the log to obtain the device file names used on the host by entering the command on the terminal window of Linux (Ubuntu) machine.

Figure 24: Checking the log for the connection

• The serial communication port get registered as 'ttyACM0'.That means it will show up as '/dev/ttyACM0'.

• In order to send the data from Ubuntu host computer to target device use the following command on host computer terminal

After receiving the above sent data at the target device the bare-metal application running on the Zynq-7000 AP SoC target device will respond back with the receiving data. Read the target response using following command on Ubuntu host machine

Figure 25: Testing the data transfer

Known issue:

When the USB controller is configured in device mode, and Vbus voltage is varied such that it crosses the Vbus valid threshold multiple times, the ULPI interface becomes unresponsive.Please follow the AR#61313 for the workaround.