Simulator Options - 2023.1 English

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2023-06-23
Version
2023.1 English

The complete set of the AI Engine simulator (aiesimulator) options are described in this section. In most cases, just pointing to pkg-dir is sufficient.

Table 1. AI Engine Simulator Options
Options Description
-h, --help Shows the help message and exits.
--display-run-interval=<time in ns> Displays time stamp periodically after each time (in ns) elapse, provided by this option, on the console. For example, aiesimulator --display-run-interval=10 --pkg-dir=./Work --i=..  on a design will display the time stamp every 10ns as follows on the console where aiesimulator is executed, as seen in Figure 1 .
--dump-vcd=<file> Dump VCD waveform information into <file>. Because the tool appends .vcd to the specified file name, it is not necessary to include the file suffix.
Note: This option allows you to access all signals. This may slow down the simulation speed. If you only want a subset of the signals you should use an option file.
Note: To generate the XPE file from the aiesimulator generated vcd file, use the vcdanalyze tool as follows:
vcdanalyze --vcd <vcdfile> --xpe [OPTIONS]
The available options are:
  • -s=<STARTTIME>: Specifies the start time (Optional).
  • -e=<ENDTIME>: Specifies the end time (Optional).
  • --out=<RPT>: Generates the workload estimation report in ".rpt" format.
  • -v: Generates verbose output (Optional).
  • --xpe: Generates the power estimate report.
  • --xpe-dir=<XPEOutputDir>: Specifies the directory for generating XPE reports. The default is ./aiesim_xpe.
For information on using the XPE file, see Power Design Manager User Guide (UG1556).
Note: The --online option and --dump-vcd option cannot be used together. If both options are specified, only --online option takes effect.
--options-file=<file> Text file used to select and generate specific VCD data. For example, aiesimulator --options-file=<options>.txt --dump-vcd. The <options.txt> file will specify modules whose data needs to be generated as VCD data.

This switch should be used along with --dump-vcd switch for generating VCD.
--enable-handshake-ext-tb Enable sample by sample transaction between aiesimulator and an external testbench. When this option is set, aiesimulator will issue a TLAST for every transaction between aiesimulator and external testbench.
--enable-memory-check Enable runtime program and data memory boundary access check. Any violation access will be reported as [ERROR] message. This option is disabled by default. When you run a simulation with this option enabled, and open the run summary in Vitis Analyzer, the graph view displays a Memory Violations tab. This tab reports all the memory violations detected in the simulation run. You can click on a specific violation and navigate to the line in the source code causing the violation.
--hang-detect-time=<time in ns> The aiesimulator will exit if all active cores in stalled state after the time period (in ns), provided by this option. For example, if the option--hang-detect-time=10 is provided to the aiesimulator, if after 10 ns all the active cores are in stalled state, the aiesimulator will exit.
-i Alias of --input-dir=<dir> option.
-o Alias of --output-dir=<dir> option.
--pkg-dir=<dir> Specify the package directory, for example, ./Work.
--profile Generates profiling data for all used cores. Allows generation of printf trace messages on the stdout and collects profiling statistics during simulation. This can slightly slow down the simulator.
Optionally, can specify the profile of specific cores by using "--profile=(col,row)(col,row)..." flag.
Note: This option is not yet available in hw_emu for AI Engine ML
--simulation-cycle-timeout=<cycles> Run the application for a given number of cycles after it is loaded.
Tip: Specify the --simulation-cycle-timeout option to end the simulation session after the specified number of cycles. However, when specifying simulation timeout during the debug process, be sure to specify a larger number of cycles because the debug will terminate when the timeout cycle is reached.
--online -ctf|-wdb

Use this option with -ctf or -wdb to parse VCD data on-the-fly, to produce a common trace format (CTF), or waveform database (WDB) output file.

For example, aiesimulator --pkg-dir=./Work --i=.. --online -wdb will produce a WDB file that can be opened in Vitis Analyzer.

Tip: The --online and --dump-vcd options cannot be used together. If both options are specified, AI Engine Simulator gives an error.
--output-time-stamp Use --output-time-stamp=no to get output file without time values and --output-time-stamp to get uniform time value (in ns) in output file.
Figure 1. AI Engine Simulator Display Run Internal Example

Hang Detection

AI Engine users can run into simulator hangs. A common cause is insufficient input data for the requested number of graph iterations, mismatch between production and consumption of stream data, cyclic dependency with stream, cascade stream or asynchronous windows, or wrong order of blocking protocol calls (acquisition of async window, read/write from streams).

Using aiesimulator option --hang-detect-time=<time_in_ns> will allow the tool to check for a hang situation on the kernels and trigger an exit of the simulation after a specified delay. It can detect lock stalls and stream stalls whether it is circuit switched or packet switched communication. Below are some examples of hang detection output:
Figure 2. Stream Stall Detection
Figure 3. Lock Stall Detection