📚 课程目录第3章开发环境搭建与工具链

3. 开发环境搭建与工具链

Kria KV260 上的实时视频分析系统并不是在板卡上“写代码”完成的，而是在一台 x86 主机上完成大部分设计、编译与打包，再通过部署与远程调试把结果推到板卡上运行。因此本节的核心是理清一条完整的工具链：Vivado 负责硬件平台，Vitis 负责加速应用与主机程序，PetaLinux 负责嵌入式 Linux 镜像与根文件系统，Kria App Store 提供可复用的参考设计，Ubuntu 桌面镜像提供板端运行与调试环境，交叉编译与远程调试则把主机与板卡连成一体。理解这条链上每个工具的输入输出，比记住安装命令更重要。

3.1 工具链的分工与数据流

先建立整体认识。Vivado 的产物是 .xsa 硬件描述文件，它描述了 PS（Processing System）配置、PL（Programmable Logic）中的加速 IP、时钟与中断连接。Vitis 以 .xsa 为输入，生成平台（platform），再在其上构建应用：既包括运行在 PS 上的主机程序（host），也包括运行在 PL 加速器上的 kernel。PetaLinux 则从同一份硬件描述出发，生成 BOOT.BIN、image.ub 以及根文件系统，负责把 Linux 跑起来。Kria App Store 中的固件（如 kria-vitis-platforms、kv260-smartcam）本质上是官方已经打包好的平台与参考应用，可以直接作为起点，避免从零搭建。

3.2 主机侧环境准备

推荐使用 Ubuntu 20.04 LTS 或 22.04 LTS 作为主机系统，内存至少 16 GB，磁盘预留 200 GB 以上，因为 Vivado 与 Vitis 的安装体积很大。安装时选择 Vitis Unified Software Platform 即可，它已经包含 Vivado、Vitis HLS、Vitis Analyzer 等组件，无需单独再装 Vivado。安装完成后，通过 source /tools/Xilinx/Vitis/2022.2/settings64.sh 把工具加入当前 shell 环境，并确认 vivado -version、vitis -version 能正常输出。

PetaLinux 需要单独安装，它依赖一批主机软件包。典型安装命令如下：

sudo apt install -y gcc g++ make git python3 python3-pip \
  libncurses5-dev libssl-dev flex bison texinfo zlib1g-dev \
  libglib2.0-dev libgl1-mesa-dev libsdl1.2-dev

# 安装 PetaLinux
./petalinux-v2022.2-10141622-installer.run --dir /tools/Xilinx/petalinux
source /tools/Xilinx/petalinux/settings.sh
echo $PETALINUX   # 应输出安装路径

Kria App Store 的固件通过 apt 或官方页面获取。以 KV260 为例，安装 kria-vitis-platforms 后，平台文件会出现在 /opt/xilinx/platforms/ 下，Vitis 创建工程时可直接选择，省去自己从 .xsa 生成平台的步骤。

3.3 交叉编译环境配置

板卡是 aarch64 架构，主机是 x86_64，因此主机上编译出的程序不能直接在板卡运行，必须使用交叉编译工具链。PetaLinux 自带 aarch64-linux-gnu- 前缀的工具链，也可以使用 Ubuntu 的 gcc-aarch64-linux-gnu。关键是要让编译器找到板端头文件与库，即 sysroot。sysroot 可以从 PetaLinux 生成的 rootfs 中导出，也可以直接使用 SDK 中的 sysroots/aarch64-xilinx-linux。

使用 CMake 时，最稳妥的方式是写一个 toolchain file，而不是在命令行里堆参数：

# aarch64-toolchain.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER   aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_SYSROOT /opt/petalinux/sysroots/aarch64-xilinx-linux)
set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

配置完成后，用 cmake -DCMAKE_TOOLCHAIN_FILE=aarch64-toolchain.cmake .. 生成构建文件，再 make。验证是否真的交叉编译成功，可以执行 file ./your_app，输出中应出现 ARM aarch64；如果显示 x86-64，说明工具链没有生效。

3.4 远程调试环境

主机与板卡之间通常通过以太网连接。板卡启动 Ubuntu 桌面镜像后，用 ip addr 查看地址，例如 192.168.1.50。主机侧先确认连通性：ping 192.168.1.50，再用 scp 把可执行文件与 .xclbin 传到板卡：

scp ./video_analyzer ubuntu@192.168.1.50:/home/ubuntu/
scp ./binary_container_1.xclbin ubuntu@192.168.1.50:/home/ubuntu/

调试分两个层次。应用层用 gdbserver：板卡上执行 gdbserver :9090 ./video_analyzer，主机上在 Vitis 中新建 Debug Configuration，选择 gdb 与 gdbserver 连接方式，目标地址填 192.168.1.50:9090，即可设置断点、查看变量。硬件层则通过 Vitis Analyzer 查看 .xclbin 中的 kernel 时序与资源占用，或通过 XRT 的 xbutil examine 确认加速器是否被正确加载。

判断环境是否真正就绪，可以按以下顺序快速自检：vivado -version 与 vitis -version 正常；petalinux-util --version 正常；aarch64-linux-gnu-gcc -v 正常；板卡能 ping 通且 SSH 可登录；xbutil examine 能列出设备。五项都通过，说明工具链已经打通。

3.5 常见问题与排查

交叉编译最常见的失败是找不到头文件，例如 fatal error: xrt.h: No such file or directory，这通常是 sysroot 路径写错或没有把 XRT 的头文件放进 sysroot。解决方法是确认 CMAKE_SYSROOT 指向的目录下确实存在 usr/include/xrt。另一个常见问题是板卡上运行时报 Failed to load xclbin，需要检查 .xclbin 是否与当前平台匹配，以及 /lib/firmware/xilinx/ 下是否有对应的固件目录。远程调试连不上时，先确认板卡防火墙没有拦截 9090 端口，再确认 gdbserver 是否真的在监听。