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

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

Zynq 嵌入式 SoC 的开发不是单一工具能完成的任务，而是由三套工具链协同支撑：Vivado 负责 PL 侧逻辑设计与硬件平台导出，Vitis 负责 PS 侧裸机/RTOS 应用与异构程序构建，PetaLinux 负责 Linux 系统镜像、设备树与根文件系统的生成。三者之间存在严格的版本对应关系，一旦错配，最典型的表现是 XSA 导入失败、BSP 无法识别硬件平台、或 PetaLinux 构建时找不到匹配的硬件描述。因此，环境搭建的第一步不是“装软件”，而是先确定一条版本主线。

版本匹配：先定主线，再装工具

AMD（原 Xilinx）每年发布若干统一版本（如 2022.2、2023.1、2023.2、2024.1），同一版本号下的 Vivado、Vitis、PetaLinux 是配套发布的。推荐做法是：以 Vivado 版本为锚点，Vitis 与 PetaLinux 使用相同年份与序号。例如选择 2023.2，则安装 Vivado 2023.2、Vitis 2023.2、PetaLinux 2023.2。跨版本组合（如 Vivado 2023.2 + PetaLinux 2022.2）通常会在 petalinux-config --get-hw-description 阶段报硬件描述解析错误，或生成的设备树与 PL 逻辑不匹配。

另一个关键约束是操作系统。Vivado/Vitis 2023.2 官方支持 Ubuntu 20.04/22.04 LTS、RHEL 8 等；PetaLinux 对宿主机的依赖包要求更严格，缺 libtinfo5、gawk、chrpath、socat 等会导致构建中途失败。建议在虚拟机或独立分区中固定一个已验证的 Ubuntu 22.04 环境，避免与日常开发环境混用。

安装顺序与关键操作

推荐按 Vivado → Vitis → PetaLinux 的顺序安装。Vivado 安装时选择“Vivado ML Standard”或“Vivado ML Enterprise”，勾选 Zynq-7000、Zynq UltraScale+ MPSoC 器件系列；Vitis 可在同一安装器中勾选，也可单独安装。安装完成后，在 ~/.bashrc 中 source 设置脚本：

source /tools/Xilinx/Vivado/2023.2/settings64.sh
source /tools/Xilinx/Vitis/2023.2/settings64.sh
source /tools/Xilinx/PetaLinux/2023.2/settings.sh

PetaLinux 安装后需执行 petalinux-util --webtalk off 关闭数据上报，并确认 petalinux-config 能正常启动。若报 /bin/sh is not bash，需将系统默认 shell 切换为 bash。

板级支持包获取

BSP 分两类。第一类是官方开发板 BSP，如 ZCU104、ZCU102、PYNQ-Z2 等，可从 AMD 官网下载对应版本的 BSP 包，或在 Vitis 新建平台工程时直接选择内置 BSP。第二类是自研板 BSP，没有现成包，必须由硬件工程师在 Vivado 中完成 Block Design、约束与实现后导出 XSA，再在 Vitis 中通过“Create Platform Project → Import XSA”生成自定义平台。PetaLinux 侧则用 petalinux-config --get-hw-description=./xsa_dir 读取同一份 XSA，自动生成 system-user.dtsi 与 pl.dtsi 骨架。

自研板首次导入 XSA 后，务必检查设备树中 PS 时钟频率、DDR 型号、UART 基地址是否与原理图一致。这些参数若与硬件不符，Linux 可能在内核启动阶段挂死，且串口无任何输出。

许可证配置

Vivado/Vitis 的 License 分两种模式。WebPACK 免费版对 Zynq-7000 与部分 Zynq UltraScale+ 器件足够，安装时登录 AMD 账号即可自动获取。若使用更大器件或需要逻辑分析仪 ILA 高级功能，则需浮动 License：在 License 服务器上运行 lmgrd，客户端设置环境变量 XILINXD_LICENSE_FILE=2100@license_server_ip，并用 lmutil lmstat -a -c 2100@ip 确认签出状态。PetaLinux 基于开源工具链，不需要 License，但需确保网络可访问其依赖源。

工程目录组织与版本管理

三套工具默认生成的目录结构差异很大，若不加整理，后期维护会非常混乱。建议在项目根目录下按职责划分：hw/ 存放 Vivado 工程与 XSA，sw/ 存放 Vitis 工作区与应用源码，os/ 存放 PetaLinux 工程，bsp/ 存放第三方 BSP 与自定义平台，scripts/ 存放构建与烧录脚本，docs/ 存放硬件手册与版本记录。

版本管理方面，Vivado 工程中的 .jou、.log、.str 以及 Vitis 的 .metadata、PetaLinux 的 build/、images/ 均不应纳入 Git。推荐在根目录放置统一的 .gitignore，只跟踪源码、约束、配置文件与脚本。对于 XSA 这类二进制产物，可用 Git LFS 管理，并在提交信息中记录对应的 Vivado 工程版本号与导出时间，确保硬件与软件版本可追溯。

不要将 PetaLinux 的 build/ 目录提交到 Git。该目录体积可达数十 GB，且每次 petalinux-build 都会重建，提交后既拖慢仓库又无法有效复用。

环境验证清单

安装完成后，按以下顺序验证：执行 vivado -version 确认版本号；执行 vitis -version 确认 Vitis 可用；执行 petalinux-version 确认 PetaLinux 版本；用官方 BSP 新建一个最小平台工程，跑通“导出 XSA → Vitis 建应用 → 生成 BOOT.BIN”的完整链路；再用 PetaLinux 对同一 XSA 执行一次 petalinux-build，确认能生成 image.ub。四步全部通过，说明工具链版本匹配、License 有效、BSP 可用，环境搭建完成。