AI Engine Compiler Options - 2020.2 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
Release Date
2020.2 English
Table 1. AI Engine Options
Option Name Description
--constraints=<string> Constraints (location, bounding box, etc.) can be specified using a JSON file. This option lets you specify one or more constraint files.
--heapsize=<int> Heap size (in bytes) used by each AI Engine (default 1024). Used for allocating any remaining file-scoped data that is not explicitly connected in the user graph.
--stacksize=<int> Stack size (in bytes) used by each AI Engine (default 1024). Used as a standard compiler calling convention including stack-allocated local variables and register spilling.
--pl-freq=<value> Specifies a frequency (in MHz) for all PL kernels and PLIOs. The default frequency is a quarter of the AI Engine frequency. The PL frequency specific to each interface is provided in the graph.
--pl-register-threshold=<value> Specifies the frequency (in MHz) threshold for registered AI Engine-PL crossings. The default frequency is one-eighth of the AI Engine frequency dependent on the specific device speed grade.
Note: Values above a quarter of the AI Engine array frequency are ignored, and a quarter is used instead.
Table 2. CDO Options
Option Name Description
--enable-ecc-scrubbing Enable ECC Scrubbing on all the AI Engines used. This option enables ECC Scrubbing while generating AI Engine ELF CDO. (One performance counter per core is used.). ECC Scrubbing is turned off by default.
Table 3. Compiler Debug Options
Option Name Description
--kernel-linting Perform consistency checking between graphs and kernels. The default is false.
--log-level=<int> Log level for verbose logging (0: no logging, 5: all debug messages). The default level is 1.
Note: The default level with -–verbose is 5.
-v | --verbose Verbose output of the AI Engine compiler emits compiler messages at various stages of compilation. These debug and tracing logs provide useful messages regarding the compilation process.
Table 4. Execution Target Options
Option Name Description
--pl-axi-lite=[true|false] PL AXI4-Lite interface to specify true or false (default: false).
--target=<hw|x86sim> The AI Engine compiler supports several build targets (default: hw):
  • The hw target produces a libadf.a for use in the hardware device on a target platform.
  • The x86sim target compiles the code for use in the x86simulator as described in x86 Functional Simulator (x86simulator).
Table 5. File Options
Option Name Description
--include=<string> This option can be used to include additional directories in the include path for the compiler front-end processing.

Specify one or more include directories.

--output=<string> Specifies an output.json file that is produced by the front end for an input data flow graph file. The output file is passed to the back-end for mapping and code generation of the AI Engine device. This is ignored for other types of input.

This is a path to a Vitis platform file that defines the hardware and software components available when doing a hardware design and its RTL co-simulation.


By default, the compiler writes all outputs to a sub-directory of the current directory, called Work. Use this option to specify a different output directory.

Table 6. Generic Options
Option Name Description
--help List the available AI Engine compiler options, sorted in the groups listed here.
--help-list Display an alphabetic list of AI Engine compiler options.
--version Display the version of the AI Engine compiler.
Table 7. Miscellaneous Options
Option Name Description
--no-init This option disables initialization of window buffers in AI Engine data memory. This option enables faster loading of the binary images into the System C-RTL co-simulation framework.
Tip: This does not affect the statically initialized lookup tables.
--nodot-graph By default, the AI Engine compiler produces .dot and .png files by default to visualize the user-specified graph and its partitioning onto the AI Engines. This option can be used to eliminate the dot graph output.
--xlopt Enable a combination of kernel optimizations based on the level (default = 0)
  • 0: Only Single Core compiler optimizations.
  • 1: AI Engine compiler analysis and guidance.
    • Guidance is provided to allow the mapper to optimally allocate large global arrays thus minimizing memory conflicts.
    • Efficient alignment of globals that are accessed as vectors. This alignment is required for the Versal AI Engine architecture.
    • Enables ease of use using kernel analysis to automatically compute heap requirements for each core (therefore you do not need to specify the heap size).
Note: Compiler optimization (xlopt > 0) reduces debug visibility.
Table 8. Module Specific Options
Option Name Description
--Xchess=<string> Can be used to pass kernel specific options to the CHESS compiler that is used to compile code for each AI Engine.

The option string is specified as <kernel-function>:<optionid>=<value>. This option string is included during compilation of generated source files on the AI Engine where the specified kernel function is mapped.

--Xelfgen=<string> Can be used to pass additional command-line options to the ELF generation phase of the compiler, which is currently run as a make command to build all AI Engine ELF files.

For example, to limit the number of parallel compilations to four, you write -Xelfgen="-j4".

--Xmapper=<string> Can be used to pass additional command-line options to the mapper phase of the compiler. For example:

These are options to try when the design is either failing to converge in the mapping or routing phase, or when you are trying to achieve better performance via reduction in memory bank conflict.

See the Mapper and Router Options for a list and description of options.

--Xpreproc=<string> Pass general option to the PREPROCESSOR phase for all source code compilations (AIE/PS/PL/x86sim). For example:
--Xpslinker=<string> Pass general option to the PS LINKER phase. For example:
--Xpslinker=-L<libpath> -l<libname>
--Xrouter=<string> Pass general option to the ROUTER phase. For example:
Table 9. Tracing Options
Option Name Description
--aie-heat-map Enable AI Engine heat map configurations (default: false)

where <value> is equal to functions.

Event trace configuration value. Where the specified functions indicates the capture of function transitions on the AI Engine.
--num-trace-streams=<int> Number of trace streams.