Building an Application via Command Line

In addition to using the SDAccel™ GUI to create projects and build hardware accelerated applications, the SDx™ system tools can be invoked with a command-line interface in a command or shell window, in which a path to the tools has been set.

TIP: To configure a command shell, source the settings64.sh or settings64.csh file on Linux, from the <install_dir>/SDx/<version> directory, where <install_dir> is the installation folder of the SDx software, and <version> is the software release.

You will recall from Building the System that an SDAccel application project is compiled in a two part process: the software build process for the host application, and the hardware build process for the accelerated kernel. The host application is compiled using xcpp, a GCC-compatible compiler.

The SDAccel Xilinx® Open Code Compiler (xocc), xocc, is a command line compiler that takes your source code and runs it through the Vivado® implementation tools to generate the bitstream and other files that are needed to program the FPGA-based accelerator cards. It supports kernels expressed in OpenCL™ C, C++ and RTL (SystemVerilog, Verilog, or VHDL).

This chapter walks through the command-line flow and shows how to build the software and hardware components from the command-line, or a script. See the SDx Command and Utility Reference Guide for details on the xocc tool and associated options.

Building the Host

Compiling

The host code (written in C/C++ using OpenCL APIs) is compiled by the Xilinx C++ (xcpp) compiler and generates host executable (.exe file) which executes on the host CPU. xcpp is a wrapper which uses standard gcc compiler along with standard gcc switches and command line arguments which should be familiar to the software developer and are not elaborated here.

TIP: xcpp is based on GCC, and therefore supports many standard GCC options which are not documented here. For information refer to the GCC Option Index.

An example of the xcpp command used to compile a design is given below:

xcpp -DSDX_PLATFORM=xilinx_vcu1525_dynamic_5_1 \
-I/${XILINX_XRT}/include/ \
-I/${XILINX_VIVADO}/include/ -g -Wall -c -o vadd.o vadd.cpp \

The various options used are detailed on the right-hand side in brackets.

Table 1. Host Code Compilation
Code	Description
xcpp
-DSDX_PLATFORM=xilinx_vcu1525_dynamic_5_1	(define macro)
-I/${XILINX_XRT}/include/	(include directory of header files)
-I/${XILINX_VIVADO}/include/	(include directory of header files)
-I<user include directory>	(user include file directory)
-g	(produce debugging information)
-Wall	(all warnings)
-c	(compile)
-o vadd.o	(specify output file, vadd.o)
vadd.cpp	(source file)

Linking

The generated object files (.o) are linked with the Xilinx SDAccel runtime shared library to create the executable (.exe).

An example of the xcpp command used to link the design is given below:

xcpp -o vadd.exe -W1 -lxilinxopencl -lpthread -lrt -lstdc++ \
-L/${XILINX_XRT}/lib/ \
-rpath,/lnx64/lib/csim vadd.o \

Note: When linking the host applications against -lxilinxopencl, the -rpath-link is needed. When linking with -lOpenCL, then -rpath-link is not needed.

The various options used are detailed on the right-hand side in parentheses.

Table 2. Linking the Host Code
Code	Description
xcpp
-o vadd.exe	(create output file, vadd.exe)
-Wl	(specify warning level)
-lxilinxopencl -lpthread -lrt -lstdcc++	(link with specified library files)
-L/${XILINX_XRT}/lib/	(search directories for library files)
-rpath,/lnx64/lib/csim	(designate runtime search path)
vadd.o	(object code file)

Building the Hardware

Compiling

The first stage in building any system is to compile a kernel accelerator function. Compilation is done using the xocc compiler. There are multiple xocc options that need to be used to correctly compile your kernel. These options are discussed here.

Kernel source files are specified on the xocc command by directly listing the source files. Multiple source files can be added.
The -k / --kernel option is used to specify the kernel name associated with the source files.
```
xocc … -k <kernel_name> <kernel_source_file> … <kernel_source_file>
```
A platform on which the kernel is to be targeted must be specified. Specify the platform using the -–platform xocc option.
```
xocc … --platform <platform_name>
```
The build target must be specified. Specify with the -t / -–target xocc option.
```
xocc … -t <build_target>
```
By default, the build_target is set to hw. However, as discussed in Build Targets, the build_target can be one of the following:
- sw_emu for software emulation
- hw_emu for hardware emulation
- hw for building on the target board
The name of the generated output file can optionally be specified using the -o option. The default output file name is <kernel>.xo.
```
xocc .. -o <xo_kernel_name> .xo
```
System and estimate reports can optionally be generated using the –R/–report_level options. Furthermore, you can optionally specify report, log, and temp directories using the –report_dir, --log_dir, and –temp_dir options respectively. These can be useful for organizing the generated files.
```
xocc ... --report_level 2 --report_dir <report_dir_name>
```
Finally, use the xocc -c/--compile option to compile the kernel. This generates an .xo file that can be used in the subsequent link stage.
```
xocc ... –c
```

Putting it all together in an example:

xocc -c -k krnl_vadd --platform xilinx_u200 -t sw_emu vadd.cl vadd.h \
-o krnl_vadd.xo --report_level 2 --report_dir reports

This performs the following:

Compile the kernel: -c
Name the Kernel: -k krnl_vadd
Specify platform: --platform xilinx_u200 platform
Target software emulation: -t sw_emu
Source input files: vadd.cl and vadd.h
Specify output file name: -o krnl_vadd.xo
Generate level 2 reports and write them to reports DIR --report_level 2 --report_dir reports

Linking

As discussed in Building the System, the second part of the build process links one or more kernels into the platform to create the binary container xclbin file. Similar to compiling, linking requires several options.

The .xo source files are specified on the xocc command by directly listing the source files. Multiple source files can be added.
```
xocc … <kernel_xo_file.xo> … <kernel_xo_file.xo>
```
You must specify the platform with the –-platform option. The platform specified must be identical to that specified during compilation.
```
xocc … --platform <platform_name>
```
You must specify the build target with the -t option. The specified target must be identical to that specified during compilation.
```
xocc … -t <build_target>
```
Like the compile stage, you can specify the name of the generated output file using the -o option. The output file in the link stage will be an .xclbin file. The default output name is a.xclbin.
```
xocc .. -o <xclbin_name>.xclbin
```
As described in Creating Multiple Instances of a Kernel, the --nk option instantiates the specified number of compute units for the given kernel in the .xclbin file. While the compute unit instance name is optional, Xilinx recommends adding one.
```
xocc ... --nk <kernel_name>: <compute_units>:<kernel_name1>:…:<kernel_nameN>
```
As described in Mapping Kernel Interfaces to Memory Resources, you can optionally use the -–sp option to specify the connection of a kernel interface to the target DDR bank. Multiple --sp options can be specified to map each of the interfaces to a particular bank.
```
xocc ... --sp <kernel_instance_name>.<interface_name>:<bank name> 
```
Linking is also done using the -l/--link option.
```
xocc ... -l 
```

Putting it all together in an example:

xocc -l --platform xilinx_u200 -t sw_emu –-nk krnl_vadd:1:krnl_vadd1 \
--sp krnl_vadd1.m_axi_gmem:DDR[3] -o vadd.xclbin krnl_vadd.xo

This performs the following:

Link the kernel: -l
Specify platform: --platform xilinx_u200
Target software emulation: -t sw_emu
Create one compute unit called krnl_vadd1:
-–nk krnl_vadd:1:krnl_vadd1
Map krnl_vadd1, port m_axi_gmem to DDR bank3:
--sp krnl_vadd1.m_axi_gmem:DDR[3]
Specify output file name: -o vadd.xclbin
Source input file: krnl_vadd.xo

Using the sdaccel.ini File

The SDAccel runtime library uses various parameters to control debug, profiling, and message logging during host application and kernel execution in software emulation, hardware emulation, and system run on the acceleration board. These control parameters are specified in a runtime initialization file.

For command line users, the runtime initialization file needs to be created manually and named sdaccel.ini. The location of the file can be specified by defining the environment variable SDACCEL_INI_PATH with the path of the directory in which the file exists. By default the tools check SDACCEL_INI_PATH, .exe path, and current directory for .ini file in that order. If it does not exist, it returns an empty string.

For SDx GUI users, the project manager creates the sdaccel.ini file automatically based on your run configuration and saves it next to the host executable.

The runtime library checks if sdaccel.ini exists in the same directory as the host executable and automatically reads the parameters from the file during start-up if it finds it.

Runtime Initialization File Format

The runtime initialization file is a text file with groups of keys and their values. Any line beginning with a semicolon (;) or a hash (#) is a comment. The group names, keys, and key values are all case sensitive.

The following is a simple example that turns on profile timeline trace and sends the runtime log messages to the console.

#Start of Debug group 
[Debug] 
timeline_trace = true

#Start of Runtime group 
[Runtime] 
runtime_log = console

The following table lists all supported groups, keys, valid key values, and short descriptions on the function of the keys.

Table 3. Debug Group
Key	Valid Values	Descriptions
`debug`	`[true\|false]`	Enable or disable kernel debug. true: enable false: disable Default: false
`profile`	`[true\|false]`	Enable or disable OpenCL code profiling. true: enable false: disable Default: false
`timeline_trace`	`[true\|false]`	Enable or disable profile timeline trace true: enable false: disable Default: false
`device_profile`	`[true\|false]`	Enable or disable device profiling. true: enable false: disable Default: false

Table 4. Runtime Group
Key	Valid Values	Descriptions
`api_checks`	`[true\|false]`	Enable or disable OpenCL API checks. true: enable false: disable Default: true
`runtime_log`	`null console syslog filename`	Specify where the runtime logs are printed null: Do not print any logs. console: Print logs to `stdout` syslog: Print logs to Linux syslog filename: Print logs to the specified file. For example, runtime_log=my_run.log Default: null
`cpu_affinity`	One or more integer	Pin all runtime threads to specified CPUs. For example, `cpu_affinity` = {4,5,6}
`polling_throttle`	An integer	Specify the time interval in microseconds that the runtime library polls the device status. Default: 0

Table 5. Emulation Group
Key	Valid Values	Descriptions
`aliveness_message_interval`	Any integer	Specify the interval in seconds that aliveness messages need to be printed Default: 300
`print_infos_in_console`	`[true\|false]`	Controls the printing of emulation info messages to users console. Emulation info messages are always logged into a file called emulation_debug.log true = print in users console false = do not print in user console Default: true
`print_warnings_in_console`	`[true\|false]`	Controls the printing emulation warning messages to users console. Emulation warning messages are always logged into a file called emulation_debug.log. true = print in users console false = do not print in user console Default: true
`print_errors_in_console`	`[true\|false]`	Controls printing emulation error messages in users console. Emulation error messages are always logged into file called emulation_debug.log. true = print in users console false = do not print in user console Default: true
`enable_oob`	`[true\|false]`	Enable or disable diagnostics of out of bound access during emulation. A warning is reported if there is any out of bound access. true: enable false: disable Default: false
`launch_waveform`	`[off\|batch\|gui]`	Specify how the waveform is saved and displayed during emulation. off: Do not launch simulator waveform GUI, and do not save wdb file batch: Do not launch simulator waveform GUI, but save wdb file gui: Launch simulator waveform GUI, and save wdb file Default: off Note: The kernel needs to be compiled with debug enabled (`xocc -g`) for the waveform to be saved and displayed in the simulator GUI.

emconfigutil Settings

The emconfigutil command and options can be provided in the Command field under emconfigutil to create an emulation configuration file.

For more information on emconfigutil and its options, refer to the "emconfigutil (Emulation Configuration) Utility" section in SDx Command and Utility Reference Guide.