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 thexocc
link 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/--compile
option. The default output name for the.xofile isa.xo; rename the file to reflect the kernel name.
The-c/--compile
command syntax is as follows:
xocc -c --platform -o .xo
kernel
keyword 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 containerxclbin
file using the-l/--link
option. The default output name for thexclbinfile isa.xclbin; rename it as needed
The-l/--link
command 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:
- ForSDAccel, see theSDAccel Environment Release Notes, Installation, and Licensing Guide(UG1238).
- ForSDSoC™, see theSDSoC Development Environment Release Notes, Installation, and Licensing Guide.
xcpp
and
xocc
commands that can be used as references for compiling user applications.
- XOCC Common Options
Options common to both Compile and Link modes.
- XOCC Options for Compile Mode
- XOCC Options for Link Mode
XOCC Common Options
sw_emu
and link with
hw_emu
.
Option | Valid Values | Description |
---|---|---|
-f or--platform |
Name of supported acceleration platform byXilinxor full path to .xpfm file that represents a platform. | Required. The--platform option 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:
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. |
-t or--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 .
Default: |
-o or--output |
File name with.xofor compiling and.xclbinfor linking, depending onxocc mode. |
Optional. Sets output file name. Default:
|
-v or--version |
N/A | Prints the version and build information of XOCC. |
-h or--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)
Syntax Example 2 (overrides more than 1 kernel clock)
DSA with two clocks (+ RTL kernel with two clock ports):
|
--profile_kernel |
|
Profiling DDR memory traffic for kernel and host. The last field for trace value ( For The |
--xp |
Refer toXP Parameters. | Specifies detailed parameter and property settings in theVivado® Design Suiteused to implement the FPGA hardware. For example:
Familiarity with theVivado Design Suiteis recommended to make the most use of these parameters. For a complete description of the |
-g or--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--report option 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 |
--log_dir |
Directory | Specifies a log directory. If the--log option 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 |
--temp_dir |
Directory | Specifies 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).If no temp directory is specified, the tool saves the files to |
--export_script |
N/A | Generates the Tcl script, Not supported for |
--custom_script |
Intended for use with the--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 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.
|
--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: |
These report levels have mappings kept in the optMap.xml file. You can override the installed optMap.xml to define custom report levels.
|
--ini_file |
Reads in XP switches from file inxocc.ini format. This might be used multiple times for multiple files. These take priority overxocc.ini files found in default locations, but explicit--xp command line switches still take priority over those found in the specified file. |
|
--interactive |
[ synth | impl ] |
xocc configures necessary environment and launches theVivadotoolset with either synthesis or implementation project. |
XOCC Options for Compile Mode
Option | Valid Values | Description |
---|---|---|
-c or--compile |
N/A | Required, but mutually exclusive with--link .Run |
-k or--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 When anOpenCLkernel is compiled without the |
-D or--define |
Valid macro name and definition pair. |
Pre-define name as a macro with definition. This option is passed to thexocc pre-processor. |
-I or--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 the |
--export_hls_project |
Specify a directory where a HLS project set-up script is exported |
|
--hls_export_mode |
Valid file types include:
|
XOCC Options for Link Mode
Option | Valid Values | Description |
---|---|---|
-O or--optimize |
Valid optimization levels: 0, 1, 2, 3, s, quick. Only one value can be used.
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.
|
--user_board_repo_paths |
Specify existing user board repository for DIMM board files. This value will be appended to |
|
--board_connection |
||
-l orlink |
N/A | Required, but mutually exclusive with--compile .Run |
--nk |
For example:
For example:
|
This option instantiates the specified number of compute units for the given kernel in the .xclbin file.The compute unit (CU) name is optional. If the CU name is not specified, the instances of the kernel are simply numbered: By default, the XOCC instantiates one compute unit for each kernel. |
-j or--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 |
bsub command line to pass to LSF cluster.This argument is required for use with |
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:
|
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 |
--sc |
Where:
|
Create a streaming connection between two compute units through their AXIS interfaces. For example, to connect the AXI ports_out port of the compute unitmem_read_1 to AXI stream ports_in of the compute unitincrement_1 , use the following: Use a separate command for each interface. |
--slr |
Where:
|
Use For example, to assign CU
IMPORTANT:If you use
--slr to assign the kernel placement, then you must also use
--sp to assign memory access for the kernel.
|
--sp |
Where:
--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 Any kernel interface not explicitly mapped to a memory resource via the
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]:
|
--sys_config |
Valid value isocl |
Specifies a system configuration setting for SoC platforms. Valid value isocl .In platform spfm file, the configuration section should contain |
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--xp
switch.
The–-xp
switch is paired with parameters to configure theVivadotools. For instance, the switch--xp
can 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.
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-–xp
command option multiple times in a singlexocc
invocation or specify the value(s) in anxocc.inifile 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 anxocc.inifile in the$HOME/.Xilinx/sdxdirectory. If the file does not exist, thenxocc
looks for it in the current working directory. If the same--xp
parameter value is specified in both the command line andxocc.inifile, the command line value is used.
The following table lists a sample of the-–xp
parameters and their values.
Parameter Name | Valid Values | Description |
---|---|---|
param:compiler.acceleratorBinaryContent |
Type: String Default Value: |
Content to insert inxclbin . Valid options arebitstream anddcp . |
param:compiler.errorOnHoldViolation |
Type: Boolean Default Value: TRUE |
Error out if there is hold violation. |
param:compiler.maxComputeUnits |
Type: Int Default Value: |
Maximum compute units allowed in the system. Any positive value will overwrite thenumComputeUnits setting 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 mentionedclibs for the specified simulator. |
param:hw_em.platformPath |
Type: String Default Value: |
Specifies the path to the custom platform directory. The directory should meet the following requirements to be used in platform creation:
|
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: |
Specifies the depth of FIFOs used in kernel data flow region. |
param:compiler.interfaceWrOutstanding |
Type: Int Range Default Value: |
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: |
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: |
Specifies the expected length of AXI write bursts on the kernel AXI interface. This is used with optioncompiler.interfaceWrOutstanding to determine the hardware buffer sizes. Values are 1 through 256. |
param:compiler.interfaceRdBurstLen |
Type: Int Range Default Value: |
Specifies the expected length of AXI read bursts on the kernel AXI interface. This is used with optioncompiler.interfaceRdOutstanding to determine the hardware buffer sizes. Values are 1 through 256. |
misc:map_connect= |
Type: String Default Value: |
Used to map AXI interfaces from a kernel to DDR memory banks.
This option is available only for DSA 4.x and earlier and deprecated for DSA 5.x and later. Use system ports using the |
prop:kernel. |
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--platform option 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.
The
Examples:
If If |
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,xocc
recursively scans the entire working directory and promotes all error messages to thexocc
output. Thepromote
andsuppress
commands below provide more control on thexocc
output.
promote
: This command indicates that matching messages should be promoted to thexocc
output.suppress
: This command indicates that matching messages should be suppressed or filtered from thexocc
output. Note that errors cannot be suppressed.
Enter only one command per line.
Command Options
The Message Rule file can have multiplepromote
andsuppress
commands. 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
Thesuppress
rules take precedence overpromote
rules. If the same message ID or severity level is passed to bothpromote
andsuppress
commands 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