Embedded Processor Emulation Using PS on x86 - 2023.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.

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_202310_1/xilinx_vck190_base_202310_1.xpfm --nd 1

followed by,

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 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.

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

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

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

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

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

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.