CSV File Format - 2025.2 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2025-11-20
Version
2025.2 English

The AI Engine simulator supports the CSV file format for PLIO-based simulation. CSV file format provides more control over transactions and allows for cycle-by-cycle injection of traffic to AI Engine. CSV file format also offers the flexibility to add empty clock cycles to the traffic injection, use the STALL command to inject multiple empty cycles, and specify TLAST and TKEEP values explicitly. With these features, you can simulate complex scenarios and analyze the behavior of the design.

To associate the CSV file with a PLIO-based input or output, you need to specify the CSV file during the graph PLIO creation.

adf::input_plio in = adf::input_plio::create("DataIn", adf::plio_32_bits, "data/input.csv");
adf::input_plio out = adf::output_plio::create("DataOut", adf::plio_32_bits, "data/output.csv");

Input File

The input CSV file to the AI Engine simulator consists of a number of comma separated columns of data. The first row in the file is the header line. The header line is defined as a CMD column, followed by data D columns, followed by the TLAST and TKEEP columns.

The number of data D columns must equal the PLIO buswidth/datawidth of kernel data being input. For example the header below corresponds to data being provided for a PLIO buswidth of 32-bit, and datawidth of int16. Hence, there are two data sample D columns in the header line.

CMD, D, D, TLAST, TKEEP

The DATA command must be used to provide data input in the lines that follow the header line.

CMD, D, D, TLAST, TKEEP
DATA, 16, 20, 0, -1
DATA, 15, 11, 0, -1

You must use the STALL command to specify the number of empty cycles to be injected in the data traffic. The STALL command mimics back pressure in the input traffic that can be useful in simulating real-life data input.

CMD, D, D, TLAST, TKEEP
DATA, 16, 20, 0, -1
DATA, 15, 11, 0, -1
STALL:100
Table 1. Input Columns
Column Description
CMD

A pre-defined set of keywords for the parser to act on. Possible values are DATA, STALL:<n>, and COMMENT.

  • DATA: This command is followed by an optional argument <n> separated by colon, as in DATA:<n>.
    • <n> indicates how many times the data is repeated as input into AI Engine. Default value of <n> is 1.
  • STALL: This command represents an empty PL cycle and is followed by an optional argument <n> seperated by colon as in STALL:<n>.
    • If you specify STALL:100, no data is driven for 100 cycles from the PL domain. If the PL frequency is 100 MHz, a stall duration of 1000 ns is present from the PL side.
    • If you do not specify the argument value <n>, the default value of STALL is 1.
  • COMMENT: This command represents a comment.
D
  • Represents the data values sent to AI Engine kernel, as per the kernel data width. For example, INT8, or INT32.
  • Data column can be repeated based on the data width and PLIO bus width combination. The number of D columns equals PLIO buswidth / datawidth.
  • Data specified in the D columns are sent to the AI Engine in the order specified in the CSV file.
TKEEP

The TKEEP column can be used to specify how the D (data) columns are processed. Based on the PLIO bus width, the allowable value of the TKEEP column and its impact will differ. The TKEEP value can be empty. If it is empty, there is no effect on the data values.

32 bit PLIO buswidth:

  • Possible values : 0x0 to 0xF
  • Effect: If AI Engine PLIO buswidth is 32 bit, the TKEEP value is ignored.

64 bit PLIO buswidth:

  • Possible values : 0x0 to 0xFF
  • Effect:
    • 0x0 <= TKEEP <= 0x0F → Lower 32 bit is valid
    • 0x0F < TKEEP <= 0xFF → Full 64 bit is valid

128 bit PLIO buswidth:

  • Possible values : 0x0 to 0xFFFF
  • Effect:
    • 0x0000 <= TKEEP <= 0x000F → Lower 32 bit is valid
    • 0x000F < TKEEP <= 0x00FF → Lower 64 bit is valid, that is, two 32 bit words are valid.
    • 0x00FF < TKEEP <= 0x0FFF → Lower 96 bit is valid, that is, three 32 bit words are valid.
    • 0x0FFF < TKEEP <= 0xFFFF → All 128 bit is valid, that is, four 32 bit words are valid.
Below are examples of appropriate TKEEP combinations and their impact (in comment) during the simulation for a CSV file that represents 32 bit data type, 64 bit PLIO bus width.
CMD, D, D, TKEEP, TLAST
COMMENT, All 64 bit is valid
DATA, 1234, 5543, -1, 0
DATA, 1234, 5543, 0x0F, 0
DATA, 1234, 5543, 0xFF, 1
DATA, 1234, 5543, 0xFF, 0

COMMENT, Only lower 32 bit is valid
DATA, 1234, 5543,0x0F, 1

COMMENT, Empty D column with 0x0<=TKEEP<=0x0F and TLAST=1
COMMENT, Only 1234 is valid
DATA, 1234,  , 0x0F, 1
TLAST
  • The TLAST column indicates whether the end of the data stream is reached. If the TLAST value is not specified, the value is 0.
  • The TLAST value can be either 0 or 1. The default TLAST value is 0.
  • TLAST = 1 indicates the end of the data stream.​
Important: You must comma-separate column headers and their corresponding values in the CSV file, even if an empty value is specified. For example, below is the CSV file with empty TLAST and TKEEP.
CMD,D,D,TLAST,TKEEP
DATA,3,2, ,
Table 2. Data Type and PLIO Width
Data Type PLIO 32 bit PLIO 64 bit PLIO 128 bit
adf::input_plio in = adf::input_plio::create("DataIn1", adf::plio_32_bits, "input.csv"); adf::input_plio in = adf::input_plio::create("DataIn1", adf::plio_64_bits, "input.csv"); adf::input_plio in = adf::input_plio::create("DataIn1", adf::plio_128_bits, "input.csv");
int8 Four data columns expected. For example:
CMD, D,D,D,D,TKEEP,TLAST
DATA, 6,8,3,2,-1,0
 Eight data columns expected. For example:
CMD, D,D,D,D,D,D,D,D, TKEEP,TLAST
DATA, 6,8,3,2,6,8,3,2, -1,0
 16 data columns expected. For example:
CMD, D,D,D,D,D,D,D,D,D,D,D,D,D,D,D,D, TKEEP,TLAST
DATA, 6,8,3,2,6,8,3,2,6,8,3,2,6,8,3,2, -1,0
int16 Two data columns expected. For example:
CMD,D,D, TKEEP,TLAST
DATA, 24,18, -1,0
 Four data columns expected. For example:
CMD, D,D,D,D, TKEEP,TLAST
DATA, 24,18,24,18, -1,0
 Eight data columns expected. For example:
CMD,D,D,D,D,D,D,D,D,TKEEP,TLAST
DATA,24,18,24,18,24,18,24,18,-1,0
int32 One data column expected.
CMD, D, TKEEP, TLAST
DATA, 2386, -1, 0
 Two data columns expected. For example:
CMD, D, D, TKEEP, TLAST
DATA, 2386, 2386, -1, 0
 Four data columns expected. For example:
CMD,D,D,D,D,TKEEP,TLAST
DATA,2386,2386,2386,2386,-1,0
int64 N/A One data column expected.
CMD, D, TKEEP, TLAST
DATA, 45678, -1, 0
 Two data columns expected. For example:
CMD, D, D, TKEEP, TLAST
DATA, 45678, 95578, -1, 0
cint16 Two data columns expected to represent one cint value (real, imag). For example:
CMD, D,D,TKEEP, TLAST
DATA,1980,485,-1,0
 Two cint values (real, imag) represented by four data columns expected. For example:
CMD, D,D,D,D, TKEEP, TLAST
DATA, 1980, 45, 180, 85, -1, 0
 Four cint values (real, imag) represented by 8 data columns expected. For example:
CMD, D,D,D,D,D,D,D,D, TKEEP, TLAST
DATA, 1980,485,180,85,980,48,190,45,-1,0
cint32 N/A One cint value (real, imag) represented by two data columns expected. For example:
CMD, D, D, TKEEP, TLAST
DATA, 1980, 485, -1, 0
 Two cint values represented by four data columns expected. For example:
CMD, D, D, D, D, TKEEP, TLAST
DATA, 1980, 45, 180, 85, -1, 0
float One data column expected. For example:
CMD, D, TKEEP, TLAST
DATA, 893.5689, -1, 0
 Two data columns expected. For example:
CMD, D, D, TKEEP, TLAST
DATA, 893.5689, 3459.3452, -1, 0
 Four data columns expected. For example:
CMD, D, D, D, D, TKEEP, TLAST
DATA,893.5689,39.32,459.352,349.345,-1,0
cfloat N/A One floating point cfloat value represented using two data columns expected. For example:
CMD, D, D, TKEEP, TLAST
DATA, 893.5689,24156.456, -1, 0
 Two floating point cfloat values represented using four data columns expected. For example:
CMD, D, D, D, D, TKEEP, TLAST
DATA, 893.5689,24156.456,93.689,256.46, -1, 0
bfloat16 Two data columns expected. For example:
CMD,D,D,TKEEP,TLAST
DATA,3.14062,3.14062,-1,0
 Four data columns expected. For example:
CMD,D,D,D,D,TKEEP,TLAST
DATA,3.14062,3.14062,3.14062,3.14062,-1,0
 Eight data columns expected. For example:
CMD,D,D,D,D,D,D,D,D,TKEEP,TLAST
DATA,3.14062,3.14062,3.14062,3.14062,3.14062,3.14062,3.14062,3.14062,-1,0
fp16 1 
CMD,D,D,TKEEP,TLAST
DATA,1.2,2.2,-1,0
 
CMD,D,D,D,D,TKEEP,TLAST
DATA,1.2,2.2,3.2,4.2,-1,0
 
CMD,D,D,D,D,D,D,D,D,TKEEP,TLAST
DATA,1.2,2.2,3.2,4.2,5.2,6.2,7.2,8.2,-1,0
mx9 1 
CMD,D,D,D,D,TKEEP,TLAST
DATA,107,149,115,45,-1,0
 
CMD,D,D,D,D,D,D,D,D,TKEEP,TLAST
DATA,107,149,115,45,192,43,55,71,-1,0
 
CMD,D,D,D,D,D,D,D,D,D,D,D,D,D,D,D,D,TLAST,TKEEP
DATA,107,149,115,45,192,43,55,71,208,44,166,120,179,68,201,41,-1,0
  1. Supported only for AIE-ML v2 devices. For details on supplying mx9 data types as uint8 representation to the AI Engine simulator, see Encoding Block Floating-point Data for AI Engine Simulator.
Note: The input/output CSV format supports both decimal and hexadecimal representation of the data format for integer data types. To use hexadecimal format, set the bool hex parameter to true in the adf::input_plio::create() API. For details, see input_plio/output_plio in AI Engine Kernel and Graph Programming Guide (UG1079).
Note: The input CSV file supports both floating-point representation and exponential representation of the data format for floating-point data types.

CSV File Format and Error Checks During Simulation

The AI Engine simulation execution generates an ERROR message for a CSV with incorrect data. The following table lists some simulation error-checking conditions the simulator applies when a CSV file is used as input.

Tip: The first line in the CSV must not be a comment. It must have only headers.
Table 3. CSV File Error
Error Scenario CSV Input Error Message
The number of DATA columns are not equal to PLIO buswidth / datawidth For example, if buswidth = 64, and datawidth = 16, you need four D columns.

Two Few D Columns:

CMD, D, D, D, TKEEP, TLAST
DATA, 10, 100, 64, -1, 0
 [ ERROR ] : In <filename>, the number of data (D) columns is not equal to PLIO buswidth/sample datawidth. Expected <expected_number>
Two Many D Columns:
CMD, D, D, D, D, D, TKEEP, TLAST
DATA, 10, 50, 150, 100, 90, -1, 0
Partial data provided in the DATA columns of the CSV For example, if buswidth = 64, and datawidth = 16, you need four D columns. You must provide data samples in all four D columns. If partial data is provided, appropriate TKEEP with TLAST=1 needs to be set. The TKEEP values determine whether the lower 32 bit is valid or the full 64 bit is valid.

Missing One Data Sample:

CMD, D, D, D, D, TKEEP, TLAST
DATA, 10, 30, 60, , -1, 0

Missing Two Data Samples:

CMD, D, D, D, D, TKEEP, TLAST
DATA, , , 50, 64, -1, 0
 [ ERROR ] : In <filename>, in line <linenumber> , partial data is being fed to plio. To feed partial data, provide appropriate TKEEP value with TLAST = 1
Empty line in the CSV file Empty Line:
CMD, D, D, D, D, TKEEP, TLAST
This line is ignored by the tool.
Invalid value specified in the CMD or D column Invalid Command in the CMD Column:
CMD, D, D, D, D, TKEEP, TLAST
DATA:*(#$, 10, 20, 30, 40, -1, 0
 [ ERROR ] : Invalid command specified at <Filename:line number>

Invalid Data Sample in D Columns:

CMD, D, D, D, D, TKEEP, TLAST
DATA, D, 20, 30, 40, -1, 0
CMD, DATA, DATA, DATA, DATA, TKEEP
 [ ERROR ] : Invalid data value detected <filename:line number>.
DATA columns ordered incorrectly D Columns are Not Side-by-Side (Incorrect Order):
CMD, D, TKEEP, TLAST, D, D, D
DATA, 10, -1, 0, 20, 30, 40
 [ ERROR ] : Ensure all the data columns (D) are specified in sequence right after the CMD column in <Filename>
DATA value is out of range for a specific datatypes For example, if data type is int8, buswidth is 32, and data sample 2323 is out of range.

DATA Value 2323 is Out of Range:

CMD, D, D, D, D, TKEEP, TLAST
DATA, 34, 2323, 23, 21, -1, 0
 [ ERROR ] : Out of range data value detected in <filename>. Datatype is <datatype_provided_from_graph>. Range is <corresponding_range>
DATA value provided is invalid Invalid Data Sample in D Column:
CMD, D, D, D, D, TKEEP, TLAST
DATA, 1.23#$#, 10, 10, 10, -1, 0
 [ ERROR ] : In <filename>, invalid data value is provided at <line number>.

Output File

As with the input CSV file, you can specify to generate a CSV file for a PLIO output port. The simulator writes the simulation output corresponding to the appropriate PLIO port into the specified output CSV file.

adf::output_plio out1 = adf::output_plio::create("DataOut1",adf::plio_32_bits,"output1.csv");
adf::output_plio out2 = adf::output_plio::create("DataOut2",adf::plio_64_bits,"output2.csv");
adf::output_plio out3 = adf::output_plio::create("DataOut3",adf::plio_128_bits,"output3.csv");

The CSV file output includes both TLAST and TKEEP data. Each output line also includes the timestamp so that you can estimate the data throughput during the simulation. The timestamp is output in ns as the last column in the output CSV file.

...
CMD, D, D, TLAST, TKEEP, TIME_NS
DATA:1, 0, 1, 0, -1, 720
DATA:1, 2, 3, 0, -1, 918.4
DATA:1, 4, 5, 0, -1, 1116.8
DATA:1, 6, 7, 0, -1, 1315.2
DATA:1, 8, 9, 0, -1, 1513.6
DATA:1, 10, 11, 0, -1, 1712
DATA:1, 12, 13, 0, -1, 1910.4
DATA:1, 14, 15, 0, -1, 2108.8
DATA:1, 16, 17, 0, -1, 2307.2
DATA:1, 18, 19, 0, -1, 2505.6
DATA:1, 20, 21, 0, -1, 2704
DATA:1, 22, 23, 0, -1, 2902.4
DATA:1, 24, 25, 0, -1, 3100.8
DATA:1, 26, 27, 0, -1, 3299.2
DATA:1, 28, 29, 0, -1, 3497.6
DATA:1, 30, 31, 0, -1, 3696
DATA:1, 32, 33, 0, -1, 3894.4
DATA:1, 34, 35, 0, -1, 4092.8
DATA:1, 36, 37, 0, -1, 4291.2
DATA:1, 38, 39, 0, -1, 4489.6
DATA:1, 40, 41, 0, -1, 4688
DATA:1, 42, 43, 0, -1, 4886.4
DATA:1, 44, 45, 0, -1, 5084.8
DATA:1, 46, 47, 0, -1, 5283.2
DATA:1, 48, 49, 0, -1, 5481.6
DATA:1, 50, 51, 0, -1, 5680
DATA:1, 52, 53, 0, -1, 5878.4
DATA:1, 54, 55, 0, -1, 6076.8
DATA:1, 56, 57, 0, -1, 6275.2
DATA:1, 58, 59, 0, -1, 6473.6
DATA:1, 60, 61, 0, -1, 6672
DATA:1, 62, 63, 0, -1, 6870.4
DATA:1, 0, 1, 0, -1, 7068.8
DATA:1, 2, 3, 0, -1, 7267.2
DATA:1, 4, 5, 0, -1, 7465.6
DATA:1, 6, 7, 0, -1, 7664
DATA:1, 8, 9, 0, -1, 7862.4
DATA:1, 10, 11, 0, -1, 8060.8
DATA:1, 12, 13, 0, -1, 8259.2
DATA:1, 14, 15, 0, -1, 8457.6
...
Note: The output CSV file supports only exponential representation of the data format for floating point data types. For example, below is the output CSV file format of the float (32-bit) data type.
CMD, D, TLAST, TKEEP, TIME_NS
DATA:1, 2.002000093e+00, 0, 0, 3264
DATA:1, 4.004000187e+00, 0, 0, 3267.2
DATA:1, 6.006000042e+00, 0, 0, 3270.4
DATA:1, 8.008000374e+00, 0, 0, 3273.6
DATA:1, 1.001000023e+01, 0, 0, 3276.8
DATA:1, 1.201200008e+01, 0, 0, 3280
DATA:1, 1.401399994e+01, 0, 0, 3283.2
DATA:1, 1.601600075e+01, 0, 0, 3286.4
DATA:1, 1.801799965e+01, 0, 0, 3328
DATA:1, 2.002000046e+01, 0, 0, 3331.2
DATA:1, 2.202199936e+01, 0, 0, 3334.4
DATA:1, 2.402400017e+01, 0, 0, 3337.6
DATA:1, 2.602599907e+01, 0, 0, 3340.8
DATA:1, 2.802799988e+01, 0, 0, 3344
DATA:1, 3.003000069e+01, 0, 0, 3347.2
DATA:1, 3.203200150e+01, 0, 0, 3350.4
DATA:1, 3.403400040e+01, 0, 0, 3395.2

Viewing the Stalls in Analysis View of the Vitis Unified IDE

You can use the STALL command in the CSV file, after you run the AI Engine and opt to generate simulation trace data. You can open the simulation run summary and view the stalls in the Vitis unified IDE. The STALL:<n> inserts stalls for n empty cycles from the PL domain. You can see the stall duration based on the PL frequency. For example,STALL:100 inserts 100 empty cycles from the PL for the duration of 1000 ns when the PL frequency is 100 MHz.

Example 1: Design with direct stream connections (no buffer) results in a stream stall for the 500 empty cycles (from the PL domain) specified.

Figure 1. CSV Entry with Stall for 500 Empty Cycles

Figure 2. Stream Stall for 500 Empty Cycles in Analysis View of the Vitis Unified IDE

Example 2: Design with buffer-connected streams results in a lock stall for the 1000 empty cycles (from the PL domain) specified.

Figure 3. CSV Entry with Stall for 1000 Empty Cycles
Figure 4. Lock Stall for 1000 Empty Cycles in Analysis View of the Vitis Unified IDE