emconfigutil (Emulation Configuration) Utility

In the command line flow, it is necessary to create an emulation configuration file and to set certain environment variables prior to running either SW or HW emulation. The emulation configuration file provides the device type and quantity to emulate, and is used by the runtime library during emulation. The emconfigutil utility automates the creation of the emulation file. Use the following steps to setup the emulation configuration file and set the environment variables:

  1. Create the emulation configuration file.
    Note: When running on real HW, the runtime and drivers query the installed HW to determine the device type and quantity are installed, along with the device characteristics..

    The emconfigutil options are given below. The --platform option is required. The syntax of the command is:

    emconfigutil --platform <platform_name> [options]
    Table 1. emconfigutil Options
    Option Valid Values Description
    --platform Target device Required. Sets target device.

    For a list of supported devices, refer to SDx Environments Release Notes, Installation, and Licensing Guide.
    --nd Any positive integer Optional. Specifies number of devices. Default is 1.
    --od Valid directory Optional. Specifies output directory. When emulating the design, the emconfig.json file must be in the same directory as the host executable.
    --save-temps N/A Optional. Specifies that intermediate files are not deleted and remain after command is executed.
    --xp Valid Xilinx parameters and properties Optional. Specifies additional parameters and properties. For example:--xp prop:solution.platform_repo_paths=my_dsa_path

    Sets the search path for the device specified in --platform option.
    -h N/A Prints help messages.

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

    When running emulation, 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 --platform xilinx_vcu1525_dynamic_5_0
 --nd 2
  2. Set the XILINX_SDX environment variable.

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

    C Shell: 

    setenv XILINX_SDX /opt/Xilinx/SDx/2018.3

    Bash: 

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

    Setting XCL_EMULATION_MODE environment variable to sw_emu (software emulation) or hw_emu (hardware emulation) changes the application execution to emulation mode. In emulation mode, 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

    Not setting the XCL_EMULATION_MODE environment variable turns off the emulation mode.

  4. Run the emulation.

    With the configuration file emconfig.json and XCL_EMULATION_MODE, use the following command line to perform emulation:

    $./host.exe kernel.xclbin