Running Emulation Targets - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2023.2 English

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

  1. Software emulation of the system for verifying the functional correctness of the complete system
    Note: This can also include running C simulation on HLS components, or running the x86simulator for verifying AI Engine components
  2. AI Engine simulator for verifying that the AI Engine kernel and graph meets performance needs of the application
  3. Hardware emulation of the system for verifying timing of the design
    Note: This can also include running C/RTL co-simulation on HLS components, or running the aiesimulator for verifying AI Engine components
  4. Testing and debugging on hardware

While running on hardware runs the system design on the physical device of the platform or accelerator card. However, running emulation targets occurs on a virtual system on the x86 processor, or in the QEMU environment on embedded processors. Software and hardware emulation targets have their own target specific drivers which are loaded at runtime by XRT. Thus, the same CPU binary can be run as-is without recompiling, by changing the target mode during runtime.

Based on the value of the XCL_EMULATION_MODE environment variable, XRT loads the target specific driver and makes the application interface with an emulation model of the hardware. The allowed values of XCL_EMULATION_MODE are sw_emu and hw_emu. If XCL_EMULATION_MODE is not set, then XRT will load the hardware driver.

Important: It is required to set XCL_EMULATION_MODE when running emulation.
Figure 1. XRT Drivers

You can also use the xrt.ini file to configure various options applicable to emulation. There is an [Emulation] specific section in xrt.ini, as described in xrt.ini File.

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 or the aiesim_options.txt found in the aiesimulator_output directory
Important: Software emulation requires all PL kernels to be HLS based, or contain C/C++ models. RTL kernels do not generally support software emulation.

When writing host code to execute in software emulation, sync all buffer objects (xrtBO) with xrtBOSync API call. To run data-driven PL kernels more than once, you can run it inside a while (1) loop in the software application.

When launching software or hardware emulation, you can specify options for the AI Engine component according to the simulator being used. These options can be specified from the script using the -x86-sim-options, or from the script using the -aie-sim-options. For more information refer to Reusing AI Engine Simulator Options in AI Engine Tools and Flows User Guide (UG1076).

When the emulation environment is fully booted and the Linux prompt is up, make sure to set the following environment variables in the QEMU environment to ensure that the host application works. These must also be set when running on hardware.

export XILINX_XRT=/usr
export LD_LIBRARY_PATH=/mnt/sd*1:
export XCL_EMULATION_MODE=hw_emu