# 系统报告复测清单

本清单用于为 `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
```

需要保存 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 混用不匹配的
`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 输出：

```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 后共享密钥不等且流程按规范
完成”的负向测试；当前脚本不提供该证据。

## 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/日志一致、所有“待复测”结论已经按真实证据更新。