168 lines
6.8 KiB
Markdown
168 lines
6.8 KiB
Markdown
# 编写所有模块的 Vivado Verilog Testbench
|
||
|
||
## Goal
|
||
|
||
为 ML-KEM 硬件项目的所有 RTL 模块编写 Verilog testbench（.v 文件），可在 Vivado xsim 中仿真。遵循已有 sha3/TB/ 的 xsim testbench 约定和风格。
|
||
|
||
## What I already know
|
||
|
||
### 项目结构
|
||
- 项目根目录：`/home/fallensigh/Dev/mlkem`
|
||
- 所有 RTL 源码在 `sync_rtl/` 下按功能分目录
|
||
- 已有 testbench 在各自的 `TB/` 子目录下
|
||
|
||
### 已有 testbench 情况
|
||
| 模块目录 | 已有 Verilator (.cpp) TB | 已有 XSIM (.v) TB | 需要新增 .v TB |
|
||
|----------|------------------------|-------------------|---------------|
|
||
| sha3/ | ✅ tb_sha3.cpp | ✅ tb_sha3_xsim.v, tb_sha3_xsim_simple.v, tb_keccak_core_xsim.v | ❌ 已完成 |
|
||
| sha3_chain/ | ✅ tb_sha3_chain.cpp | ❌ | ✅ |
|
||
| ntt/ | ✅ tb_ntt.cpp | ❌ | ✅ |
|
||
| poly_mul/ | ✅ tb_poly_mul.cpp | ❌ | ✅ |
|
||
| poly_arith/ | ✅ tb_poly_arith.cpp | ❌ | ✅ |
|
||
| sample_cbd/ | ✅ tb_sample_cbd.cpp | ❌ | ✅ |
|
||
| sample_ntt/ | ✅ tb_sample_ntt.cpp | ❌ | ✅ |
|
||
| rng/ | ✅ tb_rng.cpp | ❌ | ✅ |
|
||
| comp_decomp/ | ✅ tb_comp_decomp.cpp | ❌ | ✅ |
|
||
| storage/ | ✅ tb_storage.cpp | ❌ | ✅ |
|
||
| mod_add/ | ✅ tb_mod_add.cpp | ❌ | ✅ |
|
||
| common/ | ❌ | ❌ | ✅ (pipeline_reg, skid_buffer) |
|
||
|
||
### RTL 模块清单（按目录）
|
||
|
||
**sha3/** (已有 TB)：
|
||
- `sha3_top.v` - SHA3 顶层（G/H/J 模式）
|
||
- `keccak_core.v` - Keccak 24 轮核心
|
||
- `keccak_round.v` - 单轮 Keccak（组合逻辑）
|
||
|
||
**sha3_chain/**：
|
||
- `sha3_chain_top.v` - SHA3 链式调用顶层
|
||
|
||
**ntt/**：
|
||
- `ntt_sync.v` - NTT 同步顶层（wrapper）
|
||
- `ntt_core.v` - NTT 核心（Barrett 约简 + butterfly）
|
||
- `butterfly_unit.v` - 蝶形运算单元
|
||
- `barrett_mul.v` - Barrett 模乘
|
||
- `zeta_rom.v` - Zeta 预计算 ROM
|
||
|
||
**poly_mul/**：
|
||
- `poly_mul_sync.v` - 多项式乘法顶层
|
||
- `poly_mul_zeta_rom.v` - PolyMul zeta ROM
|
||
- `basecase_mul.v` - 基础乘法
|
||
|
||
**poly_arith/**：
|
||
- `poly_arith_sync.v` - 多项式加减（PolyAdd/PolySub）
|
||
|
||
**sample_cbd/**：
|
||
- `sample_cbd_sync.v` - CBD 采样（SHAKE-256 PRF）
|
||
|
||
**sample_ntt/**：
|
||
- `sample_ntt_sync.v` - NTT 域采样
|
||
|
||
**rng/**：
|
||
- `rng_sync.v` - Galois LFSR PRNG（256-bit）
|
||
|
||
**comp_decomp/**：
|
||
- `comp_decomp_sync.v` - 压缩/解压缩
|
||
|
||
**storage/**：
|
||
- `s_bram.v` - 单口 BRAM
|
||
- `sd_bram.v` - 简单双口 BRAM
|
||
|
||
**mod_add/**：
|
||
- `mod_add_sync.v` - 模加法
|
||
|
||
**common/**：
|
||
- `pipeline_reg.v` - 流水线寄存器
|
||
- `skid_buffer.v` - Skid Buffer
|
||
|
||
### 现有 XSIM TB 约定（参考 sha3/TB/）
|
||
- 命名：`tb_<module>_xsim.v`
|
||
- 时钟：100MHz，10ns 周期（`always #5 clk = ~clk`）
|
||
- 复位：`rst_n` 低有效 3 周期
|
||
- 自检模式：hardcode 期望值，用 `$error` 报告 mismatch
|
||
- 文件向量模式：`$readmemh` 从 hex 文件读测试向量
|
||
- 输出：`$display` 日志 + `$fwrite` 结果文件
|
||
- 超时看门狗：防止死锁
|
||
- 编译脚本：`xsim_run.tcl` (xvlog → xelab → xsim)
|
||
|
||
### 接口约定（从各模块 port 列表得出）
|
||
- 所有模块使用 synchronous valid/ready 握手
|
||
- `clk, rst_n` 标准端口
|
||
- 数据宽度：12-bit 系数（ntt/poly），256-bit（rng），512-bit（sha3）
|
||
- 部分模块有 `done_o` 信号（如 ntt_sync）
|
||
|
||
## Assumptions
|
||
|
||
1. 测试自检模式为主，可对比 Python 参考实现的期望输出
|
||
2. 简单模块（common/）用 hardcoded 向量测试
|
||
3. 复杂模块可能需要 hex 文件向量
|
||
4. 子模块（butterfly_unit, barrett_mul, zeta_rom, basecase_mul 等）通过父模块间接测试
|
||
|
||
## Decisions Made
|
||
|
||
* **测试范围**：只测顶层 sync 模块，子模块通过父模块间接覆盖
|
||
* **common/** 模块（pipeline_reg, skid_buffer）不在本次范围内
|
||
* **测试模式**：文件向量模式（`$readmemh` 读 hex 文件），参考 `tb_sha3_xsim.v` 风格
|
||
* **向量生成**：每个模块配套 Python `gen_vectors.py` 生成输入向量 `.hex` 文件
|
||
* **编译脚本**：每个模块目录一个独立的 `xsim_run.tcl`
|
||
|
||
## 需要编写 TB 的模块清单（10 个）
|
||
|
||
| # | 模块 | 文件 | 接口要点 |
|
||
|---|------|------|---------|
|
||
| 1 | `sha3_chain_top` | `sync_rtl/sha3_chain/sha3_chain_top.v` | d_in[255:0], start_i → rho_out[255:0], sigma_out[255:0] |
|
||
| 2 | `ntt_core` | `sync_rtl/ntt/ntt_core.v` | coeff_in[11:0]×256, mode → coeff_out[11:0]×256, done_o |
|
||
| 3 | `poly_mul_sync` | `sync_rtl/poly_mul/poly_mul_sync.v` | coeff_a/b ×256 → coeff_out ×256 |
|
||
| 4 | `poly_arith_sync` | `sync_rtl/poly_arith/poly_arith_sync.v` | coeff_a/b[11:0], mode → coeff_out[11:0] (流式) |
|
||
| 5 | `sample_cbd_sync` | `sync_rtl/sample_cbd/sample_cbd_sync.v` | seed_i[255:0], nonce_i[7:0], eta_i → coeff_o[11:0]×256 |
|
||
| 6 | `sample_ntt_sync` | `sync_rtl/sample_ntt/sample_ntt_sync.v` | rho_i[255:0], k/i/j_idx → coeff_o[11:0]×256 |
|
||
| 7 | `rng_sync` | `sync_rtl/rng/rng_sync.v` | valid_i → data_o[255:0] (LFSR) |
|
||
| 8 | `comp_decomp_sync` | `sync_rtl/comp_decomp/comp_decomp_sync.v` | coeff_in[11:0], d[4:0], mode → coeff_out[11:0] |
|
||
| 9 | `s_bram` / `sd_bram` | `sync_rtl/storage/s_bram.v`, `sd_bram.v` | 参数化 BRAM 读写 |
|
||
| 10 | `mod_add_sync` | `sync_rtl/mod_add/mod_add_sync.v` | a[11:0], b[11:0] → sum[11:0] |
|
||
|
||
## Requirements (final)
|
||
|
||
* 10 个顶层 sync 模块各产出 4 个文件：
|
||
- `TB/tb_<module>_xsim.v` — Verilog testbench（文件向量模式，`$readmemh` + `$fwrite`）
|
||
- `TB/vectors/<module>_input.hex` — 测试输入向量
|
||
- `TB/gen_vectors.py` — Python 脚本生成输入向量
|
||
- `TB/xsim_run.tcl` — Vivado 编译+仿真脚本
|
||
* 遵循 sha3/TB/ 的编码风格和目录结构：
|
||
- 时钟 100MHz (`always #5 clk = ~clk`)
|
||
- 复位 `rst_n` 低有效 3 周期
|
||
- valid/ready 握手协议
|
||
- 超时看门狗
|
||
- pass/fail 统计 + `$display` 报告
|
||
* 支持 `xvlog -sv` + `xelab` + `xsim -R` 流程
|
||
|
||
## Acceptance Criteria
|
||
|
||
* [ ] 10 个模块各有完整的 TB 目录：tb .v + gen_vectors.py + xsim_run.tcl
|
||
* [ ] 每个 testbench 可通过 `xvlog -sv` 编译无 error
|
||
* [ ] 每个 testbench 可通过 `xelab` + `xsim -R` 跑通仿真
|
||
* [ ] 输出清晰的 pass/fail 报告
|
||
* [ ] 包含超时看门狗防止死锁
|
||
* [ ] Python `gen_vectors.py` 可独立运行生成 hex 向量文件
|
||
|
||
## Definition of Done
|
||
|
||
* 所有 10 个模块的 4 类文件已创建
|
||
* 每个 TB 遵循 `sha3/TB/` 的代码风格
|
||
* 向量文件格式与 `$readmemh` 兼容
|
||
|
||
## Out of Scope
|
||
|
||
* Verilator C++ testbench（已有）
|
||
* 覆盖率收集
|
||
* UVM 框架
|
||
* 子模块独立 TB（butterfly_unit, barrett_mul, basecase_mul, ROM 等）
|
||
* common/ 模块 TB（pipeline_reg, skid_buffer）
|
||
|
||
## Technical Notes
|
||
|
||
- 参考已有 TB：`sync_rtl/sha3/TB/tb_sha3_xsim.v`（文件向量模式）、`sync_rtl/sha3/TB/tb_sha3_xsim_simple.v`（简单自检模式）
|
||
- 编译脚本参考：`sync_rtl/sha3/TB/xsim_run.tcl`
|
||
- RTL spec：`.trellis/spec/rtl/verilator-conventions.md`（Verilator 相关，部分适用）
|
||
- 时钟定义：`sync_rtl/common/defines.vh` 中的 `CLK_PERIOD 10.0`
|