emconfigutil Utility - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2023.2 English

When running software or hardware emulation in the command line flow, it is necessary to create an emulation configuration file, emconfig.json, used by the runtime library during emulation. The emulation configuration file defines the device type and quantity of devices to emulate for the specified platform. A single emconfig.json file can be used for both software and hardware emulation.

Note: When running on real hardware, the runtime and drivers query the installed hardware to determine the device type and quantity installed, along with the device characteristics.

To use the emconfigutil utility to automate the creation of the emulation file, specify the target platform and additional options in the emconfigutil command line:

emconfigutil --platform <platform_name> [options]

At a minimum, you must specify the target platform through the -f or -–platform option to generate the required emconfig.json file. The specified platform must be the same as specified during the host and hardware builds.

The emconfigutil options are provided in the following table.

Table 1. emconfigutil Options
Option Valid Values Description
-f or --platform Target device Required. Defines the target device from the specified platform.

For a list of supported devices, refer to Supported Platforms.

--nd Any positive integer Optional. Specifies number of devices. The default is 1.
--od Valid directory Optional. Specifies the output directory. When running emulation, the emconfig.json file must be in the same directory as the host executable. The default is to write the output in the current directory.
-s or --save-temps N/A Optional. Specifies that intermediate files are not deleted and remain after the command is executed. The default is to remove temporary files.
--xp Valid AMD parameters and properties. Optional. Specifies additional parameters and properties. For example:
--xp prop:solution.platform_repo_paths=<xsa_path>
This example sets the search path for the target platforms.
-h or --help N/A Prints command help.
The emconfigutil command generates the emconfig.json configuration file in the output directory or the current working directory.
Tip: When running emulation, the location of the emconfig.json file can be specified by the $EMCONFIG_PATH variable, or must be found in the same directory as the host executable.

The following example creates a configuration file targeting two xilinx_u200_qdma_201910_1 devices.

$emconfigutil --xilinx_u200_qdma_201910_1 --nd 2