XOCC (Xilinx OpenCL Compiler) Command Line Utility

TheXilinx®OpenCL™Compiler (xocc) is a standalone command line utility for both compiling kernel accelerator functions and linking them with theSDAccel™environment supported platforms. This section describes thexocclink and compile commands.

The first step in building any system is to select an acceleration platform supported byXilinxor third-party providers and to compile a kernel accelerator function using the-c/--compileoption. The default output name for the.xofile isa.xo; rename the file to reflect the kernel name.

The-c/--compilecommand syntax is as follows:

xocc -c --platform   -o .xo
TIP: OpenCLuses the kernelkeyword within the OpenCLfile to identify a kernel. For C/C++ kernels, you need to provide the kernel name by --kernel .

The second step is to link one or more kernels into the platform to create the binary containerxclbinfile using the-l/--linkoption. The default output name for thexclbinfile isa.xclbin; rename it as needed

The-l/--linkcommand syntax is as follows:

xocc -l --platform  .xo \ [.xo ..] -o .xclbin

For a list of supported platforms, see the release notes for the product you are using:

IMPORTANT:All provided examples included in the SDAccelinstallation use the Makefile to compile OpenCLapplications with xcppand xocccommands that can be used as references for compiling user applications.
All commands are provided in the following sections:

XOCC Common Options

IMPORTANT:Do not mix targets between compilation and linking. For instance do not compile with sw_emuand link with hw_emu.
Table 1.XOCC Common Options (For Compile and Link Modes)
Option Valid Values Description
-for--platform Name of supported acceleration platform byXilinxor full path to .xpfm file that represents a platform. Required. The--platformoption accepts either a platform name or alternatively anxpfmfile name (using full or relative path) that represents the top level of a platform. This is needed when you use a platform that is not included by default in theSDAcceltool installation. Set the targetXilinxdevice. For example:
--platform xilinx_u200_xdma_201830_2

For a list of all supported platforms and devices, see theSDAccel Product Page.

When using a platform that is not included by default in theSDAcceltool installation, the.xpfmfile that represents a platform should be provided using the full path.
-tor--target [sw_emu|hw_emu|hw] Specifies a compile target. The compile target is specified with the--target option. The default compile target ishw_emu.
  • sw_emu: Software emulation
  • hw_emu: Hardware emulation
  • hw: Hardware

Default:hw
-oor--output File name with.xofor compiling and.xclbinfor linking, depending onxoccmode. Optional. Sets output file name. Default:
  • a.xofor compile mode
  • a.xclbinfor link and build mode
-vor--version N/A Prints the version and build information of XOCC.
-hor--help N/A Prints help.
--kernel_frequency Frequency (MHz) of the kernel for single clock support. For multi-clock support, each clock ID and corresponding frequency must be entered.

For example, xocc --kernel_frequency 0:300|1:500.

 Sets a user-defined clock frequency (in MHz) for the kernel, overriding a default value from the hardware platform.

RTL kernels support multi-clock:

Syntax Example (overrides 1 clock)

  • xocc --kernel_frequency 300
  • xocc --kernel_frequency 0:300
  • DSA with one kernel clock: 300 MHz for KERNEL_CLK
  • DSA with two clocks: 300 MHz for DATA_CLK

Syntax Example 2 (overrides more than 1 kernel clock)

  • xocc --kernel_frequency 0:300|1:500

DSA with two clocks (+ RTL kernel with two clock ports):

  • 300 MHz for DATA_CLK and 500 MHz for KERNEL_CLK2
--profile_kernel

data:[ kernel_name | all ]:[ compute_unit_name | all ]:[ interface_name | all ](:[ counters | all ])

[ stall | exec ]:[ kernel_name | all ]:[ compute_unit_name | all ](:[ counters | all ])

Profiling DDR memory traffic for kernel and host.

The last field for trace value (countersorall) is optional. If not specified, the default value isall.

For[ stall | exec ], the interface_name field isnotsupported.

Thestalloption must be specified duringxocccompile (-c) to direct HLS to enable stall signals before using this option duringxocclink (-l).
--xp Refer toXP Parameters. Specifies detailed parameter and property settings in theVivado® Design Suiteused to implement the FPGA hardware. For example:
--xp :stream

Familiarity with theVivado Design Suiteis recommended to make the most use of these parameters.

For a complete description of the--xpoption, seeXP Parameters.
-gor--debug N/A Generates code for debugging.
--message-rules Message rule file name Optional. Specifies a message rule file with message controlling rules. For more details, seeUsing the Message Rule File.
--save-temps N/A Saves intermediate files/directories created during the compilation and build process.
--report_dir Directory Specifies a report directory. If the--reportoption is specified, the default is to generate all reports in the current working directory (cwd).

If no report directory is specified, the tool saves the files to/_x/reports.
--log_dir Directory Specifies a log directory. If the--logoption is specified, the default is to generate the log file in the current working directory (cwd).

If no log directory is specified, the tool saves the files to/_x/logs.
--temp_dir Directory Specifies a temp directory. If the--save-tempsoption is specified, the default is to create the temporary compilation and build files in the current working directory (cwd).

If no temp directory is specified, the tool saves the files to/_x/reports.
--export_script N/A

Generates the Tcl script,.tcl, used to executeVivadoHLS but halts beforeVivadoHLS starts. The expectation is for the script to be modified and used with the--custom_scriptoption.

Not supported for–t sw_emuwithOpenCLkernels.
--custom_script : Intended for use with the.tclfile 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.
OpenCLor C/C++ kernel source file, orXilinxobject file (.xo). For Compile mode, the input file consist of OpenCL or C/C++ kernel source files. For Link mode, the input files consists of one or more Xilinx object files (a.xo).
--user_ip_repo_paths Specifies the directory location of the existing user IP repository. This value is prefixed toip_repo_paths.

Using this switch, specify one or more IP repository paths to be given highest priority by placing these paths at the beginning of the overall IP_REPO_PATHS property for the underlyingVivadoproject. IP definitions from any of these specified paths are used ahead of IP repositories from the hardware platform (.dsa) or from theXilinxcatalog.

Multiple--user_ip_repo_pathscan be specified.

The following lists show the priority order in which IP definitions are found duringSDx™compilation flows (High to Low). Note that all of these entries can possibly include multiple directories in them.

  • For HW flow:
    1. IP definitions from --user_ip_repo_paths switch
    2. Kernel IP definitions (vpl --iprepo switch value)
    3. IP definitions from DSA IP repo
    4. IP cache dir from Install area (for example,/SDx/2018.3/data/cache/)
    5. IP cache stored inside DSA
    6. SDxspecificXilinxIPs from install area (for example,/SDx/2019.1/data/ip/)
    7. GeneralXilinxIP catalog from install area (for example,/Vivado/2019.1/data/ip/)
  • For HW EMU flow:
    1. IP definitions from --user_ip_repo_paths switch
    2. User emulation ip repository (for example,$::env(SDX_EM_REPO))
    3. Kernel IP definitions (vpl --iprepo switch value)
    4. IP cache dir from Install area (for example,/SDx/2019.1/data/cache/)
    5. IP cache stored inside DSA
    6. $::env(XILINX_SDX)/data/emulation/hw_em/ip_repo
    7. $::env(XILINX_VIVADO)/data/emulation/hw_em/ip_repo
    8. SDxSpecificXilinxIPs from install area (for example,/SDx/2019.1/data/ip/)
    9. GeneralXilinxIP catalog from install area (for example,/Vivado/2019.1/data/ip/)
--remote_ip_cache Specifies remote IP cache directory forVivadosynthesis.
--no_ip_cache N/A Turns off IP cache forVivadosynthesis.
--report_level Valid report levels:0,1,2,estimate.

Example:-R2

 These report levels have mappings kept in the optMap.xml file. You can override the installed optMap.xml to define custom report levels.
  • (Default) The-R0specification turns off all intermediate DCP generation duringVivadoimplementation. Turns on post route timing report generation.
  • The-R1specification turns on everything -R0 does, plusreport_failfast pre-opt_design, report_failfast post-opt_design, and all intermediate DCP generation.
  • The-R2specification turns on everything -R1 does, plus it addsreport_failfast post-route_design.
  • The-Restimatespecification forces theVivadoHLS tools to generate adesign.xmldatafile if it does not exist, to generate an estimate report. This option is useful for software emulation target, when design.xml is not generated by default.
--ini_file Reads in XP switches from file inxocc.iniformat. This might be used multiple times for multiple files. These take priority overxocc.inifiles found in default locations, but explicit--xpcommand line switches still take priority over those found in the specified file.
--interactive [ synth | impl ] xoccconfigures necessary environment and launches theVivadotoolset with either synthesis or implementation project.

XOCC Options for Compile Mode

Table 2.XOCC Options for Compile Mode
Option Valid Values Description
-cor--compile N/A Required, but mutually exclusive with--link.

Runxoccin compile mode,generate.xofile.
-kor--kernel Kernel to be compiled from the input.clor.c/.cppkernel source code. Required for C/C++ kernels. Optional forOpenCLkernels.

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

When anOpenCLkernel is compiled without the-koption, all the kernels in the input file are compiled.
-Dor--define Valid macro name and definition pair.

=

 Pre-define name as a macro with definition. This option is passed to thexoccpre-processor.
-Ior--include Directory name that includes required header files. Adds the directory to the list of directories to be searched for header files. This option is passed to theSDAccelcompiler preprocessor.
--max_memory_ports all | Valid forOpenCLkernels.

Sets the maximum memory ports for all kernels or for a given.
--memory_port_data_width all | : Valid forOpenCLkernels.

Sets the memory port data width to thefor all kernels or for a given.
--export_hls_project

Specify a directory where a HLS project set-up script is exported
--hls_export_mode Valid file types include:
  • xo
  • tcl

: Set an export mode from HLS with the path to an exported file.

XOCC Options for Link Mode

Table 3.XOCC Options for Link Mode
Option Valid Values Description
-Oor--optimize Valid optimization levels: 0, 1, 2, 3, s, quick. Only one value can be used.

example: --optimize 2

This option ONLY applies toVivado.

 These options control the default optimizations performed by theVivadohardware synthesis engine.

Familiarity with theVivadotool 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 might increase considerably.
  • s: Optimize for size. This reduces the logic resources for the kernel
  • quick: QuickVivadocompilation time. This might result in reduced hardware performance, and a greater use of resources in the hardware implementation.
--user_board_repo_paths

Specify existing user board repository for DIMM board files. This value will be appended toboard_part_repo_paths.
--board_connection

Specify a dual in-line memory module (DIMM) board file for each DIMM connector slot.
-lorlink N/A Required, but mutually exclusive with--compile.

Runxoccin link mode. Link.xoinput files, generate.xclbinfile.
--nk
For example: 
foo:2
For example: 
foo:3:fooA.fooB.fooC
 This option instantiates the specified number of compute units for the given kernel in the .xclbinfile.

The compute unit (CU) name is optional. If the CU name is not specified, the instances of the kernel are simply numbered:kernel_name_1,kernel_name_2, and so forth.

By default, the XOCC instantiates one compute unit for each kernel.
-jor--jobs Number of parallel jobs. Optional. This option allows detailed control of theVivado Design Suiteused to implement the FPGA hardware.

Familiarity with theVivado Design Suiteis recommended to make the most use of this option.

Specifies the number of parallel jobs to be passed to theVivado Design Suitefor implementation. Increasing the number of jobs allows the hardware implementation step to spawn more parallel processes and complete faster.
--lsf bsubcommand line to pass to LSF cluster.

This argument is required for use with--lsf.

 Optional. Use IBM Platform Load Sharing Facility (LSF) forVivadoimplementation and synthesis. For example:--lsf '{bsub -R \"select[type=X86_64]\" -N -q medium}'
--reuse_impl Imports an implemented DCP and runs only the XCLBIN packaging.
--dk <[protocol|chipscope|list_ports]::>
Where:
  • is optional. If not specified, all ports are expected to be analyzed.
  • Thechipscopeoption requires the explicit name of the compute unit to be provided for theand.
  • Theprotocoloption can accept a special keyword "all" forand for. Thechipscopeoption can not accept this keyword "all."
  • Thelist_portsoption shows a list of valid compute units and port combinations in the current design.
 Enables debug IP core insertion. Allows you to specify which compute unit interfaces to monitor with chipscope. This is useful for hardware debugging.

The System ILA debug core provides transaction level visibility into an accelerated kernel or function running on hardware. AXI traffic of interest can also be captured and viewed using the System ILA core.

The--dkoption allows you to attach System ILA cores at the interfaces to the kernels for debugging and performance monitoring purposes.
--sc 
.:.
Where:
  • is the compute unit name specified in the--nkoption. Generally this will beunless a different name was specified.
  • is the function argument name for the compute unit port that is declared as AXIS.
 Create a streaming connection between two compute units through their AXIS interfaces. For example, to connect the AXI ports_outport of the compute unitmem_read_1to AXI stream ports_inof the compute unitincrement_1, use the following:
--sc mem_read_1.s_out:increment_1.s_in
Use a separate command for each interface.
--slr :
Where:
  • is the name of the compute unit as specified in the--nkoption. Generally this will be unless a different name was specified.
  • is the SLR number to which the CU is assigned. For example, SLR0, SLR1.
  • The option must be repeated for each kernel or CU being assigned.

Use--slrto assign a compute unit (CU) to an SLR..

For example, to assign CUvadd_2to SLR2, and CUfft_1to SLR1, you would use the following:

--slr vadd_2:SLR2 --slr fft_1:SLR1
IMPORTANT:If you use --slrto assign the kernel placement, then you must also use --spto assign memory access for the kernel.
--sp .:
Where:
  • is the name of the compute unit as specified in the--nkoption. Generally this will be unless a different name was specified.

  • is the name of the function argument for the kernel, or compute unit port.

  • represents a memory resource name from the target platform. Validnames include DDR, PLRAM, and HBM.
  • [min:max]enables the use of a range of memory, such as DDR[0:2]. A single index is also supported: DDR[2].

--sp can use either kernel parameter or interface names.

IMPORTANT:HBM is available only for the U280 ES1.

Optional argument which specifies the assignment of kernel interfaces to memory resources.

A separate--spoption is required to map each kernel interface to a particular memory resource.

Any kernel interface not explicitly mapped to a memory resource via the--spoption will be automatically connected to an available memory resource.

The following example maps the input argument (A) for the specified CU of the VADD kernel to DDR[0:3], input argument (B) to HBM[0:31], and writes the output argument (C) to PLRAM[2]: 
--sp vadd_1.A:DDR[0:3] --sp vadd_1.B:HBM[0:31] --sp vadd_1.C:PLRAM[2]
--sys_config Valid value isocl Specifies a system configuration setting for SoC platforms. Valid value isocl.

In platform spfm file, the configuration section should containsdx:runtimes = "ocl."

XP Parameters

When compiling or linking, fine grain control over the hardware generated by theSDAcceltools and the hardware emulation process can be specified by using the--xpswitch.

The–-xpswitch is paired with parameters to configure theVivadotools. For instance, the switch--xpcan configure optimization, placement and timing, or set up emulation and compile options. Specific examples of these parameters include setting the clock margin, specifying the depth of FIFOs used in the kernel dataflow region, and specifying the number of outstanding writes and reads to buffer on the kernel AXI interface.

IMPORTANT:Familiarity with the Vivado Design Suiteis required 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 asparm:=. For example:

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

You can specify the-–xpcommand option multiple times in a singlexoccinvocation or specify the value(s) in anxocc.inifile with each option specified on a separate line without--xpswitch.

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

Upon invocation,xoccfirst looks for anxocc.inifile in the$HOME/.Xilinx/sdxdirectory. If the file does not exist, thenxocclooks for it in the current working directory. If the same--xpparameter value is specified in both the command line andxocc.inifile, the command line value is used.

The following table lists a sample of the-–xpparameters and their values.

Table 4.XP Parameter Options
Parameter Name Valid Values Description
param:compiler.acceleratorBinaryContent Type: String

Default Value:

 Content to insert inxclbin. Valid options arebitstreamanddcp.
param:compiler.errorOnHoldViolation Type: Boolean

Default Value: TRUE

 Error out if there is hold violation.
param:compiler.maxComputeUnits Type: Int

Default Value:-1

 Maximum compute units allowed in the system. Any positive value will overwrite thenumComputeUnitssetting in the hardware platform (.dsa). The default value of -1 preserves the setting in the DSA.
param:hw_em.compiledLibs Type: String

Default Value:

 Uses mentionedclibsfor the specified simulator.
param:hw_em.platformPath Type: String

Default Value:

 Specifies the path to the custom platform directory. Thedirectory should meet the following requirements to be used in platform creation:
  • The directory should contain a subdirectory calledip_repo.
  • The directory should contain a subdirectory calledscriptsand thisscriptsdirectory should contain ahw_em_util.tclfile. Thehw_em_util.tclfile should have following two procedures defined in it:
    • hw_em_util::add_base_platform
    • hw_em_util::generate_simulation_scripts_and_compile
param:hw_em.enableProtocolChecker Type: Boolean

Default Value: FALSE

 Enables the lightweight AXI protocol checker (lapc) during HW emulation. This is used to confirm the accuracy of any AXI interfaces in the design.
param:compiler.xclDataflowFifoDepth Type: Int

Default Value:-1

 Specifies the depth of FIFOs used in kernel data flow region.
param:compiler.interfaceWrOutstanding Type: Int Range

Default Value:0

 Specifies how many outstanding writes to buffer are on the kernel AXI interface. Values are 1 through 256.
param:compiler.interfaceRdOutstanding Type: Int Range

Default Value:0

 Specifies how many outstanding reads to buffer are on the kernel AXI interface. Values are 1 through 256.
param:compiler.interfaceWrBurstLen Type: Int Range

Default Value:0

 Specifies the expected length of AXI write bursts on the kernel AXI interface. This is used with optioncompiler.interfaceWrOutstandingto determine the hardware buffer sizes. Values are 1 through 256.
param:compiler.interfaceRdBurstLen Type: Int Range

Default Value:0

 Specifies the expected length of AXI read bursts on the kernel AXI interface. This is used with optioncompiler.interfaceRdOutstandingto determine the hardware buffer sizes. Values are 1 through 256.
misc:map_connect=.kernel.. .core. OCL_REGION_0. Type: String

Default Value:

 Used to map AXI interfaces from a kernel to DDR memory banks.
  • is add or remove.
  • is the name of the kernel.
  • is a DDR memory bank M00_AXI, M01_AXI, M02_AXI, or M03_AXI.

This option is available only for DSA 4.x and earlier and deprecated for DSA 5.x and later. Use system ports using the--spoption documented inXOCC Options for Link Mode.
prop:kernel..kernel_flags Type: String

Default Value:

 Sets specific compile flags on the kernel.
prop:solution.device_repo_path Type: String

Default Value:

 Specifies the path to a repository of hardware platforms. The--platformoption with full path to the.xpfmplatform file should be used instead.
prop:solution.hls_pre_tcl Type: String

Default Value:

 Specifies the path to aVivadoHLS Tcl file, which is executed before the C code is synthesized. This allowsVivadoHLS configuration settings to be applied prior to synthesis.
prop:solution.hls_post_tcl Type: String

Default Value:

 Specifies the path to aVivadoHLS Tcl file, which is executed after the C code is synthesized.
prop:solution.kernel_compiler_margin Type: Float

Default Value: 12.5% of the kernel clock period.

 The clock margin (in ns) for the kernel. This value is subtracted from the kernel clock period prior to synthesis to provide some margin for P&R delays.
vivado_prop:. . Type: Various

Default Value: Various

 This allows you to specify any property used in theVivadohardware compilation flow.

isrun|fileset|file|project.

Theandvalues are described inVivado 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

Ifis set tofile,currentis not supported.

Ifis set torun, 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.

Using the Message Rule File

XOCC executes variousXilinxtools during kernel compilation. These tools generate many messages that provide compilation status to you. These messages might or might not be relevant to you depending on your focus and design phase. A Message Rule file can be used to better manage these messages. It provides commands to promote important messages to the terminal or suppress unimportant ones. This helps you better understand the kernel compilation result and explore methods to optimize the kernel.

The Message Rule file (.mrf) is a text file consisting of comments and supported commands. Only one command is allowed on each line.

Comment

Any line with “#” as the first non-white space character is a comment.

Supported Commands

By default,xoccrecursively scans the entire working directory and promotes all error messages to thexoccoutput. Thepromoteandsuppresscommands below provide more control on thexoccoutput.

  • promote: This command indicates that matching messages should be promoted to thexoccoutput.
  • suppress: This command indicates that matching messages should be suppressed or filtered from thexoccoutput. Note that errors cannot be suppressed.

Enter only one command per line.

Command Options

The Message Rule file can have multiplepromoteandsuppresscommands. Each command can have one and only one of the options below. The options are case-sensitive.

  • -id []: All messages matching the specified message ID are promoted or suppressed. The message ID is in format of nnn-mmm. As an example, the following is a warning message from HLS. The message ID in this case is 204-68.
    WARNING: [XOCC 204-68] Unable to enforce a carried dependence constraint (II = 1, distance = 1, offset = 1) between bus request on port 'gmem' (/matrix_multiply_cl_kernel/mmult1.cl:57) and bus request on port 'gmem'-severity [severity_level]

    For example, to suppress messages with message ID 204-68, specify the following:suppress -id 204-68.

  • -severity []: The following are valid values for the severity level. All messages matching the specified severity level will be promoted or suppressed.
    • info
    • warning
    • critical_warning

      For example, to promote messages with severity of 'critical-warning', specify the following:promote -serverity critical_warning.

Precedence of Message Rules

Thesuppressrules take precedence overpromoterules. If the same message ID or severity level is passed to bothpromoteandsuppresscommands in the Message Rule file, the matching messages are suppressed and not displayed.

Example of Message Rule File

The following is an example of a valid Message Rule file:

# promote all warning, critical warning promote -severity warning promote -severity critical_warning # suppress the critical warning message with id 19-2342 suppress -id 19-2342