Command Line Flow

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.

TIP:To configure a command shell, source the settings64.shor settings64.cshfile on Linux, from the /SDx/directory, where is the installation folder of the SDxsoftware, and is the software release.

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 thexocctool and associated options.

Host Code Compilation and Linking

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.xcppis a wrapper which uses standardgcccompiler along with standardgccswitches and command line arguments which should be familiar to the software developer and are not elaborated here.

TIP: xcppis 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 xcppcommand 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 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).

An example of the xcppcommand 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 thexocccompiler. There are multiplexoccoptions that need to be used to correctly compile your kernel. These options are discussed here.

Kernel source files are specified on thexocccommand by directly listing the source files. Multiple source files can be added.
The -k/ --kerneloption is used to specify the kernel name associated with the source files.
```
xocc … -k   … 
```
A platform on which the kernel is to be targeted needs to be specified. Specify the platform using the -–platform xoccoption. Xilinxplatforms include xilinx_u200.
```
xocc … --platform 
```
Specify the build target with the -t / -–target xoccoption. By default, the target is set to hw. However, as discussed in Build Targets, the 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 -ooption. The default output file name is .xo.
```
xocc .. -o  .xo
```
System and estimate reports can optionally be generated using the –R/ –report_leveloptions. Furthermore, you can optionally specify report, log, and temp directories using the –report_dir, --log_dir, and –temp_diroptions respectively. These can be useful for organizing the generated files.
```
xocc ... --report_level 2 --report_dir 
```
Finally, use the xocc -c/ --compileoption 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 vadd.cl vadd.h \ -o krnl_vadd.xo --report_level 2 --report_dir reports

This performs the following:

Compile the kernel
Name the Kernelkrnl_vadd
Usexilinx_u200platform
Usevadd_file1.cppandvadd_file2.cppsource files
Generate an output file namedkrnl_vadd.xo
Generate reports and write them to the directoryreports

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 xocccommand by directly listing the source files. Multiple source files can be added.
```
xocc …  … 
```
You must specify the platform with the –platformoption. The platform specified must be identical to that specified in the compile stage.
```
xocc … --platform 
```
Like the compile stage, you can specify the name of the generated output file using the -ooption. The output file in the link stage will be an .xclbinfile. The default output name is a .xclbin.
```
xocc .. -o  .xclbin
```
As described in Creating Multiple Instances of a Kernel, the --nkoption 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 in Mapping Kernel Interfaces to Memory Resources, you can optionally use the –spoption to specify the connection of a kernel interface to the target DDR bank. Multiple --spoptions can be specified to map each of the interfaces to a particular bank.
```
xocc ... --sp .:
```
Linking is also done using the -l/ --linkoption.
```
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 thexilinx_u200platform
Create one compute unit calledkrnl_vadd1
Mapkrnl_vadd1, portm_axi_gmemto DDR bank3
Name output.xclbinfilevadd.xclbin

Using the sdaccel.ini File

The SDAccelruntime 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 namedsdaccel.iniand saved in the same directory as the host executable.

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.

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 disableOpenCLcode 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 disableOpenCLAPI 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 calledemulation_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 calledemulation_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 calledemulation_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 savewdbfile batch: Do not launch simulator waveform GUI, but savewdbfile gui: Launch simulator waveform GUI, and savewdbfile 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

Theemconfigutilcommand and options can be provided in the Command field underemconfigutilto create an emulation configuration file.

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