fallensigh/mlkem-sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 新增 mlkem_top RTL 结构图 (SVG)

Browse Source 
用模块内真实实例名/信号名绘制的 mlkem_top RTL 框图:输入端口、控制 FSM
+ 状态寄存器、共享 keccak 三路仲裁、叶子算子(sha3/snt/cbd/ntt/pmul/comp)、
五个 sd_bram 存储库、ss_o 隐式拒绝 mux 与各 dbg 回读抽头。三色连线区分
数据通路 / BRAM 端口 / 共享仲裁。
This commit is contained in:
FallenSigh
2026-06-30 02:42:31 +08:00
parent 717a9929b6
commit faf15ee113
1 changed files with 229 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
docs/mlkem_top_rtl.svg Normal file
View File

@@ -0,0 +1,229 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="1480" height="1020" viewBox="0 0 1480 1020" font-family="'DejaVu Sans Mono','Consolas',monospace">
<defs>
<marker id="arr" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L7,3 L0,6 z" fill="#444"/>
</marker>
<marker id="arrB" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L7,3 L0,6 z" fill="#1763a6"/>
</marker>
<marker id="arrR" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L7,3 L0,6 z" fill="#a33"/>
</marker>
<style>
.lbl{font-size:13px;fill:#111;}
.sub{font-size:10.5px;fill:#555;}
.port{font-size:11px;fill:#1763a6;}
.net{font-size:10px;fill:#666;}
.ttl{font-size:14px;font-weight:bold;fill:#111;}
.big{font-size:20px;font-weight:bold;fill:#111;}
.wire{stroke:#444;stroke-width:1.4;fill:none;}
.wireB{stroke:#1763a6;stroke-width:1.4;fill:none;}
.wireR{stroke:#a33;stroke-width:1.4;fill:none;}
</style>
</defs>
<rect x="0" y="0" width="1480" height="1020" fill="#fbfbf9"/>
<text x="40" y="34" class="big">mlkem_top — ML-KEM KeyGen / Encaps / Decaps (op_i: 0/1/2, runtime k_i)</text>
<text x="40" y="54" class="sub">实线=数据/系数通路 蓝=BRAM 端口 红=隐式拒绝 / 共享 keccak 仲裁 方框内为 RTL 实例名 / 信号名</text>
<!-- ================= INPUTS (left) ================= -->
<rect x="24" y="90" width="200" height="318" rx="7" fill="#eef4fb" stroke="#9bb8d6"/>
<text x="124" y="110" class="ttl" text-anchor="middle">输入端口</text>
<text x="36" y="134" class="port">k_i[2:0] op_i[1:0]</text>
<text x="36" y="154" class="port">start_i</text>
<text x="36" y="178" class="lbl">d_i[255:0]</text>
<text x="36" y="194" class="sub">KeyGen 种子 d</text>
<text x="36" y="214" class="lbl">z_i[255:0]</text>
<text x="36" y="230" class="sub">隐式拒绝种子 z</text>
<text x="36" y="250" class="lbl">msg_i[255:0]</text>
<text x="36" y="266" class="sub">Encaps 消息 m</text>
<line x1="36" y1="280" x2="212" y2="280" stroke="#9bb8d6" stroke-dasharray="3 3"/>
<text x="36" y="300" class="port">ek_in_* (Encaps)</text>
<text x="36" y="316" class="sub">公钥 ek → u_ek_bram</text>
<text x="36" y="338" class="port">dk_in_* (Decaps)</text>
<text x="36" y="354" class="sub">私钥 dk → 各区路由</text>
<text x="36" y="376" class="port">c_in_* (Decaps)</text>
<text x="36" y="392" class="sub">密文 c → u_c_in_bram</text>
<!-- ================= FSM / CONTROL ================= -->
<rect x="270" y="90" width="250" height="220" rx="8" fill="#fff3e0" stroke="#e0a440"/>
<text x="395" y="112" class="ttl" text-anchor="middle">控制 FSM (st, st_next)</text>
<text x="284" y="136" class="sub">KeyGen: G→A→C→N→M→E→H</text>
<text x="284" y="153" class="sub">Encaps: ENC_H→G→LOAD→A→TDEC</text>
<text x="284" y="167" class="sub"> →C→N→U→C1→E2MV→V→C2</text>
<text x="284" y="184" class="sub">Decaps: DEC_LOAD→DECOMP→SDEC</text>
<text x="284" y="198" class="sub"> →NTT→W→MENC→G→J→(重加密)→CMP</text>
<line x1="284" y1="210" x2="506" y2="210" stroke="#e0a440" stroke-dasharray="3 3"/>
<text x="284" y="230" class="lbl">相位选择 sel_*</text>
<text x="284" y="246" class="sub">sel_sha3 / sel_snt / sel_cbd</text>
<text x="284" y="266" class="lbl">op_r k_r (start 锁存)</text>
<text x="284" y="286" class="lbl">busy_o = (st≠IDLE)</text>
<text x="284" y="302" class="lbl">done_o = (st==DONE)</text>
<!-- registers -->
<rect x="270" y="326" width="250" height="150" rx="8" fill="#fdeef0" stroke="#d68a96"/>
<text x="395" y="346" class="ttl" text-anchor="middle">状态寄存器 (256b)</text>
<text x="284" y="368" class="lbl">rho_r / sigma_r <tspan class="sub">(ρ,σ=G)</tspan></text>
<text x="284" y="388" class="lbl">m_r <tspan class="sub">m / Decaps m'</tspan></text>
<text x="284" y="408" class="lbl">r_r <tspan class="sub">PRF 种子 r / r'</tspan></text>
<text x="284" y="428" class="lbl">hek_r <tspan class="sub">H(ek)</tspan> z_r <tspan class="sub">z</tspan></text>
<text x="284" y="448" class="lbl">ss_r <tspan class="sub">K / K'</tspan> kbar_r <tspan class="sub">K̄=J(z‖c)</tspan></text>
<text x="284" y="468" class="lbl">dec_reject <tspan class="sub">c'≠c 标志</tspan></text>
<!-- ================= SHARED KECCAK ================= -->
<rect x="560" y="92" width="300" height="196" rx="8" fill="#fbecec" stroke="#c98b8b"/>
<text x="710" y="114" class="ttl" text-anchor="middle">共享 Keccak (单核 + 相位 mux)</text>
<rect x="586" y="128" width="248" height="44" rx="6" fill="#fff" stroke="#c98b8b"/>
<text x="710" y="155" class="lbl" text-anchor="middle">u_keccak (keccak_core)</text>
<text x="586" y="196" class="net">kc_state_i_mux / kc_valid_i_mux ◄ 3-way</text>
<text x="586" y="214" class="net">kc_state_o / kc_valid_o ► 门控广播</text>
<text x="586" y="236" class="net">kc_valid_o_sha3 · _snt · _cbd</text>
<text x="586" y="258" class="sub">G/H/J、SampleNTT、CBD 分时复用 1 个核</text>
<text x="586" y="276" class="sub">(相位互斥 → sel_sha3/snt/cbd 选通)</text>
<!-- ================= HASH ENGINE ================= -->
<rect x="560" y="312" width="300" height="120" rx="8" fill="#eef7ee" stroke="#86b886"/>
<text x="710" y="334" class="ttl" text-anchor="middle">u_sha3 (sha3_top_shared)</text>
<text x="574" y="356" class="lbl">SHA3-512 G(·) → ρ‖σ / K‖r / K'‖r'</text>
<text x="574" y="376" class="lbl">SHA3-256 H(ek) (多块吸收)</text>
<text x="574" y="396" class="lbl">SHAKE-256 J(z‖c) → K̄ (多块)</text>
<text x="574" y="416" class="sub">mb_en / mb_block_i 多块；mode 选 G/H/J</text>
<!-- ================= SAMPLERS ================= -->
<rect x="560" y="456" width="300" height="76" rx="8" fill="#eef7ee" stroke="#86b886"/>
<text x="710" y="478" class="ttl" text-anchor="middle">u_snt (sample_ntt_sync_shared)</text>
<text x="574" y="498" class="lbl">Â[i][j] = SampleNTT(ρ‖j‖i) → bank_a</text>
<text x="574" y="518" class="sub">snt_coeff / snt_valid / snt_last</text>
<rect x="560" y="548" width="300" height="76" rx="8" fill="#eef7ee" stroke="#86b886"/>
<text x="710" y="570" class="ttl" text-anchor="middle">u_cbd (sample_cbd_sync_shared)</text>
<text x="574" y="590" class="lbl">CBD_η: s/e (KeyGen), y/e1/e2 (Encaps)</text>
<text x="574" y="610" class="sub">cbd_coeff → cbd_modq → bank_se / bank_t</text>
<!-- ================= ARITH ENGINES ================= -->
<rect x="560" y="648" width="300" height="80" rx="8" fill="#e9f1f7" stroke="#7fa8cc"/>
<text x="710" y="670" class="ttl" text-anchor="middle">u_ntt (ntt_core)</text>
<text x="574" y="690" class="lbl">前向 NTT(mode0) / INTT(mode1, ×3303)</text>
<text x="574" y="710" class="sub">ntt_in ◄ bank_se/bank_t；ntt_coeff ► 写回</text>
<rect x="560" y="744" width="300" height="80" rx="8" fill="#e9f1f7" stroke="#7fa8cc"/>
<text x="710" y="766" class="ttl" text-anchor="middle">u_pmul (poly_mul_sync)</text>
<text x="574" y="786" class="lbl">NTT 域逐点乘 Σ Â∘ŝ / Âᵀ∘ŷ / t̂∘ŷ / ŝ∘û</text>
<text x="574" y="806" class="sub">pm_a_in ◄ bank_a, pm_b_in ◄ bank_se → pm_coeff</text>
<rect x="560" y="840" width="300" height="80" rx="8" fill="#e9f1f7" stroke="#7fa8cc"/>
<text x="710" y="862" class="ttl" text-anchor="middle">u_comp (comp_decomp_sync)</text>
<text x="574" y="882" class="lbl">Compress_d (mode0) / Decompress_d (mode1)</text>
<text x="574" y="902" class="sub">Encaps C1/C2 压缩；Decaps DECOMP 解压</text>
<!-- accumulate / mod-add inline note -->
<rect x="270" y="500" width="250" height="120" rx="8" fill="#f4f0fa" stroke="#a78bc9"/>
<text x="395" y="522" class="ttl" text-anchor="middle">顶层内联运算</text>
<text x="284" y="544" class="sub">modQ 累加 (ST_M / U / V / W)</text>
<text x="284" y="562" class="sub">m_accq · u_accq · u_uq · u_vq · u_wq</text>
<text x="284" y="582" class="sub">byteEncode12 (ST_E) e_wbyte</text>
<text x="284" y="600" class="sub">byteDecode12 (TDEC/SDEC) td_c0/td_c1</text>
<text x="284" y="618" class="sub">bit-packer cp_* / 解包 dec_* / 比较 cmp_*</text>
<!-- ================= STORAGE BANKS (right) ================= -->
<rect x="900" y="90" width="340" height="470" rx="8" fill="#eef4fb" stroke="#9bb8d6"/>
<text x="1070" y="112" class="ttl" text-anchor="middle">系数存储库 (sd_bram, 1R/1W, 1拍读)</text>
<rect x="922" y="128" width="296" height="92" rx="6" fill="#fff" stroke="#9bb8d6"/>
<text x="934" y="148" class="lbl">u_bank_a <tspan class="sub">12×4096 (PA_AW=12)</tspan></text>
<text x="934" y="167" class="sub">Â[i][j] 矩阵；Decaps 中转 ŝ / e2 / v'</text>
<text x="934" y="185" class="net">ba_rd_addr/ba_rd_data ba_we/ba_wa/ba_wd</text>
<text x="934" y="205" class="net">slot: i*K+j</text>
<rect x="922" y="230" width="296" height="92" rx="6" fill="#fff" stroke="#9bb8d6"/>
<text x="934" y="250" class="lbl">u_bank_se <tspan class="sub">12×2048 (PSE_AW=11)</tspan></text>
<text x="934" y="269" class="sub">ŝ/ê (KeyGen) · ŷ (Encaps) · û (Decaps)</text>
<text x="934" y="287" class="net">bse_rd_addr/bse_rd_data bse_we/wa/wd</text>
<text x="934" y="307" class="net">slot_s=K² slot_e=K²+K</text>
<rect x="922" y="332" width="296" height="92" rx="6" fill="#fff" stroke="#9bb8d6"/>
<text x="934" y="352" class="lbl">u_bank_t <tspan class="sub">12×1024 (PT_AW=10)</tspan></text>
<text x="934" y="371" class="sub">t̂ · psum · Encaps v · Decaps w</text>
<text x="934" y="389" class="net">bt_rd_addr/bt_rd_data bt_we/wa/wd</text>
<text x="934" y="409" class="net">slot_t=K²+2K UPSUM=rel1</text>
<rect x="922" y="434" width="143" height="58" rx="6" fill="#fff" stroke="#9bb8d6"/>
<text x="934" y="453" class="lbl">u_ek_bram</text>
<text x="934" y="469" class="sub">8×2048</text>
<text x="934" y="485" class="sub">ek=Enc12(t̂)‖ρ</text>
<rect x="1075" y="434" width="143" height="58" rx="6" fill="#fff" stroke="#9bb8d6"/>
<text x="1087" y="453" class="lbl">u_dkp_bram</text>
<text x="1087" y="469" class="sub">8×2048</text>
<text x="1087" y="485" class="sub">dk_pke=Enc12(ŝ)</text>
<rect x="922" y="500" width="143" height="50" rx="6" fill="#fff" stroke="#9bb8d6"/>
<text x="934" y="519" class="lbl">u_ct_bram</text>
<text x="934" y="537" class="sub">8×2048 c / c'</text>
<rect x="1075" y="500" width="143" height="50" rx="6" fill="#fff" stroke="#9bb8d6"/>
<text x="1087" y="519" class="lbl">u_c_in_bram</text>
<text x="1087" y="537" class="sub">8×2048 输入 c</text>
<!-- ================= OUTPUTS ================= -->
<rect x="900" y="590" width="340" height="330" rx="8" fill="#eef9ee" stroke="#86b886"/>
<text x="1070" y="612" class="ttl" text-anchor="middle">输出 / 回读</text>
<text x="914" y="638" class="lbl">ss_o = dec_reject ? kbar_r : ss_r</text>
<text x="914" y="654" class="sub">共享密钥 K (Encaps/Decaps)</text>
<line x1="914" y1="666" x2="1226" y2="666" stroke="#86b886" stroke-dasharray="3 3"/>
<text x="914" y="688" class="lbl">dbg_ct_o ◄ u_ct_bram</text>
<text x="914" y="704" class="sub">密文 c 逐字节</text>
<text x="914" y="726" class="lbl">dbg_byte_o ◄ ek / dk_pke</text>
<text x="914" y="742" class="sub">sel: 0=ek_bram 1=dkp_bram</text>
<text x="914" y="764" class="lbl">dbg_dk_o ◄ dk_pke‖ek‖H(ek)‖z</text>
<text x="914" y="780" class="sub">完整 dk 逐字节 (1632/2400/3168B)</text>
<text x="914" y="802" class="lbl">dbg_coeff_o ◄ bank_a/se/t</text>
<text x="914" y="818" class="sub">按 dbg_slot_i 选库, 系数回读</text>
<line x1="914" y1="830" x2="1226" y2="830" stroke="#86b886" stroke-dasharray="3 3"/>
<text x="914" y="852" class="sub">调试抽头: dbg_rho_o dbg_sigma_o</text>
<text x="914" y="868" class="sub"> dbg_r_o dbg_hek_o dbg_mprime_o</text>
<text x="914" y="884" class="sub"> dbg_kbar_o dbg_decz_o dbg_dech_o</text>
<text x="914" y="906" class="sub">done_o / busy_o</text>
<!-- ============ WIRES ============ -->
<!-- inputs -> FSM/regs -->
<path class="wire" d="M224,150 L268,150" marker-end="url(#arr)"/>
<path class="wire" d="M224,182 L268,182 L268,378" marker-end="url(#arr)"/>
<path class="wire" d="M224,218 L256,218 L256,440 L268,440" marker-end="url(#arr)"/>
<path class="wire" d="M224,254 L260,254 L260,388 L268,388" marker-end="url(#arr)"/>
<!-- inputs(ek/dk/c) -> banks (blue) -->
<path class="wireB" d="M224,300 L240,300 L240,68 L1300,68 L1300,460 L1218,460" marker-end="url(#arrB)"/>
<path class="wireB" d="M224,338 L236,338 L236,72 L1296,72 L1296,463 L1218,463" marker-end="url(#arrB)"/>
<path class="wireB" d="M224,376 L232,376 L232,76 L1292,76 L1292,525 L1218,525" marker-end="url(#arrB)"/>
<!-- FSM sel -> keccak mux (red) -->
<path class="wireR" d="M520,230 L540,230 L540,180 L558,180" marker-end="url(#arrR)"/>
<!-- keccak <-> sha3/snt/cbd -->
<path class="wireR" d="M710,288 L710,310" marker-end="url(#arrR)"/>
<path class="wireR" d="M560,210 L546,210 L546,494 L558,494" marker-end="url(#arrR)"/>
<path class="wireR" d="M560,214 L544,214 L544,586 L558,586" marker-end="url(#arrR)"/>
<!-- regs <-> sha3 (rho/sigma/r/ss/kbar) -->
<path class="wire" d="M520,372 L536,372 L536,360 L558,360" marker-end="url(#arr)"/>
<path class="wire" d="M558,392 L538,392 L538,448 L520,448" marker-end="url(#arr)"/>
<!-- datapath engines -> banks (blue) -->
<path class="wireB" d="M860,494 L884,494 L884,174 L920,174" marker-end="url(#arrB)"/>
<path class="wireB" d="M860,590 L880,590 L880,276 L920,276" marker-end="url(#arrB)"/>
<path class="wireB" d="M860,688 L876,688 L876,378 L920,378" marker-end="url(#arrB)"/>
<!-- pmul reads bank_a/se -->
<path class="wireB" d="M920,200 L888,200 L888,772 L860,772" marker-end="url(#arrB)"/>
<path class="wireB" d="M920,300 L892,300 L892,776 L860,776" marker-end="url(#arrB)"/>
<!-- comp <-> ct/c_in -->
<path class="wireB" d="M860,884 L896,884 L896,524 L920,524" marker-end="url(#arrB)"/>
<!-- regs -> ss_o (red reject mux) -->
<path class="wireR" d="M520,448 L528,448 L528,948 L898,948 L898,634 L912,634" marker-end="url(#arrR)"/>
<!-- banks -> outputs (data already adjacent; show coeff readback) -->
<path class="wire" d="M1218,478 L1240,478 L1240,808 L1226,808" marker-end="url(#arr)"/>
<text x="40" y="1000" class="sub">注:同一套叶子算子 / 存储库被 KeyGen·Encaps·Decaps 三条数据通路按 FSM 相位分时复用;Decaps 重加密直接复用整条 Encaps 流水 (ENC_LOAD…ENC_C2)。</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB