Running Hardware Emulation

Running Hardware Emulation - 2024.2 English

Data Center Acceleration Using Vitis User Guide (UG1700)

Document ID

UG1700

Release Date

2025-01-15

Version

2024.2 English

Tip: Set up the command shell or window as described in Setting Up the Vitis Environment in the Data Center Acceleration using Vitis (UG1700) prior to running the builds.

Set the desired runtime settings in the xrt.ini file. This step is optional.
As described in xrt.ini File , the file specifies various parameters to control debugging, profiling, and message logging in XRT when running the host application and kernel execution. This enables the runtime to capture debugging and profile data as the application is running. The Emulation group in the xrt.ini provides features that affect your emulation run.

Tip: Be sure to use the v++ -g option when compiling your kernel code for emulation mode.
Generate an emconfig.json file from the target platform as described in emconfigutil Utility in the Vitis Reference Guide (UG1702). This is required for running hardware emulation.
The emulation configuration file, emconfig.json, is generated from the specified platform using the emconfigutil command, and provides information used by the XRT library during emulation. The following example creates the emconfig.json file for the specified target platform:
```
emconfigutil --platform xilinx_u200_xdma_201830_2
```
In emulation mode, the runtime looks for the emconfig.json file at a location specified by the $EMCONFIG_PATH variable, or in the same directory as the host executable.
Tip: It is mandatory to have an up-to-date JSON file for running emulation on your target platform.
Set the XCL_EMULATION_MODE environment variable to hw_emu (hardware emulation). This changes the application execution to emulation mode.
Use the following syntax to set the environment variable for C shell (csh):
```
setenv XCL_EMULATION_MODE hw_emu
```
Bash shell:
```
export  XCL_EMULATION_MODE=hw_emu
```
Important: The emulation targets will not run if the XCL_EMULATION_MODE environment variable is not properly set.
Run the application.
With the runtime initialization file (xrt.ini), emulation configuration file (emconfig.json), and the XCL_EMULATION_MODE environment set, run the host executable with the desired command line argument.

For example:
```
./host.exe kernel.xclbin
```
Tip: This command line assumes that the host program is written to take the name of the xclbin file as an argument, as most AMD Vitis™ examples and tutorials do. However, your application might have the name of the xclbin file hard-coded into the host program, or might require a different approach to running the application.