Vitis 烧录 FPGA 失败排查指南
在 Vitis 编译成功后进行烧录操作时，若遇到程序卡住、报错或无法识别硬件的情况，通常并非软件本身故障，而是系统底层配置未到位。
一、Linux 下 USB 权限不足
为什么连不上？
在 Linux 环境下开发 FPGA 时，最常见的问题是插入了 JTAG 下载器（如 Xilinx Platform Cable USB 或 Digilent HS2），但 Vitis 无法识别设备。
原因是 Linux 出于安全考虑，默认仅允许 root 用户访问底层 USB 设备节点。JTAG 适配器作为 USB 转 JTAG 桥芯片，需要直接与 hw_server 通信。若无权限，工具将无法工作。
使用 sudo 运行 Vitis 虽可行，但会导致 GUI 权限混乱、日志路径异常等问题。
正确做法：配置 udev 规则
Linux 提供 udev 规则机制，可自动赋予特定 USB 设备读写权限。
操作步骤如下：
# 创建并编辑 udev 规则文件
sudo nano /etc/udev/rules.d/90-xilinx-jtag.rules
将以下内容粘贴进去：
# Xilinx Platform Cable USB
SUBSYSTEM=="usb", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0008", MODE="0666", GROUP="dialout"
# Digilent HS2 / HS3
SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0666", GROUP="dialout"
# Common third-party FT2232-based JTAG cables
SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", MODE="0666", GROUP="dialout"
说明：
- idVendor 和 idProduct 是 USB 设备的唯一标识，可通过 lsusb 命令查看。
- MODE="0666" 表示所有用户可读写。
- GROUP="dialout" 确保加入串口组。
保存后，重新加载 udev 规则：
sudo udevadm control --reload-rules
sudo udevadm trigger
然后拔掉 JTAG 线再重新插入。此时执行：
ls -l /dev/bus/usb/** | grep -i "03fd\|0403"
应能看到相关设备节点的权限变为 crw-rw-rw-，且属于 dialout 组。
小贴士：如果不确定自己的 JTAG 设备 ID，插拔前后各跑一次 lsusb，对比新增项即可定位。
二、JTAG 链路中断排查
即使权限正常，仍可能遇到'设备不在链上'的提示。此时需检查 JTAG 链本身的通路是否完整。
JTAG 依靠四根核心信号线工作：TCK（时钟）、TMS（模式选择）、TDI（数据输入）、TDO（数据输出）。多个芯片串联成一条链，主机依次发送指令进行测试或编程。
当 Vitis 尝试连接时，通过 hw_server 向 JTAG 链发查询命令，等待目标返回 IDCODE。如果收不到响应，则判定为无设备。
常见故障点：
| 故障原因 | 表现 | 解法 |
|---|---|---|
| TDO 未接通或虚焊 | 链上设备数为 0 | 用万用表测 TDO 连通性 |
| FPGA 未上电或复位中 | IDCODE 无法读取 | 检查电源和 PROG_B 引脚 |
| 多器件链顺序错乱 | 识别出错的 IDCODE | 核对 BSDL 文件与拓扑结构 |
| TCK 频率过高 | 超时或 CRC 错误 | 在 Vitis 中降低 JTAG clock 至 1MHz |
快速诊断：使用 XSDB 命令行。
打开 Vitis 自带的 Xilinx Script Debugger (XSDB)，输入以下命令：
connect targets
正常情况下会看到类似输出：
Available Targets: 1 xczu7ev_1 2 pl 3 psu
如果返回空列表或提示 connection failed，说明 JTAG 链层面出了问题。
特别注意：Zynq/Zynq UltraScale+系列中，PL 侧的 JTAG 访问有时依赖 PS 侧先启动。某些板子需要先烧录 FSBL 或运行 BOOT.BIN 才能激活 JTAG 路径。如果你的板子是 SD 卡启动模式，请确保至少能完成一级引导。
三、供电稳定性检查
电源是容易被忽视的关键环节。FPGA 在配置阶段非常耗电。以 Kintex-7 为例，其配置期间的核心电压瞬态电流可达 1.5A 以上。
典型症状包括：编程中途突然中断、CRC 校验失败、FPGA 反复重启、板载 LED 闪烁异常。
判断方法：拿个万用表，测一下 VCCINT、VCCAUX、VCCO 这几个关键电源轨的电压波动情况。
理想状态下，它们应在标称值±5% 以内。如果发现电压在配置瞬间明显下跌，基本可以确定是电源问题。
工程师实战建议：
- 优先使用外接稳压电源，而不是依赖 PC 的 USB 口供电；
- 加装去耦电容：靠近 FPGA 的电源引脚并联 0.1μF 陶瓷电容 + 10μF 钽电容；
- 避免长导线供电：电阻会导致压降；
- 检查上电顺序：部分高端 FPGA 要求多电源按特定顺序上电。
真实案例：有位同事调试 Artix-7 时总出现随机配置失败，换了三次线缆都没解决。最后发现是用了劣质 USB HUB 供电，内阻太大导致电压不稳定。换上独立 5V/3A 电源后问题消失。
四、hw_server 服务状态
Vitis 点击 Program Device 时，背后真正干活的是 hw_server 后台服务程序。
工作流程：[Vitis IDE] -> [TCP, localhost:3121] -> [hw_server] -> [libusb → USB → JTAG Adapter] -> [FPGA Board]
默认情况下，Vitis 会自动拉起 hw_server。但如果端口被占用、服务崩溃或权限不足，连接就会中断。
常见问题及应对策略：
现象 1：hw_server 启动失败
查看日志文件：
cat ~/.Xilinx/hw_server.log
常见错误：
- libusb_open failed: Permission denied → 回头检查 udev 规则
- Address already in use → 3121 端口被占用，可用：
lsof -i :3121
kill -9 <pid>
手动启动服务（推荐调试时使用）：
/opt/Xilinx/Vitis/2023.2/bin/hw_server --allow-remote-clients &
添加 --allow-remote-clients 参数后，其他机器也可以通过网络连接该服务器。
连接远程服务器（跨机烧录）：
在 XSDB 中使用：
connect -host 192.168.1.100 -port 3121
注意：防火墙需放行 3121 端口，否则会被拦截。
五、实战排错流程
遇到烧录失败，按照逻辑走一遍：
- 点击 Program Device 失败？
- 查看是否有 "No hardware targets" 提示？
- 是 → 检查 udev 规则 & USB 权限 → 修复后重试
- 否 → 能否在 XSDB 中执行 connect && targets 成功？
- 否 → 检查 JTAG 物理连接、供电、TCK 频率 → 修复
- 是 → 烧录过程中超时或 CRC 错误？
- 是 → 降低 JTAG Clock（设为 1MHz）、更换优质线缆
- 否 → 检查 hw_server 是否响应？日志有无 libusb 错误？
- 是 → 重启服务、关闭冲突工具
- 否 → 可能是比特流文件问题，检查生成过程
- 成功！
六、总结
在 FPGA 开发中，软硬件协同环境的健壮性至关重要。一次成功的烧录，背后是权限管理、物理连接、电源设计、服务架构等多个环节精密配合的结果。掌握这些底层知识有助于建立系统级思维，从容应对复杂场景。下次再遇到 Vitis 烧录问题，从这四个维度逐一排查，往往比重装软件更有效。