Configuring input_plio/output_plio - 2025.2 English - UG1603

You can configure an input_plio/output_plio object to make external stream connections that cross the AI Engine-ML to the PL boundary. This occurs when a hardware platform is designed separately and the PL blocks are already instantiated inside the platform. This hardware design is exported from the Vivado tools as a package XSA and you must specify it when creating a new project in the AMD Vitis™ tools using that platform. The XSA contains a logical architecture interface specification that identifies which AI Engine-ML I/O ports the platform supports. The following is an example interface specification containing stream ports (looking from the AI Engine-ML perspective).

This interface specification describes how the platform exports two stream input ports (slave port on the AI Engine-ML array interface) and one stream output port (master port on the AI Engine-ML array interface). An input_plio/output_plio attribute specification to represents and connects these interface ports to their respective destination or source kernel ports in data flow graph.

The following example shows how the input_plio/output_plio attributes shown in the previous table can be used in a program to read input data from a file or write output data to a file. The width and frequency of the input_plio/output_plio port are also provided in the PLIO constructor.

adf::input_plio wts  = adf::input_plio::create("Weight0", adf::plio_32_bits, "inputwts.txt", 300);
adf::input_plio din  = adf::input_plio::create("Datain0", adf::plio_32_bits, "din.txt", 300);
adf::output_plio out = adf::output_plio::create("Dataout0", adf::plio_32_bits, "dout.txt", 300);

When simulated, the input weights and data are read from the two supplied files and the output data is produced in the designated output file in a streaming manner.

When a hardware platform is exported, all the AI Engine-ML to PL stream connections are already routed to specific physical channels from the PL side.

Wide Stream Data Path PLIO

Typically, the AI Engine-ML array runs at a higher clock frequency than the internal programmable logic. The --pl-freqoption can be set to specify the frequency at which the PL blocks are expected to run. To balance the throughput between AI Engine-ML and internal programmable logic, it is possible to design the PL blocks for a wider stream data path (64-bit, 128-bit), which is then sequentialized automatically into a 32-bit stream on the AI Engine-ML stream network at the AI Engine-ML to PL interface crossing.

The following example shows how wide stream input_plio/output_plio attributes can be used in a program to read input data from a file or write output data to a file.

adf::output_plio pl_out = adf::output_plio::create("TestLogicalNameOut", adf::plio_128_bits, "data/output.txt");
adf::input_plio  pl_in  = adf::input_plio::create("TestLogicalNameIn", adf::plio_128_bits, "data/input.txt");
...
adf::connect(pl_in.out[0], kernel_first.in[0]);
adf::connect(kernel_last.out[0], pl_out.in[0]);

In the previous example, two 128-bit PLIO attributes is declared: one for input and one for output. The input_plio and output_plio are then hooked up to the graph in the usual way. Data files specified in the input_plio/output_plio attributes are then automatically opened for reading the input or writing the output respectively.

When simulating input_plio/output_plio with data files, organize the data to accommodate both the width of the PL block and the data type of the connecting port on the AI Engine-ML block. For example, organize a data file representing a 32-bit PL interface to an AI Engine kernel expecting int16 as two columns per row, where each column represents a 16-bit value. As another example, organize a data file representing 64-bit PL interface to an AI Engine kernel expecting cint16 as four columns per row, where each column represents a 16-bit real or imaginary value. The same 64-bit PL interface feeding an AI Engine kernel with int32 port needs to organize the data as two columns per row of 32-bit real values. The following examples show the format of the input file for the previously mentioned scenarios.

64-bit PL interface feeding AI Engine kernel expecting cint16
input file:
0 0 0 0
1 1 1 1
2 2 2 2

64-bit PL interface feeding AI Engine kernel expecting int32
input file:
0 0
1 1
2 2

With these wide PLIO attribute specifications, the AI Engine compiler generates the AI Engine-ML array interface configuration. It converts a 64-bit or 128-bit data into a sequence of 32-bit words. The AXI4-Stream protocol used by all PL IP blocks ensures that partial data can be sent on a wider data path. This includes the appropriate strobe signals describing which words are valid.