Zynq 实战 02|开发环境搭建:Vivado / Vitis / PetaLinux 2023.2 一次装好不踩坑
Zynq 实战 02|开发环境搭建:Vivado / Vitis / PetaLinux 2023.2 一次装好不踩坑
这是《Zynq FPGA 嵌入式系统设计实战》系列的第 2 篇。 板子:Pynq-Z2(XC7Z020-1CLG400C)。工具链:Vivado / Vitis 2023.2。 上一篇:Zynq 实战 01|架构导论:把 Zynq-7000 拆开看清楚
0. 这一篇要解决什么问题
第 01 篇把 Zynq 的架构层讲清楚了。这一篇开始动手——但在写任何一行代码之前,工具链必须能跑。
听起来很简单,实际不是。Xilinx/AMD 的工具链在 2023.2 这个版本经历了几个较大的改动:Vitis 推出了新的 Unified IDE、PetaLinux 对 Ubuntu 22.04 的支持仍然有一堆手动踩的坑。如果你直接照着官方 QuickStart 走,大概率会卡在以下某一处:
- Vivado 安装完磁盘空间爆了(不裁剪会写入 ~110GB)
- PetaLinux
petalinux-create报/bin/sh: bad interpreter(dash vs bash) petalinux-build中途挂掉提示 locale 错误- Ubuntu 22.04 上 Vivado 的
lnx64.o在找libtinfo.so.5,但系统只有libtinfo.so.6 - Pynq-Z2 插上 USB 后 Vivado Hardware Manager 找不到板子
这篇文章就是把这些坑一次说清楚。
本文不涉及:PetaLinux 实际构建 Linux 镜像(那是第 05 篇)、Vivado Block Design(第 03 篇)。
1. Vivado 2023.2:下载、裁剪安装、WebPack License
1.1 安装包选择:Web Installer 还是 Single File Download?
AMD 的下载页面(https://www.xilinx.com/support/download.html,需要登录 AMD 账号)提供两类安装包:
| 类型 | Linux 文件名示例 | 大小 | 适合场景 |
|---|---|---|---|
| Web Installer | Xilinx_Unified_2023.2_1013_2256_Lin64.bin | ~280 MB | 有稳定网络,安装时在线下载组件 |
| Single File Download (SFD) | Xilinx_Unified_2023.2_1013_2256.tar.gz | ~110 GB(全量) | 离线环境、多台机器部署 |
| Windows Web Installer | Xilinx_Unified_2023.2_1013_2256_Win64.exe | ~330 MB | Windows 同理 |
推荐用 Web Installer,原因:SFD 全量包就算下载下来,安装时如果不做裁剪,最终安装目录也要占 ~110GB;Web Installer 可以在安装向导里按需勾选,最终磁盘占用差异是一样的,但下载本身快得多。
🚧 避坑:在下载页面注意选 2023.2 而不是最新版。Xilinx 工具链版本与 PetaLinux 版本必须严格对应——PetaLinux 2023.2 只能配合 Vivado/Vitis 2023.2 使用,不能混用,否则
.xsa格式不兼容(UG1144 Appendix B 有明确说明)。
1.2 安装组件裁剪——省 70GB 的关键一步
如果你在 Ubuntu 22.04 上安装,先赋权执行:
chmod +x Xilinx_Unified_2023.2_1013_2256_Lin64.bin
sudo ./Xilinx_Unified_2023.2_1013_2256_Lin64.bin
弹出图形安装向导后,到”Select Products to Install”步骤,只勾选以下内容,其余全部取消:
✅ Vivado ML Standard Edition (包含 Vitis,不用额外勾 Vitis)
└── Device Support
✅ SoCs → Zynq-7000 (我们要的)
❌ Zynq UltraScale+ MPSoC (不需要,省 ~15 GB)
❌ Versal (不需要,省 ~20 GB)
❌ UltraScale / UltraScale+ (不需要,省 ~25 GB)
❌ 7 Series (non-Zynq) (可选加,如果你有纯 FPGA 项目)
└── Design Tools
✅ Vivado Design Suite
✅ Vitis Unified Software Platform
❌ Model Composer (Matlab 相关,不需要)
└── Engineering Sample Devices → ❌ 全部取消
裁剪后的安装大小约为 30–38 GB,安装时间在 SSD 上大约 40–60 分钟。
安装路径推荐:
- Linux:
/tools/Xilinx(不要用/opt/Xilinx,某些发行版/opt下权限会有问题) - Windows:
C:\Xilinx(路径里不要有空格、中文、括号)
1.3 Ubuntu 22.04 上的 libtinfo5 问题
Vivado 2023.2 的部分二进制是较老的 glibc 编译的,链接的是 libtinfo.so.5,但 Ubuntu 22.04 只提供 libtinfo.so.6。安装完 Vivado 后第一次运行可能报:
error while loading shared libraries: libtinfo.so.5: cannot open shared object file
修复方法——先启用 universe 仓库再安装:
sudo add-apt-repository universe
sudo apt update
sudo apt install -y libtinfo5 libncurses5 libncurses5-dev
Ubuntu 22.04 的 universe 仓库里有这两个包的向下兼容版本,安装后 Vivado 就能正常启动。
1.4 WebPack License——不用花一分钱
很多教程还在讲申请 Evaluation License。实际上 Vivado 2023.2 的 ML Standard Edition(原 WebPack)对 Zynq-7000 全系列都是免费的,不需要 License 文件。
启动 Vivado 后:
Help → Manage License...
→ Get Free ISE WebPACK, ISE/Vivado IP or PetaLinux License
→ 选 "Vivado ML Standard"
→ Acquire License Online(需要 AMD 账号登录)
License 会直接绑定到你的账号,Vivado 联网验证一次后就会缓存到 ~/.Xilinx/ 目录,之后离线也能用。
🚧 避坑:Vivado ML Standard 对 Zynq-7000 没有任何功能限制——不限 LUT 数量,不限 IP 核,IP 导出也不加水印。唯一的限制是不能综合/实现 UltraScale+ 和 Versal 器件。如果你只做 Zynq-7000,完全够用。
1.5 Windows 路径额外注意
如果你在 Windows 上安装,PetaLinux 是不支持 Windows 的(只支持 Linux),但 Vivado / Vitis 本身可以在 Windows 上用。有一个实际坑:
Vivado 的 Tcl 脚本里大量使用 / 路径分隔符,对 \ 处理不一致。建议在 Windows 上始终用正斜杠,避免路径里有空格(Program Files 就会出问题),实在不行就安装到 C:\Xilinx。
2. Vitis 2023.2:Unified IDE 还是 Classic?
2.1 两者的区别
Vitis 在 2023.2 里存在两种模式:
| 模式 | 入口 | 底层 | 适合场景 |
|---|---|---|---|
| Vitis Unified IDE | vitis 命令 | 基于 Eclipse Theia(类 VSCode) | Versal、Zynq MPSoC 新工程;AI 推理加速 |
| Vitis Classic | vitis -classic 命令 | 传统 Eclipse | Zynq-7000 裸机 / FreeRTOS;旧版 SDK 工程迁移 |
AMD 的官方路线图是未来逐步废弃 Classic,全面迁移到 Unified。但截至 2023.2,对于 Zynq-7000(不是 MPSoC),有一个不得不说的现实:
- Vitis Unified IDE 的 Zynq-7000 支持并不完整——主要功能(FSP、BSP 管理、调试器集成)在 Unified 模式下针对 Zynq-7000 仍然存在若干 bug 和文档缺失
- Vitis Classic 对 Zynq-7000 工程流程最稳定——从 Vivado 导出
.xsa到创建 Platform、BSP、Application,整套流程完全畅通
结论:本系列 PS 端软件开发统一用 vitis -classic。
🚧 避坑:如果你在 2023.2 里用 Vitis Unified IDE 打开一个 Zynq-7000 baremetal 工程,会看到有些菜单选项变灰,“Create New Platform”向导跑到一半报 BSP 生成失败。这不是你的问题——是工具的问题。用
vitis -classic就正常了。
2.2 Vitis 的环境初始化
安装 Vivado 时 Vitis 一起安装,环境 setup 脚本是同一个:
# Linux - 加入 ~/.bashrc 或手动 source
source /tools/Xilinx/Vitis/2023.2/settings64.sh
# 验证
which vitis # 应该输出 /tools/Xilinx/Vitis/2023.2/bin/vitis
which vivado # 应该输出 /tools/Xilinx/Vivado/2023.2/bin/vivado
3. PetaLinux 2023.2:Ubuntu 22.04 上的五个真实坑
这一节是整篇文章信息密度最高的地方。PetaLinux 官方支持 Ubuntu 18.04 / 20.04 / 22.04,但 22.04 上默认的一些配置与 PetaLinux 预期不符,会导致奇怪的构建失败。
3.1 安装包
从 AMD 官网下载(同样需要账号登录):
petalinux-v2023.2-10121855-installer.run (约 14 GB)
这个文件名里的
10121855是 build 编号,官方页面有时只列版本号;点进去 “PetaLinux Tools” 区域能找到.run文件。
安装到非系统目录,不要用 root 安装:
chmod +x petalinux-v2023.2-10121855-installer.run
./petalinux-v2023.2-10121855-installer.run --dir /tools/petalinux/2023.2
# 同意 License → 等待解压 (10-20 分钟)
安装路径中不能有空格。/tools/petalinux/2023.2 是个好选择,跟 Vivado 的 /tools/Xilinx/ 并排放清晰。
3.2 坑 ①:dash vs bash(最常见的失败原因)
Ubuntu 22.04 默认把 /bin/sh 指向 dash(Debian Almquist Shell),而 PetaLinux 的大量 build 脚本需要 /bin/sh 是 bash。当你运行 petalinux-build 时,如果 shell 是 dash,会报:
[ERROR] Failed to build project
/bin/sh: 1: source: not found
或者:
Syntax error: "(" unexpected
修复方法(一次性,永久生效):
sudo dpkg-reconfigure dash
# 弹出对话框:Install dash as /bin/sh? → 选 <No>
# 之后 /bin/sh 会指向 bash
验证:
ls -la /bin/sh
# 应该显示 /bin/sh -> bash,而不是 dash
3.3 坑 ②:locale 必须是 en_US.UTF-8
PetaLinux 的 Yocto 构建系统对 locale 非常敏感。如果你的系统 locale 是 C、POSIX 或者中文(zh_CN.UTF-8),petalinux-build 会在 bitbake 阶段报类似:
ERROR: OE-core's bitbake requires a locale that supports UTF-8
修复:
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8
# 注销重新登录,或者 source:
source /etc/default/locale
# 验证
locale
# 应该显示 LANG=en_US.UTF-8
🚧 避坑:如果你设置了
LANG=zh_CN.UTF-8,不要改系统全局 locale(会影响你用中文的其他工具)。只在 PetaLinux 工作的 terminal session 里 export:export LANG=en_US.UTF-8 export LC_ALL=en_US.UTF-8 source /tools/petalinux/2023.2/settings.sh或者写进一个
petalinux-env.sh脚本,每次开工前 source 一下。
3.4 坑 ③:libtinfo5 和其他缺包
Ubuntu 22.04 和 PetaLinux 需要的完整依赖包列表。这是官方文档(UG1144 v2023.2 Table 2)加上实际跑通后补充的:
# 先启用 universe 仓库(libtinfo5 / libncurses5 在这里)
sudo add-apt-repository universe
sudo apt update
# 基础构建工具
sudo apt install -y \
gcc g++ make cmake git-core \
build-essential autoconf automake libtool \
gcc-multilib g++-multilib
# PetaLinux 必须的运行时库
sudo apt install -y \
libtinfo5 libncurses5 libncurses5-dev \
zlib1g-dev libssl-dev libffi-dev
# Yocto / bitbake 依赖
sudo apt install -y \
chrpath socat gawk flex bison texinfo \
diffstat xterm screen pax unzip cpio \
python3 python3-pip python3-pexpect \
python3-jinja2 python3-git python3-subunit \
python3-setuptools python3-yaml
# 网络工具(PetaLinux 测试阶段用)
sudo apt install -y \
iproute2 net-tools tftpd-hpa nfs-kernel-server
# 杂项
sudo apt install -y \
wget curl rsync expect lsb-release file
🚧 避坑:Ubuntu 22.04 删掉了
python3-distutils(把功能并入了setuptools)。如果你遇到ModuleNotFoundError: No module named 'distutils',安装python3-setuptools解决。
3.5 坑 ④:tftp 配置(板子网络调试必须)
PetaLinux 开发流程里经常要通过 TFTP 把内核/ramdisk 传给板子。Ubuntu 22.04 的 tftpd-hpa 默认配置需要调整:
sudo nano /etc/default/tftpd-hpa
改成:
TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/var/lib/tftpboot"
TFTP_ADDRESS=":69"
TFTP_OPTIONS="--secure --create"
然后:
sudo mkdir -p /var/lib/tftpboot
sudo chmod 777 /var/lib/tftpboot
sudo systemctl restart tftpd-hpa
sudo systemctl enable tftpd-hpa
3.6 坑 ⑤:安装目录权限和 source 顺序
PetaLinux 的 settings.sh 必须在每次新 shell 会话里 source:
source /tools/petalinux/2023.2/settings.sh
输出应该是:
PetaLinux environment set to '/tools/petalinux/2023.2'
WARNING: /bin/sh is not bash! ← 如果你还没改 dash 会报这个
INFO: Checking free disk space
INFO: Checking installed tools
INFO: Checking installed development libraries
INFO: Checking network and other services
把 source 命令加到 ~/.bashrc 不是个好主意——PetaLinux 的环境变量会污染 Vivado 的路径(两者都会修改 PATH)。更好的做法是写两个小脚本,按需 source。
4. USB-JTAG Cable Drivers 安装
Pynq-Z2 板子上集成了 Digilent 的 FTDI 芯片做 JTAG/UART 桥。你需要安装两层驱动:
- Xilinx Cable Drivers(Vivado 内置,对应 Xilinx 原生 JTAG)
- Digilent Adept Runtime(对应 Digilent 的 FTDI 芯片初始化)
4.1 安装 Xilinx Cable Drivers
Vivado 安装完后自带安装脚本:
sudo /tools/Xilinx/Vivado/2023.2/data/xicom/cable_drivers/lin64/install_script/install_drivers/install_drivers
这个脚本会写 udev 规则到 /etc/udev/rules.d/52-xilinx-ftdi-usb.rules 和 52-xilinx-pcusb.rules。
4.2 安装 Digilent Adept Runtime
Pynq-Z2 用的 onboard JTAG 是 Digilent 的,需要额外安装 Adept:
# 下载 Digilent Adept Runtime(从 digilent.com/reference/software/adept)
# 下载得到 digilent.adept.runtime_2.27.9-amd64.deb(版本号以官网为准)
sudo dpkg -i digilent.adept.runtime_2.27.9-amd64.deb
sudo dpkg -i digilent.adept.utilities_2.4.4-amd64.deb # 可选,包含 djtgcfg 工具
4.3 让 udev 规则生效
安装完两层驱动后:
sudo udevadm control --reload-rules
sudo udevadm trigger
# 把当前用户加入 dialout 组(不加的话 Vivado 要用 sudo 才能访问 JTAG)
sudo usermod -a -G dialout $USER
sudo usermod -a -G plugdev $USER
# 注销重新登录,或者:
newgrp dialout
🚧 避坑:如果你是 VM(VirtualBox / VMware)用的 Ubuntu,USB JTAG 直通是个额外的坑——需要在 VM 设置里把 USB 设备(Digilent USB Device)添加到 passthrough 列表,而且每次插板子都要在 VM 里手动捕获。如果可以的话,原生 Ubuntu 比 VM 里舒服得多。
5. Pynq-Z2 上电与第一次 xsdb 握手
5.1 板子配置
Pynq-Z2 有一个启动模式跳线 JP4(靠近 SD 卡槽):
JP4 跳线位置(从上到下,1-2-3 pin):
短接 1-2:JTAG 启动(调试最方便,PS 等待 JTAG 配置)
短接 2-3:SD 卡启动
不接: MIO 采样决定(可能随机)
第一次测试:跳线设为 JTAG 启动(JP4 短接 1-2)。
电源用板子附带的 12V/2A DC 接头,或者 USB-C 供 5V(Pynq-Z2 有板载降压,5V 也能工作,但 12V 更稳定)。
插上 USB-JTAG/UART 那条 Micro-USB 线(注意:靠近以太网口的那个 Micro-USB 是 JTAG+UART,靠近 HDMI 的那个是 USB OTG,别插错)。
5.2 验证 USB 连接
lsusb | grep -i "digilent\|ftdi\|0403"
# 应该出现类似:
# Bus 003 Device 004: ID 0403:6010 Future Technology Devices International...
# 或
# Bus 003 Device 004: ID 0403:7114 Future Technology Devices Digilent USB
如果什么都没有,先检查 USB 线和供电。
5.3 xsdb 第一次握手
# 先 source 环境
source /tools/Xilinx/Vitis/2023.2/settings64.sh
# 启动 xsdb(Xilinx System Debugger Shell)
xsdb
进入 xsdb% 提示符后:
# 连接 hw_server(默认本机 3121 端口)
xsdb% connect
tcfchan#0
# 查看 JTAG 链上的目标
xsdb% targets
1 APU
2 ARM Cortex-A9 #0 (Running)
3 ARM Cortex-A9 #1 (Running)
4 xc7z020
看到这个输出,说明:
- JTAG 链通了
- PS 已经识别(ARM Cortex-A9 ×2)
- PL 芯片识别(
xc7z020)
常用的 xsdb 调试命令:
# 切换到 CPU 0
xsdb% target 2
# 暂停 CPU
xsdb% stop
# 查看 PC 和寄存器
xsdb% rrd
# 读内存(读 OCM 首地址,验证可访问性)
xsdb% mrd 0xFFFC0000
# 恢复运行
xsdb% con
# 退出
xsdb% exit
🚧 避坑:如果
connect之后targets只显示1 DPC,什么 ARM 核都看不到,不是 Vivado 的问题,而是 hw_server 没启动或者 USB cable driver 没生效。检查:# 看看 hw_server 进程 ps aux | grep hw_server # 手动启动 hw_server & # 然后再 connect
UART 终端(用于串口通信,后面 Linux 启动必用):
# Pynq-Z2 的串口一般是 /dev/ttyUSB1(有时是 ttyUSB0,取决于插入顺序)
ls /dev/ttyUSB*
# 连接(115200 baud,8N1)
sudo screen /dev/ttyUSB1 115200
# 或
picocom -b 115200 /dev/ttyUSB1
6. 推荐项目目录结构
工具装好了,在开第一个 Vivado 工程之前,先把目录结构想清楚。Zynq 项目会同时涉及 Vivado(PL 硬件)、Vitis(PS 软件)、PetaLinux(Linux 系统)三部分,如果随手乱放,两周后回来看自己都不认识。
推荐的目录方案(以一个叫 pynqz2-demo 的项目为例):
~/Projects/pynqz2-demo/
│
├── hw/ # 所有硬件相关(Vivado)
│ ├── vivado_proj/ # Vivado 工程目录(.xpr)
│ │ ├── pynqz2_demo.xpr
│ │ └── ...
│ ├── src/
│ │ ├── bd/ # Block Design 的 TCL 重建脚本
│ │ │ └── design_1.tcl
│ │ ├── constraints/ # 约束文件 (.xdc)
│ │ │ └── pynqz2.xdc
│ │ ├── hdl/ # 自写 Verilog/VHDL
│ │ │ └── my_module.v
│ │ └── ip_repo/ # 自定义 IP 源码
│ └── export/ # 导出的 .xsa 文件
│ └── design_1.xsa
│
├── sw/ # PS 软件(Vitis Classic)
│ ├── platform/ # Vitis Platform 工程
│ └── apps/
│ ├── fsbl/ # First Stage Boot Loader(通常 Vitis 生成)
│ └── hello_world/ # 裸机应用
│
├── petalinux/ # PetaLinux 项目
│ └── pynqz2-linux/ # petalinux-create 生成的目录
│ ├── project-spec/
│ └── ...
│
├── scripts/ # 自动化脚本
│ ├── build_hw.tcl # Vivado 批处理构建脚本
│ └── setup_env.sh # 一键 source 环境
│
├── docs/ # 工程文档
│ └── block_design.png
│
└── README.md
scripts/setup_env.sh 的内容——这样每次开工只需要 source scripts/setup_env.sh:
#!/bin/bash
# setup_env.sh - 一键初始化 Zynq 开发环境
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
source /tools/Xilinx/Vitis/2023.2/settings64.sh
source /tools/petalinux/2023.2/settings.sh
echo "=== 环境初始化完成 ==="
echo "Vivado: $(which vivado)"
echo "Vitis: $(which vitis)"
echo "PetaLinux: $(which petalinux-build)"
echo "LANG: $LANG"
🚧 避坑:不要把 Vivado 工程目录(
vivado_proj/)整个放进 git。Vivado 工程目录里的.xpr文件每次打开都会更新时间戳,缓存文件(/vivado_proj/.cache/)动辄几 GB。正确做法是用write_bd_tcl把 Block Design 导出为 TCL 脚本放进 git,工程可以从 TCL 一键重建。下一篇讲 Block Design 时我会给出这个脚本的具体用法。
7. 本篇你应该带走的几个判断
- Vivado 2023.2 安装前先裁剪设备支持,只勾 Zynq-7000,磁盘占用从 110GB 降到 ~35GB
- Ubuntu 22.04 上
/bin/sh必须改成 bash,否则 PetaLinux 必挂 -
libtinfo5在 Ubuntu 22.04 的 universe 仓库里,不在 main 里 - Vitis 2023.2 对 Zynq-7000 用
vitis -classic,不要用 Unified IDE - xsdb
targets看到 Cortex-A9 ×2 + xc7z020 = JTAG 链通,环境搭建成功 - 工具版本三合一:Vivado / Vitis / PetaLinux 必须同为 2023.2
8. 下一篇预告
下一篇 《Zynq 实战 03|第一个 Block Design:PS + GPIO 点灯,从零到 Bitstream》,我们会:
- 用 Vivado 2023.2 创建第一个工程,添加 Zynq PS IP,完成 PS 配置
- 添加 AXI GPIO IP,连线,自动推断 AXI 地址
- 写约束文件(Pynq-Z2 的 LED 引脚是哪个)
- 生成 Bitstream、Export Hardware(
.xsa) - 用 Vitis Classic 写一个裸机程序点亮 LED
参考资料
| 文档号 | 名称 | 用途 |
|---|---|---|
| UG1144 | PetaLinux Tools Documentation: Reference Guide | PetaLinux 安装依赖(Table 2)、工程流程 |
| UG1400 | Vitis Unified Software Platform Documentation: Embedded Software Development | Vitis Classic vs Unified IDE 差异说明 |
| UG585 | Zynq-7000 SoC Technical Reference Manual | JTAG 接口章节(Chapter 27)、启动流程(Chapter 6) |
| DS190 | Zynq-7000 SoC Data Sheet: Overview | 器件选型,速度等级对应最高频率 |
| Digilent Reference | Pynq-Z2 Reference Manual | 跳线 JP4 定义、USB 接口位置 |
| AMD Support | Answer Record AR# 59128 | Vivado cable drivers 安装常见问题 |
这是《Zynq FPGA 嵌入式系统设计实战》系列第 2 篇。 如果你在搭环境的时候卡在某一步,欢迎留言说明 Ubuntu 版本和报错内容。