Running Emulation on an Embedded Processor Platform Using PS on x86 - 2022.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2022-12-07
Version
2022.2 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.
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 is only needed for Versal platforms to convert the .xsa produced by the v++ --link command into an .xclbin file. This step is not required for Zynq 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 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=$(EDGE_COMMON_SW)/sysroots/cortexa72-cortexa53-xilinx-linux​​-I$(EDGE_COMMON_SW)/sysroots/cortexa72-cortexa53-xilinx-linux/usr/include/xrt -L$(EDGE_COMMON_SW)/sysroots/cortexa72-cortexa53-xilinx-linux/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:

v++ -p -t sw_emu $(LINK_XCLBIN) $(LIBADF) --platform $(PLATFORM_PATH) --package.out_dir ./package.hw_emu --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 only needed to generate the .xclbin file:

v++ -p $(LINK_OUTPUT) $(VPP_FLAGS)​ --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 of course 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 Versal ACAP AI Engine Programming Environment User Guide (UG1076) for additional information.