Configuration Commands

Description

Specifies the default behavior for array partitioning.

Syntax

config_array_partition [OPTIONS]

Options

-throughput_driven <off | auto>

Enable automatic partial and/or complete array partitioning.

• auto : Enable automatic array partitioning with smart trade-offs between area and throughput. This is the default value.
• off : Disable automatic array partitioning.

-complete_threshold <uint:4>

Sets the threshold for completely partitioning arrays. Arrays with fewer elements than the specified threshold will be completely partitioned into individual elements.

Examples

Partitions all arrays in the design, except global arrays, with less than 12 elements into individual elements.

config_array_partition -complete_threshold 12

Description

Configures the default behavior of front-end compiling.

Syntax

config_compile [OPTIONS]

Options

-enable_auto_rewind

When TRUE uses alternative HLS implementation of pipelined loops which enables automatic loop rewind. This option is TRUE when specified, or accepts values of TRUE or FALSE. The default value is FALSE.

-name_max_length <value>

Specifies the maximum length of function names. If the length of the name is longer than the threshold, the last part of the name is truncated, and digits are added to make the name unique when required. The default is 256.

-no_signed_zeros[=true|false]

Ignores the signedness of floating-point zero so that the compiler can perform aggressive optimizations on floating-point operations. The default is off.

IMPORTANT: Using this option might change the result of any floating point calculations and result in a mismatch in C/RTL co-simulation. Please ensure your test bench is tolerant of differences and checks for a margin of difference, not exact values.

-pipeline_loops <threshold>

Specifies the lower limit used when automatically pipelining loops. The default is 64, causing Vitis HLS is to automatically pipeline loops with a tripcount of 64, or greater.

If the option is applied, the innermost loop with a tripcount higher than the threshold is pipelined, or if the tripcount of the innermost loop is less than or equal to the threshold, its parent loop is pipelined. If the innermost loop has no parent loop, the innermost loop is pipelined regardless of its tripcount.

TIP: The higher the threshold, the more likely it is that the parent loop is pipelined and the runtime is increased.

-pipeline_style <stp | flp | frp>

Specifies the default type of pipeline used by Vitis HLS for the PIPELINE pragma or directive, or for loop pipelining due to the -pipeline_loops threshold specified above. For more information on pipeline styles, refer to Flushing Pipelines.

IMPORTANT: This is a hint not a hard constraint. The tool checks design conditions for enabling pipelining. Some loops might not conform to a particular style and the tool reverts to the default style (stp) if necessary.

stp

Stall pipeline. Runs only when input data is available otherwise it stalls. This is the default setting, and is the type of pipeline used by Vitis HLS for both loop and function pipelining. Use this when a flushable pipeline is not required. For example, when there are no performance or deadlock issue due to stalls.

flp

Flushable pipeline architecture: flushes when input data is not available then stalls waiting for new data.

frp

Free-running, flushable pipeline. Runs even when input data is not available. Use this when you need better timing due to reduced pipeline control signal fanout, or when you need improved performance to avoid deadlocks. However, this pipeline style may consume more power, as the pipeline registers are clocked even if there is no data.

-pragma_strict_mode[=true|false]

Enable error messages for misplaced or misused pragmas.

-pre_tcl <arg>

Specify a TCL script to run prior to starting the csynth_design command.

-unsafe_math_optimizations[=true|false]

Ignores the signedness of floating-point zero and enables associative floating-point operations so that compiler can perform aggressive optimizations on floating-point operations. The default is OFF.

Note: Using this option might change the result of any floating point calculations and result in a mismatch in C/RTL co-simulation. Please ensure your test bench is tolerant of differences and checks for a margin of difference, not exact values.

Examples

Pipeline the innermost loop with a tripcount higher than 30, or pipeline the parent loop of the innermost loop when its tripcount is less than or equal 30:

config_compile -pipeline_loops 30

Ignore the signedness of floating-point zero:

config_compile -no_signed_zeros

Ignore the signedness of floating-point zero and enable the associative floating-point operations:

config_compile -unsafe_math_optimizations

Description

• Specifies the default behavior of dataflow pipelining (implemented by the set_directive_dataflow command).
• Allows you to specify the default channel memory type and depth.

Syntax

config_dataflow [OPTIONS]

Options

-default_channel [fifo | pingpong]

By default, a RAM memory, configured in pingpong fashion, is used to buffer the data between functions or loops when dataflow pipelining is used. When streaming data is used (that is, the data is always read and written in consecutive order), a FIFO memory is more efficient and can be selected as the default memory type.

TIP: Set arrays to streaming using the set_directive_stream command to perform FIFO accesses.

-disable_fifo_sizing_opt

Disable FIFO sizing optimizations that increase resource usage and may improve performance and reduce deadlocks.

-fifo_depth <integer>

Specifies the default depth of the FIFOs. The default depth is 2.

This option has no effect when ping-pong memories are used. If not specified, the default depth is 2, or if this is an array converted into a FIFO, the default size is the size of the original array. In some cases, this might be too conservative and introduce FIFOs that are larger than necessary. Use this option when you know that the FIFOs are larger than required.

CAUTION: Be careful when using this option. Insufficient FIFO depth might lead to deadlock situations.

-override_user_fifo_depth <value>

Use the specified depth for every hls::stream, overriding any user settings.

Note: This is useful for checking if a deadlock is due to insufficient FIFO depths in the design. By setting it to a very large value (for example, the maximum depth printed by co-simulation at the end of simulation), if there is no deadlock, then you can use the FIFO depth profiling options of co-simulation and the GUI to find the minimum depth that ensures performance and avoids deadlocks.

-scalar_fifo_depth <integer>

Specifies the minimum for scalar propagation FIFO.

Through scalar propagation, the compiler converts the scalar from C/C++ code into FIFOs. The minimal sizes of these FIFOs can be set with -start_fifo_depth. If this option is not provided, then the value of -fifo_depth is used.

-start_fifo_depth <integer>

Specifies the minimum depth of start propagation FIFOs.

This option is only valid when the channel between the producer and consumer is a FIFO. This option uses the same default value as the-fifo_depth option, which is 2. Such FIFOs can sometimes cause deadlocks, in which case you can use this option to increase the depth of the FIFO.

-strict_mode [off | warning | error]

Set the severity for messages related to dataflow canonical form.

-strict_stable_sync[=true|false]

Force synchronization of stable ports with ap_done.

-task_level_fifo_depth <integer>

Specifies the depth of the task level FIFO.

A FIFO is synchronized by ap_ctrl_chain. The write is the ap_done of the producer, the read is the ap_ready of the consumer. Like a PIPO in terms of synchronization, and like a FIFO in terms of access.

Examples

Changes the default channel from ping-pong memories to FIFOs:

config_dataflow -default_channel fifo

Changes the default channel from ping-pong memories to FIFOs with a depth of 6:

config_dataflow -default_channel fifo -fifo_depth 6

To find the cause of deadlocks, try to increase all the FIFO depths significantly, especially those that are reported by C/RTL co-simulation. If the deadlock disappears with a large "N", then it is due to insufficient FIFO depths. You can test this as follows:

config_dataflow -fifo_depth N -start_fifo_depth N -scalar_fifo_depth N -task_level_fifo_depth N

Description

Configures the default behavior of front-end compiling.

Syntax

config_debug [OPTIONS]

Options

-directory <path>

Specifies the location of HLS debugging output. If not specified, location is set to solution/.debug.

-enable[=true|false]

Enable generation of HLS debugging files used in Vitis debug flow.

Examples

The following example enables the debug files:

config_debug -enable true

Description

Configures options for export_design which can either run downstream tools or package a Vivado IP or Vitis compiled kernel object (.xo).

Syntax

config_export [OPTIONS]

Options

-description <string>

Provides a description for the catalog entry for the generated IP, used when packaging the IP.

-disable_deadlock_detection

Disables simulation-only deadlock detection in top level RTL of exported IP/XO file.

-display_name <string>

Provides a display name for the catalog entry for the generated IP, used when packaging the IP.

-format (ip_catalog | xo | syn_dcp | sysgen)

Specifies the format to package the IP. The supported formats are:

ip_catalog

A format suitable for adding to the Xilinx IP catalog.

xo

A format accepted by the v++ compiler for linking in the Vitis application acceleration flow.

syn_dcp

Synthesized checkpoint file for Vivado Design Suite. If this option is used, RTL synthesis is automatically executed. Vivado implementation can be optionally added.

sysgen

Generates a Vivado IP and .zip archive for use in System Generator.

-ip_xdc_file <arg>

Specify an XDC file whose contents will be included in the packaged IP for use during implementation in the Vivado tool.

-ip_xdc_ooc_file <arg>

Specify an out-of-context (OOC) XDC file whose contents will be included in packaged IP and used during out-of-context Vivado synthesis for the exported IP.

-ipname <string>

Provides the name component of the <Vendor>:<Library>:<Name>:<Version> (VLNV) identifier for generated IP.

-library <string>

Provides the library component of the <Vendor>:<Library>:<Name>:<Version> (VLNV) identifier for generated IP.

-output <string>

Specifies the output location of the generated IP, .xo, or DCP files. The file is written to the solution/impl folder of the current project if no output path is specified.

-rtl (verilog | VHDL)

Specifies which HDL is used when the -flow option is executed. If not specified, Verilog is the default language for the Vivado synthesized netlist.

-taxonomy <string>

Specifies the taxonomy for the catalog entry for the generated IP, used when packaging the IP.

-vendor <string>

Provides the vendor component of the <Vendor>:<Library>:<Name>:<Version> (VLNV) identifier for generated IP.

-version <string>

Provides the version component of the <Vendor>:<Library>:<Name>:<Version> (VLNV) identifier for generated IP.

-vivado_clock <arg>

Override the specified HLS clock constraint used in Vivado OOC run. This is only used for reporting purposes and will not apply to the exported IP.

-vivado_impl_strategy <string>

Specifies Vivado implementation strategy name. The default name is 'default'.

-vivado_max_timing_paths <uint:10>

Specify the max number of timing paths to report when the timing is not met in the Vivado synthesis or implementation.

-vivado_optimization_level (0 | 1 | 2 | 3)

Vivado optimization level. This option sets other vivado_* options. This only applies for report generation and will not apply to the exported IP. The default setting is 0.

-vivado_pblock <arg>

Specify a PBLOCK range to use during implementation for reporting purposes. This will not apply to the exported IP.

-vivado_phys_opt (none | place | route | all)

Specifies whether Vivado physical optimization should be run during Vivado implementation. Valid values are:

none

Do not run (default).

place

Run post-place.

route

Run post-route.

all

Run post-place and post-route.

-vivado_report_level (0 | 1 | 2)

Specifies how many Vivado reports are generated, and does not apply to the exported IP. The valid values and the associated reports are:

0

Post-synthesis utilization. Post-implementation utilization and timing.

1

Post-synthesis utilization, timing, and analysis. Post-implementation utilization, timing, and analysis.

2

Post-synthesis utilization, timing, analysis, and failfast. Post-implementation utilization, timing, and failfast. This is the default setting.

-vivado_synth_design_args <string>

Specifies extra arguments to pass to the Vivado synth_design command. The default is -directive sdx_optimization_effort_high.

-vivado_synth_strategy <string>

Specifies Vivado synth strategy name. The default strategy is "default".

Examples

The following example exports the Vitis .xo to the specified file:

export_design -description "Kernel Export" -display_name kernel_export \
-flow impl -format xo -output "tmp/hls_tests/kernel.xo"

Description

Specifies the default interface options used to implement the RTL ports of each function during interface synthesis.

Syntax

config_interface [OPTIONS]

Options

-clock_enable[=true|false]

Adds a clock-enable port (ap_ce) to the design. The default is false.

The clock enable prevents all clock operations when it is active-Low. It disables all sequential operations

-default_slave_interface [none | s_axilite]

Enables the default for the slave interface as either none, which is the default for the Vivado IP flow, or as s_axilite which is the default for the Vitis Kernel flow, as described in Vitis HLS Process Overview.

-m_axi_addr64[=true|false]

Globally enables 64-bit addressing for all m_axi ports in the design. By default, this is enabled for the Vitis flow, and otherwise disabled.

-m_axi_alignment_byte_size <size>

Specifies the memory alignment boundary for m_axi interfaces provided as bitwidth in power of two. This can help automatic burst widening. The default value is 64 when open_solution -flow_target vitis, and 0 when the target=vivado. A 0 will allow unaligned interface sizes.

IMPORTANT: Burst behavior will be incorrect if pointers are not aligned at runtime.

-m_axi_auto_max_ports[=true|false]

If the option is true, all the m_axi interfaces that are not explicitly bundled, with INTERFACE pragmas or directives, will be mapped into individual interfaces, thus increasing the resource utilization (multiple adapters). The default is false and m_axi ports are bundled into a single interface.

-m_axi_buffer_impl [auto | lutram | uram | bram]

Select the implementation for all m_axi internal buffers.

auto

Let the tool choose the implementation.

lutram

Specifies distributed RAM for the buffers.

bram

Use the Block RAM. This is the default setting.

uram

Use the UltraRAM.

-m_axi_conservative_mode

This mode tells the m_axi not to issue a write request until the associated write data is entirely available (typically, buffered into the adapter or already emitted). This can slightly increase write latency but can resolve deadlock due to concurrent requests (read or write) on the memory subsystem. The default is false, and is enabled when the option is specified.

-m_axi_flush_mode

Configure the m_axi adapter to be flushable, writing or reading garbage data if a burst is interrupted due to pipeline blocking, missing data inputs when not in conservative mode, or missing output space. The default is false. This is enabled when the option is specified.

-m_axi_latency <latency>

Globally specifies the expected latency of the m_axi interface, allowing the design to initiate a bus request a number of cycles (latency) before the read or write is expected. The default value is 64 when open_solution -flow_target vitis, and 0 when -flow_target vivado.

-m_axi_max_bitwidth <size>

Specifies the maximum bitwidth for the m_axi interfaces data channel. The default is 1024 bits. The specified value must be a power-of-two, between 8 and 1024. Note that this decreases throughput if the actual accesses are bigger than the required interface, as they will be split into a multi-cycle burst of accesses.

-m_axi_max_read_burst_length <size>

Specifies a global maximum number of data values read during a burst transfer for all m_axi interfaces. The default is 16.

-m_axi_max_widen_bitwidth <size>

Automatic port width resizing to widen bursts for the m_axi interface, up to the chosen bitwidth. The specified value must be a power of 2 between 8 and 1024, and must align with the -m_axi_alignment_size. The default value is 512 when open_solution -flow_target vitis, and 0 when the -flow_target vivado.

-m_axi_max_write_burst_length <size>

Specifies a global maximum number of data values written during a burst transfer for all m_axi interfaces. The default is 16.

-m_axi_min_bitwidth <size>

Specifies the minimum bitwidth for the m_axi interfaces data channel. The default is 8 bits. The value must be a power of 2, between 8 and 1024. Note that this does not necessarily increase throughput if the actual accesses are smaller than the required interface.

-m_axi_num_read_outstanding <size>

Specifies how many read requests can be made to the m_axi interface without a response, before the design stalls. The default value is 16. This implies internal storage in the design, and a FIFO of size:

num_read_outstanding*max_read_burst_length*word_size

-m_axi_num_write_outstanding <size>

Specifies how many write requests can be made to the m_axi interface without a response, before the design stalls. The default value is 16. This implies internal storage in the design, and a FIFO of size:

num_write_outstanding*max_write_burst_length*word_size

-m_axi_offset [off | direct | slave]

Globally controls the offset ports for all m_axi interfaces in the design.

off

No offset port is generated. This is the default value in the Vivado IP flow.

direct

Generates a scalar input offset port for directly passing the address offset into the IP through the offset port.

slave

Generates an offset port and automatically maps it to an AXI4-Lite slave. This is the default value.

-register_io [off | scalar_in | scalar_out | scalar_all]

Globally enables registers for all inputs, all outputs, or all ports on the top function. The default is off.

-s_axilite_data64[=true|false]

Set the data width for the s_axilite interface to 64 bits.

-s_axilite_status_regs [ecc | off]

Enables exposure of ECC error bits in the s_axilite register map via two clear-on-read (COR) counters per BRAM or URAM with ECC enabled.

off

No status registers generated. This is the default setting.

ecc

Enable counters for ECC errors for BRAMs and URAMs

Examples

• Exposes global variables as I/O ports.
• Adds a clock enable port.

config_interface -expose_global -clock_enable

Description

Sets the default options for micro-architecture binding of an operator (add, mul, sub...) to an FPGA implementation resource, and specify its latency.

Binding is the process in which operators (such as addition, multiplication, and shift) are mapped to specific RTL implementations. For example, a mult operation implemented as a combinational or pipelined RTL multiplier.

This command can be used multiple times to configure the default binding of different operation types to different implementation resources, or specify the default latency for that operation. The default configuration defined by config_op can be overridden by specifying the BIND_OP pragma or directive for a specific design element.

Syntax

config_op [OPTIONS] <op>

<op>

Specifies the type of operation for the specified variable. Supported values include:

• mul: integer multiplication operation

• add: integer add operation

• sub: integer subtraction operation

• fadd: single precision floating-point add operation

• fsub: single precision floating-point subtraction operation

• fdiv: single precision floating-point divide operation

• fexp: single precision floating-point exponential operation

• flog: single precision floating-point logarithmic operation

• fmul: single precision floating-point multiplication operation

• frsqrt: single precision floating-point reciprocal square root operation

• frecip: single precision floating-point reciprocal operation

• fsqrt: single precision floating-point square root operation

• dadd: double precision floating-point add operation

• dsub: double precision floating-point subtraction operation

• ddiv: double precision floating-point divide operation

• dexp: double precision floating-point exponential operation

• dlog: double precision floating-point logarithmic operation

• dmul: double precision floating-point multiplication operation

• drsqrt: double precision floating-point reciprocal square root operation

• drecip: double precision floating-point reciprocal operation

• dsqrt: double precision floating-point square root operation

• hadd: half precision floating-point add operation

• hsub: half precision floating-point subtraction operation

• hdiv: half precision floating-point divide operation

• hmul: half precision floating-point multiplication operation

• hsqrt: half precision floating-point square root operation

• facc: single precision floating-point accumulate operation

• fmacc: single precision floating-point multiply-accumulate operation

• fmadd: single precision floating-point multiply-add operation

Options

-impl [dsp | fabric | meddsp | fulldsp | maxdsp | primitivedsp | auto | none | all]

Defines the default implementation style for the specified operation. The default is to let the tool choose which implementation to use. The selections include:

• all: All implementations. This is the default setting.

• dsp: Use DSP resources

• fabric: Use non-DSP resources

• meddsp: Floating Point IP Medium Usage of DSP resources

• fulldsp: Floating Point IP Full Usage of DSP resources

• maxdsp: Floating Point IP Max Usage of DSP resources

• primitivedsp: Floating Point IP Primitive Usage of DSP resources

• auto: enable inference of combined facc | fmacc | fmadd operators

• none: disable inference of combined facc | fmacc | fmadd operators

-latency <value>

Defines the default latency for the binding of the type to the implementation resource. The valid value range varies for each implementation (-impl) of the operation. The default is -1, which applies the standard latency for the implementation resource.

TIP: The latency can be specified for a specific operation without specifying the implementation detail. This leaves Vitis HLS to choose the implementation while managing the latency.

-precision [low | high | standard]

Applies to facc, fmacc, and fmadd operators. Specify the precision for the given operator.

• low: Use a low precision (60 bit and 100 bit integer) accumulation implementation when available. This option is only available on certain non-Versal devices, and may cause RTL/Co-Sim mismatches due to insufficient precision with respect to C++ simulation. However, it can always be pipelined with an II=1 without source code changes, though it uses approximately 3X the resources of standard precision floating point accumulation.
• high: Use high precision (one extra bit) fused multiply-add implementation when available. This option is useful for high-precision applications and is very efficient on Versal devices, although it may cause RTL/Co-Sim mismatches due to the extra precision with respect to C++ simulation. It uses more resources than standard precision floating point accumulation.
• standard: standard precision floating point accumulation and multiply-add is suitable for most uses of floating-point, and is the default setting. It always uses a true floating-point accumulator that can be pipelined with II=1 on Versal devices, and II that is typically between 3 and 5 (depending on clock frequency and target device) on non-Versal devices.

Example 1

The following example binds the addition operation to the fabric, with the specified latency:

config_op add -impl fabric -latency 2

Example 2

The following example enables the floating point accumulator with low-precision to achieve II=1 on a non-Versal device:

config_op facc -impl auto -precision low

Description

Configures various attributes of the output RTL, the type of reset used, and the encoding of the state machines. It also allows you to use specific identification in the RTL.

By default, these options are applied to the top-level design and all RTL blocks within the design. You can optionally specify a specific RTL model.

Syntax

config_rtl [OPTIONS]

Options

-header <string>

Places the contents of file <string> at the top (as comments) of all output RTL and simulation files.

TIP: Use this option to ensure that the output RTL files contain user specified identification.

-kernel_profile

Add top level event and stall ports required by kernel profiling.

-module_auto_prefix

Specifies the top level function name as the prefix value. This option is ignored if config_rtl -module_prefix is also specified. This is enabled by default.

-module_prefix <string>

Specifies a user-defined prefix to be added to all RTL entity/module names.

-mult_keep_attribute

Enable keep attribute.

-register_all_io

Register all I/O signals by default. The default is false. This is enabled when the option is specified.

-register_reset_num <int>

Specifies the number of registers to add to reset signal. The default is 0.

-reset [none | control | state | all]

Variables initialized in the C/C++ code are always initialized to the same value in the RTL and therefore in the bitstream. This initialization is performed only at power-on. It is not repeated when a reset is applied to the design.

The setting applied with the -reset option determines how registers and memories are reset.

none

No reset is added to the design.

control

Resets control registers, such as those used in state machines and those used to generate I/O protocol signals. This is the default setting.

state

Resets control registers and registers or memories derived from static or global variables in the C/C++ code. Any static or global variable initialized in the C/C++ code is reset to its initialized value.

all

Resets all registers and memories in the design. Any static or global variable initialized in the C/C++ code is reset to its initialized value.

-reset_async

Causes all registers to use a asynchronous reset. If this option is not specified, a synchronous reset is used.

-reset_level (low | high)

Allows the polarity of the reset signal to be either active-Low or active-High. The default is High.

Examples

Configures the output RTL to have all registers reset with an asynchronous active-Low reset.

config_rtl -reset all -reset_async -reset_level low

Adds the contents of my_message.txt as a comment to all RTL output files.

config_rtl -header my_mesage.txt

Description

Configures the default type of scheduling performed by Vitis HLS.

Syntax

config_schedule [OPTIONS]

Options

-enable_dsp_full_reg[=true|false]

Specifies that the DSP signals should be fully registered. The default is true.

Examples

The following example disables registering DSP signals:

config_schedule -enable_dsp_full_reg=false

Description

Sets the global default options for Vitis HLS micro-architecture binding of FIFO storage elements to memory resources.

The default configuration defined by config_storage for FIFO strorage can be overridden by specifying the BIND_STORAGE pragma or directive for a specific design element, or specifying the storage_type option for the INTERFACE pragma or directive for objects on the interface.

Syntax

config_storage [OPTIONS] <type>

<type>

Configures the fifo type.

Options

-auto_srl_max_bits <value>

Specifies the maximum allowed SRL total bits (depth * width) for auto-srl implementations (-impl autosrl). The default is 1024.

-auto_srl_max_depth <value>

Specifies the maximum allowed SRL depth for auto-srl implementation (-impl autosrl). The default is 2.

-impl [autosrl | bram | lutram | uram | memory | srl]

Defines the device resource to use in binding the specified type.

Examples

The following example configures the default binding of fifo:

config_storage fifo -impl uram 

Description

Automatically unroll loops based on the loop index limit (or tripcount).

Syntax

config_unroll [OPTIONS] <value>

Options

-tripcount_threshold <value>

All loops which have fewer iterations than the specified value are automatically unrolled. The default value is 0.

Example

The following command ensures all loops which have fewer than 18 iterations are automatically unrolled during scheduling.

config_unroll -tripcount_threshold 18