3. Versal开发环境搭建与工程创建

Versal ACAP 的工程化验证与交付，第一步不是写 RTL，而是把工具链、板级支持包、目录结构和版本控制四件事一次性定稳。Versal 与以往 FPGA 最大的不同在于它同时包含 PL（可编程逻辑）、PS（Processing System，含 Arm Cortex-A72/A78 与 R5F）以及 AI Engine，因此工具链天然是 Vivado + Vitis 的组合，而不是单一工具。本节围绕“装什么、怎么装、工程怎么摆、代码怎么管”展开，给出可直接落地的做法。

一、工具链安装：版本对齐是前提

Versal 器件支持与工具版本强绑定。以常见的 Versal AI Core / Prime 系列为例，2022.2 及以上版本对 AI Engine 与 NoC 的支持更完整，而某些早期器件（如 VC1902 ES 硅片）需要特定补丁。安装前先确认三件事：目标器件型号、是否需要 AI Engine 编译、以及是否使用 Vitis 嵌入式流程。

AMD 统一安装器（Xilinx Unified Installer）是唯一入口，Vivado 与 Vitis 在同一安装目录下共存。安装时建议选择 “Vitis Embedded Development” 与 “AI Engine” 组件，并勾选对应器件族（如 Versal AI Core VC1902、Versal Prime VM1802）。安装完成后，环境变量由安装器生成的 settings64.sh（Linux）或 settings64.bat（Windows）统一设置，不要手工拼 PATH。

# Linux 下激活工具链环境
source /tools/Xilinx/2023.2/Vivado/settings64.sh
# 验证版本与器件支持
vivado -version
vitis -version
# 检查 Versal 器件是否在已安装器件库中
ls /tools/Xilinx/2023.2/Vivado/data/parts/xilinx/versal/

一个常见坑是：Vivado 与 Vitis 版本必须完全一致，否则在导出 XSA（Xilinx Support Archive）时会出现 “platform version mismatch”。建议在团队内用同一安装镜像与同一补丁号，并把版本号写进工程 README。

二、板级支持包（BSP）与平台工程

Versal 的 BSP 概念体现在两个层面：一是 Vivado 侧的板卡文件（board file），二是 Vitis 侧的 platform 工程。板卡文件描述开发板的器件、封装、DDR、时钟与接口，安装后可在 Vivado 中直接选板。若使用自研板，需要基于 AMD 提供的板卡 XML 模板修改，或直接用 part 号建工程。

Vitis 平台工程由 XSA 生成，包含硬件描述、FSBL/PLM、PMU 固件、设备树与库。创建流程是：Vivado 导出 XSA → Vitis 新建 Platform Project → 选择 XSA → 指定 OS（standalone 或 Linux）→ 生成 BSP。BSP 中的 system.mss 记录了各外设驱动与库配置，是后续应用工程的依赖来源。

三、工程目录结构：一次定好，长期受益

Versal 工程涉及 Vivado 工程、Vitis 平台、应用代码、约束、脚本与文档，若全部塞进一个目录，版本控制会迅速失控。推荐按“源码与生成物分离”的原则组织：

versal_project/
├── hw/                     # 硬件侧
│   ├── scripts/            # tcl 建工程、综合、实现脚本
│   ├── src/                # RTL、BD tcl、XDC 约束
│   ├── constraints/
│   └── xsa/                # 导出的 XSA（生成物，可归档）
├── sw/                     # 软件侧
│   ├── platform/           # Vitis platform 工程
│   ├── app_ps/             # PS 应用（C/C++）
│   └── app_ai/             # AI Engine 图与 kernel
├── ip_repo/                # 自研 IP 仓库
├── scripts/                # 顶层构建与打包脚本
├── docs/                   # 寄存器表、接口说明
└── .gitignore

关键原则：hw/src、sw/app_*、ip_repo 进版本库；Vivado 的 .runs、.cache、.hw、.sim 以及 Vitis 的 Debug/、Release/ 一律忽略。XSA 属于可重建产物，但交付节点建议归档，便于复现。

四、版本控制策略

Versal 工程的版本控制难点在于“二进制生成物多、工具版本敏感”。建议采用 Git + 分支策略：main 保持可构建、可交付；dev 用于日常集成；功能分支以 feat/xxx 命名。每次交付打 tag，tag 名包含工具版本，例如 v1.0.0_2023.2。

必须纳入版本控制的还有：工具版本清单、XSA 的 md5、BSP 配置、约束文件、IP 的 component.xml 与源码。不要提交 IP 的 .xci 生成缓存，但 .xci 本身应提交，因为它记录了 IP 参数。对于 AI Engine，aie 图与 kernel 源码必须提交，编译产物不提交。

五、IP 仓库管理

Versal 工程常复用自研 IP 与第三方 IP。Vivado 通过 ip_repo 路径识别 IP，路径下每个 IP 目录必须包含 component.xml。推荐把 IP 仓库独立成 Git 子模块或独立仓库，按 IP 名 + 版本号组织：

ip_repo/
├── axis_dma_v1_0/
│   ├── component.xml
│   ├── src/
│   └── xgui/
└── versal_noc_bridge_v2_1/
    ├── component.xml
    └── src/

在 Vivado 中通过 set_property ip_repo_paths 注册仓库，或在工程 tcl 中统一设置。IP 升级时，版本号递增，旧版本保留，避免已交付工程因 IP 变更而无法复现。对于 AI Engine，kernel 以 kernel.json 或 graph 形式管理，建议与 PL IP 分开仓库，因为其编译流程与工具版本耦合更紧。

六、一次可复现的工程创建流程

把上述内容串成可执行流程，建议用脚本而非手工点击。以下 tcl 片段展示从建工程到导出 XSA 的关键步骤（示例参数，需按实际器件替换）：

# 1. 创建 Vivado 工程
create_project versal_demo ./hw/build -part xcvc1902-vsva2197-2MP-e-S
set_property board_part xilinx.com:vck190:part0:3.0 [current_project]

# 2. 注册 IP 仓库
set_property ip_repo_paths ./ip_repo [current_project]
update_ip_catalog

# 3. 添加 RTL 与约束
add_files -fileset sources_1 ./hw/src
add_files -fileset constrs_1 ./hw/constraints

# 4. 综合、实现、导出 XSA
launch_runs impl_1 -to_step write_bitstream -jobs 8
wait_on_run impl_1
write_hw_platform -fixed -include_bit -force ./hw/xsa/versal_demo.xsa

导出 XSA 后，在 Vitis 中新建 platform 工程并指向该 XSA，选择 standalone OS，生成 BSP。此时 sw/platform 下会出现 export 目录，应用工程通过 platform 引用它。若后续硬件变更，只需重新导出 XSA 并更新 platform，应用工程重新编译即可，无需重建整个目录。

七、交付前的检查要点

• 工具版本号是否写入 README，且与 CI 环境一致；
• XSA 是否包含 bitstream，md5 是否记录；
• BSP 的 system.mss 是否随 platform 提交；
• IP 仓库是否包含 component.xml，版本号是否递增；
• .gitignore 是否覆盖 .runs、.cache、Debug、Release；
• tag 是否包含工具版本，能否从 tag 一键重建。

做到以上几点，Versal 工程就从“能跑”进入“可复现、可交付”的状态，后续的验证与工程交付才有稳定基线。