Advanced Python Traffic Generator API - 2024.1 English

The following is the list of the advanced Python traffic generator API along with their usage.

ipc_axis_master_util (<sender_io_name>) 

Used to instantiate the sender port in the Python script.

ipc_axis_slave_util(<receiver_io_name>)

Used to instantiate the receiver port in the Python script.

Example

#Instantiating AXI Slave Utilities 
data_out = ipc_axis_slave_util("DataOut")

In the example, DataOut is the external port and data_out is the user object.

b_transport(packet)

Example

#Create packet
data_packet = xtlm_ipc.axi_stream_packet() // API to generate the stream packet
data = generate_data() # custom user code to generate the data
data_packet.data = data 

data_packet.tlast = True #AXI Stream Fields
#Optional AXI Stream Parameters
data_packet.tuser = optional data
data_packet.tkeep = optional data 

#Send Transaction
data_in.b_transport(data_packet)

sample_transaction()

API Usage

Calls the API using the receiver_obj created:

packet = receiver_obj.sample_transaction()

Example

#Sample the packets
data_packet = data_out.sample_transaction() # Will wait until data is received.

Here, data_out is the receiver object and data_packet is the received packet.

ipc_axis_master_nb_util (<sender_io_name>) 

API Usage

Creates a user object using the API for sender:

sender_obj = ipc_axis_master_nb_util (<sender_io_name>) 

Parameters

Name of the external port that sends the data:

<sender_io_name>

Example

#Instantiating AXI Master Utilities 
data_in = ipc_axis_master_nb_util("DataIn")

ipc_axis_slave_nb_util(<receiver_io_name>)

Used to instantiate the receiver port for non-blocking in the Python script

API Usage

Creates a user object using the API for receiver

receiver_obj = ipc_axis_slave_util (<receiver_io_name>)

Parameters

Name of the external port that sends the data

receiver_io_name

Example

#Instantiating AXI Slave Utilities
data_out = ipc_axis_slave_nb_util("DataOut")

nb_transport(<packet>)

Non-blocking API used to send AXI4-Stream packets. Prior to transporting data you need to format it into data packets as described in Formatting Data with Traffic Generators in Python below.

API Usage

Calls the API using sender_obj:

sender_obj.nb_transport(<packet>) 

Parameters

AXI4-Stream packet:

packet

This AXI4-Stream packet is created by the user which has the following attributes:

The data that needs to be sent:

data

The TLAST value to mark the end of the packet. This is the user's choice based on the application.

tlast

If not specified, the default TLAST value is true so that every data beat is a transaction. If tlast=false no TLAST is driven. If tlast=true (specified by the user based on the application), the last data beat has tlast=true.

Some other optional AXI4-Stream packet fields are tuser and tkeep.

Example

#Create packet
data_packet = xtlm_ipc.axi_stream_packet()
data = generate_data() # custom user code to generate the desired data
data_packet.data_length = "DATA_LENGTH"
data_packet.data = data
data_packet.tlast = True #to mark end of packet. This is user's choice based on application
data_in.nb_transport(data_packet)

nb_sample_transaction()

A non-blocking API to receive the AXI stream packets.

API Usage

packet = receiver_obj.nb_sample_transaction() 

Example

#Sample the packets
# Will return data if it is available
# Will return empty list if nothing is available
# Will not wait or stop the execution until data is present to sample
data_packet = data_out.nb_sample_transaction()

Here, data_out is the receiver object and data_packet is the received packet.

no_of_available_txns

For non-blocking, this API is used to get to get number of transactions received.

API Usage

Calls the API using the user object for the receiver.

Example

data_out = ipc_axis_slave_nb_util("ReceiverName")
data = []

# Checks if any data is present to receive
if(slave.no_of_available_txns != 0) :
data = data_out.nb_sample_transaction() # fill data with respective received data

end_of_simulation()

Ends and exits the simulation.

API Usage

Call the API using the sender object

sender_obj.end_of_simulation()

Example

data_in.end_of_simulation()

Preferably used with with sw_emu/hw_emu.

disconnect()

To disconnect the socket connections (DataIn, DataOut etc)

API Usage

Calls the API using sender or receiver object:

sender_obj.disconect()
receiver_obj.disconnect()

Example

data_in.disconnect() 
data_out.disconnect()

Preferably used with x86simulator or aiesimulator.

Formatting Data with Traffic Generators in Python

Data formatting is not necessary when using the AI Engine API as described in Python API for AI Engine Graphs. However, to send or receive data using the advanced API, which expects data to be in the form of packets, you need to format the data prior to transport.

To emulate AXI4-Stream transactions AXI Traffic Generators require the payload data to be broken into appropriately sized bursts. For example, to send 128 bytes with a PLIO width of 32 bits (4 bytes) requires 128 bytes/4 bytes = 32 AXI4-Stream transactions. Converting between bytes arrays and AXI transactions can be handled in Python.

The Python struct library provides a mechanism to convert between Python and C data types. Specifically, the struct.pack and struct.unpack functions pack and unpack byte arrays according to a format string argument. The following table shows format strings for common C data types and PLIO widths.

For more information see: https://docs.python.org/3/library/struct.html