| AI Engine API User Guide (AIE-API) 2025.2

Loading...
Searching...
No Matches
Basic Type Initialization
Basic Types

### Vector Initialization

The contents of a vector are undefined when default constructed.

Warning
  Operations with undefined input vectors may not produce an error during compilation, but may not work as expected.

aie::vector<int16, 16> v;
aie::vector
Type for vector registers.
Definition vector.hpp:79

The simplest way of initializing a vector is from another vector of the same type and size.

aie::vector<int16, 16> v1;
aie::vector<int16, 16> v2 = v1;

Or as the result of an operation.

aie::vector<int16, 16> v = aie::add(v1, v2);
aie::add
auto add(const Vec1 &v1, const Vec2 &v2) -> aie_dm_resource_remove_t< Vec1 >
Returns a vector with the element-wise addition of the two input vectors.
Definition aie.hpp:3608

A vector can also be read from memory using the aie::load_v operation or iterators. See Memory for more details.

aie::vector<int16, 16> v = aie::load_v<16>(ptr);
aie::load_v
auto load_v(const T *ptr) -> vector< aie_dm_resource_remove_t< T >, Elems >
Load a vector of Elems size whose elements have type T.
Definition aie.hpp:550

Sections of a vector can be modified independently. It can be done in a per-element basis.

aie::vector<int16, 16> v;
for (unsigned i = 0; i < v.size(); ++i)
v[i] = i; // i-th element is updated
aie::vector::size
static constexpr unsigned size()
Returns the number of elements in the vector.
Definition vector.hpp:108

Or by writing subvectors.

aie::vector<int16, 8> v1;
aie::vector<int16, 8> v2;
aie::vector<int16, 16> v;
v.insert(0, v1); // This updates elements 0-7
v.insert(1, v2); // This updates elements 8-15
aie::vector::insert
vector & insert(unsigned idx, const vector< T, ElemsIn > &v)
Updates the contents of a region of the vector.
Definition vector.hpp:369

Vectors can also be concatenated into a larger vector.

aie::vector<int16, 8> v1;
aie::vector<int16, 8> v2;
aie::vector<int16, 16> v = aie::concat(v1, v2);
aie::concat
auto concat(const Acc &acc, const Accums &...accums) -> accum< typename Acc::value_type, Acc::size() *(1+sizeof...(Accums))>
Concatenate the contents of all input accumulators into a larger accumulator.
Definition aie.hpp:999

### Accumulator Initialization

Accumulators support all the aforementioned vector operations but the individual element update.

The contents of an accumulator are undefined when default constructed.

Warning
  Reading an undefined input accumulator may not produce an error during compilation, but the operation may not behave as intended.

We can initialize an accumulator from the result of an operation. Some operations such as aie::mul, are able to deduce the optimal accumulator type from their input arguments. When this is the case, it is not trivial for the developer to know what type each of the template parameters will be used in every situation, but we can let the compiler deduce them instead:

aie::vector<int16, 16> a = ...
aie::vector<int32, 16> b = ...
aie::accum result = aie::mul(a, b);
aie::mul
constexpr auto mul(const Vec1 &v1, const Vec2 &v2) -> accum< AccumTag, Vec1::size()>
Returns an accumulator of the requested type with the element-wise multiplication of the two input ve...
Definition aie.hpp:4624
aie_dm_resource::a
@ a
Memory access is bound to resource a
Definition aie_doc.hpp:1380
aie_dm_resource::b
@ b
Memory access is bound to resource b
Definition aie_doc.hpp:1381
int32
int32_t int32
Definition types.hpp:22

If we need to retrieve any of the template parameters later on, it is possible to access them by means of class member typedefs:

using result_tag = decltype(result)::value_type;
constexpr size_t result_elems = result.size();

### Initialization by Stream Read

Both vectors and accumulators can also be read from ADF abstractions such as windows and streams. See Interoperability with Adaptive Data Flow (ADF) Graph Abstractions for more details.

aie::vector<int16, 8> v = readincr_v<8>(input_stream);
aie::accum<acc48, 8> acc = readincr_v<8>(input_cascade);
readincr_v
aie::vector< T, N > readincr_v(input_stream< T > *w)
Reads a vector from the input AXI stream.
Definition stream.hpp:643
aie::accum
Type for vector accumulators.
Definition accum.hpp:49
input_cascade
Definition sliding_mul.hpp:13
input_stream
Definition array_helpers.hpp:21

### Mask Initialization

Masks are usually initialized as a result of a comparison using vectors:

aie::vector<int16, 16> a, b;
aie::mask<16> m = aie::lt(a, b);
aie::mask
Type for vector element masks.
Definition mask.hpp:21
aie::lt
mask< Vec1::size()> lt(const Vec1 &v1, const Vec2 &v2)
Compares the elements of the two input vectors and returns a mask that says what elements from the fi...
Definition aie.hpp:1364

In addition, it is possible to initialize a mask using a constant value. For example:

auto m1 = aie::mask<64>::from_uint64(0xaaaabbbbccccddddULL);
auto m2 = aie::mask<64>::from_uint32(0xaaaabbbb, 0xccccdddd);
auto m3 = aie::mask<16>::from_uint32(0b1010'1010'1011'1011);
aie::mask::from_uint64
static constexpr mask< Elems > from_uint64(uint64_t w, T &&... words)
Construct from unsigned (64b) words.
Definition mask.hpp:83
aie::mask::from_uint32
static constexpr mask< Elems > from_uint32(unsigned w, T &&... words)
Construct from unsigned (32b) words.
Definition mask.hpp:63

Tip:
  You can use the standard C/C++ macros for fixed-sized integers instead of the integer suffix. In the definition of `m1` it would look like `UINT64_C(0xaaaabbbbccccdddd)`.