Running Emulation on Data Center Accelerator Cards

Running Emulation on Data Center Accelerator Cards - 2021.2 English

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

Document ID

UG1393

Release Date

2022-03-29

Version

2021.2 English

Tip: Set up the command shell or window as described in Setting Up the Vitis Environment 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.
Create an emconfig.json file from the target platform as described in emconfigutil Utility. This is required for running hardware or software 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 sw_emu (software emulation) or hw_emu (hardware emulation) as appropriate. 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 sw_emu
```
Bash shell:
```
export  XCL_EMULATION_MODE=sw_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 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.