Running the System on Hardware - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 English

Running the system depends on the build target. The process of running on the physical hardware is different from running either software or hardware emulation. Refer to Running Emulation Targets for more information on running emulation.

Running the System project hardware build lets you see your application running on an embedded processor platform targeting an AMD Versal™ adaptive SoC or AMD Zynq™ UltraScale+™ MPSoC devices, or an accelerator card such as the AMD Alveo™ Data Center accelerator card. The performance data and results captured here are the actual performance of your accelerated application. Yet the profiling data from this run might still reveal opportunities to optimize your design.

Tip: To use the accelerator card, you must have it installed as described in Getting Started with Alveo Data Center Accelerator Cards (UG1301).
  1. Edit the xrt.ini file as described in xrt.ini File.

    This is optional, but recommended when running on hardware for evaluation purposes. You can configure XRT with the xrt.ini file to capture debugging and profile data as the application is running. To capture event trace data when running the hardware, refer to Enabling Profiling in Your Application. To debug the running hardware, refer to Debugging During Hardware Execution.

    Tip: Ensure to use the v++ -g option when compiling your kernel code for debugging.
  2. Unset the XCL_EMULATION_MODE environment variable.
    Important: The hardware build will not run if the XCL_EMULATION_MODE environment variable is set to an emulation target.
  3. For embedded platforms, boot the SD card.
    Tip: This step is only required for platforms using AMD embedded devices such as Versal adaptive SoC or Zynq UltraScale+ MPSoC.

    For an embedded processor platform, copy the contents of the ./sd_card folder produced by the v++ --package command to an SD card as the boot device for your system. Boot your system from the SD card. You will need to login to PetaLinux to run the application from the SD card, using the following steps:

    1. Login to the user name petalinux and set a password for this user if it is the first time logging in. This password will also be the sudo password.
    2. Switch user to sudo to run the host application from the SD card: sudo -i
    3. Change directory to the SD card: cd /run/media/mmcblk0p1
    4. Run the application as described in the next step.
  4. Run your application.

    The specific command line to run the application will depend on your host code. A common implementation used in AMD tutorials and examples is as follows:

    ./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 can have the name of the xclbin file hard-coded into the host program, or can require a different approach to running the application.

When running the design you can specify a number of trace options as described in Enabling Profiling in Your Application to capture design data during runtime. Any reports generated during the run are collected into the xrt.run_summary file. This collection of reports can be viewed by opening the run_summary in Vitis analyzer, and includes a Summary report, System and Platform Diagrams to illustrate the hardware design, Run Guidance offering any suggestions for improving the performance of the system, and a Profile Summary and Timeline Trace when enabled in the xrt.ini file during runtime. Refer to Working with the Analysis View (Vitis Analyzer) for additional information.