See Vitis™ Development Environment on xilinx.comSee Vitis™ AI Development Environment on xilinx.com |
Version: Vitis 2024.2
- Digital Down-conversion Chain: Converting from Intrinsics to API
Versal™ adaptive SoCs combine programmable logic (PL), processing system (PS), and AI Engines with leading-edge memory and interfacing technologies to deliver powerful heterogeneous acceleration for any application. The hardware and software are targeted for programming and optimization by data scientists and software and hardware developers. A host of tools, software, libraries, IP, middleware, and frameworks enable Versal adaptive SoCs to support all industry-standard design flows.
This tutorial demonstrates the steps to upgrade a 32-branch digital down-conversion chain so that it is compliant with the latest tools and coding practice. Examples for the following changes with side-by-side view of the original and upgraded code are included in the tutorial.
- Converting coding style from kernel functions to kernel C++ classes
- Relocating global variables to kernel class data members
- Handling state variables to enable x86sim
- Migrating Windows (deprecated) to buffers for non-stream based kernel I/O
- Replacing kernel intrinsics with equivalent AI Engine APIs
- Updating older pragmas
- Supporting x86 compilation and simulation
You can find the design description in the Digital Down-conversion Chain Implementation on AI Engine (XAPP1351). The codebase associated with the original design can be found in the Reference Design Files.
Note: Simply loading the latest version of the tools and compiling the design is not possible because the baseline Makefile has deprecated compiler options.
Important changes to the Makefile are listed below:
-
Upgrade part speed grade xcvc1902-vsva2197-1LP-e-S-es1 (previously specified by
--device) to xcvc1902-vsva2197-2MP-e-S (specified by--platform). As can be seen in the following table (referenced from Versal AI Core Series Data Sheet: DC and AC Switching Characteristics (DS957)), this increases the AI Engine clock frequency from 1 GHz to 1.25 GHz.
Recompiling and simulating the design with this change causes the throughput to increase by around 17-25%.
-
Upgrade to use v++ unified compiler command.
-
Add support for x86 compilation and simulation.
Functionality included in the init() function is migrated to the new kernel C++ class constructor. The main kernel function wrapper is migrated to a new class run() member function.
Create a header file for the class. You are required to write the static void registerKernelClass() method in the header file. Inside the registerKernelClass() method, call the REGISTER_FUNCTION macro. This macro is used to register the class run method to be executed on the AI Engine core to perform the kernel functionality.
When creating the kernel in the upper graph or subgraph, use kernel::create_object instead of kernel::create. Remove initialization_function as it is now part of class constructor.
Windows I/O connections between kernels were deprecated in the 2023.2 release of the AMD Vitis™ software platform. The AI Engine Kernel and Graph Programming Guide (UG1079) describes how the source code of a design should change to upgrade it to buffer I/Os. The following figures show the steps required (repeated for every kernel) to upgrade I/O connections from Windows to buffers.
-
Make the changes shown in the following figure in the
kernel.ccfile:
-
If the design uses classes, upgrade the associated header file.
-
In the graph file, modify the connection type and specify dimension. Note division by 4 to convert from bytes to samples.
The following example shows a side-by-side comparison of intrinsic-based code compared to API-based code. Both are functionally equivalent and produce the same final hardware usage and throughput.
Move the state variables instantiation from kernel::run to class member or use thread_local, as shown below. More information can be found in the in Memory Model section of the AI Engine Tools and Flows User Guide (UG1076).
Update chess_alignof to alignas. This is highlighted in the previous figure.
x86 compilation and functionally correct simulation is enabled using the following actions:
-
Modifying the Makefile to include target=x86sim capability.
-
Relocating global variables to kernel class data members, as highlighted in a previous step.
-
Moving state variables instantiation from
kernel::runto class member or usethread_local, as highlighted in a previous step.
The 32-branch digital down-conversion design can be built using the command line.
The first step is to set the environment variable COMMON_IMAGE_VERSAL to the full path where you have downloaded the Versal platforms corresponding to your tool release. This edit should be done in the 09-ddc_chain/Makefile file.
VERSAL_VITIS_PLATFORM = xilinx_vck190_base_202420_1
VITIS_PLATFORM_DIR = ${PLATFORM_REPO_PATHS}/${VERSAL_VITIS_PLATFORM}
export VITIS_PLATFORM_XPFM = ${VITIS_PLATFORM_DIR}/${VERSAL_VITIS_PLATFORM}.xpfm
# Set SysRoot, RootFS and Image
export VITIS_SYSROOTS = ${COMMON_IMAGE_VERSAL}/sysroots/cortexa72-cortexa53-xilinx-linux
export SDKTARGETSYSROOT = ${VITIS_SYSROOTS}
export KERNEL_IMAGE = ${COMMON_IMAGE_VERSAL}/Image
export ROOTFS = ${COMMON_IMAGE_VERSAL}/rootfs.ext4
export XLNX_VERSAL = ${COMMON_IMAGE_VERSAL}
export PLATFORM = --platform=${VITIS_PLATFORM_XPFM}
export SYSROOT = ${SDKTARGETSYSROOT}The DDC design can be built and simulated targeting x86sim to functionally verify the C code as follows:
[shell]% cd <path-to-09-ddc_chain-dir>
[shell]% make x86allThe number of simulation samples mismatch compared to expected outputs is displayed.
The DDC design can be built and simulated by targeting hardware using the Makefile as follows:
[shell]% cd <path-to-09-ddc_chain-dir>
[shell]% make allThe number of simulation samples mismatch compared to expected outputs is displayed. Achieved throughput for all branches against minimum requirement is also displayed.
In this tutorial, we highlight steps that an AI Engine designer can take to upgrade their design to use APIs instead of intrinsics. The upgraded AIE API version achieves the same throughput performance as the original code base, while being easier to read and maintain.
Table below summarizes key parameters for the older design (ran on newer version of the tools) and compares it to upgraded design.
| Original | Upgraded | |
|---|---|---|
| Support x86sim | No | Yes |
| Intrinsics vs API | Intrinsics | Mostly APIs |
| Windows vs Buffers | Windows | Buffers |
| Functionally correct | Yes | Yes |
| Throughput (MSPS) | ~247/224 | ~247/224 |
GitHub issues will be used for tracking requests and bugs. For questions, go to support.xilinx.com.
Components: xilinx-images
images in the documentation
Components: xilinx-files
The MIT License (MIT)
Copyright (c) 2023 Advanced Micro Devices, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2023 Advanced Micro Devices, Inc
Copyright © 2021 Xilinx Inc.
Components: generated-xilinx-files
Redistribution and use in binary form only, without modification, is permitted provided that the following conditions are met:
-
Redistributions must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
The name of Xilinx, Inc. may not be used to endorse or promote products redistributed with this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY XILINX, INC. "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL XILINX, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.