AI Engine-ML Memory Tile Access - 2025.1 English

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

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

Document ID

UG1603

Release Date

2025-05-29

Version

2025.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 with:

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

The shared buffer is parameterized with 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: The number of physical input ports that are used to write to the shared buffer. There are six ports that can be shared among all buffers located in a MEM Tile.
Number of output ports: The number of physical output ports that will be used to read from this buffer. There are six ports that can be shared among all buffers located in a MEM Tile.

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;