Running Software Emulation - 2022.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)
Document ID
UG1076
Release Date
2022-05-25
Version
2022.1 English

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

  1. X86 simulator
  2. Software emulation of the system
  3. AI Engine simulator
  4. Hardware emulation of the system
  5. Test and debug 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. 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).

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.