ciciec2026/doc/reports/system/REPORT_RERUN_CHECKLIST.md

系统报告复测清单

本清单用于为 system_design_report.tex 生成同一提交、可追溯的证据。不要把旧的 fpga/vivado_reports_nodsp/ 与新板级日志混合后宣称为同一版本结果。

0. 固化版本与环境

在仓库根目录执行并保存输出：

git status --short
git rev-parse HEAD
vivado -version | head -n 3
verilator --version

建议先提交当前 RTL/约束/软件变更。若工作树不干净，最终报告的证据版本无法唯一复现。

1. 必跑：RTL 静态检查

cd doc/reports/system
./tools/run_report_tests.sh lint

通过标准：命令退出码为 0，evidence/lint.log 中无 %Error。此项只证明静态可分析， 不证明 AXI、CDC 或算法功能正确。

2. 必跑：SoC 功能回归

仅编译指定软件、不运行仿真：

cd doc/reports/system
./tools/run_report_tests.sh build

需要同时运行 SoC 仿真时：

cd doc/reports/system
./tools/run_report_tests.sh soc

需要保存 VCD 时使用可选开关。默认只记录 tb_top 的时钟、复位、UART 和提交 PC， 文件写入 evidence/soc/<用例>.vcd。记录内部模块时用 VCD_SCOPE 指定层次；长时间 软件测试若递归记录整个 SoC，可能产生数 GB 文件：

SAVE_VCD=1 \
VCD_SCOPE='/tb_top/u_soc_top/u_fft_mlkem_axi_slave/u_mlkem_axi_slave/*' \
./tools/run_report_tests.sh soc

启用 VCD 后 elaboration 使用 debug_level=typical，并从 0 ns 开始记录，因此包含 上电复位和复位释放过程。只需要短窗口诊断时可额外设置 SIM_RUN_TIME=20us；该选项 会在软件完成前退出，不能作为功能回归通过证据。VCD 属于大体积临时证据，默认被 Git 忽略。

软件集合固定为 asm、fft、fft_dma、mlkem_test 和 mlkem_hello。默认 soc 会编译全部五项，但只对 mlkem_test 和 mlkem_hello 运行通用 tb_top 仿真。 asm 需要官方 ExtRAM 数据和专用 matmul 流程；fft 和 fft_dma 包含耗时很长的 软件 FFT 参考计算，因此默认只做编译检查。每次构建都会覆盖 sdk/axi_ram.mif，不要 并行执行这些用例。构建日志位于 evidence/build/。

需要更新 FFT 当前提交的功能或性能证据时，再单独执行长仿真：

./tools/run_report_tests.sh soc-fft

没有执行 soc-fft 且没有生成当前提交的板级日志时，报告中的 FFT 数值只能标记为 历史基线，不能声明为当前提交的功能回归结果。 脚本会设置 CCACHE_DISABLE=1，避免 Vivado 2019.2 在编译 XSIM 自动生成的 C 文件时 因 ccache 目录不可写而只报告不透明的 XSIM 43-3409。 同时会将 /lib64 加入 XSIM 子进程库路径，避免旧版 Vivado clang 混用不匹配的 libncurses.so.5 与 libtinfo.so.5。

逐项检查：

日志	必须出现	不得出现
evidence/build/{asm,fft,fft_dma,mlkem_test,mlkem_hello}.log	编译、链接和 objcopy 成功	Error
evidence/soc/mlkem_test.log	MLKEM_RESULT=PASS、MLKEM_DONE	任一 FAILS 非 0
evidence/soc/mlkem_hello.log	MLKEM_HELLO_RESULT=PASS、MLKEM_HELLO_DONE	RESULT=FAIL

若执行了可选的 soc-fft，再检查：

日志	必须出现	不得出现
evidence/soc/fft.log	Hardware/Software FFT Time；更新后的程序应输出 Max Abs Error	仿真超时、X/Z 扩散
evidence/soc/fft_dma.log	Hardware/Software FFT Time、Max Abs Error	DMA 死锁、仿真超时

FFT 板级验证（推荐）

FFT 的软件浮点参考在 RTL 仿真中耗时很长，默认使用板级测试作为当前提交的功能与性能 证据。使用同一提交生成的 bitstream，分别下载 fft 和 fft_dma 的程序镜像，在 115200 baud 下保存完整 UART 输出：

doc/reports/system/evidence/board/fft.log
doc/reports/system/evidence/board/fft_dma.log

fft.log 必须出现：

FFT_MAX_ABS_ERROR_RE=<不大于8>
FFT_MAX_ABS_ERROR_IM=<不大于8>
FFT_ERROR_LIMIT=8
FFT_RESULT=PASS
FFT_DONE

fft_dma.log 必须出现：

FFT_DMA_MAX_ABS_ERROR_RE=<不大于8>
FFT_DMA_MAX_ABS_ERROR_IM=<不大于8>
FFT_DMA_ERROR_LIMIT=8
FFT_DMA_RESULT=PASS
FFT_DMA_DONE

两项日志还必须保留 Hardware/Software FFT Time 和 Speedup Ratio。每项至少冷启动运行 3 次，确认结果和最大误差稳定；DMA 用例还要确认没有轮询死锁。板级日志存在时， update_report_metrics.py 会优先于 XSIM 日志读取它们。

ML-KEM 的正确计数是 3 个固定 KAT 向量、900 次执行，不是 360 个不同 KAT。若要在 报告中声称覆盖隐式拒绝，必须另外增加“篡改 ciphertext 后共享密钥不等且流程按规范 完成”的负向测试；当前脚本不提供该证据。

3. 必跑：重新布局布线与实现取证

完整实现耗时较长，单独执行：

cd doc/reports/system
./tools/run_report_tests.sh implement

该命令先从 synth_1 开始强制重跑，重新综合/布局布线并生成 bitstream，随后生成以下文件：

• evidence/vivado/timing_summary_full.rpt
• evidence/vivado/utilization.rpt
• evidence/vivado/utilization_hierarchical.rpt
• evidence/vivado/power.rpt
• evidence/vivado/clock_interaction.rpt
• evidence/vivado/cdc.rpt
• evidence/vivado/drc.rpt
• evidence/vivado/methodology.rpt
• evidence/vivado/route_status.rpt
• evidence/vivado/dsp_check.log

通过标准：

• Setup WNS 和 Hold WNS 均不小于 0；
• failing endpoints 为 0，unconstrained paths 为 0；
• CPU、SYS、ML-KEM 三个预期时钟均存在且频率正确；
• dsp_check.log 显示 DSP used 为 0；
• route status 为 fully routed；
• DRC/methodology 无 Critical Warning 被忽略；
• CDC 报告中的跨域均能对应到设计文档里的握手、同步器或异步 FIFO。report_cdc 退出码为 0 不等于 CDC 自动通过，仍需人工查看不安全类别和时钟约束。

功耗报告若仍显示 Confidence Level: Low，报告中只能称为 vectorless estimate。需要 正式功耗结论时，应对代表性 ML-KEM 和 matmul 负载回标 SAIF/VCD，再重新运行 report_power；这不是当前满分评测的前置条件。

4. 必跑：官方 5000 组 matmul 板级评测

使用最终 bitstream 和最终 user-sample.bin，保持：

MATMUL_GROUP_NUM=5000
MATMUL_FAST_START=1
MATMUL_WRITEBACK_RESULTS=0

运行官方评测工具，将完整控制台输出保存为：

doc/reports/system/evidence/board/matmul_official.log

必须保留这些行：随机种子、Expected CRC32、MATMUL_START、MATMUL_DONE、Elapsed time、Reported/Expected CRC32、Score percent。通过标准为 CRC 匹配、22 s 内收到 DONE。性能目标是小于等于 4.9 ms；同时记录硬件 DMA_CYCLES，用于区分内部批处理 周期与串口/软件尾部开销。

至少连续运行 5 个不同随机种子。报告主表填写中位数，附录写 min/median/max；不要只 选择最好一次。

5. 必跑：复位前零操作

竞赛约束要求复位前无任何操作。至少覆盖以下信号：UART 写使能、AXI AW/AR/W valid、 DMA request、matmul start、ML-KEM start。观察窗口从上电开始到每个时钟域同步复位释放。

推荐二选一：

1. 在 Vivado 仿真 testbench 中加入断言，任一信号在 reset 有效时拉高即 $fatal；
2. 板上 ILA 同时采集外部 reset、PLL locked、各域 resetn 和上述事务信号。

保存断言日志或 ILA 截图，并在文件名中包含提交短哈希。仅观察“串口没有字符”不足以 证明 DMA 和 AXI 没有操作。

6. 建议补跑：matmul 仿真与稳健性

• 组数：1、2、3、5000，覆盖 Bank 翻转和最后一组；
• DMA endpoint：对 valid/ready 随机插入 backpressure；
• 边界数据：全 0、全 0xffffffff、单位矩阵、随机矩阵；
• 控制：done W1C 后立即启动下一批，检查 CRC 清零与 group counter；
• XSIM 与 Verilator 都运行。两者结果不一致时按 RTL 竞态/未初始化问题处理，不能只保留 通过的仿真器结果。

7. 回填指标并生成 PDF

所有日志就位后执行：

cd doc/reports/system
./tools/run_report_tests.sh refresh

该命令会：

1. 从 evidence/ 提取 PPA、ML-KEM、FFT 和 matmul 指标；
2. 更新 report_metrics.tex；
3. 从 figures/*.dot 生成 PDF 矢量图；
4. 用 XeLaTeX 多轮编译报告并检查未解析引用。

最终人工检查：目录非空、没有“图??/表??”、所有图中文字可读、报告中的 commit 与 bitstream/日志一致、所有“待复测”结论已经按真实证据更新。