feat: init mlkem project with Verilator test framework

- sync_rtl/common/: skid_buffer, pipeline_reg, defines (valid/ready)
- sync_rtl/mod_add/: modular adder example with Verilator C++ TB
- test_framework/: Python-driven Verilator compile/sim/compare pipeline
- test_framework/modules/mod_add/: 50-vector test plan, full鏈路 PASS
- .trellis/spec/: RTL and test_framework conventions documented

sync_rtl/mod_add/TB/tb_mod_add.cpp

@@ -0,0 +1,120 @@
+// tb_mod_add.cpp - Verilator C++ testbench for mod_add_sync
+//
+// Reads test vectors from a hex file specified by +VECTOR_FILE= plusarg.
+// Each line: "AAA BBB" (two 12-bit hex operands).
+// Drives the DUT, waits for valid_o, writes "RESULT: CCC" to stdout.
+//
+// Clock: CLK_PERIOD ns period (from defines.vh).
+// Reset: 2 cycles low, then high.
+// Timeout: 100,000 cycles.
+
+#include <iostream>
+#include <fstream>
+#include <string>
+#include <sstream>
+#include <cstdlib>
+#include "Vmod_add_sync.h"
+#include "verilated.h"
+
+#define CLK_PERIOD_NS    10.0
+#define TIMEOUT_CYCLES   100000
+#define Q                3329
+
+static vluint64_t main_time = 0;
+
+double sc_time_stamp() {
+    return main_time;
+}
+
+int main(int argc, char** argv) {
+    Verilated::commandArgs(argc, argv);
+
+    // Parse +VECTOR_FILE= plusarg
+    const char* vector_file = NULL;
+    for (int i = 1; i < argc; i++) {
+        std::string arg(argv[i]);
+        if (arg.rfind("+VECTOR_FILE=", 0) == 0) {
+            vector_file = argv[i] + 13; // skip "+VECTOR_FILE="
+        }
+    }
+
+    if (!vector_file) {
+        std::cerr << "ERROR: +VECTOR_FILE= not specified" << std::endl;
+        return 1;
+    }
+
+    std::ifstream infile(vector_file);
+    if (!infile.is_open()) {
+        std::cerr << "ERROR: Cannot open vector file: " << vector_file << std::endl;
+        return 1;
+    }
+
+    // Instantiate DUT
+    Vmod_add_sync* dut = new Vmod_add_sync;
+
+    // Initialize
+    dut->clk    = 0;
+    dut->rst_n  = 0;
+    dut->a      = 0;
+    dut->b      = 0;
+    dut->valid_i = 0;
+    dut->ready_i = 0;
+
+    // Reset: 2 cycles low
+    for (int i = 0; i < 4; i++) {
+        dut->clk = !dut->clk;
+        main_time += (vluint64_t)(CLK_PERIOD_NS / 2.0);
+        dut->eval();
+        dut->clk = !dut->clk;
+        main_time += (vluint64_t)(CLK_PERIOD_NS / 2.0);
+        dut->eval();
+    }
+    dut->rst_n = 1;
+
+    // Always ready to receive results
+    dut->ready_i = 1;
+
+    std::string line;
+    vluint64_t cycle = 0;
+    bool waiting_result = false;
+
+    while (std::getline(infile, line)) {
+        // Skip empty lines and comments
+        if (line.empty() || line[0] == '#') continue;
+
+        // Parse hex operands
+        std::istringstream iss(line);
+        unsigned int a_val, b_val;
+        if (!(iss >> std::hex >> a_val >> b_val)) continue;
+
+        dut->a       = a_val & 0xFFF;
+        dut->b       = b_val & 0xFFF;
+        dut->valid_i = 1;
+
+        // posedge: DUT samples valid_i, pipeline_reg captures data, valid_o→1
+        dut->clk = !dut->clk;
+        main_time += (vluint64_t)(CLK_PERIOD_NS / 2.0);
+        dut->eval();
+        dut->clk = !dut->clk;
+        main_time += (vluint64_t)(CLK_PERIOD_NS / 2.0);
+        dut->eval();
+        cycle++;
+        dut->valid_i = 0;
+
+        // posedge: pipeline_reg clears valid_o (ready_i=1), but result is
+        // available on sum port right now (combinational from data_r)
+        dut->clk = !dut->clk;
+        main_time += (vluint64_t)(CLK_PERIOD_NS / 2.0);
+        dut->eval();
+        dut->clk = !dut->clk;
+        main_time += (vluint64_t)(CLK_PERIOD_NS / 2.0);
+        dut->eval();
+        cycle++;
+
+        printf("RESULT: %03X\n", dut->sum & 0xFFF);
+    }
+
+    infile.close();
+    delete dut;
+    return 0;
+}

sync_rtl/mod_add/mod_add_sync.v

@@ -0,0 +1,47 @@
+// mod_add_sync.v - Synchronous modular adder for ML-KEM
+//
+// Computes (a + b) mod Q where Q = 3329.
+// Uses pipeline_reg internally for the computation stage.
+// Result is valid one cycle after valid_i && ready_o.
+//
+// Interface:
+//   clk, rst_n    - clock, active-low reset
+//   a, b          - operands (0 <= a,b < Q)
+//   valid_i, ready_o, sum, valid_o, ready_i - valid/ready handshake
+
+`include "sync_rtl/common/defines.vh"
+
+module mod_add_sync (
+    input         clk,
+    input         rst_n,
+    input  [11:0] a,
+    input  [11:0] b,
+    input         valid_i,
+    output        ready_o,
+    output [11:0] sum,
+    output        valid_o,
+    input         ready_i
+);
+
+    // Compute (a + b) mod Q
+    wire [12:0] add_raw;       // 13 bits to hold potential overflow
+    wire [11:0] add_sub_q;     // (a + b) - Q
+    wire [11:0] mod_result;    // final (a + b) mod Q
+
+    assign add_raw   = {1'b0, a} + {1'b0, b};
+    assign add_sub_q = add_raw[11:0] - `Q;
+    assign mod_result = (add_raw < `Q) ? add_raw[11:0] : add_sub_q;
+
+    // Pipeline the result through pipeline_reg
+    pipeline_reg #(.DW(12)) u_pipe (
+        .clk    (clk),
+        .rst_n  (rst_n),
+        .data_i (mod_result),
+        .valid_i(valid_i),
+        .ready_o(ready_o),
+        .data_o (sum),
+        .valid_o(valid_o),
+        .ready_i(ready_i)
+    );
+
+endmodule