Debug Walkthrough - 2023.2 English

Version: Vitis 2023.2

Introduction

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:

1. Functional debug that involves techniques to uncover bugs in the AI Engine kernel source code.

2. 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 2023.2 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/2023-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:

1. Go to the directory where you have unzipped the Versal Common Image package.

2. In a Bash shell, run /Common Images Dir/xilinx-versal-common-v2023.2/environment-setup-cortexa72-cortexa53-xilinx-linux script. This script sets up the SDKTARGETSYSROOT and CXX variables. If the script is not present, you must run /Common Images Dir/xilinx-versal-common-v2023.2/sdk.sh.

3. Set up your ROOTFS and IMAGE to point to the rootfs.ext4 and Image files located in the /Common Images Dir/xilinx-versal-common-v2023.2 directory.

4. Set up your PLATFORM_REPO_PATHS environment variable to $XILINX_VITIS/lin64/Vitis/2023.2/base_platforms.

This tutorial targets a 2023.2 VCK190 production board.

Example Design: Peak Detector

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.

Vitis IDE Project

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.

Methods

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.

Debug Methodologies

Best Practices

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.

Support

GitHub issues will be used for tracking requests and bugs. For questions, go to support.xilinx.com.

_{Copyright © 2020–2023 Advanced Micro Devices, Inc}

^{Terms and Conditions}