See Vitis™ Development Environment on xilinx.com See Vitis™ AI Development Environment on xilinx.com |
Version: Vitis 2022.1
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. 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 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 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 read and followed the Vitis Software Platform Release Notes (v2022.1) for setting up software and installing the VCK190 base platform.
Before starting this tutorial run the following steps:
- Set up your platform by running the
xilinx-versal-common-v2022.1/environment-setup-cortexa72-cortexa53-xilinx-linux
script as provided in the platform download. This script sets up theSYSROOT
andCXX
variables. If the script is not present, you must run thexilinx-versal-common-v2022.1/sdk.sh
. - Set up your ROOTFS to point to the
xilinx-versal-common-v2022.1/rootfs.ext4
. - Set up your IMAGE to point to
xilinx-versal-common-v2022.1/Image
. - Set up your
PLATFORM_REPO_PATHS
environment variable based upon where you download the platform.
This tutorial targets VCK190 production board, PLATFORM variable in the Makefile(s) is:
PLATFORM = ${PLATFORM_REPO_PATHS}/xilinx_vck190_base_202210_1/xilinx_vck190_base_202210_1.xpfm
The architecture of the beamformer design consists of three kernels with slight differences which are scalable to various matrix sizes and throughput requirements. The design methodology is applicable to matrix multiplication including, but not limited to, 5G wireless communication.
One feature of the beamforming architecture is that only a small number of kernels are required by various system configurations. Depending on the location of the kernels in the cascading chain, they are named first, middle, and last. All the kernels implement (8x8) times (8x12) matrix multiplication and only differ in the input and output interfaces. The first kernel in the cascading chain does not have cascading input, while the last one writes the output to local memory instead of the cascading bus.
Every beamforming kernel performs eight MAC4 operations on one column of eight inputs to compute eight outputs. Each MAC4 operation takes eight coefficients and two inputs, and stores the result in a register of 384 bits. At the end of computation, the partial summations are sent to the next AI Engine core for further accumulation, or output to local memory after shift, round, and saturation.
This design has 64 tiles and 88 programmable logic input/output (PLIO) streams that the PS application prepares input data for, sends data to AI Engine kernels via PL kernels. AI Engine kernels process the data received and then send it back to the PL kernels. The PS application receives the processed data, then saves it to the designated directory/files, compares it to golden data, and prints out "TEST PASSED" or "TEST FAILED" result on the console.
The complete beamformer design is shown in the Vitis™ analyzer.
There are several ways to debug a system design that include PS, PL, and AI Engine or an AI Engine only design. Each method has the intended goal to help debug practice. For projects that are command-line based and would like to port to Vitis™ IDE, reference Port command-line based projects to Vitis IDE for detail steps.
For ease of use, a Vitis IDE exported project, beamformer_2022_1.ide.zip
can be downloaded from https://www.xilinx.com/bin/public/openDownload?filename=beamformer_2022_1.ide.zip. Then import this zip file into the Vitis IDE.
Step 0. Download data files, beamformer_data.zip
, from https://www.xilinx.com/bin/public/openDownload?filename=beamformer_data.zip. Unzip this file and save it at the same level as the Makefile of this tutorial.
Step 1. Source the Vitis IDE script or install the Vitis IDE.
Step 2. Launch the Vitis IDE using the command vitis -workspace tutorial
.
Step 3. Click on File->import.... Select Vitis project exported zip file->Next. Browse to the beamformer.ide.zip
file. Click Next->Finish.
Step 4. You should see the imported beamformer design in the Vitis IDE.
After the project is ready in the Vitis IDE, you can move on to the next steps to try out the various debug features in software and hardware emulation and also in hardware.
Note: The imported project specifies a hardware platform path that must be adjusted to your specific installed path to work correctly. Click on beamformer_system.sprj
to update the hardware platform path in the Vitis IDE.
Due to huge cost and time associated with build real system for testing and verification purposes, there are several simulation and modeling techniques to help evaluating AI Engine designs.
Classification of simulation,
- Functional vs. Timing simulations.
Functional simulator simulates the functionalities of the design only and do not model microarchitecture details and constraints. X86simulator and SW_emu are considered in this category while Aiesimulator and HW_emu are considered timing simulations that simulates execution time/performance and constraints of the design. Keeping track of those detailed timing information makes them slow and resources intensive in comparison to functional simulators.
- Application level vs. Full system simulations.
Obviously, application level simulation focus on targeted designs, e.g. AI Engine design instead of a full fledge target operating system (OS). In user level simulation, any system service requests by the simulated application are serviced by the underlying host OS. Application level simulation is usually less complex but likely to show some inaccuracies due to lack of system level support.
Supported simulations are categorize in this table.
Functional Simulation | Timing Simulation | |
Application Level Simulation | X86simulator | AIEsimulator |
System Level Simulation | SW_emu | HW_emu |
These supported simulations help to fix majority of design issues before running the AI Engine design on actual hardware. UG1076 contains more details of the simulation capabilities and how to apply the supported features to resolve design issues such as memory leaks, memory access conflicts, resource constraints, integration with PL/PS domains.
See X86simulator.
See AIEsimulator.
See SW_emu.
See HW_emu.
After fixing all AI Engine design issues with above simulations, running AI Engine design on hardware could still exhibits issues. Chapter 18, "AI Engine Hardware Profile and Debug Methodology" in UG1076 describes these stages along with detail steps included.
This is the first stage running the design on hardware. Areas to check
- Verify input and output data
- Restrict pointer usage
- Error reporting and handling reporting from host application
- XRT APIs returned status
- Design stalls analysis
- XRT Xbutil utility
- XSDB generate run summary file and display with vitis_analyzer
See AI Engine/PL kernel Debug with XRT utilities on HW, and AI Engine Debug with Profiling APIs on HW.
See AI Engine Debug with Profiling Feature.
See AI Engine Debug with Integrated Logic Analyzer.
See AI Engine Debug with Event Trace.
GitHub issues will be used for tracking requests and bugs. For questions go to support.xilinx.com.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
XD005 | © Copyright 2021-2022 Xilinx, Inc.