Iterators - 2022.2 English

AI Engine Kernel and Graph Programming Guide (UG1079)

Document ID

UG1079

Release Date

2022-10-19

Version

2022.2 English

AI Engine API provides iterators to traverse 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::cbegin_vector`	Returns a vector iterator with read-only access.
`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 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+1;
}

auto pv=aie::begin_vector<4>(init_value); //create vector iterator, first value is [1,2,3,4]
auto pv_c=aie::cbegin_vector_circular<4,16>(init_value); //create const circular vector iterator, first value is [1,2,3,4], total 16 elements
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;
}