Python API for AI Engine Graphs - 2023.2 English

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

Document ID
Release Date
2023.2 English

Here is the list of AI Engine specific APIs and their usage in integrating the traffic generators. With the Python 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
aie_input_plio( name, datatype)
aie_output_plio(name, datatype)


  • name: A string value that should match a PLIO name from the graph.
  • datatype: A string with the following supported values [ "int8", "uint8","int16", "uint16","int32", "uint32","int64", "uint64","float", "bfloat16"]
Table 1. Supported AI Engine Data Types
#num AIE kernel Datatype API Enum String Usage User Value list representation (In Python)
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]

NOTE : 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

Note: For some types like cint32 you can use int32 as it is expected that you will provide pairs of real and imaginary values in the same list. This means the size of the user list for complex types is always even.

For example, before creating external ports, you need to do AI Engine graph modifications as described at 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 python script.

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

Here, in_data and out_data define the PLIO matching in the graph code; input and output are the objects created.

The second parameter int16 is the datatype of the interfaced AI Engine kernel with traffic generator.

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


  • data: The list of specified datatype
  • tlast: Boolean value, can be true (1) or false (0)
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_list>, "false")

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

creates a blocking call to receive data
RETURNS a list of specified dataype
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()

creates a blocking call to receive a specified amount of data


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

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

creates a blocking call returning data after receiving tlast packet

RETURNS a list of specified datatype

Note: The datatype must be specified during object instantiation.
For example:
recv_data = output.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.