Building the Host Program

The host program, written in C/C++ using either the XRT native API or OpenCL™ API calls, is built using the GNU C++ compiler (g++) which is based on GNU compiler collection (GCC). Each source file is compiled to an object file (.o) and linked with the Xilinx® runtime (XRT) shared library to create the executable which runs on the host CPU.

TIP: g++ supports many standard GCC options which are not documented here. For information refer to the GCC Option Summary.

Compiling and Linking for x86

TIP: Set up the command shell or window as described in Setting Up the Vitis Environment prior to running the tools.
Each source file of the host application is compiled into an object file (.o) using the g++ compiler. 
g++ ... -c <source_file1> <source_file2> ... <source_fileN>
The generated object files (.o) are linked with the Xilinx Runtime (XRT) shared library to create the executable host program. Linking is performed using the -l option.
g++ ... -l <object_file1.o> ... <object_fileN.o>

Compiling and linking for x86 follows the standard g++ flow. The only requirement is to include the XRT header files and link the XRT shared libraries.

When compiling the source code, the following g++ options are required:

  • -I$XILINX_XRT/include/: XRT include directory.
  • -I$XILINX_VIVADO/include: Vivado tools include directory.
  • -std=c++11: Define the C++ language standard.

When linking the executable, the following g++ options are required:

  • -L$XILINX_XRT/lib/: Look in XRT library.
  • -lOpenCL: Search the named library during linking.
  • -lthread: Search the named library during linking.
  • -lrt: Search the named library during linking.
  • -lstdc++: Search the named library during linking.
Note: In the Vitis Examples you can see the addition of xcl2.cpp source file, and the -I../libs/xcl2 include statement. These additions to the host program and g++ command provide access to helper utilities used by the example code, but are generally not required for your own code.

Building XRT Native API

XRT provides a native XRT API for C, C++, and Python, as described on the XRT site at https://xilinx.github.io/XRT/2020.2/html/xrt_native_apis.html. To use the native XRT API, the host application must link with the xrt_coreutil library. The command line uses a few different settings as shown in the following example, which combines compilation and linking:

g++ -g -std=c++14 -I$XILINX_XRT/include -L$XILINX_XRT/lib -lxrt_coreutil -lthread \
-o host.exe host.cpp
IMPORTANT: The XRT API requires the use of -std=c++14.

Compiling and Linking for Arm

TIP: Set up the command shell or window as described in Setting Up the Vitis Environment prior to running the tools.

The host program (host.exe), is cross-compiled for an Arm processor, and linked using the following two step process:

  1. Compile the host.cpp into an object file (.o) using the GNU Arm cross-compiler version of g++:
    Note: aarch64 is used for Zynq® UltraScale+™ (A53) and Versal™ (A72) devices. aarch32 is used for Zynq-7000 SoC (A9) and the tool chain is in a different location. 
    $XILINX_VITIS/gnu/aarch64/lin/aarch64-linux/bin/aarch64-linux-gnu-g++ \
-D__USE_XOPEN2K8 -I$SYSROOT/usr/include/xrt -I$XILINX_VIVADO/include \
-I$SYSROOT/usr/include -c -fmessage-length=0 -std=c++14 \
--sysroot=$SYSROOT -o src/host.o ../src/host.cpp
  2. Link the object file with required libraries to build the executable application. 
    $XILINX_VITIS/gnu/aarch64/lin/aarch64-linux/bin/aarch64-linux-gnu-g++ \
-o host.exe src/host.o -lxilinxopencl -lpthread -lrt -lstdc++ -lgmp -lxrt_core \
-L$SYSROOT/usr/lib/ --sysroot=$SYSROOT

When compiling the application for use with an embedded process, you must specify the sysroot for the application. The sysroot is part of the platform where the basic system root file structure is defined, and is installed as described in Installing Embedded Platforms.

IMPORTANT: The above examples rely on the use of $SYSROOT environment variable that must be used to specify the location of the sysroot for your embedded platform.

The following are key elements to compiling the host code for an edge platform:

Compilation
  • The cross compiler needed is the aarch64-linux-gnu-g++ found in the Vitis installation hierarchy.
  • The required include paths are:
    • $SYSROOT/usr/include
    • $SYSROOT/usr/include/xrt
    • $XILINX_VIVADO/include
Linking
  • $SYSROOT/usr/lib: Library paths location.
  • xilinxopencl: XRT required library.
  • pthread: XRT required library.
  • rt: XRT required library.
  • stdc++: XRT required library.
  • gmp: XRT required library.
  • xrt_core: XRT required library.

Building XRT Native API

XRT provides a native XRT API for C, C++, and Python, as described on the XRT site at https://xilinx.github.io/XRT/2020.2/html/xrt_native_apis.html. To use the native XRT API, the host application must link with the xrt_coreutil library instead of the xlinxopencl library. The command line uses a few different settings as shown in the following example for compilation and linking:

$XILINX_VITIS/gnu/aarch64/lin/aarch64-linux/bin/aarch64-linux-gnu-g++ -c \
-D__USE_XOPEN2K8 -I$SYSROOT/usr/include/xrt -I$XILINX_VIVADO/include \
-I$SYSROOT/usr/include -fmessage-length=0 -std=c++14 --sysroot=$SYSROOT \
-o src/host.o ../src/host.cpp
$XILINX_VITIS/gnu/aarch64/lin/aarch64-linux/bin/aarch64-linux-gnu-g++ -l \
-lxrt_coreutil -lpthread -lrt -lstdc++ -lgmp -lxrt_core -L$SYSROOT/usr/lib/ \
--sysroot=$SYSROOT -o host.exe src/host.o