Vitis-Tutorials 构建与代码组织分析文档
1. 项目目录结构
Vitis-Tutorials 是 AMD/Xilinx 官方提供的 Vitis 开发环境教程集合，按功能域划分为多个顶层模块，每个模块包含设计教程、功能教程和配套文档。
graph TD
Root["Vitis-Tutorials/"] --> AIE["AI_Engine_Development/"]
Root --> Dev["Developer_Contributed/"]
Root --> Emb["Embedded_Software/"]
Root --> GS["Getting_Started/"]
Root --> HW["Hardware_Acceleration/"]
Root --> ML["Machine_Learning/"]
Root --> HLS["Vitis_HLS/"]
Root --> Plat["Vitis_Platform_Creation/"]
Root --> Docs["docs-jp/"]
Root --> Meta["CHANGELOG.md/FAQs.md/Jenkinsfile/LICENSE.txt/README.md/index.rst"]
AIE --> AIE1["AIE/ (Versal AI Engine 初代)"]
AIE --> AIEML["AIE-ML/ (Versal AI Engine-ML 增强版)"]
AIE1 --> AIE_Design["Design_Tutorials/ (端到端设计)"]
AIE1 --> AIE_Feat["Feature_Tutorials/ (功能特性演示)"]
Dev --> Dev_Examples["01-Versal_Custom_Thin_Platform/02-AIE_DSP_with_Makefile_and_GUI/03-HLS_Code_Optimization/"]
Emb --> Emb_Feat["Feature_Tutorials/ (用户管理模式/调试/脚本化)"]
Emb --> Emb_GS["Getting_Started/ (嵌入式入门)"]
GS --> GS_Vitis["Vitis/ (Vitis 基础流程)"]
GS --> GS_HLS["Vitis_HLS/ (HLS 入门)"]
GS --> GS_Lib["Vitis_Libraries/ (库使用)"]
GS --> GS_Plat["Vitis_Platform/ (平台入门)"]
HW --> HW_Design["Design_Tutorials/ (卷积/TSP/Cholesky等)"]
HW --> HW_Feat["Feature_Tutorials/ (混合C/RTL内核/HBM/P2P等)"]
HLS --> HLS_Design["Design_Tutorials/ (多项式向量化/波束成形)"]
HLS --> HLS_Feat["Feature_Tutorials/ (代码分析器)"]
Plat --> Plat_Design["Design_Tutorials/ (KV260/ZCU104/VCK190平台)"]
Plat --> Plat_Feat["Feature_Tutorials/ (Petalinux定制/平台验证)"]
核心目录职责说明
| 目录 | 职责 |
|---|---|
AI_Engine_Development/ |
Versal AI Engine 设计教程，包含 AIE 和 AIE-ML 两代引擎的端到端设计与功能演示 |
Hardware_Acceleration/ |
Alveo/Versal FPGA 硬件加速设计，涵盖 HLS 内核、RTL 内核混合集成、HBM/P2P 等高级特性 |
Getting_Started/ |
新手入门教程，覆盖 Vitis 基础流程、HLS 入门、Vitis 库使用和平台创建 |
Vitis_Platform_Creation/ |
自定义 Vitis 平台（XPFM）创建教程，支持边缘和数据中心设备 |
Developer_Contributed/ |
社区开发者贡献的设计示例 |
2. 构建/编译流水线
Vitis-Tutorials 采用异构多阶段构建流程，涵盖硬件内核编译、AI Engine 图编译、主机代码编译和系统链接四个核心阶段。
flowchart TD
subgraph Input["输入源"]
HLS_C["HLS C/C++ 内核代码"]
RTL["RTL Verilog/VHDL 内核"]
AIE_Graph["AIE Graph 代码 (C++)"]
Host_Code["主机代码 (C/C++/Python)"]
Platform["目标平台 (.xpfm)"]
end
subgraph Build_Stages["构建阶段"]
HLS_Comp["HLS 编译 (v++ -c)"]
RTL_Pack["RTL 内核打包 (Vitis RTL Kernel Wizard)"]
AIE_Comp["AIE 图编译 (aiecompiler)"]
Host_Comp["主机代码编译 (gcc/g++/CMake)"]
Link["系统链接 (v++ -l)"]
Pack["xclbin 打包"]
end
subgraph Output["输出产物"]
XO["内核目标文件 (.xo)"]
AIE_ELF["AIE 可执行文件"]
Host_Exe["主机可执行文件"]
XCLBIN["FPGA 比特流容器 (.xclbin)"]
end
Input --> Build_Stages
Build_Stages --> Output
HLS_C --> HLS_Comp
RTL --> RTL_Pack
HLS_Comp --> XO
RTL_Pack --> XO
AIE_Graph --> AIE_Comp
AIE_Comp --> AIE_ELF
Host_Code --> Host_Comp
Host_Comp --> Host_Exe
XO --> Link
AIE_ELF --> Link
Platform --> Link
Link --> Pack
Pack --> XCLBIN
核心构建流程详解
- 内核编译阶段：
- HLS 内核通过
v++ -c编译生成.xo目标文件 - RTL 内核通过 Vitis RTL Kernel Wizard 打包为
.xo文件
- HLS 内核通过
- AI Engine 编译阶段：
- AIE 图代码通过
aiecompiler编译生成 AIE 可执行文件
- AIE 图代码通过
- 主机代码编译阶段：
- 主机代码通过 gcc/g++ 或 CMake 编译，链接 XRT 运行时库
- 系统链接阶段：
v++ -l将内核目标文件、AIE 可执行文件和目标平台链接，生成最终的.xclbin比特流容器
3. 依赖管理
Vitis-Tutorials 依赖管理以工具链和平台为核心，采用声明式配置和环境变量结合的方式。
graph TD
subgraph Toolchain_Deps["工具链依赖"]
Vitis["Vitis 工具链 (2022.2+/settings.sh)"]
XRT["XRT 运行时 (setup.sh)"]
Petalinux["Petalinux (仅嵌入式平台)"]
CMake["CMake (主机代码构建)"]
end
subgraph Platform_Deps["平台依赖"]
Alveo["Alveo 数据中心平台 (.xpfm)"]
Edge["Versal/Zynq 边缘平台 (.xpfm)"]
end
subgraph Config_Files["声明式配置"]
Makefile["Makefile (构建脚本)"]
CFG["v++ 配置文件 (.cfg)"]
CMakeLists["CMakeLists.txt (主机代码)"]
end
Toolchain_Deps --> Config_Files
Platform_Deps --> Config_Files
Config_Files --> Build["构建执行"]
依赖管理策略
- 工具链依赖：
- 通过
settings.sh（Vitis）和setup.sh（XRT）环境脚本激活 - 版本要求：Vitis 2022.2+，XRT 版本与 Vitis 匹配
- 通过
- 平台依赖：
- 目标平台通过
.xpfm文件声明，在 Makefile 中通过PLATFORM变量指定 - 例如：
PLATFORM := /opt/xilinx/platforms/xilinx_u200_gen3x16_xdma_1_202110_1/xilinx_u200_gen3x16_xdma_1_202110_1.xpfm
- 目标平台通过
- 内核与系统依赖：
- 通过
.cfg配置文件声明内核实例、连接关系和性能剖析选项 - 例如：
nk=krnl_vadd:1:krnl_vadd_1声明 1 个krnl_vadd内核实例
- 通过
4. 多语言协作
Vitis-Tutorials 是典型的异构多语言项目，涉及 C/C++、RTL（Verilog/VHDL）、Python 和 AIE Graph C++ 等语言，通过 Vitis 统一工具链和 XRT 运行时实现互操作。
graph TD
subgraph Languages["语言层"]
C_Host["C/C++ 主机代码"]
Python["Python 主机代码 (XRT Python Binding)"]
HLS_Cpp["HLS C++ 内核"]
RTL["RTL Verilog/VHDL 内核"]
AIE_Cpp["AIE Graph C++"]
end
subgraph Interop["互操作层"]
XRT["XRT 运行时 (C/Python API)"]
Vitis_Link["Vitis 链接器 (v++ -l)"]
AIE_Interface["AIE-PL 接口 (Stream/MMIO)"]
end
subgraph Hardware["硬件层"]
PS["处理系统 (ARM/x86)"]
PL["可编程逻辑 (FPGA)"]
AIE["AI Engine 阵列"]
end
Languages --> Interop
Interop --> Hardware
C_Host --> XRT
Python --> XRT
HLS_Cpp --> Vitis_Link
RTL --> Vitis_Link
AIE_Cpp --> AIE_Interface
XRT --> PS
Vitis_Link --> PL
AIE_Interface --> AIE
PL <--> AIE
PS <--> PL
PS <--> AIE
多语言协作机制
- 主机与硬件交互：
- C/C++ 主机通过 XRT C API 加载
.xclbin、调用内核、管理内存 - Python 主机通过 XRT Python Binding 实现相同功能
- C/C++ 主机通过 XRT C API 加载
- HLS 与 RTL 内核混合集成：
- 通过 Vitis 链接器将 HLS 内核和 RTL 内核打包到同一个
.xclbin中 - 通过
.cfg配置文件声明内核实例和连接关系
- 通过 Vitis 链接器将 HLS 内核和 RTL 内核打包到同一个
- AIE 与 PL 交互：
- AIE 阵列通过 AXI4-Stream 或 AXI4-MM 接口与 PL 逻辑通信
- AIE Graph C++ 代码声明接口连接关系，由
aiecompiler编译实现
5. 开发工作流
Vitis-Tutorials 的典型开发工作流包括环境初始化、硬件构建、主机代码构建和运行测试四个核心环节。
flowchart TD
subgraph Env_Init["环境初始化"]
A["克隆仓库"]
B["激活 Vitis 环境"]
C["激活 XRT 环境"]
end
subgraph HW_Build["硬件构建"]
D["进入 hw_src 目录"]
E["修改 Makefile 中的 PLATFORM 变量"]
F["执行 make 构建 xclbin"]
end
subgraph SW_Build["主机代码构建"]
G["进入 sw_src 目录"]
H["执行 CMake 配置"]
I["执行 make 构建主机可执行文件"]
end
subgraph Test["运行测试"]
J["硬件仿真 (hw_emu)"]
K["硬件执行 (hw)"]
end
Env_Init --> HW_Build
HW_Build --> SW_Build
SW_Build --> Test
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
I --> J
I --> K
常用命令示例
1. 环境初始化
# 克隆仓库
git clone https://github.com/Xilinx/Vitis-Tutorials.git
cd Vitis-Tutorials
# 激活 Vitis 环境
source /opt/Xilinx/Vitis/2022.2/settings.sh
# 激活 XRT 环境
source /opt/xilinx/xrt/setup.sh
2. 硬件构建（以 Hardware_Acceleration/Design_Tutorials/10-get_moving_with_alveo 为例）
# 进入硬件源目录
cd Hardware_Acceleration/Design_Tutorials/10-get_moving_with_alveo/design_src/hw_src
# 修改 Makefile 中的 PLATFORM 变量（如果需要）
# PLATFORM := /path/to/your/platform.xpfm
# 构建硬件仿真 xclbin
make TARGET=hw_emu
# 构建硬件 xclbin
make TARGET=hw
3. 主机代码构建
# 进入软件源目录
cd ../sw_src
# 创建构建目录
mkdir build && cd build
# CMake 配置
cmake ..
# 构建主机可执行文件
make
4. 运行测试
# 硬件仿真
export XCL_EMULATION_MODE=hw_emu
./host_executable alveo_examples.xclbin
# 硬件执行
unset XCL_EMULATION_MODE
./host_executable alveo_examples.xclbin
总结
Vitis-Tutorials 是一个结构清晰、异构多语言的 FPGA/AI Engine 开发教程集合，采用分层抽象的设计理念，通过声明式配置和统一工具链实现了复杂异构系统的可复现构建。其核心特点包括：
- 清晰的目录结构：按功能域划分顶层模块，每个模块包含设计教程和功能教程
- 多阶段异构构建流程：涵盖硬件内核、AI Engine、主机代码和系统链接四个核心阶段
- 工具链与平台为核心的依赖管理：通过环境脚本和声明式配置管理依赖
- 完善的多语言协作机制：通过 XRT 和 Vitis 统一工具链实现 C/C++、RTL、Python 和 AIE Graph C++ 的互操作
- 清晰的开发工作流：从环境初始化到运行测试的完整流程，配有详细的命令示例