Compiling Your OpenCL Kernel Using the Xilinx OpenCL Compiler (xocc)

The Xilinx® OpenCL® Compiler (xocc) is a standalone command line utility for compiling kernel accelerator functions and linking them with SDAccel Environment supported platforms.

The first activity in building any system is to select an acceleration platform supported by Xilinx or third-party providers, and to compile a kernel accelerator function using the -c/--compile option.
TIP: The default output name for the .xo file is a.xo; rename the file so that it relates to the kernel.

The -c/--compile command syntax is, as follows:

xocc -c --platform <platform_name> <kernel_source_file> -o <xo_kernel_name>.xo
TIP: OpenCL uses the kernel keyword to identify a kernel, but for C/C++ kernels, we need to provide the kernel name by --kernel <kernel_name>.
The second activity is to link one or more kernels into the platform to create the binary container xclbin file using the -l/--link option.
TIP: The default output name for the xclbin file is a.xclbin; rename it as needed.

The -l/--link command syntax is, as follows: 

xocc -l --platform <platform_name> <xo_kernel1_name>.xo \ [<xo_kernel2_name>.xo ..] -o<xclbin_name>.xclbin

In SDAccel 2017.4, the provided DSA are xilinx_kcu1500_dynamic_5_0 and xilinx_vcu1525_dynamic_5_0; for other tool releases a complete list of supported platforms is included in the SDx Environments Release Notes, Installation, and Licensing Guide.

The --platform option accepts either a platform name or alternatively an xpfm filename (using full or relative path) that represents a platform. This is needed when you use a platform that is not included by default in the SDAccel tool installation, for example to use a DSA and matching board from the 2017.1/2017.2 release.

The default -target mode is the hardware (hw) system mode and can be changed with the --target <sw_emu|hw_emu|hw> option.
IMPORTANT!: The same target must be used for each pair of compile/link runs. For example, you cannot mix compiling for sw_emu then linking forhw_emu.
Table 1. XOCC Common Options (For Compile and Link Modes)
Option Valid Values Description
--platform <arg> Supported acceleration platforms by Xilinx and third-party board partners.

Required. Sets the target Xilinx device.

For a list of supported devices, see the SDAccel Supported Devices in the

SDx Environments Release Notes, Installation, and Licensing Guide.
--list_xdevices N/A Lists the supported devices.
--target <arg>

[sw_emu | hw_emu | hw]
Specify a compile target.
  • sw_emu: Software emulation
  • hw_emu: Hardware emulation
  • hw: Hardware

Default: hw
-o/-output <arg> File name with .xo or .xclbin extension depending on mode

Optional

Set output file name.

Default:

  • a.xo for compile mode

  • a.xclbin for link and build mode
--version N/A Prints the version and build information.
--help N/A Print help.
--kernel_frequency Frequency (MHz) of the kernel. Sets a user defined clock frequency in MHz for the kernel, overriding a default value from the DSA.
--pk <arg> <[kernel_name|all] : [none|stream|pipe|memory|all]

Optional.

Set a stall profile type for the given kernel(s). Default: none. For example: 
--pk <kernal_name>:stream
--profile_kernel <arg> <data:[kernel_name|all]:[compute_unit_name|all]:[interface_name|all]>

Optional.

Enable profiling DDR memory traffic for kernel and host. Default: none. For example: 
--profile_kernel data:krnl1:cu1:m_axi_gmem0
--profile_kernel data:krnl2:cu2:m_axi_gmem
--xp

Refer to XP Parameters.

 Specify detailed parameter and property settings in the Vivado tool suite used to implement the FPGA hardware.

Familiarity with the Vivado tool suite is recommended in order to make the most use of these parameters.
-g/--debug N/A Add debug constructs to the code being compiled.
--log N/A Creates a log for in the current working directory.
--message-rules <arg>

Message rule file name

 Optional. Specify a message rule file with message controlling rules. See Using the Message Rule File for more details.
--report <arg>

[estimate | system]

Generate a report type specified by <arg>:
  • estimate: Generate estimate report in report_estimate.xtxt
  • system: Generate the estimate report and detailed hardware reports in the report directory.
--save-temps N/A Save intermediate files/directories created during the compilation and build process.
--report_dir <arg>

Directory

Specify a report directory. If the --report option is specified, the default is to generate all reports in the current working directory (cwd).

--log_dir <arg>

Directory

Specify a log directory. If the --log option is specified, the default is to generate the log file in the current working directory (cwd).

--temp_dir <arg>

Directory

Specify a temp directory. If the --save-temps option is specified, the default is to create the temporary compilation and build files in the current working directory (cwd).

--export_script N/A This option allows detailed control of the Vivado tool suite used to implement the FPGA hardware.

Familiarity with the Vivado tool suite is recommended in order to make the most use of the Tcl file generated by this option.

Generates the Tcl script, <kernel_name>.tcl, used to execute Vivado HLS but halts before Vivado HLS starts. The expectation is for the script to be modified and used with the --custom_script option.

Not supported for –t sw_emu with OpenCL kernels.
--custom_script <kernel_name>:<path to kernel Tcl file>

Intended for use with the <kernel_name>.tcl file generated with --export_script.

This option allows you to customize the Tcl file used to create the kernel and execute using the customize version of the script.

input file OpenCL or C/C++ kernel source file, or Xilinx object file (.xo). Compile kernels into a.xo or a.xclbin file depending on the xocc mode.
--user_ip_repo_paths <arg> Specify the directory location Specify existing user IP repository. This value will be prefixed to ip_repo_paths.
--remote_ip_cache<arg> Specify the directory location Specify remote IP cache directory for Vivado Synthesis.
--no_ip_cache N/A Turn off IP cache for Vivado Synthesis.
Table 2. XOCC Options for Compile Mode
Option Valid Values Description
-c/--compile N/A

Required, but mutually exclusive with --link.

Run xocc in compile mode, generate .xo file.
-k/--kernel <arg> Kernel to be compiled from the input .cl or .c/.cpp kernel source code.

Required for C/C++ kernels. Optional for OpenCL kernels.

Compile/build only the specified kernel from the input file. Only one -k option is allowed per command.

When an OpenCL kernel is compiled without the -k option, all the kernels in the input file are compiled.
--define <arg>

Valid macro name and definition pair.

<name>=<definition>

 Predefine name as a macro with definition. This option is passed to the xocc preprocessor.
--include    
Table 3. XOCC Options for Link Mode
Option Valid Values Description
--optimize <arg>

Valid optimization levels: 0, 1, 2, 3, s, quick

example: --optimize2

This option ONLY applies to Vivado. The compile step runs the C code through HLS and has no bearing.

 These options control the default optimizations performed by the Vivado hardware synthesis engine.

Familiarity with the Vivado tool suite is recommended to make better use of these settings.

  • 0: Default optimization. Reduce compilation time and make debugging produce the expected results.
  • 1: Optimize to reduce power consumption. This takes more time to compile the design.
  • 2: Optimize to increase kernel speed. This option increases both compilation time and the performance of the generated code.
  • 3: This is the highest level of optimization. This option provides the highest level performance in the generated code, but compilation time may increase considerably.
  • s: Optimize for size. This reduces the logic resources for the kernel
  • quick: Quick compilation for fast run time. This may result in reduced hardware performance, and a greater use of resources in the hardware implementation.
--link N/A

Required, but mutually exclusive with --compile.

Run xocc in link mode. Link .xo input files, generate .xclbin file.
--dk <arg>

<protocol:<compute_unit_name>:<interface_name>>

For example: 
protocol:cu1:m_axi_gmem

Add Lightweight AXI Protocol Checkers (LAPC) to the specified compute units to monitor the specified interfaces.
--nk <arg> <kernel_name>: <compute_units>
For example: 
foo:2

<kernel_name>: <compute_units>:<kernel_name1>.<kernel_name2>…<kernel_nameN>

For example:
foo:3:fooA.fooB.fooC

Optional in link mode. Not applicable in compile mode.

The instance name is optional. If the instance name is not specified, the first instance is named <kernel_name>_1, the second instance will be named <kernel_name>_2, and so forth.

Instantiate the specified number of compute units for the given kernel in the .xclbin file.

Default: One compute unit per kernel.
--jobs <arg> Number of parallel jobs.

Optional. This option allows detailed control of the Vivado tool suite used to implement the FPGA hardware.

Familiarity with the Vivado tool suite is recommended in to make the most use of the Tcl file generated by this option.

Specify the number of parallel jobs to be passed to the Vivado tool suite for implementation. Increasing the number of jobs allows the hardware implementation step to spawn more parallel processes and complete faster.
--lsf <arg>

bsub command line to pass to LSF cluster.

This argument is required for use with --lsf.

 Optional. Use IBM Platform Load Sharing Facility (LSF) for Vivado implementation and synthesis. For example: --lsf '{bsub -R "select[type=X86_64]" -N -q medium}'
--reuse_synth <arg> <synthesized DCP>

Import a previously synthesized DCP and only run the Vivado tool implementation and the XCLBIN packaging.
--reuse_impl <arg> <implemented DCP>

Import a previously implemented DCP and only run the XCLBIN packaging.
--sp <arg> <kernel_inst_name>.<interface_name>:<bank>Valid DDR4 bank names are bank0, bank1, bank2, and bank3 for platforms with 4 DDR banks. For DSA 5.x and later, the --xp misc:map_connect option is deprecated and replaced with the system port --sp option with a much simpler syntax requiring only the kernel instance name, an interface name of that kernel. and the target DDR bank for the required connection. Multiple --sp options can be specified to map each of the interfaces to a particular bank.
IMPORTANT!: All examples in the SDAccel installation use Makefile to compile OpenCL applications with xcpp and xocc commands that can be used as references for compiling user applications.

XP Parameters

Use the --xp switch to specify parameter values in SDAccel™. These parameters allow fine grain control over the hardware generated by SDAccel and the hardware emulation process.
IMPORTANT!: Familiarity with the Vivado® tool suite is recommended to make the most use of these parameters. See Vivado Design Suite User Guide: High-Level Synthesis (UG902) and Vivado Design Suite User Guide: Implementation (UG904) for more information.

Parameters are specified as parm:<param_name>=<value>. For example:

xocc -–xp param:compiler.enableDSAIntegrityCheck=true 
–xp param:prop:kernel.foo.kernel_flags="-std=c++0x"

you can specify the -–xp command option multiple times in a single xocc invocation, or specify the value(s) in an xocc.ini file with each option specified on a separate line (without --xp switch).

param:prop:solution.device_repo_paths=../dsa
param:compiler.preserveHlsOutput=1

Upon invocation, xocc first looks for an xocc.ini file in the $HOME/.Xilinx/sdx directory. If the file does not exist there, xocc will then look for it in the current working directory. If the same --xp parameter value is specified in both the command line and xocc.ini file, the command line value will be used.

The following table lists the -–xp parameters and their values.

Table 4. XP Parameter Options
Parameter Name Type Default Value Description
param:compiler.acceleratorBinaryContent String <empty> The content to put in xclbin.Valid options are bitstream and dcp
param:compiler.​enableDSAIntegrityCheck Boolean False

Enables the DSA Integrity Check.

If this value is set to True, and SDAccel™ detects a DSA which has been modified outside of the Vivado® tool suite SDAccel halts operation.
param:compiler.​errorOnHoldViolation Boolean True Error out if there is hold violation.
param:compiler.​maxComputeUnits Int -1 The maximum compute units allowed in the system. Any positive value will overwrite the numComputeUnits setting in the DSA.
param:hw_em.​enableProcSyncReset Boolean false Enable proc_sync_reset in hw_em
param.hw_emplatformPath String <empty>  
param:hw_em.​compiledLibs String <empty> Uses mentioned clibs for the specified simulator.
param:hw_em.​debugLevel String OFF The debug level of the simulator. Options are:
  • OFF: Used for optimized run times
  • BATCH: for batch runs
  • GUI: for use in GUI-mode
param:hw_em.​enableProtocolChecker Boolean False Enables the AXI protocol checker during HW emulation. This is used to confirm the accuracy of any AXI interfaces in the design.
param:compiler.​interfaceLatency Int -1 This option specifies the expected latency on the kernel AXI bus, the number of clock cycles from when bus access is requested until it is granted.
param:compiler.fsanitizestring string <empty>

Software emulation runtime checks possible values:

  • address - Out of Bound Access
  • memory - Uninitialized Memory Access
  • address
  • memory - Both

The software emulation run produces a debug log: <project_dir>/Emulation-SW/<proj_name>-Default>/emulation_debug.log with emulation diagnostic messages.
param:compiler.​xclDataflowFifoDepth Int -1 Specifies the depth of FIFOs used in kernel dataflow region.
param:compiler.​interfaceWrOutstanding Int Range 0 Specifies how many outstanding writes to buffer are on the kernel AXI interface. Values are 1 through 256.
param:compiler.​interfaceRdOutstanding Int Range 0 Specifies how many outstanding reads to buffer are on the kernel AXI interface. Values are 1 through 256.
param:compiler.​interfaceWrBurstLen Int Range 0 Specifies the expected length of AXI write bursts on the kernel AXI interface. This is used with option compiler.interfaceWrOutstanding to determine the hardware buffer sizes. Values are 1 through 256.
param:compiler.​interfaceRdBurstLen Int Range 0 Specifies the expected length of AXI read bursts on the kernel AXI interface. This is used with option compiler.interfaceRdOutstanding to determine the hardware buffer sizes. Values are 1 through 256.
misc:map_connect=<type>.​kernel.<kernel_name>.​ <kernel_AXI_interface>.​core.​ OCL_REGION_0.<dest_port> String <empty> Used to map AXI interfaces from a kernel to DDR memory banks.
  • <type> is add or remove.

  • <kernel_name> is the name of the kernel.

  • <dest_port> is a DDR memory bank M00_AXI, M01_AXI, M02_AXI or M03_AXI.

This option available only for DSA 4.x and earlier,and deprecated for DSA 5.x and later: use system ports using the --sp documented in the xocc Linker Options.
prop:kernel.<kernel_name>.​kernel_flags String <empty> Sets specific compile flags on the kernel. <kernel_name>.
prop:solution.​device_repo_path String <empty> Specifies the path to the DSA repository.

The --platform option with full path to the .xpfm platform file should be used instead.
prop:solution.​hls_pre_tcl String <empty>

Specifies the path to a Vivado HLS Tcl file, which is executed before the C code is synthesized. This allows Vivado HLS configuration settings to be applied prior to synthesis.
prop:solution.​hls_post_tcl String <empty>

Specifies the path to a Vivado HLS Tcl file, which is executed after the C code is synthesized.
prop:solution.​kernel_compiler_margin Float 12.5% of the kernel clock period. The clock margin in ns for the kernel. This value is substracted from the kernel clock period prior to synthesis to provide some margin for P&R delays.
vivado_prop:<object_type>. ​<object_name>.<prop_name> Various Various This allows you to specify any property used in the Vivado hardware compilation flow.Object_type is run|fileset|file|projectThe object_name and prop_name values are described in Vivado Design Suite Properties Reference Guide, (UG912)
Examples:
vivado_prop:run.impl_1.
{STEPS.PLACE_DESIGN.ARGS.MORE 
OPTIONS}={-fanout_opt}
vivado_prop:fileset.
current.top=foo

For object_type file, current is not supported.

For object type run the special value of __KERNEL__ can be used to specify run optimization settings for 'ALL' kernels, instead of the need to specify them one by one.