--advanced Options - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 English

The --advanced.param and --advanced.prop options specify parameters and properties for use by the v++ command. When compiling or linking, these options offer fine-grain control over the hardware generated by the Vitis core development kit, and the hardware emulation process.

The arguments for the --advanced.xxx options are specified as <param_name>=<param_value>. For example:

v++ --link -–advanced.param compiler.enableXSAIntegrityCheck=true 
-–advanced.prop kernel.foo.kernel_flags="-std=c++0x"
Tip: The order of precedence between the command line and the config file, and multiple entries in the config file are described in Vitis Compiler Configuration File. However, the --advanced commands described here have the opposite precedence: config file commands take precedence over command-line arguments, and the last command encountered takes precedence over any earlier occurrences.

--advanced.param

--advanced.param <param_name>=<param_value>

Specifies advanced parameters as described in the following table.

Param Options

Table 1. Param Options
Parameter Name Valid Values Description
compiler.acceleratorBinaryContent Type: String

Default Value: <empty>

Design content to insert in the generated xclbin file. Valid options include bitstream, pdi, or dcp.

bitstream and pdi are mutually exclusive. pdi applies to Versal platforms, bitstreamapplies to non-Versal platforms.

Tip:

You can specify two values to have v++ generate two xclbin files: one containing a DCP file, and the other containing either a bitstream or PDI file. For example:

--advanced.param compiler.acceleratorBinaryContent=dcp,bitstream
--advanced.param compiler.acceleratorBinaryContent=dcp,pdi

This parameter is used while building the hardware target, this option applies to:

  • v++ --link
  • vpl.impl
  • xclbinutil
compiler.addOutputTypes Type: String

Default Value: <empty>

Additional output types produced by the Vitis compiler. Valid values include: xclbin and hw_export. Use hw_export to create a fixed XSA from dynamic hardware platforms for use in the Embedded Software Development Flow.

Applies to:

  • v++ --link
  • vpl.impl
  • XSA generation
compiler.axiDeadLockFree Type: Boolean

Default Value: TRUE

Avoid dead locks. This option is enabled by default for Vitis HLS.
compiler.​deadlockDetection Type: Boolean

Default Value: FALSE

Enables detection of kernel deadlocks during the simulation run as part of hardware emulation. The tool posts an Error message to the console and the log file when the application is deadlocked:
// ERROR!!! DEADLOCK DETECTED at 42979000 ns! SIMULATION WILL BE STOPPED! //

The message is repeated until the deadlock is terminated. You must manually terminate the application to end the deadlock condition.

Tip: When deadlocks are encountered during simulation, you can open the kernel code in Vitis HLS for additional deadlock detection and debug capability.

Applies to:

  • v++ --compile
  • Vitis HLS
  • config_export
compiler.emulationMode=<mode> Type: String

func | rtl

Indicates that the kernel should be compiled as RTL code for use in hardware emulation and hardware design, or as a C functional model with a SystemC wrapper for use in hardware emulation as described in Working with Functional Model of the HLS Kernel.

This option applies to v++ --compile. The default is to compile the kernel as RTL code.

compiler.enableIncrHwEmu Type: Boolean

Default Value: FALSE

Use to enable incremental compilation of the hardware emulation xclbin when there are minor changes made to the platform. This enables a quick rebuild of the device binary for hardware emulation when the platform has been updated.

Applies to:

  • v++ --link
  • vpl.impl
compiler.​errorOnHoldViolation Type: Boolean

Default Value: TRUE

After the last step of Vivado implementation, during timing analysis check, and clock scaling if needed. If hold violations are found, v++ quits and returns an error by default, and does not generate an xclbin. This parameter lets you over ride the default behavior.

Applies to:

  • v++ --link
  • vpl.impl
compiler.​fsanitize Type: String

Default Value: <empty>

Enables additional memory access checks for OpenCL kernels as described in Debugging OpenCL Kernels. Valid values include: address, memory.

Applies to Software Emulation and Debug.

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 option compiler.interfaceRdOutstanding to determine the hardware buffer sizes. Values are 1 through 256.

Applies to:

  • v++ --compile
  • Vitis HLS
  • config_interface
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 option compiler.interfaceWrOutstanding to determine the hardware buffer sizes. Values are 1 through 256.

Applies to:

  • v++ --compile
  • Vitis HLS
  • config_interface
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.

Applies to:

  • v++ --compile
  • Vitis HLS
  • config_interface
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.

Applies to:

  • v++ --compile
  • Vitis HLS
  • config_interface
compiler.​maxComputeUnits Type: Int

Default Value: -1

Maximum compute units allowed in the system. The default is 60 compute units, or is specified in the hardware platform (.xsa) with the numComputeUnits property.

The specified value overrides the default value or the hardware platform. The default value of -1 preserves the default.

Applies to v++ --link.

compiler.skipTimingCheckAndFrequencyScaling Type: Boolean

Default Value: FALSE

This parameter causes the Vivado tool to skip the timing check and optional clock frequency scaling that occurs after the last step of implementation process, which is either route_design or post-route phys_opt_design.

Applies to:

  • v++ --link
  • vpl.impl
​compiler.userPreCreateProjectTcl Type: String

Default Value: <empty>

Specifies a Tcl script to run before creating the Vivado project in the Vitis build process.

Applies to:

  • v++ --link
  • vpl.create_project
​compiler.userPreSysLinkOverlayTcl Type: String

Default Value: <empty>

Specifies a Tcl script to run after opening the Vivado IP integrator block design, before running the compiler-generated dr.bd.tcl script in the Vitis build process.

Applies to:

  • v++ --link
  • vpl.create_bd
​compiler.userPostSysLinkOverlayTcl Type: String

Default Value: <empty>

Specifies a Tcl script to run after running the compiler-generated dr.bd.tcl script.

Applies to:

  • v++ --link
  • vpl.update_bd
​compiler.userPostDebugProfileOverlayTcl Type: String

Default Value: <empty>

Specifies a Tcl script to run after debug profile overlay insertion in Vivado IP integrator block design in the vpl.update_bd step.

Applies to:

  • v++ --link
  • vpl.updated_bd
compiler.​worstNegativeSlack Type: Float

Default Value: 0

During timing analysis check, this specifies the worst acceptable negative slack for the design, specified in nanoseconds (ns). When negative slack exceeds the specified value, the tool might try to scale the clock frequency to achieve timing results. This specifies an acceptable negative slack value instead of zero slack.

Applies to:

  • v++ --link
  • vpl.impl
compiler.​xclDataflowFifoDepth Type: Int

Default Value: -1

Specifies the depth of FIFOs used in kernel data flow region.

Applies to:

  • v++ --compile
  • Vitis HLS
  • config_dateflow
hw_emu.aie_shim_sol_path Type: String

Default Value: <empty>

For use by Versal platforms, this option specifies the path to the AI Engine SHIM Solution constraints file which is generated by the aiecompiler.

Used during simulation, compilation, and elaboration, the file provides a logical mapping to the physical interface. This is needed for third-party simulators like Mentor Graphics Questa Advanced Simulator or Cadence Xcelium Logic Simulation.

hw_emu.​compiledLibs Type: String

Default Value: <empty>

Uses mentioned clibs for the specified simulator.

Applies to Hardware Emulation and Debug.

hw_emu.​debugMode wdb

Default Value: wdb

The default value is WDB and runs simulation in waveform mode.

This option only works in combination with the -g or --debug options.

Applies to Hardware Emulation and Debug.

hw_emu.​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.

Applies to Hardware Emulation and Debug.

hw_emu.json_device_file_path Type: String

Default Value: <empty>

For use by Versal platforms, this option specifies the path to the AI Engine JSON Device file located in the Vitis software installation area.

Used during simulation, compilation, and elaboration, the file specifies the size of the AI Engine array. This is needed for third-party simulators like Mentor Graphics Questa Advanced Simulator or Cadence Xcelium Logic Simulation.

hw_emu.platformPath Type: String

Default Value: <empty>

Specifies the path to the custom platform directory. The <platformPath> directory should meet the following requirements to be used in platform creation:
  • The directory should contain a subdirectory called ip_repo.
  • The directory should contain a subdirectory called scripts and this scripts directory should contain a hw_em_util.tcl file. The hw_em_util.tcl file should have the following two procedures defined in it:
    • hw_em_util::add_base_platform
    • hw_em_util::generate_simulation_scripts_and_compile

Applies to Hardware Emulation and Debug.

hw_emu.post_sim_settings Type: String Specifies the path to a Tcl script that is used to configure the settings of the Vivado simulator prior to running hardware emulation. This script is run after the default configuration of the tool, but prior to launching simulation. You can use the Tcl script to override specific settings, or to custom configure the simulator as needed.

Applies to Hardware Emulation and Debug.

hw_emu.reduceHwEmuCompileTime Type: Boolean

Default Value: FALSE

Move the generation of the top-level block design into the Generate Targets step of v++ --link.

Applies to Hardware Emulation and Debug.

hw_emu.​scDebugLevel none | waveform | log | waveform_and_log

Default Value: waveform_and_log

Sets the TLM transaction debug level of the Vivado logic simulator (xsim).
  • NONE to disable TLM debug
  • LOG to dump TLM transaction log info into report file
  • WAVEFORM for enabling the TLM transaction waveform view
  • WAVEFORM_AND_LOG for both the Log Messages and Waveform view

Applies to Hardware Emulation and Debug.

hw_emu.simulator XSIM | QUESTA

Default Value: XSIM

Uses the specified simulator for the hardware emulation run.

Applies to Hardware Emulation and Debug.

For example:
--advanced.param compiler.addOutputTypes="hw_export"
Tip: This option can be specified in a configuration file under the [advanced] section head using the following format:
[advanced]
param=compiler.addOutputTypes="hw_export"

--advanced.prop

--advanced.prop <arg>

Specifies advanced kernel or solution properties for kernel compilation where <arg> is one of the values described in the table below.

Table 2. Prop Options
Property Name Valid Values Description
kernel.<kernel_name>.​kernel_flags Type: String

Default Value: <empty>

Sets specific compile flags on the kernel <kernel_name>.
solution.​device_repo_path Type: String

Default Value: <empty>

Specifies the path to a repository of hardware platforms. The --platform option with full path to the .xpfm platform file should be used instead.
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 place and route delays.

--advanced.misc

--advanced.misc <arg>

Specifies advanced tool directives for kernel compilation.