TXT File Format - 2023.2 English

Input File

The default bit width for input/output streams is 32 bits. The bit width specifies the number of samples per line on the simulation input file. The interpretation of the samples on each line of the input file is dependent on the data type expected and the PLIO data width. The following table shows how the samples in the input data file are interpreted, depending on the data type and its corresponding PLIO interface specification.

PLIO and Packet Stream Interface Requirements

When the TXT file is used to provide data that represents a PLIO port and packet stream interface, the following TXT file requirements should be followed.

1. tkeep is always valid. The tkeep signal set to False is not supported.
2. Multiple numbers of data samples in a line can be combined and sent, depending on the width of the interface. The first data sample is sent in the lowest bits of the interface. For example, if the data type is int16 and the AI Engine to PL interface is 64 bits wide, the line 0 1 2 3 is sent as 0x0003000200010000 to the AI Engine.

   0 1 2 3

3. tlast in the TXT file denotes that the following line has tlast equals 1. When tlast is 1, the number of data samples sent to the AI Engine can be equal to or less than the AI Engine to PL interface width. For example, if the data type is int16 and the AI Engine to PL interface is 64 bits wide, the last line 4 5 is sent as 0x00050004 with tlast to the AI Engine:

   0 1 2 3
   tlast
   4 5

4. For the packet stream interface, tlast equals 1 denotes the end of the packet. The packet header should be specified in unsigned decimal format. For example, if the AI Engine to PL interface is 64 bits wide, the following lines send the packet header 0x8fff0000 (which is 2415853568 in unsigned decimal):

   tlast
   2415853568

   For the packet stream interface, whose data type is int16 and the AI Engine to PL interface is 64 bits wide, the following lines send the packet header 0x8fff0000, packet data 0x0, and then packet data 0xfffeffff to the AI Engine:

   2415853568 0
   tlast
   -1 -2

Output File

On each output PLIO port a file containing the stream content can be created automatically by the simulator using the same type of declaration as the input PLIO data files.

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

If the stream comes from a source that generates a TLAST flag at the end of a frame, this TLAST is also written in the output file. Below is an example of such an output file.

...
T 15984 ns
4552 4555 
T 15988 ns
4558 4561 
T 15992 ns
4564 4567 
T 15996 ns
4570 4573 
T 16 us
4576 4579 
T 16004 ns
4582 4585 
T 16008 ns
4588 4591 
T 16012 ns
4594 4597 
T 16016 ns
4600 4603 
T 16020 ns
4606 4609 
T 16024 ns
TLAST
4612 4615 
T 17940 ns
4618 4621 
T 17944 ns
4624 4627 
T 17948 ns
4630 4633 
T 17952 ns
...

From the output you can estimate the throughput of the designs for this PLIO port. Timestamps are related only to valid output. When the PLIO port is quiet, there is no indication on the output file.

Compute the throughput as the number of output samples divided by the timestamp difference:

This simple equation will overestimate the throughput if you do not take into account all the clock cycles occurring after the last output sample.

In that case you have to take into account the interframe timelapse for each frame output. This can be done if you use only the N first frames (from 0 to N-1). In that case, replace the time stamps of the throughput equation with:

• FirstTimestamp = tstart_0
• LastTimestamp = tstart_N (the first output timestamp of the last frame)

Below is an example python script that calculates the PLIO throughput It analyzes the simulation output file and calculates the throughput.

import numpy as np
from math import *
import sys
import argparse

def GetTime_ns(Stamp):
  Time_ns = float(Stamp[1])
  if(Stamp[2] == 'ps'):
    Time_ns = Time_ns/1000.0
  elif(Stamp[2] == 'us'):
    Time_ns = Time_ns*1000.0
  elif(Stamp[2] == 'ms'):
    Time_ns = Time_ns*1000000.0
  elif(Stamp[2] == 's'):
    Time_ns = Time_ns*1000000000.0
  return(Time_ns)


def ReadFile(filename):
  # Detect the number of data per PLIO output
  fdr = open(filename,'r')
  ts = fdr.readline()
  d = fdr.readline()
  dw = d.split()
  fdr.close()


  coltime = 0
  coldata = 1
  numdata = len(dw)
  coltlast = numdata + 1


  # Initializes the output array
  # Format: timestamp (in ns) val1 val2 ... valN TLAST (0 or 1)
  a = np.zeros((0,numdata+2))
  fdr = open(filename,'r')
  line = ' '
  lnum = 0;

  while line !="" :
    line = fdr.readline()
    if line=='':
      continue
    res = line.split()

    if(res[0] != 'T'): # It should be a timestamp
      continue

    l = np.zeros((1,numdata+2))
    # Extract the time stamp
    l[0][0] = GetTime_ns(res)


    line = fdr.readline()
    res = line.split()
    # extract the TLAST
    if(res[0]=='TLAST'):
      tlast = 1
      line = fdr.readline()
      res = line.split()
    else:
      tlast = 0

    l[0,coltlast] = tlast
    # Extract all values
    for i in range(numdata):
      l[0,i+1] = float(res[i])

      # Appends to the whole array
      a = np.append( a , l,axis=0)

  fdr.close()
  return(a)

def Throughput(Filename,IsComplex):
  V = ReadFile(Filename)
  print("\n==============================")
  print(Filename)
  print("\n")

  NRows = V.shape[0]
  NCols = V.shape[1]
  NFullFrames = int(np.sum(V[:,NCols-1]))
  print("Number of Full Frames: " + str(NFullFrames))


  # Basic Throughput computation
  if IsComplex:
    Ratio = 0.5
  else:
    Ratio = 1
  RawThroughputMsps = float(NRows*(NCols-2))/(V[NRows-1,0]-V[0,0])*Ratio*1000.0
  print("Raw Throughput: %.2f" % RawThroughputMsps)

  # If the output is frame based, compute a more precise throughput
  tlast = np.where(V[:,NCols-1] == 1.0)
  if(len(tlast[0])<=1):
    TotalThroughput = RawThroughput
  else:
    tlast = tlast[0]
    EndRow = tlast[len(tlast)-2]+1
    # EndRow is the number of Rows I take into account for the number of datasource
    # The timestamp I am interested in is the timestamp of the next transaction
    TotalThroughputMsps = float(EndRow*(NCols-2))/(V[EndRow,0]-V[0,0])*Ratio*1000.0
    print(" Throughput: %.2f" % TotalThroughputMsps)

  print("\n")

# Entry point of this file
if __name__ == "__main__":
  parser = argparse.ArgumentParser(prog=sys.argv[0], description='Compute the throughput corresponding to some output of AIE Simulations')
  parser.add_argument('--iscomplex', action='store_true', help='Indicates Complex data in the file')
  parser.add_argument('filename',nargs='+')
  Args = sys.argv
  Args.pop(0)
  args = parser.parse_args(Args)

for f in args.filename:
  Throughput(f,args.iscomplex)