test(top): hardware hello_world TB (full KeyGen+Encaps+Decaps protocol)

Mirror of ml-kem-r examples/hello_world.rs on the mlkem_top DUT (ML-KEM-512):
  1. Alice KeyGen(d=0x42.., z=0x77..)        -> ek (800B), dk (1632B)
  2. Bob   Encaps(ek, m=0xDE..)              -> shared_key, kem_ct (768B)
  3. Bob   XOR-encrypt "hello world"
  4. Alice Decaps(dk, kem_ct)                 -> recovered_key
  5. Alice XOR-decrypt -> "hello world"

The whole protocol runs on ONE DUT instance: ek/dk are read out of KeyGen via
the dbg taps and fed back into Encaps/Decaps through the streaming input ports,
just as the keys/ciphertext would cross the wire between Alice and Bob. Each
step prints its inputs and outputs.

Output is byte-identical to the Rust example: shared_key=ced0c031a4bee34a...,
encrypted=a6b5ac5dcb9e9425b9e3b8, decrypted="hello world", keys match.

run_hello.sh compiles the RTL + TB and runs it. Cycle counts (K=2): KeyGen
~22.9k, Encaps ~32.5k, Decaps ~50.8k.
This commit is contained in:
2026-06-29 22:06:32 +08:00
parent 2b70431923
commit f27922270a
2 changed files with 215 additions and 0 deletions

16
run_hello.sh Executable file
View File

@@ -0,0 +1,16 @@
#!/usr/bin/env bash
# run_hello.sh - compile + run the ML-KEM hello_world hardware testbench.
set -e
cd "$(dirname "$0")"
source /opt/Xilinx/Vivado/2019.2/settings64.sh >/dev/null 2>&1
export LD_PRELOAD="/usr/lib64/libtinfo.so.5"
rm -rf xsim.dir .Xil
# compile the RTL (every non-TB xvlog line from the shared tcl)
grep -E '^xvlog ' sync_rtl/top/TB/xsim_run.tcl | grep -v 'TB/tb_' | while read -r cmd; do
eval "$cmd" >/dev/null
done
xvlog -sv --relax sync_rtl/top/TB/tb_mlkem_hello_world_xsim.v >/dev/null
xelab tb_mlkem_hello_world_xsim -s mlkem_hello --timescale 1ns/1ps >/dev/null 2>&1
xsim mlkem_hello -R 2>/dev/null | grep -vE '^(#|INFO|Time resolution|run -all|exit|xsim|Vivado|====.*Simulator|SW Build|IP Build|Copyright|Tool Version|Start of|source |## )' | sed '/^$/N;/^\n$/D'