Running an Application

TIP: Set up the command shell or window as described in Setting up the Vitis Environment prior to running the builds.

As explained in Build Targets, there are three different types of builds you can target in the Vitis core development kit: software emulation, hardware emulation, and the system hardware build. Each of these build targets offers advantages, and limitations, and it is recommended that you work your way through building and running each of these targets.

Software emulation: The software emulation build compiles and links quickly, runs on the x86 system as a compiled C-model, and lets you quickly iterate on both the host code and kernel logic.
Hardware emulation: The host program runs as before, but the kernel code is compiled into an RTL behavioral model which is run in the Vivado simulator. This build and run loop takes longer but provides a cycle-accurate view of the kernel logic.
System hardware: The host program runs as before, but this time connected with the actual accelerator card, running the FPGA binary produced for your application. The performance data and results you capture here are the actual performance of your accelerated application. Yet this run might still reveal opportunities to optimize your design.

Running Emulation Builds

Edit the xrt.ini file required by XRT. This is optional, but recommended.
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 the emconfig.json file required for running emulation 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 Xilinx runtime library during emulation. The following example creates the emconfig.json file for the specified target platform:
```
emconfigutil --platform xilinx_u200_xdma_201830_2
```
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. In emulation mode, the runtime looks for the emconfig.json file in the same directory as the host executable, and reads in the target configuration for the emulation runs. This is also required for emulation runs.
Use the following syntax to set the environment variable for C target platform:
```
setenv XCL_EMULATION_MODE sw_emu
```
Bash target platform:
```
export  XCL_EMULATION_MODE=sw_emu
```
IMPORTANT: The emulation targets will not run if the XCL_EMULATION_MODE environment variable is not properly set.
For Embedded platforms, launch the emulation environment (QEMU).
TIP: This step is only required for emulating the Arm processor environment of platforms using Xilinx embedded devices such as Zynq UltraScale+ MPSoC.
As explained in Packaging the System, the Vitis compiler creates a script for setting up and launching the QEMU emulation environment called launch_sw_emu.sh or launch_hw_emu.sh. You must use this script from the command line to run the application.
Run the application.
With the runtime initialization (xrt.ini), emulation configuration file (emconfig.json), and the XCL_EMULATION_MODE environment set, run the host executable with the desired command line argument, as you normally would run it if it was not an emulation run.. 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 may have the name of the xclbin file hard-coded into the host program, or may require a different approach to running the application.

Running the System Hardware Build

Running the system hardware build will let you see the actual application running on an accelerator card, such as the Alveo Data Center accelerator card, or perhaps a prototype of an embedded processor platform. In order to use the accelerator card, you must have it installed as described in Getting Started with Alveo Data Center Accelerator Cards (UG1301).

When running on hardware, you can still have XRT configured with the xrt.ini file to capture debugging and profile data as the application is running. In this case, the Debug and Runtime sections of the file might be of interest.

Beyond the installation of the accelerator and XRT, and configuring the xrt.ini file, you must unset the XCL_EMULATION_MODE environment variable prior to running the system hardware build. If you had it set for running emulation, you will need to unset it now.

With the XCL_EMULATION_MODE environment unset, run the application on hardware as follows:

./host.exe kernel.xclbin