Building an Application via Command Line
In addition to using theSDAccel™GUI to create projects and build hardware accelerated applications, theSDx™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.
You will recall fromBuilding the Systemthat anSDAccelapplication 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 usingxcpp
, a GCC-compatible compiler.
TheSDAccelXilinx®Open Code Compiler (xocc),xocc
, is a command line compiler that takes your source code and runs it through theVivado®implementation tools to generate the bitstream and other files that are needed to program the FPGA-based accelerator cards. It supports kernels expressed inOpenCL™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 theSDx Command and Utility Reference Guidefor details on thexocc
tool and associated options.
Building the Host
Compiling
The host code (written in C/C++ usingOpenCLAPIs) is compiled by theXilinxC++ (xcpp
) compiler and generates host executable (.exefile) which executes on the host CPU.xcpp
is a wrapper which uses standardgcc
compiler along with standardgcc
switches and command line arguments which should be familiar to the software developer and are not elaborated here.
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.
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.
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 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 theXilinxSDAccelruntime shared library to create the executable (.exe).
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 \
-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.
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 thexocc
compiler. There are multiplexocc
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
… -
A platform on which the kernel is to be targeted must be specified. Specify the platform using the
-–platform xocc
option.xocc … --platform
The build target must be specified. Specify with the
-t / -–target xocc
option.xocc … -t
By default, thebuild_target
is set to hw. However, as discussed in Build Targets, thebuild_target
can be one of the following:- sw_emufor software emulation
- hw_emufor hardware emulation
- hwfor 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.xo .xocc .. -o
.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
-
Finally, use the
xocc -c
/--compile
option to compile the kernel. This generates an .xofile 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.clandvadd.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 inBuilding the System, the second part of the build process links one or more kernels into the platform to create the binary containerxclbinfile. Similar to compiling, linking requires several options.
- The.xosource files are specified on the
xocc
command by directly listing the source files. Multiple source files can be added.xocc …
… - You must specify the platform with the
–-platform
option. The platform specified must be identical to that specified during compilation.xocc … --platform
- You must specify the build target with the
-t
option. The specified target must be identical to that specified during compilation.xocc … -t
- 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.xclbinfile. The default output name isa.xclbin.xocc .. -o
.xclbin - As described inCreating Multiple Instances of a Kernel, the
--nk
option instantiates the specified number of compute units for the given kernel in the.xclbinfile. While the compute unit instance name is optional,Xilinxrecommends adding one.xocc ... --nk
: : :…: - As described inMapping 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
. : - 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
, portm_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
For command line users, the runtime initialization file needs to be created manually and namedsdaccel.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,.exepath, and current directory for.inifile in that order. If it does not exist, it returns an empty string.
ForSDxGUI users, the project manager creates thesdaccel.inifile automatically based on your run configuration and saves it next to the host executable.
The runtime library checks ifsdaccel.iniexists 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.
Key | Valid Values | Descriptions |
---|---|---|
debug |
[true|false] |
Enable or disable kernel debug.
|
profile |
[true|false] |
Enable or disableOpenCLcode profiling.
|
timeline_trace |
[true|false] |
Enable or disable profile timeline trace
|
device_profile |
[true|false] |
Enable or disable device profiling.
|
Key | Valid Values | Descriptions |
---|---|---|
api_checks |
[true|false] |
Enable or disableOpenCLAPI checks.
|
runtime_log |
null console syslog filename |
Specify where the runtime logs are printed
|
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 |
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 |
|
Controls the printing of emulation info messages to users console. Emulation info messages are always logged into a file calledemulation_debug.log
|
print_warnings_in_console |
|
Controls the printing emulation warning messages to users console. Emulation warning messages are always logged into a file calledemulation_debug.log.
|
print_errors_in_console |
|
Controls printing emulation error messages in users console. Emulation error messages are always logged into file calledemulation_debug.log.
|
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.
|
launch_waveform |
[off|batch|gui] |
Specify how the waveform is saved and displayed during emulation.
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
Theemconfigutil
command and options can be provided in the Command field underemconfigutil
to create an emulation configuration file.
For more information onemconfigutil
and its options, refer to the "emconfigutil (Emulation Configuration) Utility" section inSDx Command and Utility Reference Guide.
Figure:emconfigutil Settings