CSV File Format - 2023.2 English

The AI Engine simulator supports the CSV file format for PLIO-based simulation. This new format provides more control over transactions and allows for cycle-by-cycle injection of traffic to AI Engine. This 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 can be defined as 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 should be equal to 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

The STALL command must be used to specify the number of empty cycles to be injected in the data traffic. This command will mimic 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

To convert existing TXT file format to the CSV format, use the python script aiesim_convert_plio_txt2csv.py, as in:

$XILINX_VITIS/data/emulation/scripts/aiesim_convert_plio_txt2csv.py -txt <input txt file> --datawidth <n> --buswidth <n>

--datawidth <n> option to specify the AI Engine kernel data-width in bits. This option is mandatory.
--buswidth <n> option to specify the PLIO bus-width in bits. This option is mandatory.
--complex is optional argument, specified if AI Engine kernel data type is complex

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 should be 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`, there will be no data 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 is used to indicate 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.

Note: In the CSV file, the column headers and their corresponding values must be comma separated even though 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
Data Type	`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`

Note: For integer data types, both decimal and hexadecimal representation of the data format are supported in the input/output CSV format. To use the hexadecimal format, set 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: For floating point data types, both floating point representation and exponential representation of the data format is supported in the input CSV file.

CSV File Format and Error Checks During Simulation

For a CSV with incorrect data, an ERROR message is generated during AI Engine simulation execution. Below are some of the error checking conditions during simulation when a CSV file is provided as input.

Tip: The first line in the CSV should 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>, number of D columns is less than expected. Expected <expected_number>
	Two Many D Columns: `CMD, D, D, D, D, D, TKEEP, TLAST DATA, 10, 50, 150, 100, 90, -1, 0`	[ ERROR ] : In <filename>, number of D columns is more than expected. Expected <expected_number>
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 will 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` 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 ] : In <filename>, invalid command at <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 ] : In <filename>, in the header row, DATA columns should be packed together.
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 ] : In <filename>, out of range value is present. 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

Similar to the input CSV file, you can specify a CSV file be generated for a PLIO output port as well. The simulator write 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: For floating point data types, only exponential representation of the data format is supported in the output CSV file. 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

Using 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 where streams are connected via buffer 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