x86 Functional Simulator - 2023.2 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID
Release Date
2023.2 English

When starting development on AI Engine graphs and kernels, it is critical to verify the design behavior. This is called functional simulation and it is useful in identifying errors in the design. For example, window sizes in the graph are related to the number of iterations in a kernel. Troubleshooting to see if every kernel in a large graph is absorbing and generating the right number of samples can be time consuming and iterative in nature. The x86 simulator is an ideal choice for testing, debugging, and verifying this kind of behavior because of the speed of iteration and the high level of data visibility it provides the developer. The x86 simulation does not provide timing, resource, or performance information. The x86 simulator is running exclusively on the tool development machine. This means its performance and memory use are defined by the development machine.

While the AI Engine simulator fully models the memory of the graphs and kernels, for AI Engine array, this also means that AI Engine simulator is limited by the memory space of the AI Engine. The x86 simulator is not limited by this and provides a nearly unlimited amount of debug printf()s, large arrays, and variables. When combined with the ability to single step through the kernel, very complex design issues can quickly be isolated and addressed.

Several macros are provided to improve the kernel debug. These macros are intended for use with the x86 simulator and can be left in the code for maintainability purposes. With the benefits of the x86 simulator come some trade offs. There are several types of graph constructs that are not supported and cycle accurate behavior cannot be guaranteed to match between the AI Engine simulator and the x86 simulator. The x86 simulator is not a replacement for the AI Engine simulator. The AI Engine simulator must still be run on all designs to verify behavior and obtain performance information. For different stages of project development one tool or the other might better suit your needs.

Note: To learn more about x86 simulation limitations, refer to Limitations.

To run the x86 simulator, change the AI Engine compiler target to x86sim.

aiecompiler --target=x86sim graph.cpp

After the application is compiled for x86 simulation, the x86 simulator can be invoked as follows.


The following is the complete x86 simulator command help.

x86simulator [-h] [--help] [--h] [--pkg-dir=PKGDIR]
optional arguments:
-h,--help --h               Show this help message and exit
--pkg-dir=PKG_DIR           Set the package directory. ex: Work
--i, -i ,--input-dir=PATH   Set the input directory
--o, -o ,--output-dir=PATH  Set the output directory
--timeout=secs 		   Terminate simuation after specified number of seconds
--dump 			      Enable snapshots of data traffic on kernel ports
--dump-size    		   Set the maximum size of the snapshot file in MB
--gdb          		   Invoke from gdb
--valgrind     		   Run simulator under valgrind to detect access violations
--valgrind-gdb 		   Run simulator under valgrind and debug via gdb server
--valgrind-args=ARGS        Override default options for valgrind. Used in conjunction with --valgrind.
--disable-stop-on-deadlock  Disable deadlock detection
--trace                     Enable trace of kernel stall events
--trace-print               Print kernel stall events during simulation

The compiled binary for x86 native simulation is produced by the AI Engine compiler under the Work directory (see Compiling an AI Engine Graph Application) and is started automatically by the x86 simulator.

The input and the output files are specified in the following snippet of graph code.

adf::input_plio in1=adf::input_plio::create("In", adf::plio_32_bits, "In1.txt");
adf::output_plio out1=adf::output_plio::create("Out", adf::plio_32_bits, "Out1.txt");

When running, the x86 simulator looks in the current working directory for data/In1.txt which is one of the inputs used by the ADF graph. To distinguish the output files for the x86 simulator from the output files for the AI Engine graphs and kernels, it is critical to verify the design simulator the Out1.txt are located in current_working_dir/x86simulator_output/data/.

If a comma separated value (CSV) input file is used, the input filename is replaced with In1.csv.

Optionally, the output files produced by the simulator can be compared with a golden output ignoring white space differences.

diff –w <data>/golden.txt <data>/output.txt
Simulator Logs and Output can be visualized in the Vitis IDE:
Figure 1. Log View
Figure 2. Simulator Output View
The Simulator Output View allows you to select which output should be displayed.