Loop unrolling - Loop unrolling - 2025.2 English - UG1529

AI Engine API User Guide (AIE) (UG1529)
Document ID
UG1529
Release Date
2025-11-20
Version
2025.2 English
AI Engine API User Guide: Loop unrolling
AI Engine API User Guide (AIE-API) 2025.2
Loading...
Searching...
No Matches
Functions
Loop unrolling
Uility functions and classes » Loop functions

Overview

These functions allow users to explicitly unroll the body of a loop.

The simplest way to use them is to provide a lambda expression with the loop body. For example:

aie::vector<int, 16> a;
aie::unroll_for<int, 0, 16>([](int i) __aie_inline {
a.push(i);
});
__aie_inline
#define __aie_inline
Definition config.hpp:31
aie::vector
Type for vector registers.
Definition vector.hpp:79
aie_dm_resource::a
@ a
Memory access is bound to resource a
Definition aie_doc.hpp:1380
aie::unroll_for
constexpr void unroll_for(Fn &&fn)
Invokes a function object as many times as specified by a linear index sequence.
Definition utils.hpp:467

It is recommended that any functions or function-like objects used are marked with the always_inline attribute. There are different ways you can specify this:

  1. Preprocessor macro: __aie_inline
  2. GNU attribute syntax: __attribute__((always_inline))
  3. C++11 attribute syntax: the attribute is not C++ standard but it is supported in most common compilers: [[gnu::always_inline]], [[clang::always_inline]].

References:

Functions

template<typename T, T Start, T End, T Step = 1, typename Fn>
constexpr void aie::unroll_for (Fn &&fn)
 Invokes a function object as many times as specified by a linear index sequence.
 
template<typename T, T StartY, T EndY, T StepY, T StartX, T EndX, T StepX, typename Fn>
constexpr void aie::unroll_for_2d (Fn &&fn)
 Invokes a function object as many times as defined by a 2D index sequence.
 
template<unsigned Times, typename Fn>
constexpr void aie::unroll_times (Fn &&fn)
 Invokes a function object a given number of times.
 
template<unsigned TimesY, unsigned TimesX, typename Fn>
constexpr void aie::unroll_times_2d (Fn &&fn)
 Invokes a function object as many times as defined by a 2D index sequence.
 

Function Documentation

◆ unroll_for()

template<typename T, T Start, T End, T Step = 1, typename Fn>
void aie::unroll_for ( Fn && fn)
constexpr

Invokes a function object as many times as specified by a linear index sequence.

Template Parameters
TType of the sequence values passed to the function.
StartFirst value in the sequence.
EndUpper limit of the sequence.
StepDistance between two consecutive values in the sequence.
Parameters
fn

A function object that takes a sequence value by argument. The signature of the function should be equivalent to one of the following:

void fun(const Type &i);
void fun();

The signature does not need to have const & and the type Type must be either T or implicitly convertible from T.

◆ unroll_for_2d()

template<typename T, T StartY, T EndY, T StepY, T StartX, T EndX, T StepX, typename Fn>
void aie::unroll_for_2d ( Fn && fn)
constexpr

Invokes a function object as many times as defined by a 2D index sequence.

Template Parameters
TType of the sequence values passed to the function.
StartYFirst value in the sequence (y-axis).
EndYUpper limit of the sequence(y-axis).
StepYDistance between two consecutive values in the sequence (y-axis).
StartXFirst value in the sequence (x-axis).
EndXUpper limit of the sequence (x-axis).
StepXDistance between two consecutive values in the sequence (x-axis).
Parameters
fn

A function object that takes two values of type T by argument, one per dimension. The signature of the function should be equivalent to one the following:

void fun(const Type &y, const Type &x);
void fun();

The signature does not need to have const & and the type Type must be either T or implicitly convertible from T.

◆ unroll_times()

template<unsigned Times, typename Fn>
void aie::unroll_times ( Fn && fn)
constexpr

Invokes a function object a given number of times.

The function takes the current count by argument.

Template Parameters
TimesTotal number of function calls.
Parameters
fn

A function object that takes the current count by argument. The signature of the function should be equivalent to one of the following:

void fun(const Type &i);
void fun();

The signature does not need to have const & and the type Type must be either unsigned or implicitly convertible from it.

◆ unroll_times_2d()

template<unsigned TimesY, unsigned TimesX, typename Fn>
void aie::unroll_times_2d ( Fn && fn)
constexpr

Invokes a function object as many times as defined by a 2D index sequence.

Template Parameters
TimesYTotal number of function calls (y-axis).
TimesXTotal number of function calls (x-axis).
Parameters
fn

A function object that takes two values by argument, representing the current count for each of the dimensions. The signature of the function should be equivalent to one of the following:

void fun(const Type &y, const Type &x);
void fun();

The signature does not need to have const & and the type Type must be either unsigned or implicitly convertible from it.