emconfigutil (Emulation Configuration) Utility

In the XOCC/Makefile flow, manage the compilation and execution of host code and kernels outside the 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.

    Note: When running on real HW, the runtime and drivers query the installed HW to determine the type of device, how many of that devices are installed and the characteristics of that device.

    The following are details of the emconfigutil command line format and options:

    Table 1. emconfigutil Options
    Option Valid Values Description


    Target device

    Required. Set target device.

    For a list of supported devices, refer to the Release Notes for the product you are using:
    for all supported devices.
    --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.
    --save-temps N/A Optional. Specifies that intermediate files will not be deleted, and will remain after command is executed.
    --xp Valid Xilinx parameters and properties Optional. Specify 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 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 --platform xilinx_vcu1525_dynamic_5_0
     --nd 2
  2. Set the 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/2018.2.

    C Shell:

    setenv XILINX_SDX /opt/Xilinx/SDx/2018.2


    export XILINX_SDX=/opt/Xilinx/SDx/2018.2
  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


    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