set_directive_latency - 2022.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
Release Date
2022.2 English


Specifies a maximum or minimum latency value, or both, on a function, loop, or region.

Vitis HLS always aims for minimum latency. The behavior of the tool when minimum and maximum latency values are specified is as follows:

  • Latency is less than the minimum: If Vitis HLS can achieve less than the minimum specified latency, it extends the latency to the specified value, potentially enabling increased sharing.
  • Latency is greater than the minimum: The constraint is satisfied. No further optimizations are performed.
  • Latency is less than the maximum: The constraint is satisfied. No further optimizations are performed.
  • Latency is greater than the maximum: If Vitis HLS cannot schedule within the maximum limit, it increases effort to achieve the specified constraint. If it still fails to meet the maximum latency, it issues a warning. Vitis HLS then produces a design with the smallest achievable latency.
Tip: You can also use the LATENCY pragma or directive to limit the efforts of the tool to find an optimum solution. Specifying latency constraints for scopes within the code: loops, functions, or regions, reduces the possible solutions within that scope and can improve tool runtime. Refer to Improving Synthesis Runtime and Capacity for more information.

If the intention is to limit the total latency of all loop iterations, the latency directive should be applied to a region that encompasses the entire loop, as in this example: set_directive Region_All_Loop_A

Region_All_Loop_A: {
Loop_A: for (i=0; i<N; i++) 
  ..Loop Body... 

In this case, even if the loop is unrolled, the latency directive sets a maximum limit on all loop operations.

If Vitis HLS cannot meet a maximum latency constraint it relaxes the latency constraint and tries to achieve the best possible result.

If a minimum latency constraint is set and Vitis HLS can produce a design with a lower latency than the minimum required it inserts dummy clock cycles to meet the minimum latency.


set_directive_latency [OPTIONS] <location>
  • <location> is the location (function, loop or region) (in the format function[/label]) to be constrained.


-max <integer>
Specifies the maximum latency.
-min <integer>
Specifies the minimum latency.


Function foo is specified to have a minimum latency of 4 and a maximum latency of 8.

set_directive_latency -min=4 -max=8 foo

In function foo, loop loop_row is specified to have a maximum latency of 12. Place the pragma in the loop body.

set_directive_latency -max=12 foo/loop_row