📚 课程目录第3章 Vivado 与 Vitis 工具链搭建

3. Vivado 与 Vitis 工具链搭建

Kria 系列（K26、K24、KV260、KR260 等）本质上是“量产级 SoM + 载板”的形态，其 PL 端资源规模、PS 端外设映射、启动链路与普通开发板存在明显差异。因此，Vivado 与 Vitis 的工程搭建不能沿用“先建 RTL 工程再补约束”的随意做法，而应围绕器件选型、板级文件、IP 集成方式与版本管理四条主线来组织。本节以 KV260（器件 xck26-sfvc784-2LV-c）为例，说明一条可复现的工具链搭建路径。

一、器件与板级配置：先定“目标”，再建工程

Kria 的 PL 逻辑资源与 PS 侧 DDR、时钟、MIPI、以太网等接口在 Vivado 中通过 board_part 描述。若只选器件而不加载板级文件，Vitis 在生成平台时会缺少 PS 配置与接口定义，导致后续无法正确导出 XSA。推荐做法是：在 Vivado 安装目录下确认已安装 xilinx.com:kria_kv260:part0:1.3 一类的板级定义（版本号随工具版本变化），建工程时同时指定器件与 board part。

# 在 Vivado Tcl Console 中确认板级文件是否可用
get_board_parts *kria*
# 期望输出示例：
# xilinx.com:kria_kv260:part0:1.3
# xilinx.com:kria_kr260:part0:1.0

# 创建工程并绑定器件与板级
create_project kv260_pl ./kv260_pl -part xck26-sfvc784-2LV-c
set_property board_part xilinx.com:kria_kv260:part0:1.3 [current_project]

这里的关键判断依据是：get_property board_part [current_project] 返回的 board part 必须与目标载板一致。若使用 KR260，则需换成对应 board part，否则 PS 侧以太网、USB 等接口的默认约束会错位。器件速度等级 -2LV 属于低电压版本，时序约束中的电压与温度条件需与 SoM 实际工作条件保持一致，不能照搬普通 Kria 评估板的默认值。

二、IP 集成：以 PS 为锚点，PL 按接口挂载

Kria 的 PL 设计通常不是孤立 RTL，而是通过 AXI 与 PS 交互。推荐在 Block Design 中先例化 Zynq UltraScale+ MPSoC，再通过 Run Block Automation 应用板级预设，使 DDR、时钟、MIO 等按 KV260 的硬件定义自动配置。随后按功能挂载 PL IP，例如用 AXI GPIO 控制载板 LED、用 AXI DMA 搬运视频流、用 AXI SmartConnect 做多主多从互联。

一个常见的教学示例是“PL 侧 AXI GPIO 控制 KV260 载板 LED”。在 BD 中加入 AXI GPIO，配置为 1 位输出，将其 S_AXI 接入 PS 的 M_AXI_HPM0_LPD，并分配地址 0xA000_0000。地址分配后必须执行 Validate Design，确认无未连接接口、无地址冲突。此时 PL 端逻辑并不复杂，但地址映射与时钟域必须与 PS 侧一致，否则 Vitis 中读写会失败。

三、从 XSA 到 Vitis 平台：把硬件“固化”为可复用资产

Vivado 完成实现并生成 bitstream 后，通过 File → Export → Export Hardware 导出 XSA，务必勾选 Include bitstream。XSA 是硬件与软件之间的契约，包含 PS 配置、PL 逻辑、地址映射与时钟信息。Vitis 中新建 Platform 时导入该 XSA，选择 standalone domain，并勾选 FSBL、PMU firmware 等启动组件。平台编译成功后生成 .xpfm，应用工程通过它引用硬件定义。

这里有一个容易忽略的细节：Kria 的启动链依赖 PMU 与 FSBL，若平台中未包含这些组件，生成的 BOOT.BIN 无法正常引导。因此平台配置阶段应确认 Boot Components 中 FSBL、PMU、PL bitstream 均已勾选。应用工程中，通过 XGpio_Initialize 与 XGpio_DiscreteWrite 即可操作 AXI GPIO，地址由 xparameters.h 自动生成，无需手工硬编码。

# Vitis 中应用工程关键代码片段（AXI GPIO 输出）
#include "xgpio.h"
#include "xparameters.h"

XGpio gpio;
XGpio_Initialize(&gpio, XPAR_AXI_GPIO_0_DEVICE_ID);
XGpio_SetDataDirection(&gpio, 1, 0x0);   // 通道1设为输出
XGpio_DiscreteWrite(&gpio, 1, 0x1);      // 输出高电平点亮 LED

四、版本管理：让“能跑”变成“可复现”

Kria 工程涉及 Vivado 工程、BD、XSA、Vitis 平台与应用源码，若全部依赖 GUI 手工操作，换一台机器或换一个工具版本就可能无法复现。推荐将硬件侧以 Tcl 脚本形式纳入 Git：用 write_project_tcl 导出重建脚本，配合 XDC 约束与 BD 的 .bd 文件；软件侧保留 Vitis 源码、平台配置与编译脚本。XSA 与平台版本号应一一对应，例如 kv260_pl_v1.0.xsa 对应 kv260_platform_v1.0，并在 README 中记录 board_part 版本与工具版本。

建议在仓库根目录放置 build_hw.tcl 与 build_sw.sh，分别用于重建 Vivado 工程与编译 Vitis 平台/应用。这样即使 XSA 丢失，也能从脚本重新生成，避免“只有二进制、没有源”的交付风险。

不要将 .Xil、.runs、临时 bitstream、Vitis 工作区缓存提交到 Git。这些目录体积大且与机器相关，会显著拖慢克隆与协作效率。XSA 若体积较大，可使用 Git LFS 管理，但更推荐保留可重建的 Tcl 脚本。

五、结果判断与常见排障

工具链搭建是否成功，可通过四个节点判断：其一，Vivado 中 Validate Design 无错误、实现后时序无违例；其二，XSA 导出成功且包含 bitstream；其三，Vitis 平台编译生成 .xpfm 且无缺失组件；其四，应用工程编译出 .elf，与 FSBL、PMU、bitstream 打包为 BOOT.BIN 后可在 KV260 上启动，并能通过串口观察到 GPIO 状态变化。

常见问题包括：board_part 版本与载板不匹配导致 PS 外设错位；XSA 未包含 bitstream 导致 PL 无配置；平台未勾选 FSBL 导致无法启动；地址映射冲突导致 AXI 读写返回错误。排查时优先核对 board_part、XSA 内容与平台组件，再检查地址分配与时钟约束，通常能快速定位到工具链配置层的问题，而不是陷入 RTL 调试。