Emulation Configuration Utility (emconfigutil)

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--platformoption is required. The syntax of the command is:

    emconfigutil --platform  [options]
    Table 1.emconfigutil Options
    Option Valid Values Description
    -for--platform Target device Sets target device.

    For a list of supported devices, refer toSDAccel Environment Release Notes, Installation, and Licensing Guide(UG1238).

    Required.
    --nd Any positive integer Specifies number of devices. Default is 1. Optional.
    --od Valid directory Specifies output directory. When emulating the design, theemconfig.jsonfile must be in the same directory as the host executable. Optional.
    -sor--save-temps N/A Specifies that intermediate files are not deleted and remain after command is executed. Optional.
    --xp Valid Xilinx parameters and properties 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--platformoption.

    Optional.
    -hor--help N/A Prints help messages.

    Theemconfigutilcommand generates the configuration fileemconfig.jsonin the output directory.

    When running emulation, theemconfig.jsonfile must be in the same directory as the host executable. The following example creates a configuration file targeting twoxilinx_vcu1525_dynamic_5_0devices.

    $emconfigutil --platform xilinx_vcu1525_dynamic_5_0 --nd 2
  2. Set theXILINX_SDXenvironment variable.

    TheXILINX_SDXenvironment needs to be set and must point to theSDAccelinstallation path for the emulation to work. Below are examples assumingSDAccel™is installed in/opt/Xilinx/SDx/2019.1.

    C Shell:

    setenv XILINX_SDX /opt/Xilinx/SDx/2019.1

    Bash:

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

    SettingXCL_EMULATION_MODEenvironment variable tosw_emu(software emulation) orhw_emu(hardware emulation) changes the application execution to emulation mode. In emulation mode, runtime looks for the fileemconfig.jsonin 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 theXCL_EMULATION_MODEenvironment variable turns off the emulation mode.

  4. Run the emulation.

    With the configuration fileemconfig.jsonandXCL_EMULATION_MODE, use the following command line to perform emulation:

    $./host.exe kernel.xclbin