test: add board FFT validation and VCD capture

doc/reports/system/REPORT_RERUN_CHECKLIST.md

@@ -42,10 +42,35 @@ cd doc/reports/system
 ./tools/run_report_tests.sh soc
 ```
 
-软件集合固定为 `asm`、`fft`、`fft_dma`、`mlkem_test` 和 `mlkem_hello`。`asm`
-需要官方 ExtRAM 测试数据和专用 matmul 流程，因此 `soc` 只编译它，不用通用
-`tb_top` 仿真；其余四项编译后依次运行 SoC 仿真。每次构建都会覆盖
-`sdk/axi_ram.mif`，因此不要并行执行这些用例。构建日志位于 `evidence/build/`。
+需要保存 VCD 时使用可选开关。默认只记录 `tb_top` 的时钟、复位、UART 和提交 PC，
+文件写入 `evidence/soc/<用例>.vcd`。记录内部模块时用 `VCD_SCOPE` 指定层次；长时间
+软件测试若递归记录整个 SoC，可能产生数 GB 文件：
+
+```bash
+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 当前提交的功能或性能证据时，再单独执行长仿真：
+
+```bash
+./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 混用不匹配的
@@ -56,11 +81,51 @@ cd doc/reports/system
 | 日志 | 必须出现 | 不得出现 |
 |---|---|---|
 | `evidence/build/{asm,fft,fft_dma,mlkem_test,mlkem_hello}.log` | 编译、链接和 objcopy 成功 | `Error` |
-| `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 死锁、仿真超时 |
 | `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 输出：
+
+```text
+doc/reports/system/evidence/board/fft.log
+doc/reports/system/evidence/board/fft_dma.log
+```
+
+`fft.log` 必须出现：
+
+```text
+FFT_MAX_ABS_ERROR_RE=<不大于8>
+FFT_MAX_ABS_ERROR_IM=<不大于8>
+FFT_ERROR_LIMIT=8
+FFT_RESULT=PASS
+FFT_DONE
+```
+
+`fft_dma.log` 必须出现：
+
+```text
+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 后共享密钥不等且流程按规范
 完成”的负向测试；当前脚本不提供该证据。