| 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:

- https://clang.llvm.org/docs/AttributeReference.html#always-inline-force-inline
- https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-always_005finline-function-attribute

## 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

  T | Type of the sequence values passed to the function.
  Start | First value in the sequence.
  End | Upper limit of the sequence.
  Step | Distance 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

  T | Type of the sequence values passed to the function.
  StartY | First value in the sequence (y-axis).
  EndY | Upper limit of the sequence(y-axis).
  StepY | Distance between two consecutive values in the sequence (y-axis).
  StartX | First value in the sequence (x-axis).
  EndX | Upper limit of the sequence (x-axis).
  StepX | Distance 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

  Times | Total 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

  TimesY | Total number of function calls (y-axis).
  TimesX | Total 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.