@@ -0,0 +1,99 @@
# ML-KEM 顶层集成模块
## Goal
实现 `mlkem_top` 顶层模块，将现有 10 个子模块集成为完整的 ML-KEM 系统，支持 KeyGen、Encaps、Decaps 三个操作。对外使用 valid/ready 流式接口。
## Decisions Made
* **操作范围**：
* **接口风格**： ）
* **k 值支持**：全支持 k=2,3,4， `parameter K=4` 参数化，通过 `i_k[2:0]` 输入选择
* **Keccak 策略**：共享 1 个 `keccak_core` 实例，各消费者通过仲裁器复用。需重构 `sha3_chain_top` /`sample_cbd_sync` /`sample_ntt_sync` 接受外部 Keccak 接口
## What I already know
### 现有模块接口汇总
| 模块 | 协议 | 关键信号 | 数据宽度 | 延迟 |
|------|------|---------|:---:|------|
| `rng_sync` | v/r | `valid_i` →`data_o[255]` | 256 | 1 cycle/word |
| `sha3_chain_top` | start/done | `start_i` →`done_o` →`rho_out/sigma_out[255]` | 256→512 | ~24 cycles |
| `sha3_top` | v/r | `mode[1:0]` , `data_i[512]` →`hash_o[512]` | 512→512 | ~24 cycles |
| `sample_cbd_sync` | v/r+last | `seed_i[255],nonce_i[8],eta_i[2]` →`coeff_o[12]× | — | ~300 cycles |
| `sample_ntt_sync` | v/r+last | `rho_i[255],k_i,i_idx,j_idx` →`coeff_o[12]× | — | ~4000 cycles |
| `ntt_core` | v/r+done | `coeff_in[12]× →`coeff_out[12]× | 12→12 | ~200 cycles |
| `poly_arith_sync` | v/r | `coeff_a/b[12],mode` →`coeff_out[12]` | 12→12 | 1 cycle/coeff |
| `poly_mul_sync` | v/r | `coeff_a/b[12]× →`coeff_out[12]× | 12→12 | ~300 cycles |
| `mod_add_sync` | v/r | `a,b[12]` →`sum[12]` | 12→12 | 1 cycle |
| `comp_decomp_sync` | v/r | `coeff_in[12],d[5],mode` →`coeff_out[12]` | 12→12 | 1 cycle/coeff |
| `s_bram` | raw | `rd_en,wr_en,addr,data` | 48 | 1 cycle |
| `sd_bram` | raw | `wr_en,addr,data` | 48 | 1 cycle |
### ML-KEM 算法数据流
**KeyGen ** :
1. `d = RNG(256)` → `sha3_chain(d)` → ρ σ
2. for i in 0..k-1: `sample_ntt(ρ → `ntt_core(NTT)` → Â[i]
3. for i in 0..k-1: `sample_cbd(σ → `ntt_core(NTT)` → ŝ[i] (秘密)
4. ŝ̂ = ŝ (already in NTT domain)
5. for i in 0..k-1: `poly_add(ê[i], ŝ̂[i])` → 再 `poly_mul(ê[i], Â[i])`
6. `t̂ = ê + ŝ̂` , then `comp_decomp(t̂)` → public key pk
7. `comp_decomp(ŝ̂)` → secret key sk
**Encaps ** :
1. `m = RNG(256)`
2. `m = SHA3-256(m)` → hash
3. `(K̄, r) = G(m || H(pk))` → SHA3-512
4. for i: `sample_ntt(ρ → `ntt_core(NTT)` → Â[i]
5. for i: `sample_cbd(r, N=i)` → `ntt_core(NTT)` → ŷ[i]
6. `u = NTT^{-1}(Â^T · ŷ) + sample_cbd(r, N=k+i)`
7. `v = NTT^{-1}(t̂^T · ŷ) + sample_cbd(r, N=2k) + decompress(m)`
8. `c1 = compress(u)` , `c2 = compress(v)`
9. `K = KDF(K̄ || SHA3-256(c))`
**Decaps ** :
1. `u = decompress(c1)` , `v = decompress(c2)`
2. `u` → `ntt_core(NTT)` → û
3. `v - NTT^{-1}(ŝ̂^T · û)` → `comp_decomp(decompress)` → m'
4. `(K̄', r') = G(m' || H(pk))`
5. Re-encrypt with r' to get c'
6. If c == c', K = KDF(K̄' || SHA3-256(c)), else K = KDF(z || SHA3-256(c))
### 关键架构问题
1. **多项式存储 ** ：中间多项式（Â[0..k-1], ŝ[0..k-1], ŷ[0..k-1] 等）需要 BRAM 存储
2. **Keccak 共享 ** ：
3. **RNG 重用 ** ： ，
## Open Questions
（全部已解决）
## Requirements (final)
* 三合一顶层模块 `mlkem_top` ，通过 mode[1:0] 选择操作
* 对外 valid/ready 接口
* 多项式中间结果存入 BRAM
* 单时钟域 100MHz
* RNG 复用（串行调用）
## Acceptance Criteria (evolving)
* [ ] KeyGen 产生正确的 (pk, sk) 输出
* [ ] Encaps 产生正确的 (c, K) 输出
* [ ] Decaps 产生正确的 K 输出
* [ ] 验证 Encaps(Decaps()) consistency
* [ ] Vivado XSIM 可编译仿真
## Out of Scope
* AXI4-Full 总线桥接
* DMA 控制器
* 性能优化（多模块并行）
## Technical Notes
- 参考 FIPS 203 Section 7 (Algorithm 15-17)
- 现有模块接口见上方表格
- BRAM 参数：建议 W=12, D=256 (或 W=48 打包 4 系数)
