feat(phase3): implement storage BRAMs and Compress/Decompress

Phase 3.1 + 3.3:
- sd_bram.v: simple dual-port RAM (behavioral, auto-infer to BRAM)
- s_bram.v: single-port RAM (rd_en/wr_en, write priority)
- comp_decomp_sync.v: streaming compress/decompress with round-half-up

Verified: storage 5/5, comp_decomp 60/60 all PASS

sync_rtl/comp_decomp/TB/tb_comp_decomp.cpp

@@ -0,0 +1,125 @@
+// tb_comp_decomp.cpp - Verilator C++ testbench for comp_decomp_sync
+//
+// Reads test vectors from a hex file specified by +VECTOR_FILE= plusarg.
+// Each line: "MODE D COEFF" (e.g. "C A 3FF" for compress d=10 coeff=0x3FF).
+// MODE: 'C' for compress, 'D' for decompress.
+// Drives the DUT, waits for valid_o, writes "RESULT: COEFF" to stdout.
+//
+// Clock: 10 ns period. Reset: 2 cycles low. Timeout: 100,000 cycles.
+
+#include <iostream>
+#include <fstream>
+#include <string>
+#include <sstream>
+#include <cstdlib>
+#include "Vcomp_decomp_sync.h"
+#include "verilated.h"
+
+#define CLK_PERIOD_NS    10.0
+#define TIMEOUT_CYCLES   100000
+
+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
+    Vcomp_decomp_sync* dut = new Vcomp_decomp_sync;
+
+    // Initialize
+    dut->clk      = 0;
+    dut->rst_n    = 0;
+    dut->coeff_in = 0;
+    dut->d        = 0;
+    dut->mode     = 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;
+
+    while (std::getline(infile, line)) {
+        // Skip empty lines and comments
+        if (line.empty() || line[0] == '#') continue;
+
+        // Parse: MODE D COEFF
+        std::istringstream iss(line);
+        char mode_char;
+        unsigned int d_val, coeff_val;
+        if (!(iss >> mode_char >> std::hex >> d_val >> coeff_val)) continue;
+
+        if (mode_char == 'C')
+            dut->mode = 0;
+        else if (mode_char == 'D')
+            dut->mode = 1;
+        else
+            continue;
+
+        dut->d        = d_val & 0x1F;
+        dut->coeff_in = coeff_val & 0xFFF;
+        dut->valid_i  = 1;
+
+        // posedge: DUT samples valid_i, pipeline_reg captures data
+        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 sends result out (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++;
+
+        printf("RESULT: %03X\n", dut->coeff_out & 0xFFF);
+    }
+
+    infile.close();
+    delete dut;
+    return 0;
+}

sync_rtl/comp_decomp/comp_decomp_sync.v

@@ -0,0 +1,74 @@
+// comp_decomp_sync.v - ML-KEM coefficient compression/decompression
+//
+// Streaming: one coefficient per cycle through pipeline_reg.
+// mode=0: compress   — round((2^d * x) / Q) mod 2^d
+// mode=1: decompress — round((Q * x) / 2^d) mod Q
+// Uses round-half-up (round(2.5)=3, round(3.5)=4).
+// Integer arithmetic:
+//   compress:   (x * 2^d + Q/2) / Q,  lower d bits as result
+//   decompress: (x * Q + 2^(d-1)) / 2^d, result (always < Q)
+
+`include "sync_rtl/common/defines.vh"
+
+module comp_decomp_sync (
+    input         clk,
+    input         rst_n,
+    input  [11:0] coeff_in,
+    input  [4:0]  d,
+    input         mode,          // 0=compress, 1=decompress
+    input         valid_i,
+    output        ready_o,
+    output [11:0] coeff_out,
+    output        valid_o,
+    input         ready_i
+);
+
+    // 2^d for d in {4,5,10,11}; fits in 12 bits (max 2048)
+    wire [11:0] two_pow_d;
+    assign two_pow_d = 12'd1 << d;
+
+    // Product: 12-bit * 12-bit = max 2048*3328 = 6,815,744 → 23 bits (use 24)
+    wire [23:0] product;
+
+    // compress: x * 2^d;  decompress: x * Q
+    assign product = mode ? {12'b0, coeff_in} * {12'b0, 12'(`Q)}
+                          : {12'b0, coeff_in} * {12'b0, two_pow_d};
+
+    // Rounding offset: compress→Q/2=1664; decompress→2^(d-1)
+    wire [11:0] round_off;
+    assign round_off = mode ? (two_pow_d >> 1) : 12'd1664;
+
+    // Dividend = product + round_off  (max ~ 6,817,408 fits in 24 bits)
+    wire [23:0] dividend;
+    assign dividend = product + {12'b0, round_off};
+
+    // Divisor: compress→Q=3329; decompress→2^d
+    wire [11:0] divisor;
+    assign divisor = mode ? two_pow_d : 12'(`Q);
+
+    // Integer division (both ops positive → floor)
+    // Quotient is computed as 24b (widest operand) but fits in 12b
+    /* verilator lint_off WIDTHTRUNC */
+    wire [11:0] div_result;
+    assign div_result = dividend / {12'b0, divisor};
+    /* verilator lint_on WIDTHTRUNC */
+
+    // Final modular reduction
+    // compress: lower d bits  (mask with 2^d - 1)
+    // decompress: result < Q always, but apply mod Q for safety
+    wire [11:0] mod_result;
+    assign mod_result = mode ? (div_result % 12'(`Q)) : (div_result & (two_pow_d - 1'b1));
+
+    // Pipeline through valid/ready stage
+    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 (coeff_out),
+        .valid_o(valid_o),
+        .ready_i(ready_i)
+    );
+
+endmodule

sync_rtl/storage/TB/tb_storage.cpp

@@ -0,0 +1,111 @@
+// tb_storage.cpp - Verilator C++ testbench for storage (sd_bram top)
+//
+// Reads test vectors from +VECTOR_FILE= hex file.
+// Format: "ADDR DATA" per line (addr in 2-char hex, data in 12-char hex).
+// Writes values via sd_bram, reads back, prints "RESULT: VAL_HEX".
+// s_bram is compiled as rtl_dep.
+//
+// Clock: 10ns period. W=48, D=64, A=6 (default sd_bram parameters).
+
+#include <iostream>
+#include <fstream>
+#include <string>
+#include <sstream>
+#include <vector>
+#include <cstdint>
+#include "Vsd_bram.h"
+#include "verilated.h"
+
+#define CLK_HALF_PS 5000
+
+static vluint64_t main_time = 0;
+
+double sc_time_stamp() {
+    return (double)main_time / 1000.0;
+}
+
+static void tick(Vsd_bram* dut) {
+    dut->clk = 1;
+    main_time += CLK_HALF_PS;
+    dut->eval();
+    dut->clk = 0;
+    main_time += CLK_HALF_PS;
+    dut->eval();
+}
+
+int main(int argc, char** argv) {
+    Verilated::commandArgs(argc, argv);
+
+    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;
+            break;
+        }
+    }
+
+    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;
+    }
+
+    struct Vec { int addr; uint64_t data; };
+    std::vector<Vec> vectors;
+
+    std::string line;
+    while (std::getline(infile, line)) {
+        if (line.empty() || line[0] == '#') continue;
+        std::istringstream iss(line);
+        int a;
+        uint64_t d;
+        if (!(iss >> std::hex >> a >> d)) continue;
+        if (a < 0 || a > 63) continue;
+        vectors.push_back({a, d & 0xFFFFFFFFFFFFULL});
+    }
+    infile.close();
+
+    if (vectors.empty()) {
+        std::cerr << "ERROR: No valid vectors in file" << std::endl;
+        return 1;
+    }
+
+    Vsd_bram* dut = new Vsd_bram;
+
+    dut->clk     = 0;
+    dut->rd_addr = 0;
+    dut->wr_en   = 0;
+    dut->wr_addr = 0;
+    dut->wr_data = 0;
+    dut->eval();
+    main_time += CLK_HALF_PS;
+    dut->eval();
+
+    // --- WRITE PHASE ---
+    for (size_t i = 0; i < vectors.size(); i++) {
+        dut->wr_en   = 1;
+        dut->wr_addr = vectors[i].addr & 0x3F;
+        dut->wr_data = vectors[i].data & 0xFFFFFFFFFFFFULL;
+        tick(dut);
+    }
+    dut->wr_en   = 0;
+    dut->wr_addr = 0;
+    dut->wr_data = 0;
+    tick(dut);
+
+    // --- READ PHASE ---
+    for (size_t i = 0; i < vectors.size(); i++) {
+        dut->rd_addr = vectors[i].addr & 0x3F;
+        tick(dut);
+        printf("RESULT: %012lX\n", (unsigned long)(dut->rd_data & 0xFFFFFFFFFFFFULL));
+    }
+
+    delete dut;
+    return 0;
+}

sync_rtl/storage/s_bram.v

@@ -0,0 +1,31 @@
+// s_bram.v - Single-port behavioral RAM (shared read/write port)
+//
+// One port: either read or write per cycle (+1 cycle read latency).
+// When both rd_en and wr_en are high, write takes priority.
+// Read data is registered (1-cycle latency after rd_en).
+// No valid/ready handshake — pure memory, handshake managed at higher level.
+
+module s_bram #(
+    parameter W = 48,
+    parameter D = 512,
+    parameter A = 9
+) (
+    input  wire          clk,
+    input  wire          rd_en,
+    input  wire [A-1:0]  rd_addr,
+    output reg  [W-1:0]  rd_data,
+    input  wire          wr_en,
+    input  wire [A-1:0]  wr_addr,
+    input  wire [W-1:0]  wr_data
+);
+
+    reg [W-1:0] mem [0:D-1];
+
+    always @(posedge clk) begin
+        if (wr_en)
+            mem[wr_addr] <= wr_data;
+        else if (rd_en)
+            rd_data <= mem[rd_addr];
+    end
+
+endmodule

sync_rtl/storage/sd_bram.v

@@ -0,0 +1,32 @@
+// sd_bram.v - Simple dual-port behavioral RAM (1 read + 1 write port)
+//
+// Vivado auto-infers this as BRAM when W >= 12 and D >= 64.
+// Read:  rd_addr sampled at posedge → rd_addr_r → rd_data = mem[rd_addr_r]
+// Write: wr_data written to mem[wr_addr] at posedge when wr_en=1
+// No valid/ready handshake — pure combinational-read / registered-write memory.
+
+module sd_bram #(
+    parameter W = 48,
+    parameter D = 64,
+    parameter A = 6
+) (
+    input  wire          clk,
+    input  wire [A-1:0]  rd_addr,
+    output wire [W-1:0]  rd_data,
+    input  wire          wr_en,
+    input  wire [A-1:0]  wr_addr,
+    input  wire [W-1:0]  wr_data
+);
+
+    reg [W-1:0] mem [0:D-1];
+    reg [A-1:0] rd_addr_r;
+
+    always @(posedge clk) begin
+        rd_addr_r <= rd_addr;
+        if (wr_en)
+            mem[wr_addr] <= wr_data;
+    end
+
+    assign rd_data = mem[rd_addr_r];
+
+endmodule