FPGA 与数字 IC 设计 / 系统课时
整理检查结果与可复现交付记录
整理检查结果与可复现交付记录
双时钟流式统计模块完成 RTL 实现和仿真后,还需要把源码、测试平台、运行脚本、检查结果与未解决风险整理成可复现实验包。最终交付应允许另一位工程师在干净环境中执行一条命令,得到可追溯的通过或失败结果,而不依赖开发者本机的临时文件。
学习目标
- 整理包含 RTL、测试平台、自动化脚本和验证记录的最小交付目录。
- 编写可重复执行的回归脚本,并保留工具版本、源码版本与运行日志。
- 使用交付检查表确认测试覆盖情况、残余风险和验收条件。
冻结交付内容与验收边界
以一个包含异步 FIFO、统计累加器和 ready-valid 输出接口的双时钟模块为例。假设模块在写时钟域接收 8 位事件,在读时钟域统计事件数量,并在下游允许时输出统计快照。
交付前先冻结本次验证的范围,避免把“仿真通过”误解为“所有硬件风险已经消除”。
| 检查项目 | 本次验收条件 | 交付证据 |
|---|---|---|
| RTL 编译 | 无编译错误 | compile.log |
| 基本功能 | 输入事件与参考模型结果一致 | regression.log |
| 异步时钟 | 至少覆盖两组不同周期组合 | 测试参数与日志 |
| 背压处理 | ready=0 时有效输出保持稳定 | 断言结果 |
| 复位恢复 | 两侧复位后无旧数据误输出 | 复位测试记录 |
| FIFO 边界 | 覆盖空、满及边界读写 | 覆盖报告 |
| 综合检查 | 无意外锁存器或不支持的结构 | 综合报告 |
| 时序检查 | 已声明时钟和接口约束,检查违例 | STA 报告 |
这里的检查项目是交付示例,不代表所有结果已经通过。特别是异步 FIFO 的跨时钟域安全性,不能仅凭功能仿真证明,还需要专门的 CDC 检查以及同步器实现审查。
组织可独立复现的交付目录
推荐把可编辑输入与自动生成结果分开。以下是交付目录的示例结构,文件名是本项目约定,不是 SystemVerilog 工具强制规定的名称。

建议目录包含以下文件:
rtl/:设计源码,例如async_fifo.sv、stream_stats.sv。tb/:测试平台和参考模型,例如tb_stream_stats.sv。scripts/run_regression.sh:统一编译及仿真入口。constraints/:时钟及接口约束,注明目标工具和工艺上下文。reports/:编译、仿真、综合、时序检查结果。docs/verification.md:测试矩阵、通过条件和残余风险。README.md:工具要求、执行命令和验收方法。
至少将 RTL、测试平台、脚本、约束、README 和验证说明纳入 Git。对日志和工具生成文件可采用归档产物或发布附件方式保留;不要把包含绝对路径的大型仿真缓存直接作为交付依据。
编写一条命令执行的回归脚本
下面使用 Icarus Verilog 的 iverilog 和 vvp 演示最小交付入口,适用于相关 RTL 与测试平台受 Icarus Verilog 当前版本支持的情况。假设上述三个 .sv 文件存在,测试平台顶层为 tb_stream_stats,且运行时发现错误会调用 $fatal 使进程以非零状态退出。
在项目根目录创建 scripts/run_regression.sh:
#!/usr/bin/env bash
set -euo pipefail
# 固定工作目录,避免从其他位置调用时找不到源码
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
mkdir -p "$ROOT/reports"
# 保存工具版本和源码修订版本
iverilog -V > "$ROOT/reports/tool-version.log" 2>&1
if git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
git -C "$ROOT" rev-parse HEAD > "$ROOT/reports/commit.txt"
else
printf 'NOT_A_GIT_REPOSITORY\n' > "$ROOT/reports/commit.txt"
fi
iverilog -g2012 -s tb_stream_stats \
-o "$ROOT/reports/sim.vvp" \
"$ROOT/rtl/async_fifo.sv" \
"$ROOT/rtl/stream_stats.sv" \
"$ROOT/tb/tb_stream_stats.sv" \
> "$ROOT/reports/compile.log" 2>&1
# pipefail 保证仿真失败不会被 tee 的退出码掩盖
vvp "$ROOT/reports/sim.vvp" 2>&1 | tee "$ROOT/reports/regression.log"赋予脚本执行权限并运行:
chmod +x scripts/run_regression.sh
./scripts/run_regression.sh预期结果:对于明确在全部检查成功后打印 TEST PASS 并调用 $finish 的测试平台,终端和 reports/regression.log 均会包含以下成功标记:
TEST PASS如果测试平台没有实现该成功标记,不能根据这段示例推断输出。脚本执行成功仅表示编译及仿真进程正常结束;要避免没有执行有效检查却返回零状态,应在测试平台中统计断言和参考模型检查次数,并在检查不足或超时时调用 $fatal。
脚本还应在 README 中记录实际 Icarus Verilog 版本、运行操作系统及所需扩展功能。更换为商业仿真器时,应额外记录编译选项、库映射方式和许可证依赖。
保存结果并建立可追溯记录
执行完脚本后,不要只写一句“全部通过”。应记录具体测试配置、检查结果和证据路径,以便后来复核。
可以在 docs/verification.md 中维护以下结果表。表内状态仅演示填写方式,正式交付必须依据实际运行结果替换。
| 测试 ID | 条件 | 状态示例 | 证据 |
|---|---|---|---|
| T01 | 写时钟 10ns,读时钟 14ns | PASS | regression.log |
| T02 | 写时钟 14ns,读时钟 10ns | 待运行 | 无 |
| T03 | 连续 20 拍输出背压 | 待运行 | 无 |
| T04 | 写侧复位早于读侧释放 | 待运行 | 无 |
| T05 | FIFO 满后停止写入再恢复 | 待运行 | 无 |
上表中的周期是测试配置,不表示普通脚本已经自动执行这些组合。若要声称完成 T02~T05,测试平台和运行脚本必须实际提供对应激励,并分别输出可识别的通过证据。
将脚本的退出码、工具版本、Git 提交哈希及每组测试结果对应保存。需要长期保留时,可对交付包计算 SHA-256 校验值:
sha256sum scripts/run_regression.sh rtl/*.sv tb/*.sv预期结果是每个文件各输出一行 SHA-256 摘要与文件路径,例如摘要为 64 位十六进制字符。具体哈希取决于文件内容,不能预先写死。交付方与接收方比较摘要即可检查源文件是否一致。
登记残余风险与最终验收
残余风险不是测试失败的替代说明,而是对当前证据尚不能覆盖的场景作出明确标识。建议每项至少记录风险、影响、处理动作和责任人。
| 风险 | 可能影响 | 关闭条件 |
|---|---|---|
| 未完成 CDC 静态检查 | 跨域同步结构存在遗漏 | CDC 工具报告无未解释的严重问题 |
| 未完成目标工艺 STA | 目标频率可能无法收敛 | 指定约束下建立与保持检查通过 |
| 未测试 FIFO 极端速率差 | 边界条件可能丢失事件 | 完成速率差与满空边界回归 |
| 未验证独立复位扰动 | FIFO 状态可能不同步 | 复位测试及恢复协议检查通过 |
正式验收按以下顺序进行:
- 在干净工作目录检出指定 Git 提交,确认所有输入文件齐全。
- 安装 README 指定版本的仿真工具,执行
./scripts/run_regression.sh。 - 检查脚本退出码、断言结果、参考模型检查次数和日志中的成功标记。
- 将测试矩阵逐项对照实际证据,未执行项目标为 NOT_RUN,不得算作 PASS。
- 检查综合、STA 与 CDC 报告是否来自指定目标环境,并登记尚未关闭的问题。
- 对交付版本、审查人、审查日期和是否允许进入下一阶段作出明确记录。
一个合格的交付包应能让接收方独立重建测试、定位首次失败日志,并准确判断哪些条件已经验证、哪些条件仍存在风险。只有结果可重跑、证据可对应、边界写清楚,模块才具备进入后续集成评审的条件。