fallensigh/mlkem-sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
FallenSigh
2026-06-25 20:48:38 +08:00
parent ae5f0ca048
commit d4c3fc86fc
42 changed files with 7745 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

270
sync_rtl/sample_cbd/TB/gen_vectors.py Normal file
View File

@@ -0,0 +1,270 @@
#!/usr/bin/env python3
"""gen_vectors.py - Test vector generator for sample_cbd_sync module.
Generates random seed+nonce+eta test vectors, computes expected CBD coefficients
using Python hashlib (stdlib only), and writes input hex and expected output hex files.
Algorithm (matching RTL sample_cbd_sync.v):
PRF(sigma, N) = SHAKE-256(sigma || N) → squeeze eta*64 bytes
For each of 256 coefficients:
eta=2: read 4 bits, coeff = (b0+b1) - (b2+b3)
eta=3: read 6 bits, coeff = (b0+b1+b2) - (b3+b4+b5)
Each coefficient in range [-eta, eta], stored as 12-bit signed.
Bit ordering (FIPS 202 / RTL match):
The RTL feeds seed_i[0] as the first bit into SHA3.
Python hashlib expects bytes[0] LSB as the first bit.
$readmemh stores hex with MSB first → seed_i[255:0] MSB-first.
So: Python input = reverse(bytes.fromhex(seed_hex)) + bytes([nonce]).
Usage:
python3 gen_vectors.py # Generate vectors
python3 gen_vectors.py --verify # Verify results against expected
"""
import hashlib
import os
import random
import sys
N_COEFFS = 256
Q = 3329 # not used for CBD, but for reference
def random_hex(bits):
"""Generate a random hex string (MSB-first) of the given bit length."""
val = random.getrandbits(bits)
num_nibbles = (bits + 3) // 4
return f"{val:0{num_nibbles}X}"
def bits_from_bytes(data):
"""Convert bytes to LSB-first bit string.
data[0] LSB = bits[0], data[0] bit 1 = bits[1], ...
"""
bits = []
for b in data:
for bit in range(8):
bits.append('1' if (b >> bit) & 1 else '0')
return ''.join(bits)
def shake256_prf(seed_hex, nonce, eta):
"""Compute SHAKE-256(seed || nonce) matching RTL bit ordering.
Args:
seed_hex: 64-char hex string (MSB-first, as stored by $readmemh).
nonce: 8-bit integer.
eta: 2 or 3.
Returns:
bytes: eta * 64 bytes of SHAKE-256 squeeze output.
"""
# seed_hex is MSB-first: seed_i[255:0] = 256'h<seed_hex>
# RTL feeds seed_i[0] first into SHA3.
# Python: reverse bytes so that byte[0] = seed_i[7:0],
# then append nonce byte.
seed_bytes = bytes.fromhex(seed_hex) # MSB-first bytes
shake_input = bytes(reversed(seed_bytes)) + bytes([nonce & 0xFF])
shake = hashlib.shake_256(shake_input)
return shake.digest(eta * 64)
def cbd_sample(prf_bytes, eta):
"""Apply Centered Binomial Distribution to PRF output bytes.
Args:
prf_bytes: bytes from SHAKE-256 squeeze (eta * 64 bytes).
eta: 2 or 3.
Returns:
list of 256 signed integers in range [-eta, eta].
"""
bits = bits_from_bytes(prf_bytes)
step = eta * 2 # 4 for eta=2, 6 for eta=3
half = eta # 2 for eta=2, 3 for eta=3
coeffs = []
for i in range(N_COEFFS):
pos_sum = sum(1 for j in range(half) if bits[step * i + j] == '1')
neg_sum = sum(1 for j in range(half) if bits[step * i + half + j] == '1')
coeffs.append(pos_sum - neg_sum)
return coeffs
def coeff_to_hex_12signed(val):
"""Convert signed 12-bit value to 3-char hex string (two's complement)."""
masked = val & 0xFFF # 12-bit unsigned
return f"{masked:03X}"
def generate_one(eta):
"""Generate a single test vector.
Returns:
dict with 'seed_hex', 'nonce', 'eta', 'coeffs' keys.
"""
seed_hex = random_hex(256)
nonce = random.randint(0, 255)
prf_bytes = shake256_prf(seed_hex, nonce, eta)
coeffs = cbd_sample(prf_bytes, eta)
return {
"seed_hex": seed_hex,
"nonce": nonce,
"eta": eta,
"coeffs": coeffs,
}
def write_input_hex(vectors, filepath):
"""Write input vectors as packed hex for $readmemh.
Each line: {eta[1:0], nonce[7:0], seed[255:0]} = 266 bits.
Written as 67 hex chars (268 bits, top 2 bits zero).
"""
os.makedirs(os.path.dirname(filepath), exist_ok=True)
with open(filepath, "w") as f:
for v in vectors:
eta = v["eta"]
nonce = v["nonce"]
seed_hex = v["seed_hex"]
# Pack: {2'b00, eta[1:0], nonce[7:0], seed[255:0]} = 268 bits = 67 hex chars
# The first hex char carries eta in its lower 2 bits:
# hex value = 0x0 | eta → nibble = 0b00XX where XX = eta
# TB reads vec_eta = vector_mem[idx][265:264]
packed = f"{eta & 0x3:01X}{nonce:02X}{seed_hex}" # 1+2+64 = 67 chars
f.write(packed + "\n")
def write_expected_hex(vectors, filepath):
"""Write expected coefficients: one 12-bit hex value per line."""
os.makedirs(os.path.dirname(filepath), exist_ok=True)
with open(filepath, "w") as f:
for i, v in enumerate(vectors):
f.write(f"# VECTOR_{i} eta={v['eta']} nonce=0x{v['nonce']:02X} seed={v['seed_hex']}\n")
for c in v["coeffs"]:
f.write(coeff_to_hex_12signed(c) + "\n")
def verify_results(result_file, vectors):
"""Verify RTL output against expected values.
Args:
result_file: Path to RTL result file (coeff hex per line).
vectors: List of vector dicts with 'coeffs'.
Returns:
bool: True if all vectors match.
"""
with open(result_file, "r") as f:
lines = [line.strip() for line in f
if line.strip() and not line.strip().startswith("#")]
# lines may contain trailing comments separated by " #"
cleaned = []
for line in lines:
comment_idx = line.find(" #")
if comment_idx >= 0:
line = line[:comment_idx].strip()
cleaned.append(line)
expected_all = []
for v in vectors:
for c in v["coeffs"]:
expected_all.append(coeff_to_hex_12signed(c))
if len(cleaned) != len(expected_all):
print(f" COUNT MISMATCH: got {len(cleaned)}, expected {len(expected_all)}")
return False
mismatches = 0
for i, (g, e) in enumerate(zip(cleaned, expected_all)):
if g.upper() != e.upper():
if mismatches < 10:
print(f" MISMATCH[{i}]: got={g.upper()}, expected={e.upper()}")
mismatches += 1
if mismatches > 0:
print(f" Total mismatches: {mismatches}")
return False
return True
def main():
vector_count = 4 # 2 vectors with eta=2, 2 with eta=3
base_dir = os.path.dirname(os.path.abspath(__file__))
vectors_dir = os.path.join(base_dir, "vectors")
input_file = os.path.join(vectors_dir, "sample_cbd_input.hex")
expected_file = os.path.join(vectors_dir, "sample_cbd_expected.hex")
result_file = os.path.join(vectors_dir, "sample_cbd_result.hex")
verify_mode = "--verify" in sys.argv
if verify_mode:
if not os.path.exists(result_file):
print(f"ERROR: Result file not found: {result_file}")
print(" Run simulation first to generate results.")
sys.exit(1)
if not os.path.exists(input_file):
print(f"ERROR: Input file not found: {input_file}")
sys.exit(1)
print(f"Verifying results from {result_file}...")
# Recompute expected from input file
with open(input_file, "r") as f:
input_lines = [l.strip() for l in f if l.strip()]
vectors = []
for line in input_lines:
if len(line) != 67:
print(f"WARNING: Skipping line with unexpected length {len(line)}: {line[:20]}...")
continue
# Parse: first char = eta_nibble, next 2 = nonce, next 64 = seed
eta_nibble = int(line[0], 16)
eta = eta_nibble >> 2 # bits[3:2]
nonce = int(line[1:3], 16)
seed_hex = line[3:]
prf_bytes = shake256_prf(seed_hex, nonce, eta)
coeffs = cbd_sample(prf_bytes, eta)
vectors.append({"seed_hex": seed_hex, "nonce": nonce, "eta": eta, "coeffs": coeffs})
ok = verify_results(result_file, vectors)
if ok:
print("ALL VECTORS PASSED")
else:
print("VERIFICATION FAILED")
sys.exit(1)
else:
# Generate mode
print(f"Generating {vector_count} test vectors...")
vectors = []
# eta=2 vectors
for i in range(vector_count // 2):
v = generate_one(eta=2)
vectors.append(v)
print(f" Vector {len(vectors)-1}: eta=2, nonce=0x{v['nonce']:02X}, "
f"seed={v['seed_hex'][:8]}..., coeffs[0]={v['coeffs'][0]}")
# eta=3 vectors
for i in range(vector_count // 2):
v = generate_one(eta=3)
vectors.append(v)
print(f" Vector {len(vectors)-1}: eta=3, nonce=0x{v['nonce']:02X}, "
f"seed={v['seed_hex'][:8]}..., coeffs[0]={v['coeffs'][0]}")
write_input_hex(vectors, input_file)
print(f"Wrote {len(vectors)} vectors to {input_file}")
write_expected_hex(vectors, expected_file)
print(f"Wrote expected coefficients to {expected_file}")
# Sanity checks
for v in vectors:
for c in v["coeffs"]:
assert -v["eta"] <= c <= v["eta"], \
f"Coefficient {c} out of range [-{v['eta']}, {v['eta']}]"
print("All sanity checks passed.")
if __name__ == "__main__":
main()

257
sync_rtl/sample_cbd/TB/tb_sample_cbd_xsim.v Normal file
View File

@@ -0,0 +1,257 @@
// tb_sample_cbd_xsim.v - Vivado xsim testbench for sample_cbd_sync
//
// Reads test vectors from a hex file using $readmemh.
// Each line is a packed hex word: {eta_i[1:0], nonce_i[7:0], seed_i[255:0]}
// - seed_i[255:0] : 64 hex chars (LSB = seed_i[0])
// - nonce_i[7:0] : 2 hex chars
// - eta_i[1:0] : 1 hex char (2 or 3)
// - Total: 67 hex chars (266 bits), zero-padded to fill 4-bit nibbles
//
// Drives sample_cbd_sync, waits for valid_o, collects 256 coefficients,
// and writes results to an output file.
//
// Usage:
// xvlog -sv sample_cbd_sync.v TB/tb_sample_cbd_xsim.v
// xelab tb_sample_cbd_xsim -s tb_sample_cbd_xsim
// xsim tb_sample_cbd_xsim -R
//
// Prerequisites:
// - Generate vectors: python3 TB/gen_vectors.py
// - Output file: vectors/sample_cbd_input.hex
`timescale 1ns / 1ps
module tb_sample_cbd_xsim;
// ================================================================
// Parameters
// ================================================================
parameter VECTOR_FILE = "sync_rtl/sample_cbd/TB/vectors/sample_cbd_input.hex";
parameter RESULT_FILE = "sync_rtl/sample_cbd/TB/vectors/sample_cbd_result.hex";
parameter EXPECT_FILE = "sync_rtl/sample_cbd/TB/vectors/sample_cbd_expected.hex";
parameter MAX_VECTORS = 32;
parameter TIMEOUT_CYCLES = 10000;
parameter N_COEFFS = 256;
// ================================================================
// DUT signals
// ================================================================
reg clk;
reg rst_n;
reg [255:0] seed_i;
reg [7:0] nonce_i;
reg [1:0] eta_i;
reg valid_i;
wire ready_o;
wire [11:0] coeff_o;
wire valid_o;
reg ready_i;
wire last_o;
// ================================================================
// DUT instantiation
// ================================================================
sample_cbd_sync u_dut (
.clk (clk),
.rst_n (rst_n),
.seed_i (seed_i),
.nonce_i (nonce_i),
.eta_i (eta_i),
.valid_i (valid_i),
.ready_o (ready_o),
.coeff_o (coeff_o),
.valid_o (valid_o),
.ready_i (ready_i),
.last_o (last_o)
);
// ================================================================
// Clock generation: 100 MHz (10 ns period)
// ================================================================
initial clk = 1'b0;
always #5 clk = ~clk;
// ================================================================
// Vector memory (loaded by $readmemh)
// 266 bits per word: {eta_i[1:0], nonce_i[7:0], seed_i[255:0]}
// Hex: 67 chars = 268 bits, top 2 bits zero-padded
// ================================================================
reg [267:0] vector_mem [0:MAX_VECTORS-1];
integer vec_count;
integer idx;
integer cycle_count;
integer result_fd;
integer coeff_idx;
// Test result tracking
integer pass_count;
integer fail_count;
// ================================================================
// Hex-to-ASCII conversion helper (for output file)
// ================================================================
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
// ================================================================
// Main test sequence
// ================================================================
initial begin
vec_count = 0;
// Load vectors from hex file
$readmemh(VECTOR_FILE, vector_mem);
// Count non-zero/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] === {268{1'bx}} || vector_mem[idx] === {268{1'bz}}))
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: <67 hex chars> = {eta, nonce, seed}");
$finish;
end
$display("INFO: Loaded %0d test vectors 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
seed_i <= 256'd0;
nonce_i <= 8'd0;
eta_i <= 2'd2;
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] vec_seed;
reg [7:0] vec_nonce;
reg [1:0] vec_eta;
// Extract fields from packed vector_mem
// vector_mem[267:0] = {2'b0, eta_i, nonce_i, seed_i}
vec_seed = vector_mem[idx][255:0];
vec_nonce = vector_mem[idx][263:256];
vec_eta = vector_mem[idx][265:264];
$display("INFO: Vector %0d - eta=%0d, nonce=0x%02h, seed[0:31]=%0h...",
idx, vec_eta, vec_nonce, vec_seed[31:0]);
// Drive DUT with input
seed_i <= vec_seed;
nonce_i <= vec_nonce;
eta_i <= vec_eta;
valid_i <= 1'b1;
@(posedge clk);
valid_i <= 1'b0;
// Wait for valid_o, then collect all 256 coefficients
// The DUT uses ready/valid handshake; we set ready_i=1
coeff_idx = 0;
cycle_count = 0;
// Write vector header to result file
$fwrite(result_fd, "# VECTOR_%0d eta=%0d nonce=0x%02h seed=0x%064h\n",
idx, vec_eta, vec_nonce, vec_seed);
while (coeff_idx < N_COEFFS && cycle_count < TIMEOUT_CYCLES) begin
@(posedge clk);
cycle_count = cycle_count + 1;
if (valid_o) begin
// Capture coefficient
begin
integer k;
reg [3:0] nib;
for (k = 2; k >= 0; k = k - 1) begin
nib = coeff_o[(k*4)+:4];
$fwrite(result_fd, "%c", nibble_to_ascii(nib));
end
end
coeff_idx = coeff_idx + 1;
if (last_o)
$fwrite(result_fd, " # last at coeff_idx=%0d", coeff_idx);
$fwrite(result_fd, "\n");
end
end
if (cycle_count >= TIMEOUT_CYCLES) begin
$display("ERROR: Timeout on vector %0d (got %0d/%0d coefficients)",
idx, coeff_idx, N_COEFFS);
fail_count = fail_count + 1;
end else if (coeff_idx != N_COEFFS) begin
$display("ERROR: Vector %0d incomplete (got %0d/%0d coefficients)",
idx, coeff_idx, N_COEFFS);
fail_count = fail_count + 1;
end else begin
$display("INFO: Vector %0d PASSED (%0d coefficients in %0d cycles)",
idx, coeff_idx, cycle_count);
pass_count = pass_count + 1;
end
// Wait for DUT to return to IDLE before next vector
@(posedge clk);
end // inner begin block
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 (global)
// ================================================================
initial begin
#(TIMEOUT_CYCLES * 10 * 100); // TIMEOUT_CYCLES * 10ns * extra margin
$display("FATAL: Global simulation timeout reached");
$finish;
end
endmodule

1028
sync_rtl/sample_cbd/TB/vectors/sample_cbd_expected.hex Normal file
View File

File diff suppressed because it is too large Load Diff

4
sync_rtl/sample_cbd/TB/vectors/sample_cbd_input.hex Normal file
View File

@@ -0,0 +1,4 @@
27F692D88854B85E2DF61697261CCC8931119F593F90A499EA6AD3229F6301D280E
24A7D2BAA804507EA9069043D6D395FBF42E1BB02BE0A1894B98E8F5F734FE5C22A
3C7E07D2297A5E9B056F40AA0AF595CB3121E03CCBB86CC25C012EC008D07DC8481
3A0A67134FA9332AD1430AF5003D24E856EB38A0219B48B68A24C5C85E73AF79026

56
sync_rtl/sample_cbd/TB/xsim_run.tcl Normal file
View File

@@ -0,0 +1,56 @@
# xsim_run.tcl - Vivado xsim compilation and simulation for sample_cbd_sync
#
# Compiles sample_cbd_sync RTL + SHA3 dependencies + testbench and runs simulation.
# Run from the project root: ~/Dev/mlkem/
#
# Prerequisites:
# source /opt/Xilinx/Vivado/2019.2/settings64.sh
#
# Usage:
# xsim -runall sync_rtl/sample_cbd/TB/xsim_run.tcl
#
# # Or step-by-step:
# vivado -mode batch -source sync_rtl/sample_cbd/TB/xsim_run.tcl
# ================================================================
# Configuration
# ================================================================
set SRC_DIR sync_rtl/sample_cbd
set SHA3_DIR sync_rtl/sha3
set COMMON_DIR sync_rtl/common
set TB_DIR sync_rtl/sample_cbd/TB
# ================================================================
# Step 1: Compile all source files (xvlog)
# ================================================================
puts "=== Compiling RTL sources ==="
# Keccak round (combinational, used by keccak_core)
xvlog -sv ${SHA3_DIR}/keccak_round.v
# Keccak core (24-round sequential core, used by sample_cbd_sync)
xvlog -sv ${SHA3_DIR}/keccak_core.v
# sample_cbd_sync (DUT)
xvlog -sv ${SRC_DIR}/sample_cbd_sync.v
# ================================================================
# Step 2: Compile testbench
# ================================================================
puts "=== Compiling testbench ==="
xvlog -sv ${TB_DIR}/tb_sample_cbd_xsim.v
# ================================================================
# Step 3: Elaborate snapshot (xelab)
# ================================================================
puts "=== Elaborating snapshot ==="
xelab tb_sample_cbd_xsim -s tb_sample_cbd_xsim
# ================================================================
# Step 4: Run simulation
# ================================================================
puts "=== Running simulation ==="
xsim tb_sample_cbd_xsim -R
puts ""
puts "=== sample_cbd simulation complete ==="