AI Engine-ML Memory Tile Access - AI Engine-ML Memory Tile Access - 2026.1 English - UG1603

AI Engine-ML Kernel and Graph Programming Guide (UG1603)
Document ID
UG1603
Release Date
2026-07-08
Version
2026.1 English

Access to Memory tiles must be declared and managed in the graph.

Memory Tile Related API

A buffer within a Memory tile must be declared in the graph class and parameterized in the constructor of the class. This type of buffer is called shared_buffer. The following code snippet shows the various APIs for the shared buffers.

class basic_memgraph : public adf::graph {

public:
adf::kernel mk;
adf::port<input> din;
adf::port<output> dout;

adf::shared_buffer<int32> mtxin;

basic_memgraph() {
  mk = adf::kernel::create(maker_buf1d);
  adf::source(mk) = "maker.cpp";
  adf::runtime<ratio>(mk) = 0.9;

  // Create 2-dimensional buffer in a memory tile, 
  // with 1 input port and 1 output port
  mtxin = adf::shared_buffer<int32>::create({FRAME_LENGTH, NFRAMES},1,1);

  // Define the read and write access scheme to the shared buffer
  adf::write_access(mtxin.in[0]) = adf::tiling(/*  Tiling Parameters  */);
  adf::read_access(mtxin.out[0]) = adf::tiling(/*  Tiling Parameters  */);

  // Specify that the read/write access scheme should be repeated 12 times
  adf::repetition_count(mtxin) = 12;

  // Indicate that the buffer should be implemented as ping-pong buffer
  adf::num_buffers(mtxin) = 2;

  adf::connect(din, mtxin.in[0]);
  adf::connect(mtxin.out[0],mk.in[0]);
  adf::connect(mk.out[0], dout);
  };
};

The line adf::shared_buffer<int32> mtxin; declares a buffer located in a MEM Tile called mtxin that contains int32 data. The data can be any type supported by the AI Engine-ML.

In the class constructor, the buffer is parameterized as follows:

mtxin = adf::shared_buffer<int32>::create({FRAME_LENGTH, NFRAMES},1,1);

The shared buffer is parameterized with the following three attributes:

Size
A vector of 1, 2, 3 or 4 attributes defining the sizes over the various dimensions of the buffer. These sizes are defined in terms of samples.
Number of input ports
Each MEM Tile provides six S2MM input channels [0-5], which can be shared across all buffers within the tile. In addition to these local channels, DMA S2MM channels [0-3] from both the west and east neighboring tiles can access the local memory banks. This increases the total number of input ports available to a MEM Tile to 14 (6 local + 4 from the west + 4 from the east). Consequently, the neighboring tiles have four fewer ports each, leaving them with only two available ports.
Number of output ports
Each MEM Tile provides six MM2S input channels [0-5], which can be shared across all buffers within the tile. In addition to these local channels, DMA MM2S channels [0-3] from both the west and east neighboring tiles can access the local memory banks. This increases the total number of output ports available to a MEM Tile to fourteen (6 local + 4 from the west + 4 from the east). Consequently, the neighboring tiles have four fewer ports each, leaving them with only two available ports.

Refer to the Versal Adaptive SoC AIE-ML Architecture Manual (AM020) for more details.

The write order to the buffer and the read order from the buffer must be defined for each port. Tiling Parameters and Buffer Descriptors and Tiling Parameters Specification explain this. There is no restriction on the pattern of reads and writes except that all tile boundary addresses must be 32-bit aligned.

Overlapping data (reads and writes) is allowed, but the reads and writes cannot access data outside the buffer dimensions. If a read port generates addresses outside the buffer dimension, a zero can be propagated to the output port. This is called zero-padding. The read_access and write_access APIs specify the access patterns.
adf::write_access(mtxin.in[0]) = adf::tiling(/*  Tiling Parameters  */);
adf::read_access(mtxin.out[0]) = adf::tiling(/*  Tiling Parameters  */);
Note: Because all tile boundary addresses must be 32-bit word aligned, the dimension 0 length is restricted as follows:
  • A multiple of 2 for 16-bit data
  • A multiple of 4 for 8-bit data
  • A multiple of 8 for 4-bit data
For each iteration of the system, the access pattern might need to be repeated multiple times. The repetition_count method allows you to define this parameter:
adf::repetition_count(mtxin) = 12;
By default, a single buffer is instantiated in the MEM Tile. You can instantiate ping-pong buffers to increase throughput as follows:
adf::num_buffers(mtxin) = 2;