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

test_framework/modules/comp_decomp/gen_vectors.py

@@ -0,0 +1,119 @@
+"""gen_vectors.py - Test vector generator for comp_decomp module.
+
+Generates (mode, d, coeff) input tuples and computes expected
+compress/decompress results matching the Python reference implementation.
+Uses round-half-up (round(2.5)=3, round(3.5)=4).
+"""
+
+import os
+import random
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', 'lib'))
+
+from vector_gen import VectorGenerator
+
+Q = 3329  # ML-KEM prime modulus
+
+
+def round_customize(a: float) -> int:
+    """Round-half-up: round(2.5)=3, round(3.5)=4.
+    
+    Matches the reference implementation in de_compress.py.
+    """
+    tmp = int(a) + 0.5
+    if a >= tmp:
+        return int(a) + 1
+    else:
+        return int(a)
+
+
+def compress(z_q: int, q: int, d: int) -> int:
+    """Compress coefficient: round((2^d / q) * z_q) mod 2^d."""
+    _2d = 2 ** d
+    return round_customize((_2d / q) * z_q) % _2d
+
+
+def decompress(z_d: int, q: int, d: int) -> int:
+    """Decompress coefficient: round((q / 2^d) * z_d)."""
+    _2d = 2 ** d
+    return round_customize((q / _2d) * z_d)
+
+
+class CompDecompVectorGenerator(VectorGenerator):
+    """Generates test vectors for the comp_decomp_sync module."""
+
+    def generate_one(self, params: dict) -> dict:
+        """Generate a single (mode, d, coeff) test vector.
+
+        Args:
+            params: dict with 'mode' ('compress'/'decompress') and 'd' (int).
+
+        Returns:
+            dict with 'input' and 'expected' keys.
+        """
+        mode = params.get('mode', 'compress')
+        d = params.get('d', 10)
+
+        if mode == 'compress':
+            coeff = random.randint(0, Q - 1)
+            result = compress(coeff, Q, d)
+        else:
+            coeff = random.randint(0, (2 ** d) - 1)
+            result = decompress(coeff, Q, d)
+
+        return {
+            'input': {'mode': mode, 'd': d, 'coeff': coeff},
+            'expected': {'result': result}
+        }
+
+    def write_hex_file(self, vectors: list[dict], filepath: str) -> None:
+        """Write input vectors as 'MODE D COEFF' format.
+
+        MODE: 'C' for compress, 'D' for decompress.
+        D and COEFF are hex-encoded.
+
+        Example: 'C A 3FF' for compress with d=10, coeff=0x3FF.
+        """
+        os.makedirs(os.path.dirname(filepath), exist_ok=True)
+        with open(filepath, 'w') as f:
+            for v in vectors:
+                inp = v['input']
+                mode_char = 'C' if inp['mode'] == 'compress' else 'D'
+                d_val = inp['d']
+                coeff_val = inp['coeff']
+                f.write(f'{mode_char} {d_val:X} {coeff_val:03X}\n')
+
+    def write_expected_file(self, vectors: list[dict], filepath: str) -> None:
+        """Write expected output as zero-padded 3-digit hex values.
+
+        One value per line matching the %03X format in the testbench.
+        """
+        os.makedirs(os.path.dirname(filepath), exist_ok=True)
+        with open(filepath, 'w') as f:
+            for v in vectors:
+                result = v['expected']['result']
+                f.write(f'{result:03X}\n')
+
+    def compare_results(self, got: list[str], expected_file: str) -> bool:
+        """Compare RTL output against expected values.
+
+        Args:
+            got: List of hex result strings from simulation.
+            expected_file: Path to expected hex file.
+
+        Returns:
+            bool: True if all results match.
+        """
+        with open(expected_file, 'r') as f:
+            expected = [line.strip() for line in f
+                        if line.strip() and not line.startswith('#')]
+
+        if len(got) != len(expected):
+            return False
+
+        for i, (g, e) in enumerate(zip(got, expected)):
+            if g.upper() != e.upper():
+                return False
+
+        return True

test_framework/modules/comp_decomp/test_plan.json

@@ -0,0 +1,38 @@
+{
+  "module": "comp_decomp",
+  "rtl_top": "sync_rtl/comp_decomp/comp_decomp_sync.v",
+  "rtl_deps": ["sync_rtl/common/pipeline_reg.v"],
+  "tb_cpp": "sync_rtl/comp_decomp/TB/tb_comp_decomp.cpp",
+  "simulator": "verilator",
+  "timeout_s": 30,
+  "cases": [
+    {
+      "id": "compress_du10",
+      "description": "Compress with du=10 (ML-KEM-512/768)",
+      "params": {"mode": "compress", "d": 10},
+      "num_vectors": 20,
+      "tolerance": "bit_exact"
+    },
+    {
+      "id": "compress_dv4",
+      "description": "Compress with dv=4 (ML-KEM-512/768)",
+      "params": {"mode": "compress", "d": 4},
+      "num_vectors": 20,
+      "tolerance": "bit_exact"
+    },
+    {
+      "id": "decompress_du10",
+      "description": "Decompress with du=10",
+      "params": {"mode": "decompress", "d": 10},
+      "num_vectors": 10,
+      "tolerance": "bit_exact"
+    },
+    {
+      "id": "decompress_dv4",
+      "description": "Decompress with dv=4",
+      "params": {"mode": "decompress", "d": 4},
+      "num_vectors": 10,
+      "tolerance": "bit_exact"
+    }
+  ]
+}

test_framework/modules/storage/gen_vectors.py

@@ -0,0 +1,67 @@
+"""gen_vectors.py - Test vector generator for storage (sd_bram) module.
+
+Generates (addr, data) write pairs and expected read-back values.
+Address space: 0..63 (6-bit) | Data width: 48-bit.
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..', 'lib'))
+
+from vector_gen import VectorGenerator
+
+
+class StorageVectorGenerator(VectorGenerator):
+    """Generates write/read test vectors for sd_bram behavioral RAM."""
+
+    def generate_one(self, params: dict) -> dict:
+        """Generate a single (addr, data) write pair.
+
+        Uses sequential addresses 0..N-1 and deterministic 48-bit data
+        patterns for reproducible testing.
+
+        Args:
+            params: Unused for storage basic case.
+
+        Returns:
+            dict with 'input' and 'expected' keys.
+        """
+        # Sequential address assignment during generation
+        # addr is determined by position; data is a deterministic pattern
+        # The actual index is handled in write_hex_file for sequential addresses
+        return {
+            'data': 0  # placeholder — filled in write_hex_file by index
+        }
+
+    def write_hex_file(self, vectors: list[dict], filepath: str) -> None:
+        """Write input vectors as "AA DDDDDDDDDDDD" hex lines.
+
+        Uses sequential addresses 0..N-1 and deterministic 48-bit data:
+        data = (addr * 0x100000000001 + 0xDEADBEEFCAFE) & 0xFFFF_FFFF_FFFF
+
+        Args:
+            vectors: List of vector dicts from generate_one().
+            filepath: Path to write the hex file.
+        """
+        os.makedirs(os.path.dirname(filepath), exist_ok=True)
+        with open(filepath, 'w') as f:
+            for i in range(len(vectors)):
+                addr = i
+                # Deterministic 48-bit pattern: spreads bits across the word
+                data = ((addr + 1) * 0x100000000001 + 0xDEADBEEFCAFE) & 0xFFFFFFFFFFFF
+                f.write(f'{addr:02X} {data:012X}\n')
+
+    def write_expected_file(self, vectors: list[dict], filepath: str) -> None:
+        """Write expected read-back values (same patterns as written).
+
+        Args:
+            vectors: List of vector dicts from generate_one().
+            filepath: Path to write the expected hex file.
+        """
+        os.makedirs(os.path.dirname(filepath), exist_ok=True)
+        with open(filepath, 'w') as f:
+            for i in range(len(vectors)):
+                addr = i
+                data = ((addr + 1) * 0x100000000001 + 0xDEADBEEFCAFE) & 0xFFFFFFFFFFFF
+                f.write(f'{data:012X}\n')

test_framework/modules/storage/test_plan.json

@@ -0,0 +1,17 @@
+{
+  "module": "storage",
+  "rtl_top": "sync_rtl/storage/sd_bram.v",
+  "rtl_deps": ["sync_rtl/storage/s_bram.v"],
+  "tb_cpp": "sync_rtl/storage/TB/tb_storage.cpp",
+  "simulator": "verilator",
+  "timeout_s": 30,
+  "cases": [
+    {
+      "id": "rw_test",
+      "description": "Write-read test for sd_bram (s_bram compiled as dep)",
+      "params": {},
+      "num_vectors": 5,
+      "tolerance": "bit_exact"
+    }
+  ]
+}