Buffer Port Attributes and API - 2024.1 English

AI Engine Kernel and Graph Programming Guide (UG1079)

Document ID
Release Date
2024.1 English

Attributes on buffer ports that can be configured are the buffer port's size, margin, locking protocol (synchronous or asynchronous), addressing mode (linear or circular), and single buffer versus ping-pong-buffer. Of these attributes, margin, locking protocol and addressing mode are specified in the kernel function signature. Single buffer versus. ping-pong buffer is specified in the graph.

The size of a buffer port can be specified either in the kernel signature or in the graph constructor. If the kernel function signature does not specify the size or if it is specified to be adf::inherited_extent, then the size must be specified in the graph using the dimensions() API. The dimensions() API is used in the constructor of the graph and configures buffer port size in terms of the number of samples.

adf::inherited_extent, represents the size of the buffer which will be inferred from the context, e.g., it is inferred from the specification in the graph.

The buffer port margin represents the number of samples copied from the end of one block to the beginning of the next one. If a margin parameter is specified, the total memory allocated is the sum of sample size and margin size, multiplied by template data type in number of bytes( (sample size + margin size) * sizeof (data type)). In the case of a circular output buffer, the margin can be specified as adf::inherited_margin. In this situation, the margin size will be specified by the sink connected to this output port.

An example function prototype specifying margin size follows:

simple(input_buffer<int32, adf::extents<adf::inherited_extent>, 
        adf::margin<MARGIN_SIZE>> & in0,
        output_buffer<int32> & out0);
  • Buffer port types define their dimensions and margin in number of samples of data. To determine the actual data size stored in physical memory, you will need to multiply the total number of samples with supported data type in bytes.
  • If there is no margin, buffer size must be a multiple of 16 bytes. Otherwise, both buffer and margin size must be a multiple of 32 bytes.
  • Constructs related to I/O buffers are defined in the adf namespace. Therefore, these constructs need to be qualified with adf::, unless you include using namespace adf;.