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

feat(mlkem_top): parameterize K in {2,3,4} (ML-KEM 512/768/1024)

Browse Source 
Generalize KeyGen from K=2-hardcoded to compile-time parameter K:
- eta1 derived (3 for K=2, else 2); slot layout SLOT_S/E/T = K*K+{0,K,2K},
  NUM_SLOTS = K*K+3K; SAW=5 slot-addr width.
- A-stage: explicit a_i/a_j row-major counters (slot = i*K+j) instead of
  K=2 bit-tricks. C/N stages: parametric slot bases, 2K polys.
- M-stage: m_i/m_j widened to 3-bit (must reach K=4); slots i*K+j etc.
- E-stage: 2K polys, e_is_dk split, rho offset 384*K.
- H(ek): H_NBLK=ceil((EK_BYTES+1)/136), H_LAST padding generalized;
  h_blk 4-bit. Byte mems sized EK_BYTES/DK_BYTES.
- Widen dbg_byte_idx_i to [10:0] (ek up to 1568B for K=4).

Parametric TB (tb_mlkem_kg_katK, KP generic + CASE plusarg). Verified
byte-exact vs NIST KAT:
  K=2 (512):  cases 0..4  ek 800B  / dk 1632B
  K=3 (768):  cases 0..2  ek 1184B / dk 2400B  (~36k cyc)
  K=4 (1024): cases 0..2  ek 1568B / dk 3168B  (~54k cyc)
run_tb.sh top runs all three parameter sets.
This commit is contained in:
FallenSigh
2026-06-28 02:59:58 +08:00
parent 2f46c0790f
commit b2bf798454
27 changed files with 25166 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
sync_rtl/top/TB/tb_mlkem_kg_katK_xsim.v Normal file
View File

@@ -0,0 +1,76 @@
// tb_mlkem_kg_katK_xsim.v - ML-KEM KeyGen vs NIST KAT, parametric K (KP) + CASE.
// xelab -generic_top KP=2|3|4 ; xsim -testplusarg CASE=n
// KP=2 -> k2 vectors (ML-KEM-512), KP=3 -> k3 (768), KP=4 -> k4 (1024).
// ek = 384*KP+32 bytes (==KAT pk), dk = 768*KP+96 bytes (==KAT sk).
`timescale 1ns/1ps
module tb_mlkem_kg_katK_xsim;
parameter KP = 2;
localparam EKB = 384*KP + 32;
localparam DKB = 768*KP + 96;
reg clk=0, rst_n=0, start_i=0;
reg [255:0] d_i, z_i;
wire busy_o, done_o;
reg [3:0] dbg_slot_i=0; reg [7:0] dbg_idx_i=0; wire [11:0] dbg_coeff_o;
reg dbg_byte_sel_i=0; reg [10:0] dbg_byte_idx_i=0; wire [7:0] dbg_byte_o;
reg [11:0] dbg_dk_idx_i=0; wire [7:0] dbg_dk_o;
wire [255:0] dbg_rho_o, dbg_sigma_o;
mlkem_top #(.K(KP)) dut (
.clk(clk), .rst_n(rst_n), .d_i(d_i), .z_i(z_i), .start_i(start_i),
.busy_o(busy_o), .done_o(done_o),
.dbg_slot_i(dbg_slot_i), .dbg_idx_i(dbg_idx_i), .dbg_coeff_o(dbg_coeff_o),
.dbg_byte_sel_i(dbg_byte_sel_i), .dbg_byte_idx_i(dbg_byte_idx_i), .dbg_byte_o(dbg_byte_o),
.dbg_dk_idx_i(dbg_dk_idx_i), .dbg_dk_o(dbg_dk_o),
.dbg_rho_o(dbg_rho_o), .dbg_sigma_o(dbg_sigma_o)
);
always #5 clk = ~clk;
reg [255:0] dmem [0:0];
reg [255:0] zmem [0:0];
reg [7:0] ek_gold [0:EKB-1];
reg [7:0] dk_gold [0:DKB-1];
integer c, i, errors, casenum;
reg [8*80-1:0] tag, dfile, zfile, ekfile, dkfile;
initial begin
if (!$value$plusargs("CASE=%d", casenum)) casenum = 0;
$sformat(tag, "k%0d", KP);
$sformat(dfile, "sync_rtl/top/TB/vectors/kat_%0s_c%0d_d.hex", tag, casenum);
$sformat(zfile, "sync_rtl/top/TB/vectors/kat_%0s_c%0d_z.hex", tag, casenum);
$sformat(ekfile, "sync_rtl/top/TB/vectors/kat_%0s_c%0d_ek.hex", tag, casenum);
$sformat(dkfile, "sync_rtl/top/TB/vectors/kat_%0s_c%0d_dk.hex", tag, casenum);
$readmemh(dfile, dmem);
$readmemh(zfile, zmem);
$readmemh(ekfile, ek_gold);
$readmemh(dkfile, dk_gold);
d_i = dmem[0]; z_i = zmem[0];
rst_n=0; repeat(4) @(posedge clk); rst_n=1; @(posedge clk);
start_i=1; @(posedge clk); start_i=0;
c=0; while(!done_o && c<2000000) begin @(posedge clk); c=c+1; end
if(!done_o) begin $display("FAIL K=%0d case %0d: timeout", KP, casenum); $finish; end
$display("=== ML-KEM K=%0d KAT case %0d: KeyGen done in %0d cyc ===", KP, casenum, c);
errors = 0;
dbg_byte_sel_i = 1'b0;
for (i = 0; i < EKB; i = i + 1) begin
dbg_byte_idx_i = i[10:0]; @(posedge clk); @(posedge clk);
if (dbg_byte_o !== ek_gold[i]) begin
if (errors < 8) $display(" EK[%0d] got=%02x exp=%02x", i, dbg_byte_o, ek_gold[i]);
errors = errors + 1;
end
end
for (i = 0; i < DKB; i = i + 1) begin
dbg_dk_idx_i = i[11:0]; @(posedge clk); @(posedge clk);
if (dbg_dk_o !== dk_gold[i]) begin
if (errors < 8) $display(" DK[%0d] got=%02x exp=%02x", i, dbg_dk_o, dk_gold[i]);
errors = errors + 1;
end
end
if (errors == 0) $display("K=%0d CASE %0d PASS: ek (%0dB)==pk, dk (%0dB)==sk", KP, casenum, EKB, DKB);
else $display("K=%0d CASE %0d FAIL: %0d mismatches", KP, casenum, errors);
$finish;
end
initial begin #120000000; $display("FAIL: global timeout"); $finish; end
endmodule

1
sync_rtl/top/TB/vectors/kat_k3_c0_d.hex Normal file
View File

@@ -0,0 +1 @@
2426f1941779574d3f1b163bd57f7e173e229e630ec7f7073bdf365137c4bb6d

2400
sync_rtl/top/TB/vectors/kat_k3_c0_dk.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1184
sync_rtl/top/TB/vectors/kat_k3_c0_ek.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1
sync_rtl/top/TB/vectors/kat_k3_c0_z.hex Normal file
View File

@@ -0,0 +1 @@
687acf9406694974d383032f7579378f449c75d0560af56cf921ec48404896f6

1
sync_rtl/top/TB/vectors/kat_k3_c1_d.hex Normal file
View File

@@ -0,0 +1 @@
9b68d9d2390fa18739b239a58649393a28f97f6b164ec5e4334f4df864fc9cd6

2400
sync_rtl/top/TB/vectors/kat_k3_c1_dk.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1184
sync_rtl/top/TB/vectors/kat_k3_c1_ek.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1
sync_rtl/top/TB/vectors/kat_k3_c1_z.hex Normal file
View File

@@ -0,0 +1 @@
a02e20d538b412ff074d121a80b0583e0b54e85b267da0789c5ca565342ee66d

1
sync_rtl/top/TB/vectors/kat_k3_c2_d.hex Normal file
View File

@@ -0,0 +1 @@
905eb1f02ade542733c35132f5a998d3ec80d20ec8ed235bf228081157034763

2400
sync_rtl/top/TB/vectors/kat_k3_c2_dk.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1184
sync_rtl/top/TB/vectors/kat_k3_c2_ek.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1
sync_rtl/top/TB/vectors/kat_k3_c2_z.hex Normal file
View File

@@ -0,0 +1 @@
d026bb15f52e8df87779ff953ccf42a9d5401111c402c448d77cb291bbe6aa1e

1
sync_rtl/top/TB/vectors/kat_k4_c0_d.hex Normal file
View File

@@ -0,0 +1 @@
2426f1941779574d3f1b163bd57f7e173e229e630ec7f7073bdf365137c4bb6d

3168
sync_rtl/top/TB/vectors/kat_k4_c0_dk.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1568
sync_rtl/top/TB/vectors/kat_k4_c0_ek.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1
sync_rtl/top/TB/vectors/kat_k4_c0_z.hex Normal file
View File

@@ -0,0 +1 @@
687acf9406694974d383032f7579378f449c75d0560af56cf921ec48404896f6

1
sync_rtl/top/TB/vectors/kat_k4_c1_d.hex Normal file
View File

@@ -0,0 +1 @@
9b68d9d2390fa18739b239a58649393a28f97f6b164ec5e4334f4df864fc9cd6

3168
sync_rtl/top/TB/vectors/kat_k4_c1_dk.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1568
sync_rtl/top/TB/vectors/kat_k4_c1_ek.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1
sync_rtl/top/TB/vectors/kat_k4_c1_z.hex Normal file
View File

@@ -0,0 +1 @@
a02e20d538b412ff074d121a80b0583e0b54e85b267da0789c5ca565342ee66d

1
sync_rtl/top/TB/vectors/kat_k4_c2_d.hex Normal file
View File

@@ -0,0 +1 @@
905eb1f02ade542733c35132f5a998d3ec80d20ec8ed235bf228081157034763

3168
sync_rtl/top/TB/vectors/kat_k4_c2_dk.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1568
sync_rtl/top/TB/vectors/kat_k4_c2_ek.hex Normal file
View File

File diff suppressed because it is too large Load Diff

1
sync_rtl/top/TB/vectors/kat_k4_c2_z.hex Normal file
View File

@@ -0,0 +1 @@
d026bb15f52e8df87779ff953ccf42a9d5401111c402c448d77cb291bbe6aa1e

48
sync_rtl/top/TB/xsim_run.tcl
View File

@@ -1,16 +1,12 @@
# xsim_run.tcl - Vivado XSIM for mlkem_top ML-KEM-512 KeyGen.
# xsim_run.tcl - Vivado XSIM for mlkem_top ML-KEM KeyGen, all K in {2,3,4}.
#
# Compiles the full KeyGen datapath + all leaf modules, then runs the
# end-to-end NIST KAT testbench for count=0..4 (each verifies ek==KAT.pk
# 800B and dk==KAT.sk 1632B byte-exact).
# Compiles the full KeyGen datapath + leaf modules, then runs the parametric
# NIST KAT testbench for ML-KEM-512 (K=2), 768 (K=3), 1024 (K=4). Each case
# verifies ek==KAT.pk and dk==KAT.sk byte-exact.
#
# Run from project root:
# ./run_tb.sh top
# (or: vivado-style step-by-step with the commands below)
# ================================================================
# Step 1: Compile RTL sources (leaf modules + top)
# ================================================================
# ---- Step 1: compile RTL ----
xvlog -sv --relax -i . sync_rtl/sha3/keccak_round.v
xvlog -sv --relax -i . sync_rtl/sha3/keccak_core.v
xvlog -sv --relax -i . sync_rtl/sha3/sha3_top.v
@@ -25,21 +21,23 @@ xvlog -sv --relax -i . sync_rtl/poly_mul/poly_mul_zeta_rom.v
xvlog -sv --relax -i . sync_rtl/poly_mul/poly_mul_sync.v
xvlog -sv --relax -i . sync_rtl/top/mlkem_top.v
# ================================================================
# Step 2: Compile KAT testbench (parameterized by +CASE=n)
# ================================================================
xvlog -sv --relax sync_rtl/top/TB/tb_mlkem_kg_katN_xsim.v
# ---- Step 2: compile parametric KAT testbench ----
xvlog -sv --relax sync_rtl/top/TB/tb_mlkem_kg_katK_xsim.v
# ================================================================
# Step 3: Elaborate snapshot
# ================================================================
xelab tb_mlkem_kg_katN_xsim -s mlkem_kg_kat --timescale 1ns/1ps
# ---- Step 3: elaborate one snapshot per K ----
xelab tb_mlkem_kg_katK_xsim -generic_top KP=2 -s mlkem_kg_k2 --timescale 1ns/1ps
xelab tb_mlkem_kg_katK_xsim -generic_top KP=3 -s mlkem_kg_k3 --timescale 1ns/1ps
xelab tb_mlkem_kg_katK_xsim -generic_top KP=4 -s mlkem_kg_k4 --timescale 1ns/1ps
# ================================================================
# Step 4: Run all 5 KAT cases (count=0..4)
# ================================================================
xsim mlkem_kg_kat -R -testplusarg CASE=0
xsim mlkem_kg_kat -R -testplusarg CASE=1
xsim mlkem_kg_kat -R -testplusarg CASE=2
xsim mlkem_kg_kat -R -testplusarg CASE=3
xsim mlkem_kg_kat -R -testplusarg CASE=4
# ---- Step 4: run KAT cases (K=2: 0..4, K=3/4: 0..2) ----
xsim mlkem_kg_k2 -R -testplusarg CASE=0
xsim mlkem_kg_k2 -R -testplusarg CASE=1
xsim mlkem_kg_k2 -R -testplusarg CASE=2
xsim mlkem_kg_k2 -R -testplusarg CASE=3
xsim mlkem_kg_k2 -R -testplusarg CASE=4
xsim mlkem_kg_k3 -R -testplusarg CASE=0
xsim mlkem_kg_k3 -R -testplusarg CASE=1
xsim mlkem_kg_k3 -R -testplusarg CASE=2
xsim mlkem_kg_k4 -R -testplusarg CASE=0
xsim mlkem_kg_k4 -R -testplusarg CASE=1
xsim mlkem_kg_k4 -R -testplusarg CASE=2