mlkem-sync/.trellis/tasks/archive/2026-06/06-26-mlkem-top-integration/prd.md

ML-KEM 顶层集成模块

Goal

实现 mlkem_top 顶层模块，将现有 10 个子模块集成为完整的 ML-KEM 系统，支持 KeyGen、Encaps、Decaps 三个操作。对外使用 valid/ready 流式接口。

Decisions Made

• 操作范围：KeyGen + Encaps + Decaps 全部实现
• 接口风格：valid/ready 流式接口（类似 AXI-Stream）
• 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]×256	—	~300 cycles
sample_ntt_sync	v/r+last	rho_i[255],k_i,i_idx,j_idx→coeff_o[12]×256	—	~4000 cycles
ntt_core	v/r+done	coeff_in[12]×256,mode→coeff_out[12]×256	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]×256→coeff_out[12]×256	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(ρ, k, i, 0) → ntt_core(NTT) → Â[i]
3. for i in 0..k-1: sample_cbd(σ, N=i) → 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(ρ, k, i, 0) → 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 共享：sha3_chain_top 和 sample_ntt/sample_cbd 内部都有 sha3_top 实例，需决定共享还是各自独立
3. RNG 重用：KeyGen/Encaps 中多次调用 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 系数)