test: support 1000 KAT Vectors
This commit is contained in:
354
run_tb.sh
354
run_tb.sh
@@ -3,14 +3,14 @@
|
||||
#
|
||||
# Usage: ./run_tb.sh <module> [K] [CASE]
|
||||
# ./run_tb.sh ntt # run the module's full xsim_run.tcl
|
||||
# ./run_tb.sh top # ML-KEM KeyGen: all K, all cases
|
||||
# ./run_tb.sh top 2 # only K=2 (ML-KEM-512), all its cases
|
||||
# ./run_tb.sh top # ML-KEM KeyGen: all K, all KAT vectors
|
||||
# ./run_tb.sh top 2 # only K=2 (ML-KEM-512), all KAT vectors
|
||||
# ./run_tb.sh top 2 3 # only K=2, only CASE=3
|
||||
# ./run_tb.sh top 4 0 # only K=4 (ML-KEM-1024), CASE=0
|
||||
# ./run_tb.sh enc # ML-KEM Encaps: all K, all cases (0..2)
|
||||
# ./run_tb.sh enc 2 # Encaps K=2, all its cases
|
||||
# ./run_tb.sh enc # ML-KEM Encaps: all K, all KAT vectors
|
||||
# ./run_tb.sh enc 2 # Encaps K=2, all KAT vectors
|
||||
# ./run_tb.sh enc 4 1 # Encaps K=4, only CASE=1
|
||||
# ./run_tb.sh dec # ML-KEM Decaps: all K, all cases (0..2)
|
||||
# ./run_tb.sh dec # ML-KEM Decaps: all K, all KAT vectors
|
||||
# ./run_tb.sh dec 2 0 # Decaps K=2, only CASE=0
|
||||
# ./run_tb.sh hello [K] # hello_world end-to-end (single instance; K=2/3/4)
|
||||
# ./run_tb.sh hello two [K] # hello_world end-to-end (two instances; K=2/3/4)
|
||||
@@ -20,8 +20,10 @@
|
||||
# all compile the xvlog lines from sync_rtl/top/TB/xsim_run.tcl. They differ only
|
||||
# in the testbench: top -> tb_mlkem_kg_katK_xsim, enc -> tb_mlkem_enc_katK_xsim,
|
||||
# dec -> tb_mlkem_dec_katK_xsim.
|
||||
# For these, K (2/3/4) and CASE select a single KAT run so you can iterate
|
||||
# quickly. Other modules ignore the extra args and run their xsim_run.tcl verbatim.
|
||||
# For these, K (2/3/4) and CASE select a subset of the KAT run so you can
|
||||
# iterate quickly. Without CASE the script generates/enumerates every vector in
|
||||
# test_data/kat_MLKEM_{512,768,1024}.rsp. Limit xsim parallelism with
|
||||
# RUN_TB_JOBS=N (default: min(nproc, 4)).
|
||||
#
|
||||
# Prerequisites:
|
||||
# Vivado 2019.2 at /opt/Xilinx/Vivado/2019.2/
|
||||
@@ -30,6 +32,8 @@ set -e
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
VIVADO_SETTINGS="/opt/Xilinx/Vivado/2019.2/settings64.sh"
|
||||
KAT_VECTOR_DIR="$SCRIPT_DIR/sync_rtl/top/TB/vectors"
|
||||
KAT_RUN_VECTOR_DIR=""
|
||||
|
||||
if [ "$1" = "--list" ]; then
|
||||
echo "Available modules:"
|
||||
@@ -117,114 +121,240 @@ execute_tcl() {
|
||||
# the shared xsim.dir BEFORE any parallel run starts).
|
||||
#
|
||||
# run_xsim_jobs <module-tag> <pass-grep-regex> <pass-match-string> <spec>...
|
||||
# each <spec> = "snapshot:K:CASE". Launches all specs in parallel, waits,
|
||||
# then prints an ordered summary and returns nonzero if any job failed.
|
||||
# each <spec> = "snapshot:K:CASE". Launches specs with bounded parallelism,
|
||||
# waits, then prints an ordered summary and returns nonzero if any job failed.
|
||||
PAR_BASE="${TMPDIR:-/tmp}/run_tb_par_$$"
|
||||
KAT_TMP_BASE="${TMPDIR:-/tmp}/run_tb_vectors_$$"
|
||||
trap 'rm -rf "$PAR_BASE" "$KAT_TMP_BASE"' EXIT
|
||||
|
||||
print_timing_summary() {
|
||||
local logs=("$@")
|
||||
local found=0 log
|
||||
|
||||
for log in "${logs[@]}"; do
|
||||
if [ -f "$log" ] && grep -q '^TIME ' "$log"; then
|
||||
found=1
|
||||
fi
|
||||
done
|
||||
[ "$found" -eq 0 ] && return 0
|
||||
|
||||
echo ""
|
||||
echo "Timing summary (clk=20MHz, period=50ns)"
|
||||
printf " %-7s %-3s %-5s %10s %12s %12s %s\n" "OP" "K" "CASE" "cycles" "time_us" "time_ms" "log"
|
||||
for log in "${logs[@]}"; do
|
||||
[ -f "$log" ] || continue
|
||||
awk -v logfile="$log" '
|
||||
/^TIME / {
|
||||
k = ""; c = ""; op = ""; cycles = ""; runtime = "";
|
||||
for (i = 1; i <= NF; i++) {
|
||||
split($i, a, "=");
|
||||
if (a[1] == "K") k = a[2];
|
||||
else if (a[1] == "CASE") c = a[2];
|
||||
else if (a[1] == "OP") op = a[2];
|
||||
else if (a[1] == "cycles") cycles = a[2];
|
||||
else if (a[1] == "runtime") runtime = a[2];
|
||||
}
|
||||
if (runtime != "") {
|
||||
printf " %-7s %-3s %-5s %10d %12.3f %12.3f %s\n",
|
||||
op, k, c, cycles, runtime / 1000.0, runtime / 1000000.0, logfile;
|
||||
}
|
||||
}
|
||||
' "$log"
|
||||
done
|
||||
|
||||
local found_state=0
|
||||
for log in "${logs[@]}"; do
|
||||
if [ -f "$log" ] && grep -q '^ STATE ' "$log"; then
|
||||
found_state=1
|
||||
fi
|
||||
done
|
||||
[ "$found_state" -eq 0 ] && return 0
|
||||
|
||||
echo ""
|
||||
echo "State timing breakdown (clk=20MHz, period=50ns)"
|
||||
printf " %-7s %-3s %-5s %-12s %10s %12s\n" "OP" "K" "CASE" "STATE" "cycles" "time_us"
|
||||
for log in "${logs[@]}"; do
|
||||
[ -f "$log" ] || continue
|
||||
awk '
|
||||
/^TIME_BREAKDOWN / {
|
||||
k = ""; c = ""; op = "";
|
||||
for (i = 1; i <= NF; i++) {
|
||||
split($i, a, "=");
|
||||
if (a[1] == "K") k = a[2];
|
||||
else if (a[1] == "CASE") c = a[2];
|
||||
else if (a[1] == "OP") op = a[2];
|
||||
}
|
||||
next;
|
||||
}
|
||||
/^ STATE / {
|
||||
state = $2;
|
||||
cycles = "";
|
||||
time_ns = "";
|
||||
/^TIME / {
|
||||
cycles = ""; runtime = "";
|
||||
for (i = 1; i <= NF; i++) {
|
||||
split($i, a, "=");
|
||||
if (a[1] == "cycles") cycles = a[2];
|
||||
else if (a[1] == "time_ns") time_ns = a[2];
|
||||
else if (a[1] == "runtime") runtime = a[2];
|
||||
}
|
||||
if (time_ns != "") {
|
||||
printf " %-7s %-3s %-5s %-12s %10d %12.3f\n",
|
||||
op, k, c, state, cycles, time_ns / 1000.0;
|
||||
if (cycles != "") {
|
||||
n++;
|
||||
sum_cycles += cycles;
|
||||
if (runtime != "") sum_runtime += runtime;
|
||||
}
|
||||
}
|
||||
' "$log"
|
||||
done
|
||||
END {
|
||||
if (n == 0) {
|
||||
print "Timing average: no TIME records found";
|
||||
} else {
|
||||
printf "Timing average (clk=20MHz, period=50ns): runs=%d avg_cycles=%.1f avg_time_us=%.3f avg_time_ms=%.3f\n",
|
||||
n, sum_cycles / n, (sum_runtime / n) / 1000.0, (sum_runtime / n) / 1000000.0;
|
||||
}
|
||||
}
|
||||
' "${logs[@]}"
|
||||
}
|
||||
|
||||
validate_kat_selection() {
|
||||
local ksel="$1" csel="$2"
|
||||
case "$ksel" in
|
||||
""|2|3|4) ;;
|
||||
*) echo "ERROR: K must be 2, 3, or 4 (got '$ksel')"; return 1 ;;
|
||||
esac
|
||||
if [ -n "$csel" ] && ! [[ "$csel" =~ ^[0-9]+$ ]]; then
|
||||
echo "ERROR: CASE must be a non-negative integer (got '$csel')"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
generate_kat_vectors() {
|
||||
local op="$1" ksel="${2:-}" csel="${3:-}"
|
||||
|
||||
validate_kat_selection "$ksel" "$csel" || return 1
|
||||
KAT_RUN_VECTOR_DIR="$KAT_TMP_BASE/$op"
|
||||
rm -rf "$KAT_RUN_VECTOR_DIR"
|
||||
mkdir -p "$KAT_RUN_VECTOR_DIR"
|
||||
[ -d "$KAT_VECTOR_DIR/encgold" ] && ln -s "$KAT_VECTOR_DIR/encgold" "$KAT_RUN_VECTOR_DIR/encgold"
|
||||
[ -d "$KAT_VECTOR_DIR/decgold" ] && ln -s "$KAT_VECTOR_DIR/decgold" "$KAT_RUN_VECTOR_DIR/decgold"
|
||||
|
||||
python3 - "$SCRIPT_DIR" "$op" "${ksel:-all}" "${csel:-all}" "$KAT_RUN_VECTOR_DIR" <<'PY'
|
||||
import pathlib
|
||||
import sys
|
||||
|
||||
root = pathlib.Path(sys.argv[1])
|
||||
op = sys.argv[2]
|
||||
ksel = sys.argv[3]
|
||||
csel = sys.argv[4]
|
||||
out_dir = pathlib.Path(sys.argv[5])
|
||||
|
||||
ks = [2, 3, 4] if ksel == "all" else [int(ksel)]
|
||||
case_filter = None if csel == "all" else int(csel)
|
||||
rsp_by_k = {
|
||||
2: root / "test_data" / "kat_MLKEM_512.rsp",
|
||||
3: root / "test_data" / "kat_MLKEM_768.rsp",
|
||||
4: root / "test_data" / "kat_MLKEM_1024.rsp",
|
||||
}
|
||||
|
||||
def parse_rsp(path):
|
||||
records = []
|
||||
cur = {}
|
||||
with path.open("r", encoding="ascii") as f:
|
||||
for raw in f:
|
||||
line = raw.strip()
|
||||
if not line or line.startswith("#") or " = " not in line:
|
||||
continue
|
||||
key, val = line.split(" = ", 1)
|
||||
if key == "count":
|
||||
if cur:
|
||||
records.append(cur)
|
||||
cur = {"count": int(val)}
|
||||
else:
|
||||
cur[key] = val.lower()
|
||||
if cur:
|
||||
records.append(cur)
|
||||
return records
|
||||
|
||||
def bytes_of(hexstr, field, count, k):
|
||||
if len(hexstr) % 2:
|
||||
raise SystemExit(f"odd hex length for {field}, K={k}, count={count}")
|
||||
return [hexstr[i:i + 2] for i in range(0, len(hexstr), 2)]
|
||||
|
||||
def write_bytes(path, hexstr, field, count, k):
|
||||
data = bytes_of(hexstr, field, count, k)
|
||||
path.write_text("".join(b + "\n" for b in data), encoding="ascii")
|
||||
|
||||
def write_word256_reversed(path, hexstr, field, count, k):
|
||||
data = bytes_of(hexstr, field, count, k)
|
||||
if len(data) != 32:
|
||||
raise SystemExit(f"{field} must be 32 bytes, got {len(data)}, K={k}, count={count}")
|
||||
path.write_text("".join(reversed(data)) + "\n", encoding="ascii")
|
||||
|
||||
def require(rec, keys, k):
|
||||
missing = [key for key in keys if key not in rec]
|
||||
if missing:
|
||||
raise SystemExit(f"missing {','.join(missing)} in K={k}, count={rec.get('count')}")
|
||||
|
||||
summary = []
|
||||
for k in ks:
|
||||
records = parse_rsp(rsp_by_k[k])
|
||||
wrote = 0
|
||||
for rec in records:
|
||||
count = rec["count"]
|
||||
if case_filter is not None and count != case_filter:
|
||||
continue
|
||||
tag = f"k{k}"
|
||||
if op == "top":
|
||||
require(rec, ["d", "z", "pk", "sk"], k)
|
||||
base = out_dir / f"kat_{tag}_c{count}"
|
||||
write_word256_reversed(base.with_name(base.name + "_d.hex"), rec["d"], "d", count, k)
|
||||
write_word256_reversed(base.with_name(base.name + "_z.hex"), rec["z"], "z", count, k)
|
||||
write_bytes(base.with_name(base.name + "_ek.hex"), rec["pk"], "pk", count, k)
|
||||
write_bytes(base.with_name(base.name + "_dk.hex"), rec["sk"], "sk", count, k)
|
||||
elif op == "enc":
|
||||
require(rec, ["pk", "msg", "ct", "ss"], k)
|
||||
base = out_dir / f"enc_{tag}_c{count}"
|
||||
write_bytes(base.with_name(base.name + "_ek.hex"), rec["pk"], "pk", count, k)
|
||||
write_bytes(base.with_name(base.name + "_m.hex"), rec["msg"], "msg", count, k)
|
||||
write_bytes(base.with_name(base.name + "_ct.hex"), rec["ct"], "ct", count, k)
|
||||
write_bytes(base.with_name(base.name + "_ss.hex"), rec["ss"], "ss", count, k)
|
||||
elif op == "dec":
|
||||
require(rec, ["sk", "ct", "ss", "ct_n", "ss_n"], k)
|
||||
base = out_dir / f"dec_{tag}_c{count}"
|
||||
write_bytes(base.with_name(base.name + "_dk.hex"), rec["sk"], "sk", count, k)
|
||||
write_bytes(base.with_name(base.name + "_ct.hex"), rec["ct"], "ct", count, k)
|
||||
write_bytes(base.with_name(base.name + "_ss.hex"), rec["ss"], "ss", count, k)
|
||||
write_bytes(base.with_name(base.name + "_ctn.hex"), rec["ct_n"], "ct_n", count, k)
|
||||
write_bytes(base.with_name(base.name + "_ssn.hex"), rec["ss_n"], "ss_n", count, k)
|
||||
else:
|
||||
raise SystemExit(f"unknown KAT op: {op}")
|
||||
wrote += 1
|
||||
if case_filter is not None and wrote == 0:
|
||||
raise SystemExit(f"CASE={case_filter} not found in {rsp_by_k[k]}")
|
||||
summary.append(f"K={k}:{wrote}")
|
||||
|
||||
print(f" generated {op} KAT vector files ({', '.join(summary)})")
|
||||
PY
|
||||
}
|
||||
|
||||
kat_cases_for() {
|
||||
local op="$1" k="$2" prefix suffix
|
||||
local dir="${KAT_RUN_VECTOR_DIR:-$KAT_VECTOR_DIR}"
|
||||
case "$op" in
|
||||
top) prefix="kat_k${k}_c"; suffix="_d\\.hex" ;;
|
||||
enc) prefix="enc_k${k}_c"; suffix="_ek\\.hex" ;;
|
||||
dec) prefix="dec_k${k}_c"; suffix="_dk\\.hex" ;;
|
||||
*) echo "ERROR: unknown KAT op '$op'" >&2; return 1 ;;
|
||||
esac
|
||||
|
||||
find "$dir" -maxdepth 1 -type f -printf '%f\n' \
|
||||
| sed -n "s/^${prefix}\([0-9][0-9]*\)${suffix}$/\1/p" \
|
||||
| sort -n \
|
||||
| tr '\n' ' '
|
||||
}
|
||||
|
||||
run_xsim_jobs() {
|
||||
local mtag="$1" pgrep="$2" pmatch="$3"; shift 3
|
||||
local specs=("$@")
|
||||
local repo; repo="$(pwd)"
|
||||
local max_jobs="${RUN_TB_JOBS:-}"
|
||||
if [ -z "$max_jobs" ]; then
|
||||
if command -v nproc >/dev/null 2>&1; then
|
||||
max_jobs="$(nproc)"
|
||||
[ "$max_jobs" -gt 4 ] && max_jobs=4
|
||||
else
|
||||
max_jobs=4
|
||||
fi
|
||||
fi
|
||||
case "$max_jobs" in
|
||||
''|*[!0-9]*|0) echo "ERROR: RUN_TB_JOBS must be a positive integer (got '$max_jobs')"; return 1 ;;
|
||||
esac
|
||||
|
||||
rm -rf "$PAR_BASE"; mkdir -p "$PAR_BASE"
|
||||
echo " launching ${#specs[@]} xsim job(s), parallelism=$max_jobs"
|
||||
|
||||
# launch all jobs in parallel
|
||||
local s snap k c wd
|
||||
local s snap k c wd active=0 launched=0 total_specs=${#specs[@]}
|
||||
for s in "${specs[@]}"; do
|
||||
IFS=: read -r snap k c <<< "$s"
|
||||
launched=$((launched + 1))
|
||||
if [ -t 1 ]; then
|
||||
printf "\r running [%d/%d] K=%s CASE=%s" "$launched" "$total_specs" "$k" "$c"
|
||||
else
|
||||
echo " running [$launched/$total_specs] K=$k CASE=$c"
|
||||
fi
|
||||
wd="$PAR_BASE/${mtag}_k${k}_c${c}"
|
||||
mkdir -p "$wd"
|
||||
cp -r "$repo/xsim.dir" "$wd/xsim.dir"
|
||||
# The TB loads vectors via repo-relative $readmemh paths
|
||||
# (sync_rtl/top/TB/vectors/...). xsim resolves these against the run
|
||||
# cwd, so symlink the repo's sync_rtl tree into each private workdir.
|
||||
# The TB loads vectors via repo-relative $readmemh paths. xsim resolves
|
||||
# these against the run cwd, so mount the generated vector directory
|
||||
# under each private workdir.
|
||||
if [ -n "$KAT_RUN_VECTOR_DIR" ]; then
|
||||
mkdir -p "$wd/sync_rtl/top/TB"
|
||||
ln -sf "$KAT_RUN_VECTOR_DIR" "$wd/sync_rtl/top/TB/vectors"
|
||||
else
|
||||
ln -sf "$repo/sync_rtl" "$wd/sync_rtl"
|
||||
fi
|
||||
(
|
||||
cd "$wd"
|
||||
{
|
||||
echo "xsim $snap -R -testplusarg CASE=$c"
|
||||
xsim "$snap" -R -testplusarg "CASE=$c" --nolog > "$wd/run.out" 2>&1
|
||||
xsim "$snap" -R -testplusarg "CASE=$c" --nolog
|
||||
} > "$wd/run.out" 2>&1
|
||||
) &
|
||||
active=$((active + 1))
|
||||
if [ "$active" -ge "$max_jobs" ]; then
|
||||
wait -n || true
|
||||
active=$((active - 1))
|
||||
fi
|
||||
done
|
||||
wait
|
||||
wait || true
|
||||
[ -t 1 ] && echo ""
|
||||
|
||||
# ordered summary + per-job log copy to /tmp/run_tb_<mtag>_k*_c*.log
|
||||
local fail=0 pf nf log timing_logs=()
|
||||
# ordered result aggregation + per-job log copy to /tmp/run_tb_<mtag>_k*_c*.log
|
||||
local fail=0 pf nf log ok
|
||||
local total=0 pass_count=0 fail_count=0 noresult_count=0 fnf_count=0
|
||||
local timing_logs=() failures=()
|
||||
for s in "${specs[@]}"; do
|
||||
IFS=: read -r snap k c <<< "$s"
|
||||
wd="$PAR_BASE/${mtag}_k${k}_c${c}"
|
||||
@@ -233,14 +363,38 @@ run_xsim_jobs() {
|
||||
timing_logs+=("$log")
|
||||
pf=$(grep -oE "$pgrep" "$log" | tail -1)
|
||||
nf=$(grep -c 'cannot be opened' "$log")
|
||||
echo " K=$k CASE=$c -> ${pf:-NORESULT} (file-not-found=$nf, log: $log)"
|
||||
total=$((total + 1))
|
||||
[ -n "$pf" ] || noresult_count=$((noresult_count + 1))
|
||||
[ "$nf" -eq 0 ] || fnf_count=$((fnf_count + 1))
|
||||
|
||||
# pmatch == "PASS*" means "any PASS (Dn) stage tag"; else exact match.
|
||||
if [ "$pmatch" = "PASS*" ]; then
|
||||
{ [[ "$pf" == PASS* ]] && [ "$nf" -eq 0 ]; } || fail=1
|
||||
[[ "$pf" == PASS* ]] && [ "$nf" -eq 0 ]; ok=$?
|
||||
else
|
||||
{ [ "$pf" = "$pmatch" ] && [ "$nf" -eq 0 ]; } || fail=1
|
||||
[ "$pf" = "$pmatch" ] && [ "$nf" -eq 0 ]; ok=$?
|
||||
fi
|
||||
|
||||
if [ "$ok" -eq 0 ]; then
|
||||
pass_count=$((pass_count + 1))
|
||||
else
|
||||
fail=1
|
||||
fail_count=$((fail_count + 1))
|
||||
if [ "${#failures[@]}" -lt 20 ]; then
|
||||
failures+=("K=$k CASE=$c -> ${pf:-NORESULT} (file-not-found=$nf, log: $log)")
|
||||
fi
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "Result summary: total=$total success=$pass_count failure=$fail_count noresult=$noresult_count file-not-found=$fnf_count"
|
||||
if [ "$fail_count" -gt 0 ]; then
|
||||
echo "Failed cases (first ${#failures[@]} of $fail_count):"
|
||||
local item
|
||||
for item in "${failures[@]}"; do
|
||||
echo " $item"
|
||||
done
|
||||
fi
|
||||
|
||||
print_timing_summary "${timing_logs[@]}"
|
||||
rm -rf "$PAR_BASE"
|
||||
return $fail
|
||||
@@ -248,11 +402,12 @@ run_xsim_jobs() {
|
||||
|
||||
# Fast single-K / single-case path for the 'top' (ML-KEM KeyGen) module.
|
||||
# Compiles the same RTL as the tcl, but elaborates ONLY the requested K and
|
||||
# runs the CASE(s) in parallel. Avoids the 3-snapshot + 11-run serial sweep.
|
||||
# runs the generated/enumerated CASE(s) through the bounded parallel launcher.
|
||||
run_top_selected() {
|
||||
local tcl_file="$1" ksel="$2" csel="$3"
|
||||
set +e # we do our own error handling / result parsing here
|
||||
|
||||
generate_kat_vectors top "$ksel" "$csel" || return 1
|
||||
rm -rf xsim.dir .Xil
|
||||
|
||||
# Compile every xvlog line from the tcl, verbatim.
|
||||
@@ -267,10 +422,13 @@ run_top_selected() {
|
||||
echo " xelab tb_mlkem_kg_katK_xsim -generic_top KP=$k -s mlkem_kg_k$k --timescale 1ns/1ps"
|
||||
xelab tb_mlkem_kg_katK_xsim -generic_top KP=$k -s mlkem_kg_k$k --timescale 1ns/1ps \
|
||||
|| { echo "ELAB FAILED for K=$k"; return 1; }
|
||||
# Cases per K: K=2 has 0..4, K=3/4 have 0..2.
|
||||
local cases
|
||||
if [ "$k" = "2" ]; then cases="0 1 2 3 4"; else cases="0 1 2"; fi
|
||||
if [ -n "$csel" ]; then cases="$csel"; fi
|
||||
if [ -n "$csel" ]; then
|
||||
cases="$csel"
|
||||
else
|
||||
cases="$(kat_cases_for top "$k")"
|
||||
fi
|
||||
[ -n "$cases" ] || { echo "ERROR: no KeyGen KAT cases found for K=$k"; return 1; }
|
||||
local c
|
||||
for c in $cases; do specs+=("mlkem_kg_k$k:$k:$c"); done
|
||||
done
|
||||
@@ -285,6 +443,7 @@ run_enc_selected() {
|
||||
local tcl_file="$1" ksel="$2" csel="$3"
|
||||
set +e
|
||||
|
||||
generate_kat_vectors enc "$ksel" "$csel" || return 1
|
||||
rm -rf xsim.dir .Xil
|
||||
|
||||
# Compile every xvlog line from the tcl EXCEPT the KeyGen TB (the encaps TB
|
||||
@@ -306,8 +465,13 @@ run_enc_selected() {
|
||||
echo " xelab tb_mlkem_enc_katK_xsim -generic_top KP=$k -s mlkem_enc_k$k --timescale 1ns/1ps"
|
||||
xelab tb_mlkem_enc_katK_xsim -generic_top KP=$k -s mlkem_enc_k$k --timescale 1ns/1ps \
|
||||
|| { echo "ELAB FAILED for K=$k"; return 1; }
|
||||
local cases="0 1 2"
|
||||
if [ -n "$csel" ]; then cases="$csel"; fi
|
||||
local cases
|
||||
if [ -n "$csel" ]; then
|
||||
cases="$csel"
|
||||
else
|
||||
cases="$(kat_cases_for enc "$k")"
|
||||
fi
|
||||
[ -n "$cases" ] || { echo "ERROR: no Encaps KAT cases found for K=$k"; return 1; }
|
||||
local c
|
||||
for c in $cases; do specs+=("mlkem_enc_k$k:$k:$c"); done
|
||||
done
|
||||
@@ -321,6 +485,7 @@ run_dec_selected() {
|
||||
local tcl_file="$1" ksel="$2" csel="$3"
|
||||
set +e
|
||||
|
||||
generate_kat_vectors dec "$ksel" "$csel" || return 1
|
||||
rm -rf xsim.dir .Xil
|
||||
|
||||
while read -r cmd; do
|
||||
@@ -338,8 +503,13 @@ run_dec_selected() {
|
||||
echo " xelab tb_mlkem_dec_katK_xsim -generic_top KP=$k -s mlkem_dec_k$k --timescale 1ns/1ps"
|
||||
xelab tb_mlkem_dec_katK_xsim -generic_top KP=$k -s mlkem_dec_k$k --timescale 1ns/1ps \
|
||||
|| { echo "ELAB FAILED for K=$k"; return 1; }
|
||||
local cases="0 1 2"
|
||||
if [ -n "$csel" ]; then cases="$csel"; fi
|
||||
local cases
|
||||
if [ -n "$csel" ]; then
|
||||
cases="$csel"
|
||||
else
|
||||
cases="$(kat_cases_for dec "$k")"
|
||||
fi
|
||||
[ -n "$cases" ] || { echo "ERROR: no Decaps KAT cases found for K=$k"; return 1; }
|
||||
local c
|
||||
for c in $cases; do specs+=("mlkem_dec_k$k:$k:$c"); done
|
||||
done
|
||||
|
||||
@@ -1,34 +1,22 @@
|
||||
#!/usr/bin/env python3
|
||||
"""gen_vectors.py - Test vector generator for sample_ntt_sync module.
|
||||
"""Generate FIPS 203 SampleNTT test vectors for sample_ntt_sync.
|
||||
|
||||
Generates random rho+k+i+j test vectors, computes expected coefficients using
|
||||
Keccak-p[1600, 24] matching the RTL's per-permutation squeeze pattern.
|
||||
The reference oracle is hashlib.shake_128 (FIPS 202). It samples
|
||||
SHAKE128(rho || j || i) by reading three bytes at a time and accepting
|
||||
d1 = b0 + 256 * (b1 mod 16) and d2 = floor(b1 / 16) + 16 * b2 when d < Q.
|
||||
|
||||
The RTL sample_ntt_sync absorbs rho || j || i, then repeatedly permutes
|
||||
the keccak state, extracting d1,d2 from bits [23:0] of each permuted state
|
||||
with rejection sampling (d < Q=3329).
|
||||
|
||||
Algorithm (matching RTL exactly):
|
||||
1. Build absorb state: pad10*1 padding for SHAKE-128 (rate=1344) on msg(272b)
|
||||
2. state = keccak_p(absorb_state)
|
||||
3. Extract d1 = (state[11:8] << 8) | state[7:0]
|
||||
d2 = (state[23:16] << 4) | state[15:12]
|
||||
4. If d1 < Q: output d1 (12-bit unsigned)
|
||||
5. If d2 < Q: output d2
|
||||
6. state = keccak_p(state)
|
||||
7. Repeat 3-6 until 256 coefficients collected
|
||||
|
||||
Bit ordering (FIPS 202 / RTL match):
|
||||
The RTL feeds rho_i[0] as the first message bit into SHA3.
|
||||
$readmemh stores hex MSB-first → rho_i[255:0] in MSB-first order.
|
||||
Python: input bytes = reversed(bytes.fromhex(rho_hex)) + bytes([j, i])
|
||||
The RTL feeds rho_i[0] as the first message byte. $readmemh loads
|
||||
rho_i[255:0] MSB-first, so Python passes
|
||||
reversed(bytes.fromhex(rho_hex)) + bytes([j, i]) to SHAKE-128.
|
||||
|
||||
Usage:
|
||||
python3 gen_vectors.py # Generate vectors
|
||||
python3 gen_vectors.py --verify # Verify results against expected
|
||||
python3 gen_vectors.py --refresh-expected # Recompute checked-in oracle
|
||||
python3 gen_vectors.py --selftest # Run Keccak-p self-test
|
||||
"""
|
||||
|
||||
import hashlib
|
||||
import os
|
||||
import random
|
||||
import sys
|
||||
@@ -36,6 +24,15 @@ import sys
|
||||
Q = 3329
|
||||
N_COEFFS = 256
|
||||
|
||||
# This vector accepts its 256th coefficient as d2 from group 168, the final
|
||||
# group of a SHAKE-128 rate block. It guards the no-extra-permutation boundary.
|
||||
RATE_BOUNDARY_VECTOR = {
|
||||
"rho_hex": "7484937160DBF5D93F7D69AEA2DF7C7C77B3A6B02D6B4D579CF975E6F8562097",
|
||||
"k": 2,
|
||||
"i": 1,
|
||||
"j": 1,
|
||||
}
|
||||
|
||||
# ======================================================================
|
||||
# Keccak-p[1600, 24] implementation (stdlib only, matches RTL exactly)
|
||||
# ======================================================================
|
||||
@@ -269,10 +266,7 @@ def extract_d1_d2(state):
|
||||
|
||||
|
||||
def sample_ntt_compute(rho_hex, k, i, j):
|
||||
"""Compute expected coefficients matching RTL sample_ntt_sync.
|
||||
|
||||
The RTL absorbs rho || j || i, then repeatedly permutes,
|
||||
extracting d1,d2 from each permuted state with rejection sampling.
|
||||
"""Compute the FIPS 203 SampleNTT output for one matrix polynomial.
|
||||
|
||||
Args:
|
||||
rho_hex: 64-char hex string.
|
||||
@@ -283,12 +277,19 @@ def sample_ntt_compute(rho_hex, k, i, j):
|
||||
Returns:
|
||||
list of 256 integers in [0, Q-1].
|
||||
"""
|
||||
state = build_absorb_state(rho_hex, j, i)
|
||||
state = keccak_p(state)
|
||||
|
||||
del k
|
||||
msg = bytes.fromhex(rho_hex)[::-1] + bytes([j & 0xFF, i & 0xFF])
|
||||
coeffs = []
|
||||
out_len = 168
|
||||
processed = 0
|
||||
|
||||
while len(coeffs) < N_COEFFS:
|
||||
d1, d2 = extract_d1_d2(state)
|
||||
stream = hashlib.shake_128(msg).digest(out_len)
|
||||
for off in range(processed, len(stream) - 2, 3):
|
||||
b0, b1, b2 = stream[off:off + 3]
|
||||
d1 = b0 + 256 * (b1 & 0x0F)
|
||||
d2 = (b1 >> 4) + 16 * b2
|
||||
|
||||
if d1 < Q:
|
||||
coeffs.append(d1)
|
||||
if len(coeffs) == N_COEFFS:
|
||||
@@ -297,8 +298,8 @@ def sample_ntt_compute(rho_hex, k, i, j):
|
||||
coeffs.append(d2)
|
||||
if len(coeffs) == N_COEFFS:
|
||||
break
|
||||
# Re-permute for next squeeze
|
||||
state = keccak_p(state)
|
||||
processed = out_len
|
||||
out_len += 168
|
||||
|
||||
return coeffs
|
||||
|
||||
@@ -367,9 +368,7 @@ 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 idx, v in enumerate(vectors):
|
||||
f.write(f"# VECTOR_{idx} k={v['k']} i={v['i']} j={v['j']} "
|
||||
f"rho={v['rho_hex']}\n")
|
||||
for v in vectors:
|
||||
for c in v["coeffs"]:
|
||||
f.write(coeff_to_hex(c) + "\n")
|
||||
|
||||
@@ -424,7 +423,7 @@ def main():
|
||||
|
||||
if "--selftest" in sys.argv:
|
||||
keccak_p_selftest()
|
||||
print("Running quick smoke test on sample_ntt computation...")
|
||||
print("Running FIPS SampleNTT reference self-test...")
|
||||
rho = "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F"
|
||||
coeffs = sample_ntt_compute(rho, k=4, i=0, j=0)
|
||||
print(f" rho={rho[:16]}...: {len(coeffs)} coefficients")
|
||||
@@ -467,14 +466,33 @@ def main():
|
||||
else:
|
||||
print("VERIFICATION FAILED")
|
||||
sys.exit(1)
|
||||
elif "--refresh-expected" in sys.argv:
|
||||
if not os.path.exists(input_file):
|
||||
print(f"ERROR: Input file not found: {input_file}")
|
||||
sys.exit(1)
|
||||
|
||||
vectors = []
|
||||
with open(input_file, "r") as f:
|
||||
for line in f:
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
if len(line) != 66:
|
||||
raise ValueError(f"invalid packed input vector: {line}")
|
||||
header = int(line[:2], 16)
|
||||
vectors.append({
|
||||
"rho_hex": line[2:],
|
||||
"k": header & 0x7,
|
||||
"i": (header >> 3) & 0x3,
|
||||
"j": (header >> 5) & 0x3,
|
||||
})
|
||||
for v in vectors:
|
||||
v["coeffs"] = sample_ntt_compute(v["rho_hex"], v["k"], v["i"], v["j"])
|
||||
write_expected_hex(vectors, expected_file)
|
||||
print(f"Wrote {len(vectors)} FIPS SampleNTT expected vectors to {expected_file}")
|
||||
else:
|
||||
# Generate mode — only input vectors (no expected outputs).
|
||||
# The RTL uses per-permutation Keccak-p extraction that may not
|
||||
# match standard SHAKE-128 bit-stream output. The TB performs a
|
||||
# smoke test: 256 coefficients, each in [0, Q-1].
|
||||
vector_count = 4
|
||||
print(f"Generating {vector_count} random input vectors...")
|
||||
print(f"(Expected outputs are NOT computed — TB uses smoke-test only.)")
|
||||
|
||||
vectors = []
|
||||
for idx in range(vector_count):
|
||||
@@ -490,8 +508,15 @@ def main():
|
||||
})
|
||||
print(f" Vector {idx}: k={k}, i={i}, j={j}, rho={rho_hex[:8]}...")
|
||||
|
||||
vectors.append(RATE_BOUNDARY_VECTOR.copy())
|
||||
print(" Boundary vector: k=2, i=1, j=1 (256th coefficient is group 168 d2)")
|
||||
|
||||
write_input_hex(vectors, input_file)
|
||||
for v in vectors:
|
||||
v["coeffs"] = sample_ntt_compute(v["rho_hex"], v["k"], v["i"], v["j"])
|
||||
write_expected_hex(vectors, expected_file)
|
||||
print(f"Wrote {len(vectors)} vectors to {input_file}")
|
||||
print(f"Wrote FIPS SampleNTT expected values to {expected_file}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@@ -1,10 +1,7 @@
|
||||
// tb_sample_ntt_xsim.v - Vivado xsim smoke-test testbench for sample_ntt_sync
|
||||
// tb_sample_ntt_xsim.v - Vivado xsim FIPS SampleNTT testbench
|
||||
//
|
||||
// Drives the DUT with test vectors from a hex file, then verifies that
|
||||
// the DUT produces exactly 256 coefficients, each in range [0, Q-1].
|
||||
// This is a smoke test — it does NOT compare against Python expected values
|
||||
// because the RTL uses a per-permutation Keccak-p approach that differs
|
||||
// from standard SHAKE-128 bit-stream semantics.
|
||||
// Drives the DUT with test vectors from a hex file and checks every coefficient
|
||||
// against the FIPS 203 reference generated by gen_vectors.py.
|
||||
//
|
||||
// Vector format (packed hex, 66 chars for $readmemh):
|
||||
// {j_idx[1:0], i_idx[1:0], k_i[2:0], rho_i[255:0]} (264 bits → 66 hex chars)
|
||||
@@ -16,7 +13,8 @@
|
||||
//
|
||||
// Prerequisites:
|
||||
// - Generate vectors: python3 TB/gen_vectors.py
|
||||
// - Output file: vectors/sample_ntt_input.hex
|
||||
// - Or refresh expected vectors: python3 TB/gen_vectors.py --refresh-expected
|
||||
// - Output files: vectors/sample_ntt_input.hex, vectors/sample_ntt_expected.hex
|
||||
|
||||
`timescale 1ns / 1ps
|
||||
|
||||
@@ -26,7 +24,9 @@ module tb_sample_ntt_xsim;
|
||||
// Parameters
|
||||
// ================================================================
|
||||
parameter VECTOR_FILE = "sync_rtl/sample_ntt/TB/vectors/sample_ntt_input.hex";
|
||||
parameter MAX_VECTORS = 32; // max lines in input file
|
||||
parameter EXPECTED_FILE = "sync_rtl/sample_ntt/TB/vectors/sample_ntt_expected.hex";
|
||||
parameter MAX_VECTORS = 32; // allocation limit for input vectors
|
||||
parameter VECTOR_COUNT = 5; // vectors present in VECTOR_FILE
|
||||
parameter Q = 3329; // ML-KEM modulus
|
||||
parameter N_COEFFS = 256; // coefficients per polynomial
|
||||
parameter TIMEOUT = 500000; // per-vector timeout (cycles)
|
||||
@@ -75,6 +75,7 @@ module tb_sample_ntt_xsim;
|
||||
// Vector memory (loaded by $readmemh)
|
||||
// ================================================================
|
||||
reg [263:0] vector_mem [0:MAX_VECTORS-1];
|
||||
reg [11:0] expected_mem [0:MAX_VECTORS*N_COEFFS-1];
|
||||
integer vec_count;
|
||||
integer idx;
|
||||
integer cycle_count;
|
||||
@@ -88,27 +89,14 @@ module tb_sample_ntt_xsim;
|
||||
// Main test sequence
|
||||
// ================================================================
|
||||
initial begin
|
||||
vec_count = 0;
|
||||
|
||||
// Load vectors from hex file
|
||||
$readmemh(VECTOR_FILE, vector_mem);
|
||||
$readmemh(EXPECTED_FILE, expected_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] === {264{1'bx}} || vector_mem[idx] === {264{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: <66 hex chars> = {j, i, k, rho}");
|
||||
vec_count = VECTOR_COUNT;
|
||||
if (vec_count < 1 || vec_count > MAX_VECTORS) begin
|
||||
$display("ERROR: VECTOR_COUNT=%0d must be in [1,%0d]",
|
||||
vec_count, MAX_VECTORS);
|
||||
$finish;
|
||||
end
|
||||
|
||||
@@ -141,6 +129,8 @@ module tb_sample_ntt_xsim;
|
||||
reg [1:0] vec_i;
|
||||
reg [1:0] vec_j;
|
||||
reg range_ok;
|
||||
reg coeff_ok;
|
||||
reg last_ok;
|
||||
|
||||
// Extract fields from packed vector_mem
|
||||
// vector_mem[263:0] = {1'b0, j_idx, i_idx, k_i, rho_i}
|
||||
@@ -170,18 +160,31 @@ module tb_sample_ntt_xsim;
|
||||
coeff_idx = 0;
|
||||
cycle_count = 0;
|
||||
range_ok = 1'b1; // assume OK until proven otherwise
|
||||
coeff_ok = 1'b1;
|
||||
last_ok = 1'b1;
|
||||
|
||||
while (coeff_idx < N_COEFFS && cycle_count < TIMEOUT) begin
|
||||
@(posedge clk);
|
||||
cycle_count = cycle_count + 1;
|
||||
|
||||
if (valid_o) begin
|
||||
if (coeff_o !== expected_mem[idx*N_COEFFS + coeff_idx]) begin
|
||||
$display("ERROR: Vector %0d coeff[%0d] mismatch: got=%03h expected=%03h",
|
||||
idx, coeff_idx, coeff_o,
|
||||
expected_mem[idx*N_COEFFS + coeff_idx]);
|
||||
coeff_ok = 1'b0;
|
||||
end
|
||||
// Check range: coefficient must be in [0, Q-1]
|
||||
if (coeff_o >= Q) begin
|
||||
$display("ERROR: Vector %0d coeff[%0d]=%0d out of range [0,%0d]",
|
||||
idx, coeff_idx, coeff_o, Q-1);
|
||||
range_ok = 1'b0;
|
||||
end
|
||||
if (last_o !== (coeff_idx == N_COEFFS-1)) begin
|
||||
$display("ERROR: Vector %0d coeff[%0d] last_o=%b expected=%b",
|
||||
idx, coeff_idx, last_o, coeff_idx == N_COEFFS-1);
|
||||
last_ok = 1'b0;
|
||||
end
|
||||
coeff_idx = coeff_idx + 1;
|
||||
end
|
||||
end
|
||||
@@ -199,8 +202,16 @@ module tb_sample_ntt_xsim;
|
||||
$display("ERROR: Vector %0d produced out-of-range coefficients",
|
||||
idx);
|
||||
fail_count = fail_count + 1;
|
||||
end else if (!coeff_ok) begin
|
||||
$display("ERROR: Vector %0d did not match FIPS SampleNTT",
|
||||
idx);
|
||||
fail_count = fail_count + 1;
|
||||
end else if (!last_ok) begin
|
||||
$display("ERROR: Vector %0d asserted last_o on the wrong coefficient",
|
||||
idx);
|
||||
fail_count = fail_count + 1;
|
||||
end else begin
|
||||
$display("INFO: Vector %0d PASSED (%0d coefficients in %0d cycles, all in range)",
|
||||
$display("INFO: Vector %0d PASSED (%0d FIPS-matching coefficients in %0d cycles)",
|
||||
idx, coeff_idx, cycle_count);
|
||||
pass_count = pass_count + 1;
|
||||
end
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -2,3 +2,4 @@
|
||||
12F9652FD859317D04232072A19A8A4E2ABE9A8D5402819FC53C33C337C6797E4B
|
||||
52CFFFE52DCB27B795B608BD58C7D52D79367553276B2B54C039E0650A0D86AFDA
|
||||
735E2459D975610B15D89165C144715F9D218BC08EE93CE6AD0B52F8FE751CAA56
|
||||
2A7484937160DBF5D93F7D69AEA2DF7C7C77B3A6B02D6B4D579CF975E6F8562097
|
||||
|
||||
Reference in New Issue
Block a user