Embedded Processor Emulation Using PS on x86 - 2024.1 English

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

Document ID
UG1393
Release Date
2024-05-30
Version
2024.1 English

Running emulation under the QEMU environment for embedded processors is compute-intensive and requires additional setup and configuration. You must cross-compile the embedded application using arm-gcc, create an SD card image, and boot Linux under the QEMU environment before running the application. The PS on x86 feature lets you simulate your embedded system design on an x86 processor with much less effort. This feature requires you to compile the PS application using an x86 version of gcc or g++ compiler, and to build your .xclbin file to run on an emulation platform for software emulation created by emconfigutil.

Important: PS on x86 compilation is only valid for software emulation and requires GCC 8.3 or later. This feature also requires the x86 installation of XRT as described in Installing Xilinx Runtime and Platforms. In addition, for AI Engine designs, you must enable the --package.defer_aie_run option as shown in the config file examples below.

The process for building and running software emulation using PS on x86 is as follows:

  1. Compile the PS application using the standard gcc compiler rather than the Arm cross-compiler. This is described in Compiling and Linking for x86.
  2. Compile and link the device binary (.xclbin) using standard v++ commands as described in Building the Device Binary.
  3. For the PS on x86 flow the v++ --package command tells the tool what processor to use for emulation (--package.emu_ps).

    For AMD Versal™ platforms it is also needed to convert the .xsa produced by the v++ --link command into an .xclbin file. This step is not required for AMD Zynq™ UltraScale+™ MPSoC based platforms.

  4. Use the emconfigutil Utility to create an emconfig.json file for software emulation.
    emconfigutil --platform xilinx_zcu102_base_202220_1
  5. Set the XCL_EMULATION_MODE environment variable to sw_emu for software emulation mode.
    Important: The emulation targets will not run if the XCL_EMULATION_MODE environment variable is not properly set.
  6. Run the application. For example:
    ./host.exe kernel.xclbin

The following are example emconfigutil and v++ --package commands. Use the emconfigutil to create the virtual platform needed for emulation, and the v++ --package comand to create the system for emulation.

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

followed by,

v++ -p -t sw_emu \
    --package.defer_aie_run \
    --platform $PLATFORM_REPO_PATHS/xilinx_vck190_base_202410_1/xilinx_vck190_base_202410_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 commands:

setenv XCL_EMULATION_MODE sw_emu
./host_ps_on_x86 a.xclbin

The following table describes the differences in building the PS application and device binary (.xclbin) for running software emulation under QEMU and for running PS on x86.

Table 1. Running SW Emulation for PS on X86
Process Running SW_EMU under QEMU SW_EMU with PS on X86
Host compilation

Requires cross-compilation using arm-gcc and requires SYSROOT definition, and embedded include and library files:

aarch64-linux-gnu-g++ -o hello_world \
host.cpp -lxrt_coreutil -pthread \
--sysroot=<path-to-sysroot>​​ \
-I<path-to-sysroot>/usr/include/xrt \
-L<path-to-sysroot>/usr/lib

Requires x86 gcc and requires x86 installation of XRT:

g++ -o hello_world host.cpp \
-lxrt_coreutil -pthread \
-I$(XILINX_XRT)/include \
-L$(XILINX_XRT)/lib​​
Package

Requires SD card image creation to run under QEMU, specifies the emulation processor to be QEMU:

v++ -p -t sw_emu $(LINK_XCLBIN) $(LIBADF) \
--platform $(PLATFORM_PATH) \
--package.out_dir ./package.sw_emu \
--package.emu_ps qemu \
--package.rootfs $(EDGE_COMMON_SW)/rootfs.ext4 \
--package.kernel_image $(EDGE_COMMON_SW)/Image \
--package.sd_file xrt.ini \
--package.sd_file ./run_app.sh \
-o vadd.xclbin --package.sd_file ./hello_world

For PS on x86 simulation the --package command is needed to identify the PS for emulation, and to generate the .xclbin file:

v++ -p $(LINK_OUTPUT) $(VPP_FLAGS)​ \
--package.emu_ps x86 \
--package.defer_aie_run \
--package.out_dir $(PACKAGE_OUT) \
-o $(BUILD_DIR)/kernel.xclbin​
Running Simulation​​

Requires use of launch_emulation shell script to setup QEMU and run the simulation:

./launch_sw_emu.sh -run-app \
 $(RUN_APP_SCRIPT) | tee run_app.log;​​

Set emulation mode environment variable and launch application directly:

XCL_EMULATION_MODE=sw_emu 
./$(EXECUTABLE) $(CMD_ARGS)

You can compile the same PS code using arm-gcc in x86 gcc. However, any ARM-only data types or libraries that are linked in your PS code will not work when compiled for x86. Refer to ps_on_x86 on GitHub for an example of running software emulation using this feature.

Tip: In order to compile and run AI Engine applications for PS on x86, refer to AI Engine Tools and Flows User Guide (UG1076) for additional information.