1 Revision History


This wiki page complements the 2016.2 version of the Base TRD. For other versions, refer to the Zynq UltraScale+ MPSoC Base TRD overview page.

Change Log:
  • Update all projects, IP and tools versions to 2016.2
  • Add PMU firmware



2 Overview


The Zynq UltraScale+ MPSoC Base Targeted Reference Design (TRD) is an embedded video processing application running on a combination of APU (SMP Linux), RPU (bare-metal) and PL.

The design consists of the following video data paths:
  • Two video capture pipelines:
    • one capturing video from a test pattern generator (TPG) implemented inside the PL
    • the other capturing video from an external HDMI source via FMC daughter card (optional)
  • A memory-to-memory processing pipeline implementing a 2D-convolution filter with programmable coefficients.
  • A display pipeline with two layers, one used for video and the other for a graphical user interface (GUI) rendered by the GPU.

The TRD demonstrates the value of offloading computation intensive tasks like the 2D-convolution filter from the PS onto PL, thereby freeing APU resources. The APU load is plotted on the GUI to compare a pure software vs hardware accelerated implementation. The RPU is used to monitor the live memory throughput of the design by reading the built-in AXI performance monitors (APM) inside the PS. The data is sent to the APU via the OpenAMP communication framework and plotted on the GUI.

This wiki contains information about:
  • How to setup the ZCU102 evaluation board and run the reference design.
  • How to build all the TRD components based on the provided source files via detailed step-by-step tutorials.

Additional material that is not hosted on the wiki:


Note: Certain material in this reference design is separately licensed by third parties and may be subject to the GNU General Public License version 2, the GNU Lesser General License version 2.1, or other licenses.



3 Software Tools and System Requirements


3.1 Hardware


Required:
  • ZCU102 evaluation board (rev B or newer) / power cable
  • Monitor with DisplayPort input supporting one of the following resolutions:
    • 3840x2160 or
    • 1920x1080 or
    • 1280x720
  • Display Port cable (DP certified)
  • USB hub with mouse and keyboard
  • SD card

Optional:
  • Avnet FMC-HDMI-CAM daughter card / HDMI cable
  • HDMI video source with input resolution set to:
    • 1080p60 for 1080p60 display or
    • 720p60 for 720p60 display

3.2 Software Tools


Required:

Optional:

3.3 Licensing


The video Test Pattern Generator IP inside the Vivado project requires a license which can be obtained from here.

Steps to generate the license:
  1. Click on the link mentioned above.
  2. Fill in the login details and proceed.
  3. Click on “Generate Node-Locked License" icon as shown in the picture:
    TPG_lic.jpg
  4. Under system information, give the host details.
  5. Proceed until you get the license agreement and accept it.
  6. The License (.lic file) will be sent to the email-id mentioned in the login details.
  7. Copy the license file locally and give the same path in the SDSOC license manager.

3.4 Compatibility


The reference design has been tested successfully with the following user-supplied components.

DisplayPort Monitor:
Make/Model
Native Resolution
Viewsonic VP2780-4K
3840x2160 (30Hz)
LG 27MU67-B
3840x2160 (30Hz)
Acer S277HK
3840x2160 (30Hz)
Dell U2414H
1920x1080 (60Hz)
GeChic On-Lap1303H
1920x1080 (60Hz)

DisplayPort Cable:
  • Cable Matters DisplayPort Cable-E342987
  • Monster Advanced DisplayPort Cable-E194698



4 Design File Hierarchy


The Zynq UltraScale+ MPSoC Base TRD zip file is released with the source code including PetaLinux BSP, SDSoC and Xilinx SDK projects, and an SD card image that enables the user to run the video demonstration and software application. It also includes the binaries necessary to configure and boot the ZCU102 evaluation board. The top-level directory structure is shown in the figure below.

mpsoc_dir_structure_2016_2.png



5 Installation and Operating Instructions


5.1 Board Setup


Required:
  • Connect power supply to J52.
  • Connect USB mouse and keyboard using a USB hub to J83.
  • Connect DisplayPort cable to P11; connect other end to monitor.
  • Insert SD card (FAT formatted) with binaries copied from TRD_HOME/sdcard directory.
  • Select one of the provided autostart shell scripts based on your desired display resolution and rename it:
    • for 3840x2160 (4K), rename the file autostart_2160p.sh to autostart.sh
    • for 1920x1080, rename the file autostart_1080p.sh to autostart.sh
    • for 1280x720, rename the file autostart_720p.sh to autostart.sh

Optional:
  • Connect FMC-HDMI-CAM to HPC0 FMC slot.
  • Connect HDMI cable to HDMI IN port of FMC-HDMI-CAM; connect other end to HDMI source.
  • Vadj needs to be set to 1.8V (default) for correct operation.
  • Connect micro-USB cable to J83 USB UART connector; use the following settings for your terminal emulator:
    • Baud Rate: 115200
    • Data: 8 bit
    • Parity: None
    • Stop: 1 bit
    • Flow Control: None

Jumpers & Switches:
  • Set boot mode switch to SD boot (SW6[4:1] - on,off,on,off).
  • Configure USB 2.0 jumpers for host mode (default - see ZCU102 eval board user guide).

board_setup.PNG

5.2 Run the Application


Tutorial:
  • Power on the board; make sure INIT_B, done and all power rail LEDs are lit green.
  • After ~30 seconds, the display will turn on and the application will start automatically, targeting the resolution specified in the autostart.sh script (default is 3840x2160).
  • Upon application exit, use the below login and password to log into the framebuffer console:
    root@Xilinx-ZCU102-2016_2 login: root
    password: root
  • The SD card file system is mounted at /media/card
  • To re-start the TRD application type run_video.sh
  • The script prompts user to enter the choice based on the desired target resolution.
    root@Xilinx-ZCU102-2016_2:~# run_video.sh
    ****************************************************
    ** Zynq UltraScale+ MPSoC Base TRD Qt Application **
    ****************************************************
    Select video resolution:
    1 --> 3840x2160
    2 --> 1920x1080
    3 --> 1280x720
    _
  • The user can now control the application from the GUI's control bar (bottom) displayed on the monitor.
    main_display.jpg
  • The following video sources are available:
    • Built-in Test Pattern Generator (TPG); different patterns can be selected
    • HDMI input via FMC-HDMI-CAM daughter card (optional)
  • A 2D convolution filter can be turned on and different filter presets can be selected; the following filter modes are available:
    • OFF - accelerator is disabled/bypassed
    • SW - accelerator is run on A53
    • HW - accelerator is run on PL
  • The video info panel (top left) shows essential settings/statistics.
  • The CPU utilization graph (top right) shows CPU load for each of the four A53 cores.
  • The memory throughput graph (bottom right) shows memory traffic generated by video source, filter and display.
  • The TPG settings panel gives access to advanced TPG controls:
    tpg_settings.jpg
  • The 2D filter settings panel gives access to advanced filter controls:
    2dfilter_settings.jpg



6 Tool Flow Tutorials


This wiki page assumes that the user has already downloaded the Zynq UltraScale+ MPSoC Base TRD zip file and extracted its contents. For reference in the following tutorials, we export TRD_HOME as environment variable.
% export TRD_HOME=</path/to/downloaded/zip-file>/zcu102-base-trd-2016-2

The below figure shows an overview of all the projects provided in this package as well as inter-dependencies and generated output products. The following sections show step-by-step instructions for rebuilding all project components. Note that pre-built components are depicted as dashed lines and therefore the corresponding build steps are optional and can be skipped (see [Optional] marking). The Vivado hardware design is packaged as part of the SDSoC platform and shall therefore be built through the SDSoC tool flow only.

mpsoc_base_trd_project_dependencies_2016_2.png

6.1 Build the Petalinux BSP


The PetaLinux BSP is pre-configured for this reference design application and includes the following components:
  • u-boot bootloader u-boot.elf
  • ARM trusted firmware (ATF) bl31.elf
  • Linux kernel
  • Device tree
  • Linux root file system (rootfs)

The generated file image.ub contains the Linux kernel, devicetree blob, and rootfs in a single FIT image.

Tutorial:
  1. Change the directory to the PetaLinux board support package (BSP)
    % cd $TRD_HOME/apu/petalinux_bsp
  2. Configure all PetaLinux components
    % petalinux-config --oldconfig
  3. Build all PetaLinux components including u-boot, kernel, device tree blob and rootfs
    % petalinux-build
    • The generated SYSROOT contains all system libraries and headers required to compile and link the video_qt2 application and is located at $TRD_HOME/apu/petalinux_bsp/build/linux/rootfs/stage.
    • The generated Linux image binaries will be placed at $TRD_HOME/apu/petalinux_bsp/images/linux.
  4. [Optional] Copy the generated image.ub, u-boot.elf, and bl31.elf binaries into the SDSoC platform's boot directory $TRD_HOME/apu/zcu102_base_trd/boot or use the pre-built versions at the same location.

6.2 Build the APU Video Qt Application


The video Qt application video_app is a Linux application that executes on the APU running in SMP Linux mode. It consists of the following components:
  • Performance monitor client library perfapm-client
  • 2D filter accelerator library filter2d generated through SDSoC
  • Core video library video_lib
  • Graphical user interface (GUI) video_qt2

The application controls the video capture and video processing pipelines implemented in the PL as well as the display pipeline inside the PS via a GUI based on the Qt framework. The video processing function can be either run as pure software algorithm on the APU or as hardware accelerator in the PL. The SDSoC tool is used to generate and instantiate the hardware accelerator using high-level synthesis (HLS) as well as the data motion network and accelerator/DMA drivers. The perfapm-client library receives performance data from the RPU-1 core via the remoteproc/RPMsg frameworks.

Prerequisites:
  1. Ensure the steps mentioned in section 6.1 are executed first.
  2. Set the SYSROOT environment variable, add the Qt host tools directory to your PATH variable, and set up the Qt environment:
    % export SYSROOT=$TRD_HOME/apu/petalinux_bsp/build/linux/rootfs/stage
    % export PATH=$PETALINUX/tools/yocto-sdk/sysroots/x86_64-petalinux-linux/usr/bin/qt5:$PATH
    % source $TRD_HOME/apu/video_app/video_qt2/qmake_set_env.sh

Tutorial:
  1. Launch the SDSoC tool from the console
    % cd $TRD_HOME/apu
    % sdsoc -workspace $TRD_HOME/apu/video_app
  2. Close the Welcome screen and create a new SDSoC project under File -> New -> SDSoC Project.
    • Enter filter2d as project-name.
    • In Target Platform section, click on Other. In Select SDSoC platform directory window, browse to $TRD_HOME/apu/zcu102_base_trd and then click OK.
    • Select OS 'Linux'
    • Check Shared Library box
    • Click Next.
    zc102_base_trd_2016.1_sdsoc_2.png
  3. In Available Templates section, select 2D Filter and click Finish.
    mpsoc_base_trd_2016_2_2dfilter_template.png
  4. In the filter2d SDSoC project tab, under Build Configurations, set the Active Configuration to SDRelease.
    • Make sure the Generate Bitstream and Generate SD Card Image options are checked.
    • Make sure the filter2d_sds function is listed under Hardware Functions and the Clock Frequency is set to 300MHz.
    zcu102_base_trd_2016_1_sdsoc_config.jpg
  5. Right-click on filter2d project and under C/C++ Settings ->Settings section, switch to the Build Artifact tab and set Output prefix to 'lib' and click OK.
    zc102_base_trd_2016.1_sdsoc_5.png
  6. Build the filter2d project with 2D filter in HW:
    • By default, 2d filter in HW is already selected.
    • Right-click on the filter2d project and select Build Project.
    • The generated SD card image will be placed at $TRD_HOME/apu/video_app/filter2d/SDRelease/sd_card.
    • The below figure shows the resource utilization of the PL design.
    mpsoc_base_trd_2016_2_utilization.png
  7. Import the video_app projects:
    • Click File -> Import... -> General -> Existing Projects into Workspace and click Next.
    • Navigate to the $TRD_HOME/apu/video_app directory using the Browse button and click OK.
    • Select the perfapm-client, video_lib and video_qt2 projects.
    • Click Finish.
    zc102_base_trd_2016.1_sdsoc_6.png
  8. Generate Makefile for video_qt2:
    • Right click on the video_qt2 project, navigate to Make Targets -> Build...
    • In Make Targets window, make sure qmake is selected and click Build.
    zc102_base_trd_2016.1_sdsoc_7.png
  9. Build the video_qt2 project:
    • Right click on the video_qt2 project and select Build Project.
    • The video_lib and perfapm-client projects will be built automatically as they are project dependencies of video_qt2.
    • The generated elf file will be placed at $TRD_HOME/apu/video_app/video_qt2/video_qt2.
  10. [Optional] Copy the above binary to the $TRD_HOME/apu/video_app/filter2d/SDRelease/sd_card/bin directory or use the pre-built version of it.
  11. [Optional] Build the filter2d project with the 2D filter in SW:
    • From filter2d project, navigate to 'src' -> 'filter2d_sds.cpp' -> 'filter2d_sds(...)' function. Right click on 'filter2d_sds(...)' function, select Toggle HW/SW.
    • Right-click on the filter2d project and select Clean Project.
    • Right-click on the filter2d project and select Build Project.
    • The generated SD card image will be placed at $TRD_HOME/apu/video_app/filter2d/SDRelease/sd_card.
    zc102_base_trd_2016.1_sdsoc_8.png
  12. IMPORTANT Undefine the MAKEFLAGS environment variable set by the qmake_set_env.sh script at the beginning of this tutorial, otherwise subsequent tutorials will fail
    % unset MAKEFLAGS

6.3 Build the RPU-1 Performance Monitor Server Application


The performance monitor server application perfapm-server is a bare-metal application that executes on RPU-1. The firmware binary is loaded by the APU master at the end of the Linux boot process. RPU-1 and APU establish a communication channel using the OpenAMP framework. RPU-1 gathers performance data like memory throughput from the PS AXI performance monitor (APM) units and sends it across to the APU where the data is received by the perfapm-client library and then visualized on a plotted graph.

Tutorial:
  1. Launch the Xilinx software development kit (XSDK) from the console
    % cd $TRD_HOME/rpu1
    % xsdk -workspace $TRD_HOME/rpu1/perfapm-server
  2. Close the Welcome screen and import the perfapm-server projects.
    • Click File -> Import... -> General -> Existing Projects into Workspace and click Next.
    • Navigate to the $TRD_HOME/rpu1/perfapm-server directory using the Browse button and click OK.
    • Select the perfapm, perfapm-server, perfapm-server_bsp, and zcu102_base_trd_wrapper_hw_platform_0 projects.
    • Click Finish.
    zcu102_base_trd_2016_1_perf_projects.jpg
  3. Build the imported projects:
    • Right-click on the perfapm-server project and select Build Project.
    • The generated elf file will be placed at $TRD_HOME/rpu1/perfapm-server/perfapm-server/Debug/perfapm-server.elf.
  4. [Optional] Copy the above binary into the PetaLinux BSP at $TRD_HOME/apu/petalinux_bsp/components/apps/perfapm_server/data.
    • Follow the steps mentioned in section 6.1 to (re-)generate the PetaLinux components.

6.4 Build the RPU-0 FSBL


The first stage bootloader fsbl is a bare-metal application that executes on RPU-0. It is reponsible for doing basic system initialization and loading (most of) the various processing units with their respective executables as well as the PL bitstream. After the FSBL exits, the remaining processors are released from reset and start executing.

Tutorial:
  1. Launch the Xilinx software development kit (XSDK) from the console
    % cd $TRD_HOME/rpu0
    % xsdk -workspace $TRD_HOME/rpu0/fsbl
  2. Close the Welcome screen and import the fsbl projects.
    • Click File -> Import... -> General -> Existing Projects into Workspace and click Next.
    • Navigate to the $TRD_HOME/rpu0/fsbl directory using the Browse button.
    • Select the fsbl_r5_0, fsbl_r5_0_bsp, and zcu102_base_trd_wrapper_hw_platform projects.
    • Click Finish.
    zcu102_base_trd_2016_1_fsbl_projects.jpg
  3. Build the imported projects:
    • Right-click on the fsbl_r5_0 project and select Build Project.
    • The generated elf file will be placed at $TRD_HOME/rpu0/fsbl/fsbl_r5_0/Debug/fsbl_r5_0.elf.
  4. [Optional] Copy the above binary into the SDSoC platform at $TRD_HOME/apu/zcu102_base_trd/boot.
    • Follow the steps mentioned in section 6.2 to (re-)generate the SD card image.

6.5 Build the RPU-0 Heartbeat Application


The heartbeat application is a FreeRTOS application that executes on RPU-0 after the FSBL has finished. This application is a simple dual task application that demostrates communication between the two tasks by printing messages to the UART1 console.

Tutorial:
  1. Launch the Xilinx software development kit (XSDK) from the console
    % cd $TRD_HOME/rpu0
    % xsdk -workspace $TRD_HOME/rpu0/heartbeat
  2. Close the Welcome screen and import the hearbeat projects.
    • Click File -> Import... -> General -> Existing Projects into Workspace and click Next.
    • Navigate to the $TRD_HOME/rpu0/heartbeat directory using the Browse button.
    • Select the heartbeat, heartbeat_bsp, and zcu102_base_trd_wrapper_hw_platform_0 projects.
    • Click Finish.
    zcu102_base_trd_2016_1_heartbeat_projects.jpg
  3. Build the imported projects:
    • Right-click on the heartbeat project and select Build Project.
    • The generated elf file will be placed at $TRD_HOME/rpu0/heartbeat/heartbeat/Debug/heartbeat.elf.
  4. [Optional] Copy the above binary into the SDSoC platform at $TRD_HOME/apu/zcu102_base_trd/boot.
    • Follow the steps mentioned in section 6.2 to (re-)generate the SD card image.

6.6 Build the PMU Firmware


The pmu_fw application is a bare-metal application that executes on the PMU MicroBlaze. It is loaded by the CSU early on in the boot process before the FSBL executes. The application's primary responsibility is to handle power management.

Tutorial:
  1. Launch the Xilinx software development kit (XSDK) from the console.
    % cd $TRD_HOME/pmu
    % xsdk -workspace $TRD_HOME/pmu/pmu_fw
  2. Close the Welcome screen and import the PMU firmware projects.
    • Click File -> Import... -> General -> Existing Projects into Workspace and click Next.
    • Navigate to the $TRD_HOME/pmu/pmu_fw directory using the Browse button.
    • Select the pmu_fw, pmu_fw_bsp, and zcu102_base_trd_hw_platform projects.
    • Click Finish.
    mpsoc_base_trd_pmu_fw.png
  3. Build the imported projects:
    • Right-click on the pmu_fw project and select Build Project.
    • The generated elf file will be placed at $TRD_HOME/pmu/pmu_fw/pmu_fw/Debug/pmu_fw.elf.
  4. [Optional] Copy the above binary into the SDSoC platform at $TRD_HOME/apu/zcu102_base_trd/boot.
    • Follow the steps mentioned in section 6.2 to (re-)generate the SD card image.



7 Other Information


7.1 Known Issues


  • The board doesn't boot and the INIT_B LED stays red.
    • Frequency: Rare
    • Workaround: Power cycle the board
  • The framebuffer console doesn't comes up with DRM driver reporting below error:
    xilinx-drm amba:xilinx_drm: No connectors reported connected with modes
    [drm] Cannot find any crtc or sizes - going 1024x768
    • Frequency: Rare
    • Workaround: Power cycle the board
  • DRM reports the folowing kernel oops when video Qt application is exited in 1080/720p mode
    vblank wait timed out on crtc 0
    • Frequency: Common
    • Workaround: None - no functional impact
  • Linux boot hangs at
    Uncompressing Kernel Image ... OK
    • Frequency: Rare
    • Workaround: Power cycle the board
  • SDSoC accelerator code runs very slow in pure software implementation when SDDebug configuration is used
    • Frequency: Common
    • Workaround: Set project build configurations to SDRelease which sets sdsoc compiler to optimize most (-O3)
  • Benign SDSoC warnings:
    Unable to determine the memory attributes passed to frm_data_in of function filter2d_sds
    Unable to determine the memory attributes passed to frm_data_out of function filter2d_sds
    • Frequency: Common
    • Workaround: None - can be ignored
  • Linux 'reboot' command not working
    • Frequency: Common
    • Workaround: Power cycle the board
  • At 1080p and 720p resolutions, the mouse cursor disappears when moved too far to the right and/or bottom of the screen
    • Frequency: Common
    • Workaround: Move mouse toward left and/or top until the cursor reappers on the screen
  • HDMI input is not working, GUI displays error message
    FMC not connected
    • Frequency: Common
    • Workaround: Based on AR 67127
      • Connect a cable to the USB-UART port, open a terminal emulator and connect to COM3 of the quad-UART (use the same terminal settings as listed in 5.1) -> the MSP430 System Controller can be controlled through this serial terminal
      • Power up the board without the FMC card plugged in to the HPC0 slot -> VADJ will be set by the MSP430 System Controller to 1.8V (default)
      • Use the MSP430 System Controller to turn off VADJ -> the VADJ_FMC LED will turn off
      • Plug in the FMC card to the HPC0 slot
      • Use the MSP430 System Controller to set VADJ to 1.8V -> the VADJ_FMC LED will turn back on
      • Press the POR_B button to reset and reboot the system

7.2 Limitations


  • The application only supports the following display resolutions: 3840x2160p30, 1920x1080p60, and 1280x720p60.
  • The application does not support audio.
  • HDMI input is only available via Avnet FMC-HDMI-CAM daughter card connected to the HPC0 slot; the on-board HDMI connectors are not used.
  • HDMI input only supports 1920x1080p60 and 1280x720p60 video resolutions and the resolution must match the display resolution.
  • HDMI input does not support HDCP content protected sources.
  • Make sure the DisplayPort cable is plugged in when you power on the board, otherwise the framebuffer console will default to 1024x768 resolution and the application will not start.
  • DP-to-HDMI adapters are not supported, see AR 67462



8 Support


To obtain technical support for this reference design, go to the:
  • Xilinx Answers Database to locate answers to known issues
  • Xilinx Community Forums to ask questions or discuss technical details and issues. Please make sure to browse the existing topics first before filing a new topic. If you do file a new topic, make sure it is filed in the sub-forum that best describes your issue or question e.g. Embedded Linux for any Linux related questions. Please include "ZCU102 Base TRD" and the release version in the topic name along with a brief summary of the issue.