Loop Flattening and Unrolling - Loop Flattening and Unrolling - 2026.1 English - UG1079

You can flatten loops completely with the chess_flatten_loop pragma. Flattening is useful for small loops that the AI Engine compiler does not optimally automated.

for(int i=0;i<6;i++) chess_flatten_loop {...}
for(...) chess_loop_count(6) chess_flatten_loop {...}

With chess_unroll_loop(N), the loop body can be duplicated N-1 times, and the loop count is divided by N. The loop can also be completely unrolled by chess_unroll_loop(*). The loop is unrolled and rewritten as a repeated sequence of similar independent statements.

chess_unroll_loop(N) creates an additional preamble loop. When the loop count is known at compile time, this preamble loop fully unrolls. However, if the loop bound is not a compile-time constant but is guaranteed to be a multiple of N, use chess_unroll_loop_assuming_multiple(N) instead. This prevents the extra preamble loop, reducing program memory usage.

Loop flattening occurs in the final scheduling phase such that code generation still uses the loop construct. Unlike loop flattening, loop unrolling duplicates iterations of code, and the duplicated codes can be compiled differently. You can use unrolling to improve software pipelining of loops, but it can place a burden on scheduling if the unrolled loop count is large.