syn.directive.loop_flatten - syn.directive.loop_flatten - 2026.1 English - UG1399

Description

This option collapses inner nested loops into a single loop so the tool can pipeline all iterations to improve latency.

Only innermost loops support pipelining after unrolling. Outer loops execute only in dataflow or sequential mode. Sequential outer loops fully execute inner loops per iteration, adding entry, exit, and inner‑loop latency. Flattening merges nested loops into one pipelined loop, enabling iteration overlap and typically improving performance, however:

• Flattening does not always succeed because the code must follow specific coding styles.
• In some cases, operations or dependencies in the outer loop can degrade timing and initiation interval.

Apply syn.directive.loop_flatten to the loop body of the innermost loop in the loop hierarchy. Only perfect or almost‑perfect nested loops, after function inlining or loop unrolling, support flattening in this manner.

Perfect loop nests

• The body of each non-innermost loop contains one and only one subloop, and no other instructions.

Almost-perfect loop nests

• The body of each non-innermost loop contains one and only one subloop, and no other control flow.
• The body of each non-innermost loop must contain no function call containing a loop.

For almost‑perfect loops, the compiler automatically pushes instructions between loops into the innermost loop to create perfectly nested loops.

In addition, flattening also requires specific conditions.

• Each loop must be a for-loop, not a while-loop, and without break statements.

• The compiler must compute each loop’s tripcount before flattening, but the tripcount does not need to be a constant. Typical coding style involve the following.

  • A loop with a loop counter incremented by a numerical constant.
  • A lower bound and upper bound for the loop counter that do not depend on the loops to be flattened (they need to be "loop-invariant").

An example of non flattenability is a loop whose inner tripcount depends on the outer loop counter.

The compiler cannot flatten imperfect loop nests that contain multiple subloops or control flow. In these cases, restructure the code manually by pushing instructions into the innermost loop or unrolling inner loops to create a perfect loop nest.

Syntax

syn.directive.loop_flatten=[OPTIONS] <location>

• <location> is the location (inner-most loop), in the format function[/label].

Options

off

Optional keyword. Prevents flattening the loop that contains loop_flatten off with its subloops (if any).

Important: The presence of the LOOP_FLATTEN pragma or directive enables the optimization. The addition of off disables it.

Examples

Flattens loop_1 in function foo and all (perfect or almost-perfect) loops above it in the loop hierarchy, into a single loop.

syn.directive.loop_flatten=foo/loop_1

Prevents loop flattening in loop_2 of function foo.

syn.directive.loop_flatten=off foo/loop_2