Vivado 增量综合检查点错误的排查与解决

问题现象

在 Vivado 2024.2 中重新编译 ISP Pipeline IP 后，遇到以下问题：

1. 打开项目时弹出 Critical Warning：

   [Project 1-19] Could not find the file 
   '.../AI_3D_Camera.srcs/utils_1/imports/synth_1/design_1_wrapper.dcp'
   

2. 综合失败：

   [Common 17-69] Command failed: File '...design_1_wrapper.dcp' does not exist
   

3. 综合报告中的警告：

   [Synth 8-6895] The reference checkpoint ... is not suitable for use 
   with incremental synthesis for this design.
   

问题根源

Vivado 的增量综合（Incremental Synthesis）功能会保存上一次综合的检查点文件（.dcp），用于加速后续的增量编译。

问题发生原因：

1. 我清理项目时删除了 utils_1/ 目录下的检查点文件
2. 但 Vivado 项目文件 .xpr 中仍然硬编码引用了这个文件路径
3. Vivado 启动时尝试加载这个不存在的文件，导致失败

排查过程

1. 查找项目文件中的引用

grep -i "incremental\|design_1_wrapper.dcp" AI_3D_Camera.xpr

发现项目文件中有如下配置：

<Run Id="synth_1" ... AutoIncrementalCheckpoint="true" IncrementalCheckpoint="$PSRCDIR/utils_1/imports/synth_1/design_1_wrapper.dcp"AutoIncrementalDir="$PSRCDIR/utils_1/imports/synth_1"...>

关键问题：IncrementalCheckpoint="..." 这个属性硬编码了检查点文件路径。

2. 理解增量综合机制

Vivado 增量综合有两种模式：

模式	配置	行为
手动指定	IncrementalCheckpoint="具体路径"	强制使用指定的检查点，找不到就报错
自动管理	AutoIncrementalCheckpoint="true"	Vivado 自动管理，找不到就完整综合

我的项目错误地使用了手动指定模式，导致必须找到那个已删除的文件。

解决方案

编辑 .xpr 项目文件，移除硬编码的检查点路径，改用自动管理模式。

修改前（错误配置）：

<Run Id="synth_1" Type="Ft3:Synth" ... AutoIncrementalCheckpoint="true" IncrementalCheckpoint="$PSRCDIR/utils_1/imports/synth_1/design_1_wrapper.dcp"AutoIncrementalDir="$PSRCDIR/utils_1/imports/synth_1"AutoRQSDir="$PSRCDIR/utils_1/imports/synth_1"...>

修改后（正确配置）：

<Run Id="synth_1" Type="Ft3:Synth" ... AutoIncrementalCheckpoint="true" AutoIncrementalDir="$PSRCDIR/utils_1/imports/synth_1"AutoRQSDir="$PSRCDIR/utils_1/imports/synth_1"...>

关键改动：删除 IncrementalCheckpoint="..." 属性。

具体操作步骤

1. 关闭 Vivado 项目

2. 备份项目文件：

   cp AI_3D_Camera.xpr AI_3D_Camera.xpr.backup
   

3. 编辑 .xpr 文件，找到 <Run Id="synth_1" 这一行，删除 IncrementalCheckpoint 属性

4. 保存并重新打开项目

效果验证

修改后：

• ✅ 打开项目不再有 Critical Warning 弹窗
• ✅ 综合可以正常运行
• ✅ Vivado 会在第一次综合后自动生成新的检查点
• ✅ 后续的增量综合功能正常工作

关于增量综合的最佳实践

什么时候使用增量综合？

适合场景：

• 小的设计修改（改约束、改参数）
• 局部模块调试
• 反复迭代优化

不适合场景：

• 大规模 IP 更换（如本例）
• 重大架构调整
• 初次编译

推荐配置

<!-- 推荐：启用自动增量综合 -->
<Run Id="synth_1" AutoIncrementalCheckpoint="true"AutoIncrementalDir="$PSRCDIR/utils_1/imports/synth_1"...>

优点：

1. Vivado 自动判断是否适合增量综合
2. 找不到检查点时自动完整综合
3. 设计变化太大时自动回退完整综合
4. 无需手动管理检查点文件

如何禁用增量综合？

如果确定不需要增量综合，可以完全禁用：

<Run Id="synth_1" AutoIncrementalCheckpoint="false"...>

或通过 Vivado TCL Console：

set_property INCREMENTAL_CHECKPOINT "" [get_runs synth_1]
set_property AUTO_INCREMENTAL_CHECKPOINT 0 [get_runs synth_1]

清理旧的检查点文件

如果想清理增量综合产生的文件（释放磁盘空间）：

# 删除增量综合检查点
rm -rf project.srcs/utils_1/# 或在 Vivado 中
# Tools → Settings → Project Settings → Incremental Compile → Clean

总结

1. 问题根源：.xpr 文件中硬编码的检查点路径失效
2. 解决办法：移除 IncrementalCheckpoint 属性，使用自动管理模式
3. 预防措施：不要手动指定增量综合检查点路径，让 Vivado 自动管理
4. 副作用：无，修改后功能更健壮

这个问题在 Vivado 项目清理、IP 更新、项目迁移时容易遇到，掌握排查方法可以快速解决。

---

环境信息：

• Vivado 版本：2024.2
• 器件：xczu4ev-sfvc784-2-i (Zynq UltraScale+)
• 问题类型：增量综合检查点引用错误