See Vitis™ Development Environment on xilinx.comSee Vitis™ AI Development Environment on xilinx.com |
Version: Vitis 2024.1
The AMD Vitis™ environment development methodology reflects the heterogeneous nature of AMD Versal™ adapative SoC systems, which typically consist of a processing system (PS), programmable logic (PL), and AI Engine (AIE) functionality. Using the Vitis tools, you can develop and verify these components independently and gradually integrate them to form the final system.
The Vitis environment design flow is an iterative process that might loop through each step multiple times, adding layers or elements to the adaptable system through subsequent iterations. Teams can iterate through the early steps more quickly and take more time with later steps, which provide more detailed performance data.
A system-level debug of AI Engine designs that could use up to 400 tiles in the AI Engine domain, PL interfaces and kernels, and PS application can be done at several stages in the design flow. The system-level debug of AI Engine designs can be categorized as follows:
- Functional debug that involves techniques to uncover bugs in the AI Engine kernel source code.
- Performance level debug that involves debug techniques to uncover reasons for the throughput drop or reasons for larger latencies when the AI Engine graph is run either in simulation or in hardware.
Techniques to uncover both functional and performance level bugs are described in the following sections.
Source level debug includes visibility into the register contents view, variable values view, breakpoints view, and hence, necessitates a GUI. The Vitis integrated design environment (IDE) is the tool that supports these debug requirements. This tutorial demonstrates how to use the Vitis IDE to manage these challenges and additional tools and methodologies to assist with your design debug.
IMPORTANT: Before beginning the tutorial, make sure you have installed the Vitis 2024.1 software. The Vitis release includes all the embedded base platforms including the VCK190 base platform that is used in this tutorial. Ensure you have downloaded the Common Images for Embedded Vitis Platforms from this link: https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-platforms/2024-1.html.
The common image package contains a prebuilt Linux kernel and root file system that can be used with a Versal adaptive SoC board for embedded design development using Vitis. Before starting this tutorial, run the following steps:
- Go to the directory where you have unzipped the Versal Common Image package.
- In a Bash shell, run
/Common Images Dir/xilinx-versal-common-v2024.1/environment-setup-cortexa72-cortexa53-xilinx-linux script. This script sets up theSDKTARGETSYSROOTandCXXvariables. If the script is not present, you must run/Common Images Dir/xilinx-versal-common-v2024.1/sdk.sh. - Set up your
ROOTFSandIMAGEto point to therootfs.ext4andImagefiles located in the/Common Images Dir/xilinx-versal-common-v2024.1directory. - Set up your PLATFORM_REPO_PATHS environment variable to
$XILINX_VITIS/lin64/Vitis/2024.1/base_platforms.
This tutorial targets a 2024.1 VCK190 production board.
The architecture of the Peak detector consists of three kernels. A peak_detect kernel and two postprocessing kernels, data_shuffle and upscale. The peak_detect kernel takes the vector input data of type int32 and size 16 for every iteration and computes, 1) max(16-lane input) 2) an expression on minimum value using APIs and sends it over stream and buffer respectively. The stream output is broadcasted to the two kernels, data_shuffle and upscale, for postprocessing.
The complete design is shown in the Vitis analyzer.
Use the design files from <tutorial_path>/09-debug-walkthrough/cmd_src and create a system project manually in Unified Vitis IDE using the steps mentioned in Port a Command Line Project to a Vitis IDE System Project.
There are several ways to debug a system design that include the PS, PL, and AI Engine or an AI Engine only design. Each method has the intended goal to help debug practice. The following are some debug methodlogies that helps analyzing the design and take decisions to improve.
Use the design files from <tutorial_path>/09-debug-walkthrough/cmd_src and create a system project manually in Unified Vitis IDE using the steps mentioned in Port a Command Line Project to a Vitis IDE System Project.
There are several ways to debug a system design that include the PS, PL, and AI Engine or an AI Engine only design. Each method has the intended goal to help debug practice. The following are debug methodologies that help with analyzing the design and making improvements.
| X86 Simulation - Vitis IDE Flow | |
| Build and Simulate in the Vitis IDE | Demonstrates how to use the Vitis IDE to build and simulate the AI Engine design. |
| Debug Using printf() | Demonstrates how to add the formatted `printf()` to print debug messages. |
| Debug Using printf() with Vector Data Types | Demonstrates how to print the vector output data value via `printf()`. |
| Debug Using the Vitis IDE Debugger | Demonstrates how to use the Vitis IDE debugger to debug an AI Engine design. |
| x86simulator Options for Debugging | Demonstrates how to use the x86simulator options file for debugging. |
| Data Dump | Demonstrates how to use the data dump feature with a practical scenario. |
| Deadlock Detection | Demonstrates how to debug deadlock scenarios in an x86simulation. |
| Trace Report in the File | Demonstrates how to visualize the trace report in the file. |
| Trace Report in the Output Console | Demonstrates how to visualize the trace report in the output console during runtime. |
| Memory Access Violation and Valgrind Support | Demonstrates how to debug memory access violations in an AI Enigne design using Valgrind support. |
| Using the GDB in the Command Line | Demonstrates debugging in command line using the GNU Debugger (GDB). |
| x86simulation on the Command Line | Demonstrates how to run x86simulation on the command line. |
| x86simulation with the GDB | Demonstrates how to use the GDB during x86simulation. |
| x86simulator Using a GDB Server | Demonstrates how to use a GDB server to debug the design. |
| AIE Simulation - Vitis IDE Flow | |
| Build and Simulate in the Vitis IDE | Demonstrates how to use the Vitis IDE to build and simulate an AI Engine design. |
| Debug Using printf | Explains how to add a `printf()` statement, and view the output in the console. |
| Debug Using the Vitis IDE Debugger | Explores different debugging techniques that use the Vitis IDE debugger. |
| Enabling Profile and Trace Options | Explains how to enable profile and trace options in the Vitis IDE. Explores different event trace dump options like VCD and WDB. |
| Deadlock Detection | Shows a practical deadlock scenario and some simulator options to identify the deadlock. |
| Visualizing Deadlock in the Vitis Analyzer | Explains how to visualize deadlock using trace information in the Vitis Analyzer, and identify the root cause. |
| Debugging Memory Access Violations | Introduces an out of bound read access, and explains how to identify the violations using AI Engine simulator options. |
| Single Kernel Debug | Explains how to debug a single kernel design usign a pipeline view in the Vitis IDE. |
| Design Performance Debug | Shows how to calculate kernel latency and throughput using profile information. |
| Software Emulation - Vitis IDE Flow | |
| Build for Software Emulation Using the Vitis IDE | Explains how to create a system project, build for sofware emulation, and run. |
| Using the Vitis IDE for Software Emulation Debug | Explains how to debug for software emulation using the Vitis IDE. |
| Hardware Emulation - Vitis IDE Flow | |
| Build for Hardware Emulation Using the Vitis IDE | Explains how to create a system project, build for hardware emulation, and run. |
| Debug PL Kernels Using the Vivado Logic Simulator | Explains how to use the AMD Vivado™ XSIM to debug the PL kernels. |
| Performance of the AI Engine Using Hardware Emulation Results | This section profiles the system for hardware emulation and compares the throughput of the AI Engine design in hardware emulation with the throughput in a AI Engine simulation. |
| Command Line Project Source Code Debug with the Vitis IDE | This section helps you debug your command line project using the features of the Vitis IDE debugger without porting your system design to the IDE. |
| Hardware - Command Line Flow | |
| Running the Design on Hardware | Explains how to determine the functional correctness of the design by running on hardware. |
| Error Handling and Reporting in the Host Application |
Explains how to use error reporting APIs to handle errors in the host code. * XRT error handling APIs - This method reports errors that can be detected during the XRT runtime function call or underneath driver, system, hardware, etc. * Using XBUtil - XButil error reporting can accumulate all the errors from various classes and sorts them by timestamp. |
| Analyzing Run Results |
Explains different techniques (XRT, XBUtil, and XSDB) to analyze the design by running on hardware and helps to choose from the following methodologies. - AI Engine status using XRT - Using XRT is fast and host executable can automatically reads the `xrt.ini` file to configure the runtime. - * Manual AI Engine status using XBUtil utility - XBUtil is a standalone command utility included with XRT and does not require any special file to handle. You can directly use XBUtil commands on the console after boot. - Deadlock detection using XSDB - XSDB runs independent of XRT and can analyze the results before, during, or after design runs. Also, you can use the XSDB for baremetal applications in addition to the Linux-based applications. |
| Using APIs in the Host Application |
Explains how to modify the host code to add APIs in the host application that helps profiling the design for getting throughput, latency, and bandwidth. - Profiling Graph throughput - Provides insight on how to modify the host code for profiling the number of samples sent and received. * Profiling to count Samples sent and received (Exercise Step) - Provides insight on how to modify the host code for profiling the number of samples sent and received. |
| Hardware Profiling Feature - XRT Flow |
Explains how to set up the configuration file `xrt.ini`, and run the hardware design to generate profile data using the XRT flow. - Open multiple profile runs in Vitis Analyzer - This exercise helps you understand how to open different profile summaries (two different runs) in a single Vitis Analyzer view. - Profiling Data Explaination - This explains how to analyze AI Engine core,memory and interface profiling data. Also discusses what action should be taken based on the stall time and DMA lock time. |
| Hardware Profiling Feature - XSDB Flow |
This method explains how to use the XSDB-based flow to profile for both baremetal and Linux operating systems. |
| Profiling Using PL Profile Monitors | Explains how to insert PL profile monitors in the v++link command. This helps identify specific PL kernels(s) causing a performance drop. |
| Inserting ILA(s) to Monitor Specific AXI Interfaces | Explains how to insert one or more integrated logic analyzers (ILAs) to monitor specific PL AXI interfaces to help identify exactly where and when a throughput drop occurs. Also helps in identifying whether data is sent correctly to the AI Engine from the PL compenents and received correctly from the AI Engine to the PL. |
| Build the Design for Event Trace Analysis |
Explains how to use different event trace options for compiling and its significance. Also walks through the steps to generate the hardware image. - Prepare for the hardware run. |
| Event Trace Analysis - XRT Flow |
Explains how to do an AI Engine event trace and analysis by setting up the configuration file `xrt.ini` and run the hardware design to generate trace data using the XRT flow. * Launch Vitis Analyzer to Examine Event Trace Files - Details of the Event Trace data |
| Event Trace Analysis - XSDB Flow |
This method explains how to use the XSDB-based flow to perform event trace analysis on an AI Engine design. |
| Event Trace Considerations |
This method explains how to use the XSDB-based flow to perform event trace analysis on anAI Engine design. - Event Trace Choice Considerations - Number of Event Trace Streams Methodology - Event Trace Limitations |
| Debug the Host/Kernel Source Code Using the Vitis IDE |
Explains how to set up the target connection for hardware in the Vitis IDE and debug the host code and kernel source code in the Vitis IDE debugger. |
The foundation of the Vitis environment design methodology is an iterative approach and parallel development. As a result, AMD strongly recommends the following best practices:
- Develop the adaptable subsystem and the custom platform in parallel.
- A well-partitioned system means that these two elements can be developed and verified independently, saving time and effort. Debug and verify the AI Engine graph and each of the PL kernels individually before proceeding with integration.
- Taking this approach maximizes the chances of rapid convergence during the integration phase. It is much easier to debug integration issues when all components are known to be correct.
- Use a standard AMD platform (such as the VCK190) to integrate, and verify the adaptable subsystem comprised of the AI Engine graph and PL kernels before targeting the custom platform.
- AMD platforms are preverified and ready to be deployed on hardware. By using a standard AMD platform, developers of AI Engine graphs and PL kernels can verify the adaptable subsystem using simulation or hardware boards without the uncertainties and the complexities of the custom platform.
- Ensure performance goals are met at each stage of the flow.
- Performance results do not improve when running the full system in hardware versus simulating individual components in isolation. Therefore, it is essential to thoroughly check for and debug any performance issues as early as possible in the flow. Ensuring that performance goals are met at the component level is easier than in the context of a complex system that includes interactions between all of the components.
GitHub issues will be used for tracking requests and bugs. For questions, go to support.xilinx.com.
Copyright © 2020–2024 Advanced Micro Devices, Inc