Running Software and Hardware Emulation in XOCC Flow

In the XOCC/Makefile flow, users manage compilation and execution of host code and kernels outside the Vivado® Xilinx SDAccel™ development environment. Follow the steps below to run software and hardware emulation:

  1. Create the emulation configuration file.

    For software or hardware emulation, the runtime library needs to know what devices and how many to emulate. This information is provided to the runtime library by an emulation configuration file. SDAccel provides a utility, emconfigutil to automate creation of the emulation configuration file. The following are details of the emconfigutil command line format and options:

    Option Valid Values Description
    --xdevice

                             

    		 Target device Required: Set target device. See the SDx Environments Release Notes, Installation, and Licensing Guide for all supported devices. This command is deprecated in Release 2017.4, and replaced with the --platformcommand.
    --nd Any positive integer Optional: Number of devices. Default is 1.
    --od Valid directory Optional: Output directory, emconfig.json file must be in the same directory as the host executable.
    --xp Valid Xilinx parameters and properties

    Optional: Specify additional parameters and properties. For example:

    --xp prop:solution.device_repo_paths=my_dsa_path

    Sets the search path for the device specified in --xdevice option.
    -h NA Print help messages

    The emconfigutil command creates the configuration file emconfig.json in the output directory.

    The emconfig.json file must be in the same directory as the host executable. The following example creates a configuration file targeting two xilinx_vcu1525_dynamic_5_0 devices.

    $emconfigutil --xdevice xilinx_vcu1525_dynamic_5_0
 --nd 2
  2. Set XILINX_SDX environment variable

    The XILINX_SDX environment needs to be set and pointed to the SDAccel installation path for the emulation to work. Below are examples assuming SDAccel is installed in /opt/Xilinx/SDx/2017.4

    C Shell: 

    setenv XILINX_SDX /opt/Xilinx/SDx/2017.4

    Bash: 

    export XILINX_SDX=/opt/Xilinx/SDx/2017.4
  3. Set emulation mode

    Setting XCL_EMULATION_MODE environment variable to sw_emu or hw_emu changes the application execution to emulation mode, sw_emu for software emulation or hw_emu for hardware emulation, so that the runtime looks for the file emconfig.json in the same directory as the host executable and reads in the target configuration for the emulation runs.

    C Shell:

    setenv XCL_EMULATION_MODE sw_emu

    Bash:

    export  XCL_EMULATION_MODE=sw_emu

    Unsetting the XCL_EMULATION_MODE environment variable will turn off the emulation mode.

  4. Run Software or Hardware emulation

    With the configuration file emconfig.json and XCL_EMULATION_MODE set to sw_emu, execute the host application with proper arguments to run Software emulation. Alternatively, use setting hw_emu to run hardware emulation. 

    $./host.exe kernel.xclbin