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:

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
`-f` or `--platform`	Target device	Sets target device. For a list of supported devices, refer to SDAccel 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, the emconfig.json file must be in the same directory as the host executable. Optional.
`-s` or `--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 `--platform` option. Optional.
`-h` or `--help`	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

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

C Shell:
```
setenv XILINX_SDX /opt/Xilinx/SDx/2019.1
```
Bash:
```
export XILINX_SDX=/opt/Xilinx/SDx/2019.1
```
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.
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
```