feat(tb): add Vivado XSIM Verilog testbenches for all 10 sync modules

Add file-based vector testbenches ( + ) for: - mod_add_sync, rng_sync, poly_arith_sync, comp_decomp_sync - s_bram/sd_bram, sha3_chain_top - ntt_core, poly_mul_sync - sample_cbd_sync, sample_ntt_sync Each module includes: - tb_<module>_xsim.v: Vivado XSIM testbench - gen_vectors.py: Python vector generator (stdlib only) - vectors/<module>_input.hex: test input vectors - xsim_run.tcl: compile + elaborate + simulate script
2026-06-25 20:48:38 +08:00
parent ae5f0ca048
commit d4c3fc86fc
42 changed files with 7745 additions and 0 deletions
--- a/sync_rtl/rng/TB/gen_vectors.py
+++ b/sync_rtl/rng/TB/gen_vectors.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Generate expected LFSR output states for rng_sync module.
+
+Computes the Galois LFSR sequence for the RTL default seed and writes
+expected states to rng_input.hex (one 256-bit hex word per line).
+
+The RTL uses a Galois LFSR with taps at bits 255, 253, 252, 247, 0.
+
+On each valid_i pulse, the LFSR advances to the next state. valid_o
+is asserted the following cycle with data_o = new state.
+"""
+
+import os
+
+# Default seed from rng_sync.v
+SEED = 0xDEADBEEFCAFEBABEFEEDFACEDECAFBAD1234567887654321ABCDEF010FEDCBA9
+
+# Number of test vectors to generate
+NUM_VECTORS = 32
+
+
+def lfsr_advance(state):
+    """
+    Advance the 256-bit Galois LFSR by one step.
+
+    RTL tap positions (0-indexed): 255, 253, 252, 247, 0.
+
+    Algorithm (matching the RTL):
+      1. feedback = state[0] (LSB)
+      2. Shift right by 1: lfsr_next[i] = state[i+1] for i=0..254
+      3. lfsr_next[255] = feedback
+      4. XOR feedback into lfsr_next at tap-derived positions:
+         - bit 254 (tap 255 after shift: 255 -> 254)
+         - bit 252 (tap 253 after shift: 253 -> 252)
+         - bit 251 (tap 252 after shift: 252 -> 251)
+         - bit 246 (tap 247 after shift: 247 -> 246)
+    """
+    feedback = state & 1
+
+    # Shift right by 1
+    next_state = state >> 1
+
+    # MSB gets feedback
+    if feedback:
+        next_state |= (1 << 255)
+
+    # XOR feedback at tap-derived positions
+    if feedback:
+        next_state ^= (1 << 254)
+        next_state ^= (1 << 252)
+        next_state ^= (1 << 251)
+        next_state ^= (1 << 246)
+
+    return next_state
+
+
+def format_hex_256(val):
+    """Format 256-bit integer as 64-character hex string."""
+    return f"{val:064x}"
+
+
+def main():
+    vectors_dir = os.path.join(os.path.dirname(__file__), "vectors")
+    os.makedirs(vectors_dir, exist_ok=True)
+
+    output_path = os.path.join(vectors_dir, "rng_input.hex")
+
+    state = SEED
+    with open(output_path, "w") as f:
+        print(f"Seed: {format_hex_256(SEED)}")
+        print(f"Generating {NUM_VECTORS} expected LFSR states...")
+        print()
+
+        for i in range(NUM_VECTORS):
+            # Each valid_i advances the LFSR; the next state is what
+            # appears on data_o when valid_o is asserted.
+            state = lfsr_advance(state)
+            f.write(format_hex_256(state) + "\n")
+            print(f"[{i:3d}] step {i+1}: {format_hex_256(state)}")
+
+    print(f"\nWrote {NUM_VECTORS} vectors to {output_path}")
+
+
+if __name__ == "__main__":
+    main()
--- a/sync_rtl/rng/TB/tb_rng_xsim.v
+++ b/sync_rtl/rng/TB/tb_rng_xsim.v
@@ -0,0 +1,230 @@
+// tb_rng_xsim.v - Standard Verilog testbench for rng_sync targeting Vivado xsim
+//
+// Reads expected LFSR output states from a hex file using $readmemh.
+// Each line is a single 256-bit hex number = expected data_o after
+// each valid_i pulse.
+//
+// Drives rng_sync, toggles valid_i for each vector, captures data_o,
+// compares against expected value, and writes pass/fail results.
+//
+// Parameters:
+//   VECTOR_FILE - path to input hex file (default: "vectors/rng_input.hex")
+//   RESULT_FILE - path to output file    (default: "vectors/rng_result.hex")
+//
+// Usage:
+//   xvlog -sv sync_rtl/rng/rng_sync.v
+//   xvlog -sv sync_rtl/rng/TB/tb_rng_xsim.v
+//   xelab tb_rng_xsim -s tb_rng_xsim
+//   xsim tb_rng_xsim -R
+
+`timescale 1ns / 1ps
+
+module tb_rng_xsim;
+
+    // ================================================================
+    // Parameters
+    // ================================================================
+    parameter VECTOR_FILE = "sync_rtl/rng/TB/vectors/rng_input.hex";
+    parameter RESULT_FILE = "sync_rtl/rng/TB/vectors/rng_result.hex";
+    parameter MAX_VECTORS = 256;
+    parameter TIMEOUT_CYCLES = 1000;
+
+    // ================================================================
+    // DUT signals
+    // ================================================================
+    reg              clk;
+    reg              rst_n;
+    reg              valid_i;
+    wire             ready_o;
+    wire [255:0]     data_o;
+    wire             valid_o;
+    reg              ready_i;
+
+    // ================================================================
+    // DUT instantiation
+    // ================================================================
+    rng_sync u_dut (
+        .clk     (clk),
+        .rst_n   (rst_n),
+        .valid_i (valid_i),
+        .ready_o (ready_o),
+        .data_o  (data_o),
+        .valid_o (valid_o),
+        .ready_i (ready_i)
+    );
+
+    // ================================================================
+    // Clock generation: 100 MHz (10 ns period)
+    // ================================================================
+    initial clk = 1'b0;
+    always #5 clk = ~clk;
+
+    // ================================================================
+    // Vector memory (loaded by $readmemh)
+    // Each word is 256 bits = the expected data_o value
+    // ================================================================
+    reg [255:0] vector_mem [0:MAX_VECTORS-1];
+    integer     vec_count;
+    integer     idx;
+    integer     cycle_count;
+    integer     result_fd;
+
+    // Test result tracking
+    integer     pass_count;
+    integer     fail_count;
+
+    // ================================================================
+    // 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};  // '0'-'9'
+            else
+                nibble_to_ascii = 8'h41 + ({4'd0, nibble} - 4'd10); // 'A'-'F'
+        end
+    endfunction
+
+    // Helper: write 256-bit value as 64 hex chars to file
+    task write_hex_256bit;
+        input integer fd;
+        input [255:0] val;
+        reg [3:0] nib;
+        integer j;
+        begin
+            for (j = 63; j >= 0; j = j - 1) begin
+                nib = val[(j*4)+:4];
+                $fwrite(fd, "%c", nibble_to_ascii(nib));
+            end
+        end
+    endtask
+
+    // ================================================================
+    // Main test sequence
+    // ================================================================
+    initial begin
+        // Count loaded vectors
+        vec_count = 0;
+
+        // Load vectors from hex file
+        $readmemh(VECTOR_FILE, vector_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 && (vector_mem[idx] === 256'hx || vector_mem[idx] === 256'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: <64 hex chars> = expected 256-bit LFSR state");
+            $finish;
+        end
+
+        $display("INFO: Loaded %0d expected LFSR states from %s", vec_count, VECTOR_FILE);
+
+        // Open result file
+        result_fd = $fopen(RESULT_FILE, "w");
+        if (result_fd == 0) begin
+            $display("ERROR: Cannot open result file: %s", RESULT_FILE);
+            $finish;
+        end
+
+        // Initialize DUT inputs
+        valid_i <= 1'b0;
+        ready_i <= 1'b1;  // always ready to accept output
+
+        // Reset sequence: rst_n low for 3 cycles, then high
+        rst_n <= 1'b0;
+        repeat (3) @(posedge clk);
+        rst_n <= 1'b1;
+        @(posedge clk);
+
+        pass_count = 0;
+        fail_count = 0;
+
+        // ============================================================
+        // Process each vector
+        // ============================================================
+        for (idx = 0; idx < vec_count; idx = idx + 1) begin
+            begin
+                reg [255:0] expected;
+                reg [255:0] captured;
+
+                expected = vector_mem[idx];
+
+                $display("INFO: Vector %0d", idx);
+
+                // Drive DUT: pulse valid_i for one cycle
+                valid_i <= 1'b1;
+                @(posedge clk);
+                valid_i <= 1'b0;
+
+                // Wait for valid_o
+                cycle_count = 0;
+                while (!valid_o && cycle_count < TIMEOUT_CYCLES) begin
+                    @(posedge clk);
+                    cycle_count = cycle_count + 1;
+                end
+
+                if (cycle_count >= TIMEOUT_CYCLES) begin
+                    $display("ERROR: Timeout waiting for valid_o on vector %0d", idx);
+                    $fwrite(result_fd, "FAIL: %0d - timeout\n", idx);
+                    fail_count = fail_count + 1;
+                end else begin
+                    // Capture output
+                    captured = data_o;
+
+                    // Compare with expected
+                    if (captured === expected) begin
+                        $display("  PASS: data_o matches expected");
+                        $fwrite(result_fd, "PASS: %0d\n", idx);
+                        pass_count = pass_count + 1;
+                    end else begin
+                        $display("  FAIL: data_o mismatch");
+                        $display("    Expected: %h", expected);
+                        $display("    Got:      %h", captured);
+                        $fwrite(result_fd, "FAIL: %0d - mismatch (expected mask)\n", idx);
+                        fail_count = fail_count + 1;
+                    end
+                end
+
+                // One extra cycle for valid_o handshake with ready_i
+                @(posedge clk);
+            end
+        end
+
+        // ============================================================
+        // Summary
+        // ============================================================
+        $fclose(result_fd);
+
+        $display("========================================");
+        $display("TEST COMPLETE");
+        $display("  Total vectors: %0d", vec_count);
+        $display("  Passed:        %0d", pass_count);
+        $display("  Failed:        %0d", fail_count);
+        $display("  Results written to: %s", RESULT_FILE);
+        $display("========================================");
+
+        $finish;
+    end
+
+    // ================================================================
+    // Timeout watchdog
+    // ================================================================
+    initial begin
+        #(TIMEOUT_CYCLES * 10 * 100);  // TIMEOUT_CYCLES * 10ns per cycle * extra margin
+        $display("FATAL: Global simulation timeout reached");
+        $finish;
+    end
+
+endmodule
--- a/sync_rtl/rng/TB/vectors/rng_input.hex
+++ b/sync_rtl/rng/TB/vectors/rng_input.hex
@@ -0,0 +1,32 @@
+b716df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f78087f6e5d4
+5b8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc043fb72ea
+2dc5b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde021fdb975
+cea2dbeefcafebabefeedfacedecafbad1234567887654321abcdef010fedcba
+67516df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f78087f6e5d
+ebe8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc043fb72e
+75f45b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde021fdb97
+e2ba2dbeefcafebabefeedfacedecafbad1234567887654321abcdef010fedcb
+a91d16df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f78087f6e5
+8cce8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc043fb72
+466745b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde021fdb9
+fb73a2dbeefcafebabefeedfacedecafbad1234567887654321abcdef010fedc
+7db9d16df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f78087f6e
+3edce8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc043fb7
+c72e745b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde021fdb
+bbd73a2dbeefcafebabefeedfacedecafbad1234567887654321abcdef010fed
+85ab9d16df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f78087f6
+42d5ce8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc043fb
+f92ae745b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde021fd
+a4d573a2dbeefcafebabefeedfacedecafbad1234567887654321abcdef010fe
+526ab9d16df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f78087f
+f1755ce8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc043f
+a0faae745b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde021f
+883d573a2dbeefcafebabefeedfacedecafbad1234567887654321abcdef010f
+9c5eab9d16df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f78087
+966f55ce8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc043
+9377aae745b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde021
+91fbd573a2dbeefcafebabefeedfacedecafbad1234567887654321abcdef010
+48fdeab9d16df77e57f5d5f7f76fd676f657dd6891a2b3c43b2a190d5e6f7808
+247ef55ce8b6fbbf2bfaeafbfbb7eb3b7b2beeb448d159e21d950c86af37bc04
+123f7aae745b7ddf95fd757dfddbf59dbd95f75a2468acf10eca8643579bde02
+091fbd573a2dbeefcafebabefeedfacedecafbad1234567887654321abcdef01
--- a/sync_rtl/rng/TB/xsim_run.tcl
+++ b/sync_rtl/rng/TB/xsim_run.tcl
@@ -0,0 +1,54 @@
+# xsim_run.tcl - Vivado xsim compilation and simulation script for rng_sync
+#
+# Compiles rng_sync RTL plus the file-based vector testbench and runs simulation.
+# Run from the project root: ~/Dev/mlkem/
+#
+# Prerequisites:
+#   source /opt/Xilinx/Vivado/2019.2/settings64.sh
+#
+# Usage:
+#   vivado -mode batch -source sync_rtl/rng/TB/xsim_run.tcl
+#
+#   # Or step-by-step:
+#   xvlog -sv sync_rtl/rng/rng_sync.v
+#   xvlog -sv sync_rtl/rng/TB/tb_rng_xsim.v
+#   xelab tb_rng_xsim -s tb_rng_xsim
+#   xsim tb_rng_xsim -R
+
+# ================================================================
+# Configuration
+# ================================================================
+set SRC_DIR  sync_rtl/rng
+set TB_DIR   sync_rtl/rng/TB
+
+# ================================================================
+# Step 1: Compile all source files (xvlog)
+# ================================================================
+puts "=== Compiling RTL sources ==="
+
+# rng_sync (self-contained, no external dependencies)
+xvlog -sv ${SRC_DIR}/rng_sync.v
+
+# ================================================================
+# Step 2: Compile testbench
+# ================================================================
+puts "=== Compiling testbench ==="
+
+# File-based vector testbench
+xvlog -sv ${TB_DIR}/tb_rng_xsim.v
+
+# ================================================================
+# Step 3: Elaborate snapshot (xelab)
+# ================================================================
+puts "=== Elaborating snapshot ==="
+
+xelab tb_rng_xsim -s tb_rng_xsim
+
+# ================================================================
+# Step 4: Run simulation
+# ================================================================
+puts "=== Running rng_sync file-based vector test ==="
+xsim tb_rng_xsim -R
+
+puts ""
+puts "=== rng_sync simulation complete ==="