如何准备一个可复现的问题工程

固定输入

记录 RTL commit、工具完整版本、文件清单、约束、测试名称、随机种子与启动命令。相对路径从统一工程根目录解析。外部初始化文件也属于输入，不能仅发送 RTL。

保留最早的失败证据

保存首次错误附近的日志、退出码和预期行为。先解释“期望第 100 个周期收到响应，实际超时”，再附波形。压缩案例时每删除一个模块或约束都要重跑，确认同一问题仍出现。

清理与交接

从干净目录重新执行一遍，避免依赖旧缓存。共享前去掉密钥、客户数据和无关源文件，并确认允许共享的范围。README 写清环境、一个入口命令、正常结果和已知限制。

原理与信号关系

一次可复现运行不是只有 RTL。源文件顺序、include 路径、宏、顶层参数、工具版本、存储初始化文件和输入种子都会改变展开后的设计。构建目录应与源目录分离，运行记录应能指出使用了哪个输入集合。尤其在软硬件分开编译时，两侧读到同一个参数名字不等于得到相同的值，必须保存展开配置并比较接口宽度。

动手步骤与预期结果

按下面的顺序执行，每一步都留下可复核的证据。若当前步骤的预期条件未满足，先停在该阶段定位原因；不要继续累积后续错误。涉及工具、板卡或专用硬件的步骤，需要使用本工程实际版本和配置，示例数值不能直接替代设备规格。

1. 创建只含本用例的文件清单

   预期与判定：使用工程相对路径，明确唯一顶层；从空 build 目录能够重新构建。

2. 保存输入摘要

   预期与判定：将 RTL、约束、初始化文件和测试配置纳入摘要；工具自动生成文件与密钥不纳入公开包。

3. 记录启动命令与版本

   预期与判定：保存退出码、stdout/stderr、随机种子；并行作业使用独立目录，避免覆盖 snapshot。

4. 在新目录重跑

   预期与判定：删除的仅是临时构建产物；同一输入应得到同一功能摘要，不能依赖上次遗留文件。

保存为 manifest.py，在工程根目录用 Python 3 执行；示例仅对显式文件清单求摘要。

from pathlib import Path
import hashlib
files = ["rtl/top.sv", "tb/top_tb.sv", "mem/init.hex"]
for name in files:
    p = Path(name)
    print(hashlib.sha256(p.read_bytes()).hexdigest(), name)

典型故障：从现象到复测

下面的案例是为说明定位方法而构造的教学场景，不代表真实客户事故或本平台设备实测。实践时先确认现象与证据相符，再采用相应修复；若证据不同，应回到前一步缩小范围，避免把同一种表象都归因于同一个问题。

完成检查

• 干净目录可复现
• 有预期与实际结果
• 共享包不含凭据或无关项目数据

延伸阅读与来源

本文为黄河电子原创教学说明。产品命令与支持范围请以实际安装版本的官方文档为准。

• AMD Vivado 开发者资源
• Cadence Palladium 产品资料

继续阅读