Iterators - 2024.1 English

AI Engine Kernel and Graph Programming Guide (UG1079)

Document ID

UG1079

Release Date

2024-06-05

Version

2024.1 English

The AI Engine API provides iterators to access AI Engine memory. The AI Engine API provides iterators to iterate over both scalar and vector data types. In addition, it also provides circular iterators. The following table lists the different types of iterators provided by the AI Engine API.

Table 1. Iterators
Iterator	Description
`aie::begin`	Returns a scalar iterator.
`aie::cbegin`	Returns a scalar iterator with read-only access.
`aie::begin_circular`	Returns a scalar circular iterator. You can specify the circular buffer size.
`aie::cbegin_circular`	Returns a scalar iterator with read-only access.
`aie::begin_random_circular`	Returns a scalar circulator iterator with random access.
`aie::cbegin_random_circular`	Returns a scalar circulator iterator with random, read-only access.
`aie::begin_vector`	Returns a vector iterator. You can specify the size of the vector.
`aie::begin_restrict_vector`	Same as `aie::begin_vector`, but the return iterator is considered restrict.
`aie::cbegin_vector`	Returns a vector iterator with read-only access.
`aie::cbegin_restrict_vector`	Same as `aie::cbegin_vector`, but the return iterator is considered restrict.
`aie::begin_restrict_vector`	Returns a vector iterator that is a restrict type.
`aie::cbegin_restrict_vector`	Returns a vector iterator that is a restrict type with read-only access.
`aie::begin_vector_circular`	Returns a circular vector iterator. You can specify the elementary vector size and total circular buffer size.
`aie::cbegin_vector_circular`	Returns a circular vector iterator with read-only access.
`aie::begin_vector_random_circular`	Returns a circular iterator for the array described by the given address and size.
`aie::cbegin_vector_random_circular`	Returns a circular iterator for the array described by the given address and size, with read-only access.

These iterators can be divided into two categories: forward iterator and random access iterator. They all support the following:

dereferencing *
operator ++
operator ==
operator !=

Random access iterator supports more operators. For example, aie::begin_vector and aie::begin_vector_random_circular also support the following:

operator --
operator +
operator -
operator +=
operator -=

For more information about the type of each iterator, see Memory in the AI Engine API User Guide (UG1529).

One of the benefits of circular buffer is that it avoids out-of-bound memory access. Following are some examples of using iterator to access memory.

alignas(aie::vector_decl_align) int32 init_value[16]={1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16};
auto iIter = aie::begin(init_value);
for(int i=0;i<16;i++, iIter++){
  *iIter=*iIter+1;
}

alignas(aie::vector_decl_align) int32 init_value[16]={1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16};

// create vector iterator
// first value is [1,2,3,4]
auto pv=aie::begin_vector<4>(init_value); 

// create const circular vector iterator
// first value is [1,2,3,4]
// total 16 elements
auto pv_c=aie::cbegin_vector_circular<4,16>(init_value);  
for(;pv!=init_value+16;pv++){
  aie::vector<int32,4> buff=*pv;
  aie::print(*pv,true,"pv:");
}
for(int i=0;i<5;i++){

  // go back to start 
  // if reach the end of the circular buffer
  aie::vector<int32,4> buff=*pv_c++;
}

// point to circular buffer size 16.
auto p=aie::begin_circular<16>(init_value); 

for(int i=0;i<N;i++){ 

  // return back to init_value+0
  // if reaches init_value+16
  *p++=i;
}

__attribute__ ((noinline)) void pass_through(input_buffer<int> & __restrict in,
    output_buffer<int> & __restrict out
    ){
  auto inIter1=aie::cbegin_restrict_vector<8>(in);
  auto outIter=aie::begin_restrict_vector<8>(out);
  for(int i=0;i<32;i++) {
    *outIter++=*inIter++;
  }
}