Zynq UltraScale+ MPSoC VCU TRD 2019.1 - Run and Build Flow



Table of Contents

1 Overview

The below sections describe the detailed run and build steps for all the TRD components. For the overview, software tools, system requirements, design files, and board setup follow the link below:



2 Run Flow



Please note that the Windows format option can't be used.

NOTE: The SD card file system is mounted at /media/card. Optional storage medium SATA and USB are mounted at /media/sata and /media/usb respectively.

2.1 Graphic User Interface

A QT based graphical user interface (GUI) provides control and monitoring interface. GUI will run on DP only.

NOTE1: QT GUI will work on for VCU TRD Multi-stream design and HDMI Video Capture and HDMI Display with the Audio design.

NOTE2: Make sure monitor is in DP mode when you run the QT GUI app.

Run the below command to launch GUI on Display port when connected.

% run_vcu.sh

The GUI is not supported for HDMI Tx. In HDMI 4kp60 mode, GUI requires additional ~2GB memory bandwidth. If you invoke the GUI cause memory bandwidth issue. So HDMI Tx, use only command line application (vcu_gst_app). The table below provides the supported display interfaces for both GUI and command line application.

Display InterfaceGUICommand Line Application
DisplayPort
HDMINot supported


The figure below shows the home screen of the GUI when only DP is connected.


GUI only supports single stream playback. Supported resolutions are 1080p and 4kp. The supported frame rate for 1080p is 60 fps and 30fps for 4kp. For all multi-stream use case and 4kp60 single stream, the user has to run command line applications.

QT GUI has the following options for the user to select:

Number of Input
This determines the number of active video sources. Only one input source is supported.

Output
This option allows the user to select a sink for the pipeline. Supported output sink types are display port, record, and stream. For the Display Port, the available Codec options are either enc-dec or Pass-through. For Record and Stream Out, the available Codec option is Enc.

Demo Mode


Input Settings
The below figure shows the input settings window with configuration options.


Different configuration options available in the QT pop up window are:

Input Source (Input 1)
The following video sources (4K) are available as part of input video selection:


Codec
The following options are available as part of Codec functionality


Preset
There are six predefined presets. If the user edits any control options preset mode switches to “Custom”.

Profile = Main, Rate Control = CBR, Filler Data = true, QP = Auto, L2 Cache = true, Latency mode = Normal, Low Bandwidth = false, Gop Mode = Basic, B-frame = 0, Slice = 8 and GoP Length = 60 common for all above options.

Please refer to the Supported Encoder Format section for the supported encoder format in this release.


SCD
Enable or Disable SCD in the pipeline


Settings
A user can control the encoder, record and stream out configuration from the GUI, Settings option are enabled when the pipeline is in the stop state. The user can control the encoder parameters when output option is selected as Display port/Record/Stream.


Encoder
This can be either H264 or H265.

Profile
The standard defines a set of capabilities, which are referred to as profiles, targeting specific classes of applications. These are declared as a profile code (profile_idc) and a set of constraints applied in the encoder. This allows a decoder to recognize the requirements to decode that specific stream.
H264 supports baseline, main and high profile. In H265 only main profile is supported.

QP
Quantization in an encoder is controlled by a quantization parameter. It specifies how to generate the QP per coding unit (CU). Two modes are supported-


Rate Control
Constant bitrate (CBR), variable bitrate (VBR) and low-latency are supported. CBR mode generates a constant bit rate that you can predefine. CBR is recommended for limited bandwidth use cases.

Bitrate
Encoding bit rate. In digital multimedia, bit rate often refers to the number of bits used per unit of playback time to represent a continuous medium such as audio or video after source coding (data compression).

B-frame
Short for bi-directional frame, or bi-directional predictive frame, a video compression method used by the MPEG standard. It ranges from 0 to 4.

Slice
The number of slices produced for each frame. Each slice contains one or more complete macroblock/CTU row(s). Slices are distributed over the frame as regularly as possible. If slice-size is defined as well more slices may be produced to fit the slice-size requirement
Range:
4-22 4kp resolution with HEVC codec
4-32 4kp resolution with AVC codec
4-32 1080p resolution with HEVC codec
4-32 1080p resolution with AVC codec

GoP Length
In video coding, a group of pictures, or GOP structure, specifies the order in which intra and inter-frames are arranged. And GoP-length is a length between two Intra frames. The GOP is a collection of successive pictures within a coded video stream. Each coded video stream consists of successive GOPs, from which the visible frames are generated. Its range is from 1 to 1000.

Filler Data
Filler Data NAL units for CBR rate control to maintain constant bitrate throughout the playback. It can be enabled or disabled. It is applicable to CBR mode only.

L2 Cache
Enable or Disable L2Cache buffer in the encoding process.

Latency Mode
Encoder latency mode. It can be normal or sub_frame mode.

Low Bandwidth
If enabled, decrease the vertical search range used for P-frame motion estimation to reduce the bandwidth.

Gop Mode
Group of Pictures mode. It can be Basic, low_delay_p, or low_delay_b.

Record
When Output option is selected as Record, A tab will be enabled in settings window through which user can record the video into the storage medium.


Storage
This option specifies a storage device for the recorded file. The list is dynamically populated based on mounted storage devices. Supported storage devices are SD, USB, and SATA.

Output File Name
Name of the output file. For H264, recorded file get saved as <Source name>_H264_rec_<timestamp>.ts and for H265 it will be <Source name>_H265_rec_<timestamp>.ts

Duration
This option will specify the Recording time duration. It ranges from 1-3 mins.

NOTE: Due to speed and storage constraints it is recommended to use USB/SATA storage devices for the record.

Stream-out
The stream-out panel allows the user to configure streaming parameters.

Stream-out Prerequisites when zcu106 board is connected to host machine:



Sink
Provides sink option for the stream-out. It is set to PS Ethernet.

Host IP
IP address of a computer or other Zynq® UltraScale+™ MPSoC board in which streaming video will be played on. It is set to 192.168.25.89 by default.

IP
This option will show the IP address of the board if the Ethernet link is up. If no Ethernet link is connected then it will show “Not Connected”.

Port
Port number of the Ethernet link. By default, it is set to 5004.

Steps for Stream Out
Here are the steps to get the ZCU106 TRD to play out to VLC:


Audio Settings
The Audio Settings panel allows the user to configure audio parameters.

Note: The Audio Settings are only applicable in-case of HDMI Video Capture and HDMI Display with Audio design.


Enable Audio
Enable or Disable audio in a pipeline. It is set to false by default.
Source 
It can be HDMI or I2S
Render
It can be DP or I2S
Format
The format of the audio. It is set to S24_32LE by default.
Channel
The number of audio channels. It is set to 2 by default.
Sampling Rate
To set the audio sampling rate. It is set to 48000 by default.
Volume
To set the volume level. It is set to 2.0 by default.
Note: To increase volume in DP use below command:


% devmem 0XFD4AC000 32 0xffffffff 


Stream-In
Stream-In panel allows the user to enter a network URL.

Stream-In Prerequisites when 2 ZCU106 boards are connected:

Uri
Provides the network URL to receive the network stream. As an e.g. “udp://192.168.25.89:5004/”.

Steps for Stream Out from one board and Stream In from another board

NOTE: It is recommended to use rev-1.0 or rev-F board.

2.2 GStreamer Application (vcu_gst_app)

The vcu_gst_app is a command line multi-threaded Linux application that uses the vcu_gst_lib interface similar to vcu_qt. The command line application requires an input configuration file (input.cfg) to be provided in the plain text. Refer to the Appendix A - Input Configuration File (input.cfg) for the file format and description.

Before the execution of vcu_gst_app, we need to check the HDMI-Rx or SDI-Rx link status depending on the design. Refer to Appendix B for how to check the HDMI and SDI Link Status.

NOTE: Before execution of vcu_gst_app, we need to run below modetest command manually in the background to set CRTC configurations in case of Full-Fledged VCU TRD main design.

% modetest -D a0070000.v_mix -s 41:3840x2160-60@BG24 &

NOTE: Before execution of vcu_gst_app, we need to run below modetest command manually in the background to set CRTC configurations in case of PL DDR HDMI design.

% modetest -D a0070000.v_mix -s 37:3840x2160-60@BG24 &

CRTC configurations are set by default in case of other designs.

% vcu_gst_app < path to *.cfg file>


Note: Required Storage medium SATA and USB are mounted at /media/sata and /media/usb respectively.

Example:

4kp60 HEVC_HIGH Display Pipeline execution

% vcu_gst_app /media/card/config/1-4kp60/Display/Single_4kp60_HEVC_HIGH.cfg

4kp60 HEVC_HIGH Record Pipeline execution

% vcu_gst_app /media/card/config/1-4kp60/Record/Single_4kp60_HEVC_HIGH.cfg

4kp60 HEVC_HIGH Stream-out Pipeline execution

% vcu_gst_app /media/card/config/1-4kp60/Stream-out/Single_4kp60_HEVC_HIGH.cfg

4kp60 HEVC_HIGH Stream-in Pipeline execution

% vcu_gst_app /media/card/config/1-4kp60/Stream-in/input.cfg

NOTE: Make sure HDMI-Rx should be configured to 4kp60 mode.

To measure the latency of the pipeline, run the below command. The latency data is huge, so dump it to a file.

% GST_DEBUG="GST_TRACER:7" GST_TRACERS="latency;scheduletime" ./vcu_gst_app ./input.cfg >& dump_log.txt

2.2.1 Multistream

When the number of input is more than one in the command line application, it is a multi-stream use case. The command line application supports multi-streaming, multi-recording, or multi-display. The input source type can be HDMI, TPG and MIPI.

Note: The multi-stream feature is supported in VCU TRD design only with HDMI, TPG, and MIPI and in VCU AUDIO design ( 2 streams) only with HDMI, MIPI.

Ex:

2-4kp30 HEVC_MEDIUM Display Pipeline execution

% vcu_gst_app /media/card/config/2-4kp30/Display/2_4kp30_HEVC_MEDIUM.cfg

NOTE: Make sure HDMI-Rx is configured to 4kp30 mode.


4-1080p60 HEVC_15Mbps Display Pipeline execution

% vcu_gst_app /media/card/config/4-1080p60/Display/4_1080p60_HEVC_15Mbps.cfg

NOTE: Make sure HDMI-Rx is configured to 1920x1080p60 mode.



8-1080p30 HEVC_7.5Mbps Display Pipeline execution

% vcu_gst_app /media/card/config/8-1080p30/Display/8_1080p30_HEVC_7_5Mbps.cfg

NOTE: Make sure HDMI-Rx is configured to 1920x1080p30 mode.

2.2.2 Streaming

Streaming Prerequisites when 2 ZCU106 boards are connected

Steps for Streaming

% vcu_gst_app < path to stream out config file >
% vcu_gst_app < path to stream in config file >

Streaming Prerequisites when ZCU106 board is connected to host machine:

Steps for Streaming

% vcu_gst_app < path to stream out config file >

NOTE: It is recommended to use rev-1.0 or rev-F board.



3 Build Flow


The following tutorials assume that the $TRD_HOME environment variable is set as given below.

% export TRD_HOME=</path/to/downloaded/zipfile>/rdf0428-zcu106-vcu-trd-2019-1

3.1 Hardware Design

Refer to the Vivado Design Suite User Guide: Using the Vivado IDE, UG893, for setting up Vivado environment.

On Linux:

  1. Open a Linux terminal
  2. Change directory to $TRD_HOME/pl
  3. Run the following command in Vivado shell to create the Vivado IPI project and invoke the GUI.
% vivado -source scripts/<Name of tcl script as per hardware design>

The table below lists the available hardware designs and the script used to generate hardware project. These can be found in the scripts folder in a package under "pl/scripts".

DesignProjectScript
VCU TRDVCU TRDvcu_trd_proj.tcl
Multistream AudioHDMI-Rx + VCU + HDMI-Tx + Audio and 
MIPI-Rx+VCU+HDMI-TX+Audio -
[ I2S-Rx +I2s-Tx ]
vcu_audio_proj.tcl
SDI Capture and Display with AudioSDI-Rx + VCU + SDI-Tx + Audiovcu_sdirxtx_proj.tcl
HDMI Capture and Display with PL DDRHDMI-Rx + VCU + HDMI-Tx + PL DDRvcu_plddr_hdmi_proj.tcl
VCU PCIeVCU PCIevcu_pcie_proj.tcl
 VCU 10g VCU 10g vcu_10g_proj.tcl
 HDMI Capture HDMI Rx + VCU vcu_hdmirx_proj.tcl
 HDMI Display VCU + HDMI Tx vcu_hdmitx_proj.tcl
 SDI Capture SDI Rx + VCU vcu_sdirx_proj.tcl
 SDI Display VCU + SDI Txvcu_sditx_proj.tcl
 VCU SDx VCU SDx vcu_sdx_proj.tcl


Select tcl script as mentioned in the above table for different hardware design as e.g use below command for Full-Fledged VCU TRD hardware design.

% vivado -source scripts/vcu_trd_proj.tcl


After executing the script, the Vivado IPI block design comes up as shown in the below figure.


Note: If the user gets any pop-up with “No implementation Results available”. Click “Yes”. Then, if any pop-up comes up with “Launch runs”, Click "OK”.

The design is implemented and a pop-up window comes up saying “Open Implemented Design”. Click "OK".



After opening the implemented design, the window looks as shown in the below figure.
Note: The actual results might graphically look different than the image shown






The HDF is created at $TRD_HOME/pl/<path to project>/<path to sdk>/<path to hdf>. As an e.g  the HDF is created at $TRD_HOME/pl/vcu_trd/vcu_trd.sdk/vcu_trd_wrapper.hdf  for VCU TRD hardware design.


3.2 VCU PetaLinux BSP

This tutorial shows how to build the Linux image and boot image using the PetaLinux build tool.
PetaLinux Installation: Refer to the PetaLinux Tools Documentation (UG1144) for installation.

NOTE: It is recommended to follow the build steps in sequence.

% source <path/to/petalinux-installer>/tool/petalinux-v2019.1-final/settings.sh
% echo $PETALINUX

Post PetaLinux installation $PETALINUX environment variable should be set.pci

% cd $TRD_HOME/apu/vcu_petalinux_bsp
% petalinux-create -t project -s xilinx-vcu-trd-zcu106-v2019.1-final.bsp
% cd xilinx-vcu-trd-zcu106-v2019.1-final
% petalinux-config --get-hw-description=<Path to prebuilt HDF>

The table below lists the available hardware designs and HDF path. These can be found in the prebuilt folder in the package under "pl/prebuilt".

DesignProjectHDF Path
VCU TRDVCU TRDvcu_trd
Multistream AudioHDMI-Rx + VCU + HDMI-Tx + Audio and 
MIPI-Rx+VCU+HDMI-TX+Audio -
[ I2S-Rx +I2s-Tx ]
vcu_audio
10G Ethernet Video streaming10G HDMI-Rx + VCU + HDMI-Txvcu_10g
SDI Capture and Display with AudioSDI-Rx + VCU + SDI-Tx + Audiovcu_sdirxtx
HDMI Video CaptureHDMI-Rx + VCUvcu_hdmirx
HDMI Video DisplayVCU + HDMI-Txvcu_hdmitx
SDI Video CaptureSDI-Rx + VCUvcu_sdirx
SDI Video DisplayVCU + SDI-Txvcu_sditx
10G Ethernet Video Streaming With SDSoC acceleratorHDMI-Rx + VCU + HDMI-Tx + SDSoCvcu_sdx
HDMI Capture and Display with PL DDRHDMI-Rx + VCU + HDMI-Tx + PL DDRvcu_plddr_hdmi
PCIe transcodePCIe XDMA+ VCUvcu_pcie

As an e.g use below command to configure the PetaLinux project for VCU TRD multi-stream design.

% petalinux-config --get-hw-description=$TRD_HOME/pl/prebuilt/vcu_trd/

NOTE:

% petalinux-config --get-hw-description=<Path to modified HDF>
% petalinux-config --get-hw-description=$TRD_HOME/pl/vcu_trd/vcu_trd.sdk
% cp project-spec/meta-user/recipes-bsp/device-tree/files/<dtsi file name as per design>  project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi

The table below lists the available hardware designs and its dtsi.

DesignProjectdtsi
VCU TRDVCU TRDvcu_trd.dtsi
Multistream  AudioHDMI-Rx + VCU + HDMI-Tx + Audio and 
MIPI-Rx+VCU+HDMI-TX+Audio -
[ I2S-Rx +I2s-Tx ]
vcu_audio.dtsi
10G Ethernet Video streaming10G HDMI-Rx + VCU + HDMI-Txvcu_10g.dtsi
SDI Capture and Display with AudioSDI-Rx + VCU + SDI-Txvcu_sdirxtx.dtsi
HDMI Video CaptureHDMI-Rx + VCUvcu_hdmirx.dtsi
HDMI Video DisplayVCU + HDMI-Txvcu_hdmitx.dtsi
SDI Video CaptureSDI-Rx + VCUvcu_sdirx.dtsi
SDI Video DisplayVCU + SDI-Txvcu_sditx.dtsi
10G Ethernet Video Streaming With SDSoC acceleratorHDMI-Rx + VCU + HDMI-Tx + SDSoCvcu_sdx.dtsi
HDMI Capture and Display with PL DDRHDMI-Rx + VCU + HDMI-Tx + PL DDRvcu_plddr_hdmi.dtsi
PCIe transcodePCIe XDMA + VCUvcu_pcie.dtsi

As an e.g use below command to copy design dtsi file to system-user.dtsi for VCU TRD design.

% cp project-spec/meta-user/recipes-bsp/device-tree/files/vcu_trd.dtsi  project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi


NOTE:

VCU TRD design & PL DDR HDMI design

Edit "project-spec/meta-user/recipes-kernel/linux/linux-xlnx_%.bbappend" file for VCU TRD design and PL DDR HDMI design by following below steps

SRC_URI += "file://user.cfg"

SRC_URI_append = " \
                                file://0001-media-xilinx-TPG-Add-IOCTL-to-set-PPC.patch \
                                file://0002-Add-2nd-HDMI-support-by-adding-a-dummy-driver.patch \
                                file://0005-drm-xlnx_mixer-Dont-enable-primary-plane-by-default.patch \
                                file://0004-drm_atomic_helper-Supress-vblank-timeout-warning-mes.patch \
                                file://0006-drivers-misc-add-support-for-interrupt-based-PCIe-en.patch  \
"

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"


Custom EDID Support
The TRD design is tested/validated with ABOX 2017 and NVIDIA SHIELD Pro. If you want to try with any new HDMI source, you need to generate the EDID of the new source and update it in the TRD bsp. Refer to Custom EDID Support for adding the newly generated EDID file.


% petalinux-build
% petalinux-build --sdk
% petalinux-package --sysroot
% cd images/linux
% petalinux-package --boot --fsbl zynqmp_fsbl.elf --u-boot u-boot.elf --pmufw pmufw.elf --fpga system.bit
cp BOOT.BIN image.ub $TRD_HOME/images/<Path to Design images>

The table below lists the available hardware design and its image path. These can be found in the package under "images".

DesignProjectImage Path
VCU TRDVCU TRDvcu_trd
HDMI AudioHDMI-Rx + VCU + HDMI-Tx + Audiovcu_audio
10G Ethernet Video streaming10G HDMI-Rx + VCU + HDMI-Txvcu_10g
SDI Capture and Display with AudioSDI-Rx + VCU + SDI-Txvcu_sdirxtx
HDMI Video CaptureHDMI-Rx + VCUvcu_hdmirx
HDMI Video DisplayVCU + HDMI-Txvcu_hdmitx
SDI Video CaptureSDI-Rx + VCUvcu_sdirx
SDI Video DisplayVCU + SDI-Txvcu_sditx
10G Ethernet Video Streaming With SDSoC acceleratorHDMI-Rx + VCU + HDMI-Tx + SDSoCvcu_sdx
HDMI Capture and Display with PL DDRHDMI-Rx + VCU + HDMI-Tx + PL DDRvcu_plddr_hdmi
PCIe transcodePCIe XDMA + VCUvcu_pcie

As an e.g If images are generated for VCU TRD design then use below command to copy images to SD card directory

% cp BOOT.BIN image.ub $TRD_HOME/images/vcu_trd/


NOTE: It is recommended to follow the build steps in sequence.

3.3 VCU APM library

This tutorial shows how to build the VCU APM library.

% source <compiled petalinux bsp path>/images/linux/sdk/environment-setup-aarch64-xilinx-linux
% cd $TRD_HOME/apu/apps
% xsdk -workspace .



3.4 VCU Video library

This tutorial shows how to build the VCU video library.

3.5 VCU GST library

This tutorial shows how to build the VCU GST library.

3.6 VCU GST APP

This tutorial shows how to build the VCU GST APP.

3.7 VCU Qt Application

This tutorial shows how to build the VCU Qt application.

% cd $TRD_HOME/apu/apps/vcu_qt
% qmake vcu_qt.pro -r -spec linux-oe-g++
% make
% cp -f vcu_qt $TRD_HOME/images/<Path to Design images>/bin/


3.8 PCIe Lib

This tutorial shows how to build the PCIe library.

NOTE: The PCIe library is required for PCIe transcode design only.  

3.9 PCIe Transcode

This tutorial shows how to build the PCIe transcode application. PCIe transcode application depends on the pcie_lib project, so build pcie_lib before building pcie_transcode application.  

NOTE: The PCIe library is required for PCIe transcode design only.  


4 Appendix A - Input Configuration File (input.cfg)

Refer below link for VCU TRD design Appendix A

Refer below link for Multistream Audio design Appendix A

Refer below link for 10G HDMI Video Capture and HDMI Display design Appendix A

Refer below link for SDI Video Capture and SDI Display design Appendix A

Refer below link for HDMI Video Capture design Appendix A

Refer below link for HDMI Video Display design Appendix A

Refer below link for SDI Video Capture design Appendix A

Refer below link for SDI Video Display design Appendix A

Refer below link for HDMI Video Capture and HDMI Display with SDSoC support design Appendix A

Refer below link for HDMI Video Capture and HDMI Display with PL DDR design Appendix A



5 Appendix B

Refer below link for Full-Fledged VCU TRD design Appendix B

Refer below link for Multistream Audio design Appendix B

Refer below link for 10G HDMI Video Capture and HDMI Display design Appendix B

Refer below link for SDI Video Capture and SDI Display design Appendix B

Refer below link for HDMI Video Capture design Appendix B

Refer below link for HDMI Video Display design Appendix B

Refer below link for SDI Video Capture design Appendix B

Refer below link for SDI Video Display design Appendix B

Refer below link for HDMI Video Capture and HDMI Display with SDSoC support design Appendix B

Refer below link for HDMI Video Capture and HDMI Display with PL DDR design Appendix B