set_directive_unroll - 2021.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
Release Date
2021.2 English


Transforms loops by creating multiples copies of the loop body.

A loop is executed for the number of iterations specified by the loop induction variable. The number of iterations may also be impacted by logic inside the loop body (for example, break or modifications to any loop exit variable). The loop is implemented in the RTL by a block of logic representing the loop body, which is executed for the same number of iterations.

The set_directive_unroll command allows the loop to be fully unrolled. Unrolling the loop creates as many copies of the loop body in the RTL as there are loop iterations, or partially unrolled by a factor N, creating N copies of the loop body and adjusting the loop iteration accordingly.

If the factor N used for partial unrolling is not an integer multiple of the original loop iteration count, the original exit condition must be checked after each unrolled fragment of the loop body.

To unroll a loop completely, the loop bounds must be known at compile time. This is not required for partial unrolling.


set_directive_unroll [OPTIONS] <location>
  • <location> is the location of the loop (in the format function[/label]) to be unrolled.


-factor <integer>
Specifies a non-zero integer indicating that partial unrolling is requested.

The loop body is repeated this number of times. The iteration information is adjusted accordingly.

Effective only if a factor is specified (partial unrolling).
  • Fixed bounds

    No exit condition check is performed if the iteration count is a multiple of the factor.

    If the iteration count is not an integer multiple of the factor, the tool:
    • Prevents unrolling.
    • Issues a warning that the exit check must be performed to proceed.
  • Variable bounds

    The exit condition check is removed. You must ensure that:

    • The variable bounds is an integer multiple of the factor.
    • No exit check is in fact required.


Unrolls loop L1 in function foo. Place the pragma in the body of loop L1.

set_directive_unroll foo/L1

Specifies an unroll factor of 4 on loop L2 of function foo. Removes the exit check. Place the pragma in the body of loop L2.

set_directive_unroll -skip_exit_check -factor 4 foo/L2

Unrolls all loops inside loop L3 in function foo, but not loop L3 itself. The -region option specifies the location be considered an enclosing region and not a loop label.

set_directive_unroll -region foo/L3