Python API for AI Engine Graphs - 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)

Parameters:

• 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()

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

Parameters:

• 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.

receive_data()

receive_data()
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()

receive_data_with_size()

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

Parameters:

• 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.

receive_data_on_tlast()

receive_data_on_tlast()
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.