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

delete mlkem_top

Browse Source
This commit is contained in:
FallenSigh
2026-06-27 03:20:52 +08:00
parent 038ba8ecf2
commit 1cace51649
17 changed files with 0 additions and 4409 deletions
Download Patch File Download Diff File Expand all files Collapse all files

491
sync_rtl/top/TB/tb_mlkem_top_xsim.v
View File

@@ -1,491 +0,0 @@
// tb_mlkem_top_xsim.v - KAT (Known Answer Test) testbench for mlkem_top
//
// Reads FIPS 203 test vectors from hex files using $readmemh.
// Uses Verilog `force` to inject known d/z/m values into the DUT's
// internal registers, overriding the internal RNG output for deterministic
// KAT verification.
//
// IMPORTANT: The mlkem_top module has a known design deadlock:
// sha3_chain_top_shared requires kc_ready_o to transition IDLE→BUSY,
// but keccak_arbiter requires cons_valid_i[0]=1 before granting it.
// Workaround: force chain_kc_ready_o wire to 1 during all tests.
//
// Input vector format (192 hex chars = 768 bits per line):
// bits [767:512] = d (256 bits)
// bits [511:256] = msg (256 bits)
// bits [255:0] = z (256 bits)
//
// Expected output format (6464 hex chars = 25856 bits per line):
// bits [25855:19456] = pk (800 bytes = 6400 bits)
// bits [19455:6400] = sk (1632 bytes = 13056 bits)
// bits [6399:256] = ct (768 bytes = 6144 bits)
// bits [255:0] = ss (32 bytes = 256 bits)
//
// Test flow per vector:
// 1. Force d_reg and run KeyGen → verify done_o, capture pk/sk
// 2. Force m_reg and run Encaps → verify done_o, capture ct/K
// 3. Force z_reg and run Decaps → verify done_o, capture K_dec
//
// Usage:
// xvlog -sv -i . <all_deps>.v tb_mlkem_top_xsim.v
// xelab tb_mlkem_top_xsim -s tb_mlkem_top_xsim --timescale 1ns/1ps
// xsim tb_mlkem_top_xsim -R
`timescale 1ns / 1ps
module tb_mlkem_top_xsim;
// ================================================================
// Parameters
// ================================================================
parameter VECTOR_FILE = "sync_rtl/top/TB/vectors/mlkem_top_input.hex";
parameter EXPECTED_FILE = "sync_rtl/top/TB/vectors/mlkem_top_expected.hex";
parameter MAX_VECTORS = 16;
parameter TIMEOUT_CYCLES = 10000000; // mlkem_top is SLOW (millions of cycles)
parameter K_PARAM = 4; // matches DUT K=4
localparam PK_WIDTH = 12 * K_PARAM * 256; // 12288
localparam SK_WIDTH = 12 * K_PARAM * 256; // 12288
localparam CT_WIDTH = 12 * K_PARAM * 256; // 12288
// Expected widths for ML-KEM-512 (k=2):
localparam EXP_PK_WIDTH = 6400; // 800 bytes
localparam EXP_SK_WIDTH = 13056; // 1632 bytes
localparam EXP_CT_WIDTH = 6144; // 768 bytes
localparam EXP_SS_WIDTH = 256; // 32 bytes
// ================================================================
// DUT signals
// ================================================================
reg clk;
reg rst_n;
reg [1:0] mode;
reg [2:0] i_k;
reg valid_i;
wire ready_o;
wire [PK_WIDTH-1:0] pk_o;
wire [SK_WIDTH-1:0] sk_o;
wire pk_valid;
wire sk_valid;
wire [CT_WIDTH-1:0] ct_o;
wire [255:0] K_o;
wire ct_valid;
wire K_valid;
wire [255:0] K_o_dec;
wire K_valid_dec;
wire done_o;
// ================================================================
// DUT instantiation
// ================================================================
mlkem_top #(.K(K_PARAM)) u_dut (
.clk (clk),
.rst_n (rst_n),
.mode (mode),
.i_k (i_k),
.valid_i (valid_i),
.ready_o (ready_o),
.pk_o (pk_o),
.sk_o (sk_o),
.pk_valid (pk_valid),
.sk_valid (sk_valid),
.ct_o (ct_o),
.K_o (K_o),
.ct_valid (ct_valid),
.K_valid (K_valid),
.K_o_dec (K_o_dec),
.K_valid_dec (K_valid_dec),
.done_o (done_o)
);
// ================================================================
// Clock generation: 100 MHz (10 ns period)
// ================================================================
initial clk = 1'b0;
always #5 clk = ~clk;
// ================================================================
// Vector memories (loaded by $readmemh)
// ================================================================
reg [767:0] input_mem [0:MAX_VECTORS-1];
reg [25855:0] expected_mem [0:MAX_VECTORS-1];
// ================================================================
// Test variables
// ================================================================
integer vec_count;
integer idx;
integer cycle_count;
integer pass_count;
integer fail_count;
integer kg_pass, kg_fail;
integer en_pass, en_fail;
integer dc_pass, dc_fail;
// ================================================================
// Hex-to-ASCII conversion helper
// ================================================================
function [7:0] nibble_to_ascii;
input [3:0] nibble;
begin
if (nibble < 4'd10)
nibble_to_ascii = 8'h30 + {4'd0, nibble};
else
nibble_to_ascii = 8'h41 + ({4'd0, nibble} - 4'd10);
end
endfunction
// ================================================================
// Print 256-bit value as hex
// ================================================================
task print_hex256;
input [255:0] val;
input [256*8:1] label;
integer bit_idx;
reg [3:0] nib;
begin
$write("%s: ", label);
for (bit_idx = 63; bit_idx >= 0; bit_idx = bit_idx - 1) begin
nib = val[(bit_idx*4)+:4];
$write("%c", nibble_to_ascii(nib));
end
$write("\n");
end
endtask
// ================================================================
// Wait for done_o with timeout
// Sets result_var: 0 = timeout, 1 = got done
// ================================================================
integer wfd_result;
task wait_for_done;
input [256*8:1] op_name;
integer cyc;
begin
cyc = 0;
while (!done_o && cyc < TIMEOUT_CYCLES) begin
@(posedge clk);
cyc = cyc + 1;
end
if (cyc >= TIMEOUT_CYCLES) begin
$display("ERROR: %s timeout after %0d cycles", op_name, TIMEOUT_CYCLES);
wfd_result = 0;
end else begin
$display("INFO: %s done after %0d cycles", op_name, cyc);
wfd_result = 1;
end
end
endtask
// ================================================================
// Main test sequence
// ================================================================
initial begin
// ------------------------------------------------------------
// Count loaded vectors
// ------------------------------------------------------------
vec_count = 0;
// Load vectors from hex files
$readmemh(VECTOR_FILE, input_mem);
$readmemh(EXPECTED_FILE, expected_mem);
// Count non-X entries to determine actual vector count
begin
integer found_end;
found_end = 0;
for (idx = 0; idx < MAX_VECTORS; idx = idx + 1) begin
if (!found_end && (input_mem[idx] === 768'hx || input_mem[idx] === 768'hz))
found_end = 1;
else if (!found_end)
vec_count = vec_count + 1;
end
end
if (vec_count == 0) begin
$display("ERROR: No vectors loaded from %s", VECTOR_FILE);
$display(" Check that the file exists and is in the correct format.");
$display(" Each line: <192 hex chars> = d(64) + msg(64) + z(64)");
$finish;
end
$display("====================================================");
$display("MLKEM_TOP KAT TESTBENCH");
$display(" Vectors loaded: %0d", vec_count);
$display(" Input file: %s", VECTOR_FILE);
$display(" Expected file: %s", EXPECTED_FILE);
$display(" Timeout: %0d cycles (~%0d ms)",
TIMEOUT_CYCLES, TIMEOUT_CYCLES * 10 / 1000);
$display("====================================================");
// ------------------------------------------------------------
// Initialize signals
// ------------------------------------------------------------
mode <= 2'd0;
i_k <= 3'd2; // ML-KEM-512
valid_i <= 1'b0;
// Reset sequence: rst_n low for 3 cycles, then high
rst_n <= 1'b0;
repeat (5) @(posedge clk);
rst_n <= 1'b1;
@(posedge clk);
// ------------------------------------------------------------
// WORKAROUND: Force chain_kc_ready_o to break arbiter deadlock
// The sha3_chain_top_shared module requires kc_ready_o=1 in its
// ST_IDLE→ST_BUSY transition, but the keccak_arbiter won't
// assert cons_ready_o[0] until cons_valid_i[0]=1 (which the
// chain doesn't assert until it reaches ST_BUSY). Deadlock.
// Forcing chain_kc_ready_o=1 breaks this cycle.
//
// WORKAROUND: Force ntt_valid_o to 1 to fix done_o timing issue
// The mlkem_top FSM uses ntt_done_o to enter the output-read
// state, but ntt_core asserts done_o AFTER S_OUTPUT completes.
// Forcing ntt_valid_o=1 lets the FSM complete its output phase.
// ------------------------------------------------------------
force u_dut.chain_kc_ready_o = 1'b1;
force u_dut.ntt_valid_o = 1'b1;
$display("INFO: Forced chain_kc_ready_o=1 (arbiter deadlock workaround)");
$display("INFO: Forced ntt_valid_o=1 (ntt done_o timing workaround)");
// Reset counters
pass_count = 0;
fail_count = 0;
kg_pass = 0; kg_fail = 0;
en_pass = 0; en_fail = 0;
dc_pass = 0; dc_fail = 0;
// ============================================================
// Process each vector
// ============================================================
for (idx = 0; idx < vec_count; idx = idx + 1) begin
reg [255:0] d_val, msg_val, z_val;
reg [EXP_PK_WIDTH-1:0] exp_pk;
reg [EXP_SK_WIDTH-1:0] exp_sk;
reg [EXP_CT_WIDTH-1:0] exp_ct;
reg [EXP_SS_WIDTH-1:0] exp_ss;
// Extract test vector fields
d_val = input_mem[idx][767:512];
msg_val = input_mem[idx][511:256];
z_val = input_mem[idx][255:0];
// Extract expected outputs
exp_ss = expected_mem[idx][0 +: EXP_SS_WIDTH];
exp_ct = expected_mem[idx][EXP_SS_WIDTH +: EXP_CT_WIDTH];
exp_sk = expected_mem[idx][EXP_SS_WIDTH + EXP_CT_WIDTH +: EXP_SK_WIDTH];
exp_pk = expected_mem[idx][EXP_SS_WIDTH + EXP_CT_WIDTH + EXP_SK_WIDTH +: EXP_PK_WIDTH];
$display("----------------------------------------------------");
$display("VECTOR %0d (count=%0d)", idx, idx);
print_hex256(d_val, " d ");
print_hex256(msg_val, " msg");
print_hex256(z_val, " z ");
print_hex256(exp_ss, " expected ss");
// ========================================================
// STEP 1: KeyGen (mode=00)
// ========================================================
$display("--- KeyGen ---");
// Force d_reg to KAT value RIGHT NOW (before starting KeyGen)
// The force persists until we release it
force u_dut.d_reg = d_val;
// Start KeyGen
mode <= 2'b00;
i_k <= 3'd2;
valid_i <= 1'b1;
@(posedge clk);
valid_i <= 1'b0;
// Wait for done_o
wait_for_done("KeyGen");
if (wfd_result) begin
// Release force now that KeyGen is done
release u_dut.d_reg;
// Check pk_valid and sk_valid
if (pk_valid && sk_valid) begin
// Check pk output
if (pk_o[EXP_PK_WIDTH-1:0] == exp_pk) begin
$display(" PASS: pk matches expected");
kg_pass = kg_pass + 1;
end else begin
$display(" FAIL: pk mismatch");
print_hex256(pk_o[255:0], " pk[low] ");
print_hex256(exp_pk[255:0], " exp[low] ");
kg_fail = kg_fail + 1;
end
// Check sk output
if (sk_o[SK_WIDTH-1:0] == exp_sk[SK_WIDTH-1:0]) begin
$display(" PASS: sk matches expected");
end else begin
$display(" FAIL: sk mismatch");
kg_fail = kg_fail + 1;
end
end else begin
$display(" FAIL: pk_valid=%b sk_valid=%b", pk_valid, sk_valid);
kg_fail = kg_fail + 1;
end
end else begin
release u_dut.d_reg;
$display(" FAIL: KeyGen timeout");
kg_fail = kg_fail + 1;
// DUT is stuck. Reset for next operation.
rst_n <= 1'b0;
repeat (5) @(posedge clk);
rst_n <= 1'b1;
force u_dut.chain_kc_ready_o = 1'b1;
force u_dut.ntt_valid_o = 1'b1;
@(posedge clk);
end
// Wait for DUT to return to IDLE
repeat (2) @(posedge clk);
// ========================================================
// STEP 2: Encaps (mode=01)
// ========================================================
$display("--- Encaps ---");
// Force m_reg to KAT value
force u_dut.m_reg = msg_val;
// Start Encaps
mode <= 2'b01;
i_k <= 3'd2;
valid_i <= 1'b1;
@(posedge clk);
valid_i <= 1'b0;
// Wait for done_o
wait_for_done("Encaps");
if (wfd_result) begin
release u_dut.m_reg;
if (ct_valid && K_valid) begin
// Check ct output
if (ct_o[EXP_CT_WIDTH-1:0] == exp_ct) begin
$display(" PASS: ct matches expected");
en_pass = en_pass + 1;
end else begin
$display(" FAIL: ct mismatch");
print_hex256(ct_o[255:0], " ct[low] ");
print_hex256(exp_ct[255:0], " exp[low] ");
en_fail = en_fail + 1;
end
// Check K (shared secret)
if (K_o == exp_ss) begin
$display(" PASS: K matches expected ss");
end else begin
$display(" FAIL: K mismatch");
print_hex256(K_o, " K ");
print_hex256(exp_ss, " exp_ss");
en_fail = en_fail + 1;
end
end else begin
$display(" FAIL: ct_valid=%b K_valid=%b", ct_valid, K_valid);
en_fail = en_fail + 1;
end
end else begin
release u_dut.m_reg;
$display(" FAIL: Encaps timeout");
en_fail = en_fail + 1;
// DUT is stuck. Reset for next operation.
rst_n <= 1'b0;
repeat (5) @(posedge clk);
rst_n <= 1'b1;
force u_dut.chain_kc_ready_o = 1'b1;
force u_dut.ntt_valid_o = 1'b1;
@(posedge clk);
end
// Wait for DUT to return to IDLE
repeat (2) @(posedge clk);
// ========================================================
// STEP 3: Decaps (mode=10)
// ========================================================
$display("--- Decaps ---");
// Force z_reg to KAT value
force u_dut.z_reg = z_val;
// Start Decaps
mode <= 2'b10;
i_k <= 3'd2;
valid_i <= 1'b1;
@(posedge clk);
valid_i <= 1'b0;
// Wait for done_o
wait_for_done("Decaps");
if (wfd_result) begin
release u_dut.z_reg;
if (K_valid_dec) begin
$display(" PASS: Decaps completed (K_valid_dec asserted)");
dc_pass = dc_pass + 1;
end else begin
$display(" FAIL: Decaps K_valid_dec not asserted");
dc_fail = dc_fail + 1;
end
end else begin
release u_dut.z_reg;
$display(" FAIL: Decaps timeout (placeholder states — expected)");
dc_fail = dc_fail + 1;
// Decaps FSM is now stuck. Reset DUT so next vector
// can start with a clean state.
rst_n <= 1'b0;
repeat (5) @(posedge clk);
rst_n <= 1'b1;
// Re-apply workaround forces (reset may have cleared them)
force u_dut.chain_kc_ready_o = 1'b1;
force u_dut.ntt_valid_o = 1'b1;
@(posedge clk);
end
// Wait for DUT to return to IDLE
repeat (2) @(posedge clk);
end
// ------------------------------------------------------------
// Release deadlock workarounds
// ------------------------------------------------------------
release u_dut.chain_kc_ready_o;
release u_dut.ntt_valid_o;
// ============================================================
// Summary
// ============================================================
$display("====================================================");
$display("TEST COMPLETE");
$display(" KeyGen: PASS=%0d FAIL=%0d", kg_pass, kg_fail);
$display(" Encaps: PASS=%0d FAIL=%0d", en_pass, en_fail);
$display(" Decaps: PASS=%0d FAIL=%0d", dc_pass, dc_fail);
$display(" Total: PASS=%0d FAIL=%0d",
kg_pass + en_pass + dc_pass,
kg_fail + en_fail + dc_fail);
$display("====================================================");
$finish;
end
// ================================================================
// Timeout watchdog
// ================================================================
initial begin
#(TIMEOUT_CYCLES * 10 * 100); // TIMEOUT_CYCLES * 10ns * extra margin
$display("FATAL: Global simulation timeout reached (%0d ns)",
TIMEOUT_CYCLES * 10 * 100);
$finish;
end
endmodule

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

@@ -1,187 +0,0 @@
# NOTE: On some systems, you may need:
# export LD_PRELOAD=/usr/lib64/libtinfo.so.5
# before running this script.
# xsim_run.tcl - Vivado xsim compilation and simulation for mlkem_top KAT testbench
#
# Compiles ALL RTL dependencies for mlkem_top plus the testbench.
# Run from the project root: ~/Dev/mlkem/
#
# Prerequisites:
# source /opt/Xilinx/Vivado/2019.2/settings64.sh
#
# Usage examples:
# # Run mlkem_top KAT testbench
# xsim tb_mlkem_top_xsim -R
#
# # Step-by-step:
# vivado -mode batch -source sync_rtl/top/TB/xsim_run.tcl
#
# # Or via run_tb.sh:
# ./run_tb.sh mlkem_top
# ================================================================
# Configuration
# ================================================================
set COMMON_DIR sync_rtl/common
set SHA3_DIR sync_rtl/sha3
set SHA3C_DIR sync_rtl/sha3_chain
set RNG_DIR sync_rtl/rng
set NTT_DIR sync_rtl/ntt
set PA_DIR sync_rtl/poly_arith
set PM_DIR sync_rtl/poly_mul
set CBD_DIR sync_rtl/sample_cbd
set SNT_DIR sync_rtl/sample_ntt
set CD_DIR sync_rtl/comp_decomp
set MA_DIR sync_rtl/mod_add
set STOR_DIR sync_rtl/storage
set TOP_DIR sync_rtl/top
set TB_DIR sync_rtl/top/TB
# ================================================================
# Step 1: Compile common infrastructure
# ================================================================
puts "=== Compiling common infrastructure ==="
# Pipeline register (used by many modules)
xvlog -sv -i . ${COMMON_DIR}/pipeline_reg.v
# Skid buffer (backpressure buffer)
xvlog -sv -i . ${COMMON_DIR}/skid_buffer.v
# ================================================================
# Step 2: Compile SHA3 / Keccak core
# ================================================================
puts "=== Compiling SHA3/Keccak core ==="
# Keccak round (combinational, θ/ρ/π/χ/ι)
xvlog -sv ${SHA3_DIR}/keccak_round.v
# Keccak core (24-round sequential keccak-f[1600])
xvlog -sv ${SHA3_DIR}/keccak_core.v
# SHA3 top wrapper (G/H/J modes, with internal keccak_core)
xvlog -sv -i . ${SHA3_DIR}/sha3_top.v
# ================================================================
# Step 3: Compile SHA3 chain (G function)
# ================================================================
puts "=== Compiling SHA3 chain ==="
# sha3_chain_top_shared (G: d → rho, sigma, with external keccak_core)
xvlog -sv -i . ${SHA3C_DIR}/sha3_chain_top_shared.v
# ================================================================
# Step 4: Compile RNG
# ================================================================
puts "=== Compiling RNG ==="
# rng_sync (256-bit Galois LFSR)
xvlog -sv ${RNG_DIR}/rng_sync.v
# ================================================================
# Step 5: Compile NTT core and dependencies
# ================================================================
puts "=== Compiling NTT core ==="
# Zeta ROM (twiddle factors, 128 × 12-bit)
xvlog -sv ${NTT_DIR}/zeta_rom.v
# Barrett modular multiplier (a·b mod q)
xvlog -sv ${NTT_DIR}/barrett_mul.v
# Butterfly unit (CT/GS butterfly for NTT/INTT)
xvlog -sv ${NTT_DIR}/butterfly_unit.v
# NTT core (256-coeff NTT/INTT FSM)
xvlog -sv -i . ${NTT_DIR}/ntt_core.v
# ================================================================
# Step 6: Compile polynomial arithmetic
# ================================================================
puts "=== Compiling polynomial arithmetic ==="
# poly_arith_sync (element-wise poly add/sub)
xvlog -sv ${PA_DIR}/poly_arith_sync.v
# ================================================================
# Step 7: Compile polynomial multiplication
# ================================================================
puts "=== Compiling polynomial multiplication ==="
# Zeta ROM for poly_mul (degree-1 basecase)
xvlog -sv ${PM_DIR}/poly_mul_zeta_rom.v
# Basecase multiplier (degree-1 Karatsuba)
xvlog -sv ${PM_DIR}/basecase_mul.v
# poly_mul_sync (NTT-domain polynomial multiplier)
xvlog -sv -i . ${PM_DIR}/poly_mul_sync.v
# ================================================================
# Step 8: Compile sampling modules
# ================================================================
puts "=== Compiling sampling modules ==="
# sample_cbd_sync_shared (CBD sampling with external keccak)
xvlog -sv -i . ${CBD_DIR}/sample_cbd_sync_shared.v
# sample_ntt_sync_shared (SampleNTT with external keccak)
xvlog -sv -i . ${SNT_DIR}/sample_ntt_sync_shared.v
# ================================================================
# Step 9: Compile compression and modular arithmetic
# ================================================================
puts "=== Compiling compression and modular arithmetic ==="
# comp_decomp_sync (Compress_q / Decompress_q)
xvlog -sv ${CD_DIR}/comp_decomp_sync.v
# mod_add_sync ((a + b) mod q, streaming)
xvlog -sv ${MA_DIR}/mod_add_sync.v
# ================================================================
# Step 10: Compile storage (BRAM)
# ================================================================
puts "=== Compiling storage BRAMs ==="
# Single-port BRAM
xvlog -sv ${STOR_DIR}/s_bram.v
# Simple dual-port BRAM
xvlog -sv ${STOR_DIR}/sd_bram.v
# ================================================================
# Step 11: Compile top-level integration
# ================================================================
puts "=== Compiling top-level integration ==="
# keccak_arbiter (round-robin arbiter for shared keccak)
xvlog -sv -i . ${TOP_DIR}/keccak_arbiter.v
# mlkem_top (top-level KeyGen/Encaps/Decaps FSM)
xvlog -sv -i . ${TOP_DIR}/mlkem_top.v
# ================================================================
# Step 12: Compile testbench
# ================================================================
puts "=== Compiling testbench ==="
# tb_mlkem_top_xsim (KAT vector testbench)
xvlog -sv ${TB_DIR}/tb_mlkem_top_xsim.v
# ================================================================
# Step 13: Elaborate snapshot (xelab)
# ================================================================
puts "=== Elaborating snapshot ==="
xelab tb_mlkem_top_xsim -s tb_mlkem_top_xsim --timescale 1ns/1ps
# ================================================================
# Step 14: Run simulation
# ================================================================
puts ""
puts "=== Running mlkem_top KAT simulation ==="
xsim tb_mlkem_top_xsim -R
puts ""
puts "=== mlkem_top simulation complete ==="