MATLAB API for AI Engine Graphs - 2024.1 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
UG1393
Release Date
2024-07-03
Version
2024.1 English

Here is the list of AI Engine specific APIs and their usage in integrating the traffic generators. With the MATLAB API you can create the traffic generator code to generate data to pass into or collect data from your AI Engine graph. Use the following API to instantiate objects to send and receive data. You can provide any datatype vector/list to send_data or receive_data.

Instantiating Classes to Send or Receive Data

You need to set the MATLAB library path to use the APIs:

vivado = getenv("XILINX_VIVADO");
libPath = fullfile(vivado, "/data/emulation/matlab/xtlm_ipc");
addpath(libPath)
aie_input_plio(name, datatype)
aie_output_plio(name, datatype)

Parameters:

  • name: A string value that should match a PLIO name from the graph
  • datatype: A string with the supported values [ "int8", "uint8","int16", "uint16","int32", "uint32","int64", "uint64","float", "bfloat16"]

For example, before creating external ports you need to make ADF graph modifications as described Graph Modification in Using Traffic Generators for AI Engine Designs. Once graph modifications are done, you can create the sender and receiver objects for the AI Engine in your MATLAB script.

input = aie_input_plio("in_data", 'int16')
output = aie_output_plio("out_data", 'int16')

Here in_data and out_data are the PLIOs defined in the graph code, input and output are the instantiated traffic generator objects.

Table 1. Supported AI Engine Data Types
#num AIE kernel Datatype API Enum String Usage User Value list representation (In MATLAB)
1 int8 int8 input_port = aie_input_plio('input_port_name',"int8") data = [12 23 2 -2 23]
2 int16 int16 input_port = aie_input_plio('input_port_name',"int16") data = [1212 121 232 -2323]
3 int32 int32 input_port = aie_input_plio('input_port_name',"int32") data = [ 121 23234 2323232 23 -878787]
4 int64 int64 input_port = aie_input_plio('input_port_name',"int64") data = [232 2342232 -23482947 238273]
5 uint8 uint8 input_port = aie_input_plio('input_port_name',"uint8") data = [23 23 12]
6 uint16 uint16 input_port = aie_input_plio('input_port_name',"uint16") data = [236 23728 2378 8237]
7 uint32 uint32 input_port = aie_input_plio('input_port_name',"uint32") data = [267 2376 2362736 232767362]
8 uint64 uint64 input_port = aie_input_plio('input_port_name',"uint64") data = [347 2348 327 98932 872389]
9 float float input_port = aie_input_plio('input_port_name',"float") data = [3.14 2.3234 3472.23]
10 bfloat16 bfloat16 input_port = aie_input_plio('input_port_name',"bfloat16")

data = [3.14 2.3234 3472.23]

Float and Bfloat16 representations in floating point are similar.But when transferred to AIE, float will be transmitted in 32 bits. bfloat16 will be trasmitted in 16 bits.

11 cfloat float input_port = aie_input_plio('input_port_name', "float")

data = [3.14 2.2323 23.3 23.33]

NOTE : From left, even positions will be real and odd positions will be imaginary

12 cint16 int16 input_port = aie_input_plio('input_port_name',"int16")

data = [32 232 232 234]

NOTE : From left, even positions will be real and odd positions will be imaginary

13 cint32 int32 input_port = aie_input_plio('input_port_name',"int32")

data = [23 -23 23 -232]

NOTE : From left, even positions will be real and odd positions will be imaginary

send_data()
send_data(data, tlast)
creates a non-blocking call to send data

RETURNS nothing

Parameters:

  • data: list of specified datatype for the object
  • tlast: boolean value, can be true or false
Note: The datatype must be specified during object instantiation.
The following is an example of creating the traffic generator object and sending data through it:
input = aie_input_plio("in_data", "uint32")
input.send_data(<data_set>, "false")

This API call sends the data to the AI Engine kernel via "in_data" PLIO connected to the traffic generator.

receive_data()
receive_data()
creates a blocking call to receive data

RETURNS a list of specified datatype

Note: The datatype must be specified during object instantiation
For example:
recv_data = output.receive_data()

recv_data is a list containing the returned value of receive_data()

receive_data_with_size()
receive_data_with_size(data_size)
creates a blocking call to receive a specified amount of data

RETURNS a list of specified datatype

Parameters:

  • data_size: integer value indicating the amount of data in bytes to receive
Note: Data size is specified in bytes
For example:
recv_data = output.receive_data_with_size(1024)

This is a blocking API which blocks until the specified bytes of data is received.

receive_data_on_tlast()
receive_data_on_tlast()
creates a blocking call returning data after receiving tlast packet

RETURNS list of specified data type

Note: The data type must be specified during object instantiation
For example:
recv_data = receive_data_on_tlast()

recv_data contains the returned data from receive_data_on_tlast(). This is a blocking API which will wait until it gets the TLAST signal.