docs: rebuild system report and test workflow

doc/reports/system/REPORT_RERUN_CHECKLIST.md

@@ -0,0 +1,168 @@
+# 系统报告复测清单
+
+本清单用于为 `system_design_report.tex` 生成同一提交、可追溯的证据。不要把旧的
+`fpga/vivado_reports_nodsp/` 与新板级日志混合后宣称为同一版本结果。
+
+## 0. 固化版本与环境
+
+在仓库根目录执行并保存输出：
+
+```bash
+git status --short
+git rev-parse HEAD
+vivado -version | head -n 3
+verilator --version
+```
+
+建议先提交当前 RTL/约束/软件变更。若工作树不干净，最终报告的证据版本无法唯一复现。
+
+## 1. 必跑：RTL 静态检查
+
+```bash
+cd doc/reports/system
+./tools/run_report_tests.sh lint
+```
+
+通过标准：命令退出码为 0，`evidence/lint.log` 中无 `%Error`。此项只证明静态可分析，
+不证明 AXI、CDC 或算法功能正确。
+
+## 2. 必跑：SoC 功能回归
+
+仅编译指定软件、不运行仿真：
+
+```bash
+cd doc/reports/system
+./tools/run_report_tests.sh build
+```
+
+需要同时运行 SoC 仿真时：
+
+```bash
+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/`。
+脚本会设置 `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/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` |
+
+ML-KEM 的正确计数是 3 个固定 KAT 向量、900 次执行，不是 360 个不同 KAT。若要在
+报告中声称覆盖隐式拒绝，必须另外增加“篡改 ciphertext 后共享密钥不等且流程按规范
+完成”的负向测试；当前脚本不提供该证据。
+
+## 3. 必跑：重新布局布线与实现取证
+
+完整实现耗时较长，单独执行：
+
+```bash
+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`，保持：
+
+```text
+MATMUL_GROUP_NUM=5000
+MATMUL_FAST_START=1
+MATMUL_WRITEBACK_RESULTS=0
+```
+
+运行官方评测工具，将完整控制台输出保存为：
+
+```text
+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
+
+所有日志就位后执行：
+
+```bash
+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/日志一致、所有“待复测”结论已经按真实证据更新。