AI Engine-ML Memory Tile Access - 2025.2 English

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

AI Engine-ML Kernel and Graph Programming Guide (UG1603)

Document ID

UG1603

Release Date

2025-11-26

Version

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

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 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.
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 as well as the read order from the buffer must be defined for each port. This is explained in Tiling Parameters and Buffer Descriptors and Tiling Parameters Specification. There is no restriction on the pattern of reads and writes except that all tile boundary addresses should 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. These access patterns are specified using read_access and write_access API:

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 should be 32-bit word aligned, dimension 0 length is restricted to a multiple of 2 for 16-bit data, a multiple of 4 for 8-bit data, and 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 the user to define this parameter:

adf::repetition_count(mtxin) = 12;

By default, a single buffer is instantiated in the MEM Tile. Ping-Pong buffers can be instantiated to increase throughput as follows:

adf::num_buffers(mtxin) = 2;