From a369a421b7fd1ffd3222e042568cc82b295cfd76 Mon Sep 17 00:00:00 2001 From: FallenSigh Date: Wed, 24 Jun 2026 23:28:06 +0800 Subject: [PATCH] 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 | 125 ++++++++++++++++++ sync_rtl/comp_decomp/comp_decomp_sync.v | 74 +++++++++++ sync_rtl/storage/TB/tb_storage.cpp | 111 ++++++++++++++++ sync_rtl/storage/s_bram.v | 31 +++++ sync_rtl/storage/sd_bram.v | 32 +++++ .../modules/comp_decomp/gen_vectors.py | 119 +++++++++++++++++ .../modules/comp_decomp/test_plan.json | 38 ++++++ test_framework/modules/storage/gen_vectors.py | 67 ++++++++++ test_framework/modules/storage/test_plan.json | 17 +++ 9 files changed, 614 insertions(+) create mode 100644 sync_rtl/comp_decomp/TB/tb_comp_decomp.cpp create mode 100644 sync_rtl/comp_decomp/comp_decomp_sync.v create mode 100644 sync_rtl/storage/TB/tb_storage.cpp create mode 100644 sync_rtl/storage/s_bram.v create mode 100644 sync_rtl/storage/sd_bram.v create mode 100644 test_framework/modules/comp_decomp/gen_vectors.py create mode 100644 test_framework/modules/comp_decomp/test_plan.json create mode 100644 test_framework/modules/storage/gen_vectors.py create mode 100644 test_framework/modules/storage/test_plan.json diff --git a/sync_rtl/comp_decomp/TB/tb_comp_decomp.cpp b/sync_rtl/comp_decomp/TB/tb_comp_decomp.cpp new file mode 100644 index 0000000..a1d1ef8 --- /dev/null +++ b/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 +#include +#include +#include +#include +#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; +} diff --git a/sync_rtl/comp_decomp/comp_decomp_sync.v b/sync_rtl/comp_decomp/comp_decomp_sync.v new file mode 100644 index 0000000..2c199da --- /dev/null +++ b/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 diff --git a/sync_rtl/storage/TB/tb_storage.cpp b/sync_rtl/storage/TB/tb_storage.cpp new file mode 100644 index 0000000..4304e01 --- /dev/null +++ b/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 +#include +#include +#include +#include +#include +#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 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; +} diff --git a/sync_rtl/storage/s_bram.v b/sync_rtl/storage/s_bram.v new file mode 100644 index 0000000..972b9b8 --- /dev/null +++ b/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 diff --git a/sync_rtl/storage/sd_bram.v b/sync_rtl/storage/sd_bram.v new file mode 100644 index 0000000..5bcb7c6 --- /dev/null +++ b/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 diff --git a/test_framework/modules/comp_decomp/gen_vectors.py b/test_framework/modules/comp_decomp/gen_vectors.py new file mode 100644 index 0000000..0affd77 --- /dev/null +++ b/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 diff --git a/test_framework/modules/comp_decomp/test_plan.json b/test_framework/modules/comp_decomp/test_plan.json new file mode 100644 index 0000000..479ecb9 --- /dev/null +++ b/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" + } + ] +} diff --git a/test_framework/modules/storage/gen_vectors.py b/test_framework/modules/storage/gen_vectors.py new file mode 100644 index 0000000..e6bd91e --- /dev/null +++ b/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') diff --git a/test_framework/modules/storage/test_plan.json b/test_framework/modules/storage/test_plan.json new file mode 100644 index 0000000..455d6c1 --- /dev/null +++ b/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" + } + ] +}