Running Software Emulation - 2023.1 English

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

In the typical AI Engine development flow, the steps will be as follows.

  1. Running the x86 simulator for verifying the functional correctness of the AI Engine kernels and graph
  2. Software emulation of the system for verifying the functional correctness of the complete system
  3. AI Engine simulator for verifying that the AI Engine kernel and graph meets performance needs of the application
  4. Hardware emulation of the entire system
  5. Testing and debugging on hardware

Generally, software emulation is the first step to building and testing the system in a functional process through the custom host code you create rather than the simulator test host code.

Software emulation for a system with the AI Engine can be useful in:

  • Checking initial system behavior with a limited known data set
  • Functional integration and debugging of PS, PL, and ADF graph using GDB
  • Testing the system with external traffic generator using Python, or C++
  • Running system with C-based models for RTL kernels
  • Applying AI Engine simulation options through the x86.options file in Work/options
Important: Software emulation requires all PL kernels to be HLS based, or contain C/C++ models.
Note: When writing host code to execute in software emulation, make sure all buffer objects (xrtBO) are synced with xrtBOSync API call.

To run free running PL kernels more than once, you can run it inside a while (1) loop.

To build the project for software emulation confirm that the target option of the aiecompiler is -target=x86sim. The v++ link and v++ package command-s are set to -target=sw_emu.

Running Software Emulation with x86 Model for the PS Arm Processor

This v++ -p command packages the design. In addition to package, the emconfigutil command should be used to generate the device, board and device tree details (emconfig.json).

emconfigutil --platform $PLATFORM_REPO_PATHS/xilinx_vck190_base_202310_1/xilinx_vck190_base_202310_1.xpfm --nd 1

followed by,

cd ./sw
v++ -p -t sw_emu \
    --package.defer_aie_run \
    --platform $PLATFORM_REPO_PATHS/xilinx_vck190_base_202310_1/xilinx_vck190_base_202310_1.xpfm \
    --package.sd_dir $PLATFORM_REPO_PATHS/sw/versal/xrt \
    --package.out_dir ./package.sw_emu \
    --package.ps_on_x86 \
    --package.sd_file ./emconfig.json \
    ../tutorial.xsa ../libadf.a

To run the software emulation use the following command

setenv XCL_EMULATION_MODE sw_emu
./host_ps_on_x86 a.xclbin

Running Software Emulation with QEMU Model for the PS ARM Processor

The v++ package command generates the launch_sw_emu.sh script as part of the process for packaging the system. This script launches the QEMU emulation environment for the AI Engine application for test and debug purposes. Software emulation runs separate x86 processes for the PL kernels and AI Engine kernels, and runs QEMU for the PS host application.

Use the following command to run software emulation:

./launch_sw_emu.sh
Important: For HLS free running kernels, the HLS kernel code needs to be changed to run indefinitely in software emulation. Refer to Free Running Kernels in Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).
To launch QEMU, packaging is required with sd_card.img.
Note: To avoid overhead of booting Petalinux on full QEMU and launching QEMU, you can compile the same embedded application using x86 GCC (instead of ARM-GCC). For more details, see Compiling the Embedded Application for the x86 Processor.

When launching software emulation, you can specify options for the x86simulator simulator that runs the graph application. The options can be specified from the launch_sw_emu.sh script using the -x86-sim-options as described in Reusing x86 Simulator Options.

When the emulation is fully booted and the Linux prompt is up, make sure to set the following environment variables in the QEMU environment.

export XILINX_XRT=/usr
export LD_LIBRARY_PATH=/mnt/sd*1:/tmp:$LD_LIBRARY_PATH
export XCL_EMULATION_MODE=sw_emu

This ensures that the host application works. Now the application can be executed on the Linux prompt.