Command Line Flow

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.

Host Code Compilation and Linking

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

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)

Kernel Code Compilation and Linking

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 needs to be specified. Specify the platform using the -–platform xocc option. Xilinx platforms include xilinx_u200.
```
xocc … --platform <platform_name>
```
Specify the build target with the -t / -–target xocc option. By default, the target is set to hw. However, as discussed in Build Targets, the 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 vadd.cl vadd.h \
-o krnl_vadd.xo --report_level 2 --report_dir reports

This performs the following:

Compile the kernel
Name the Kernel krnl_vadd
Use xilinx_u200 platform
Use vadd_file1.cpp and vadd_file2.cpp source files
Generate an output file named krnl_vadd.xo
Generate reports and write them to the directory 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 in the compile stage.
```
xocc … --platform <platform_name>
```
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 –nk krnl_vadd:1:krnl_vadd1 \
--sp krnl_vadd1.m_axi_gmem:DDR[3] -o vadd.xclbin

This performs the following:

Link the kernel
Use the xilinx_u200 platform
Create one compute unit called krnl_vadd1
Map krnl_vadd1, port m_axi_gmem to DDR bank3
Name output .xclbin file vadd.xclbin

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. The file must be named sdaccel.ini and saved in the same directory as the host executable.

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
`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.