fix(tb): fix Vivado 2019.2 compatibility and add run_tb.sh

- Replace -include_dirs . with -i . (Vivado 2019.2 syntax)
- Add --timescale 1ns/1ps to all xelab commands
- Add LD_PRELOAD comment for ncurses compatibility
- Add run_tb.sh convenience script
  Usage: ./run_tb.sh mod_add
         ./run_tb.sh --list
- Update spec with Vivado 2019.2 compatibility notes

.trellis/spec/rtl/xsim-tb-conventions.md

@@ -144,26 +144,54 @@ d00d00
 
 Width `W` must evenly contain all packed fields. Use padding bits to align to hex-char boundaries (multiples of 4 bits).
 
+## Running Testbenches
+
+### Quick Run
+```bash
+# List available modules
+./run_tb.sh --list
+
+# Run a specific module
+./run_tb.sh mod_add
+```
+
+### Manual Run
+```bash
+source /opt/Xilinx/Vivado/2019.2/settings64.sh
+export LD_PRELOAD=/usr/lib64/libtinfo.so.5  # required for Vivado 2019.2 on modern Linux
+cd ~/Dev/mlkem
+vivado -mode batch -source sync_rtl/mod_add/TB/xsim_run.tcl
+```
+
+### Vivado 2019.2 Compatibility Notes
+- **Include flag**: Use `-i .` (not `-include_dirs .` — that's Vivado 2020+)
+- **ncurses fix**: `export LD_PRELOAD=/usr/lib64/libtinfo.so.5` resolves `_nc_tiparm` symbol error from bundled LLVM 3.1
+- **Timescale**: Always pass `--timescale 1ns/1ps` to `xelab` (RTL modules may lack `timescale directives)
+
 ## xsim_run.tcl
 
 ```tcl
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+
 # Compile RTL dependencies (order matters for submodule hierarchy)
-xvlog -sv -include_dirs . <rtl_dir>/<submodule>.v
+xvlog -sv -i . <rtl_dir>/<submodule>.v
-xvlog -sv -include_dirs . <rtl_dir>/<dut>.v
+xvlog -sv -i . <rtl_dir>/<dut>.v
 
 # Compile testbench
 xvlog -sv <tb_dir>/tb_<module>_xsim.v
 
 # Elaborate
-xelab tb_<module>_xsim -s <snapshot>
+xelab tb_<module>_xsim -s <snapshot> --timescale 1ns/1ps
 
 # Run
 xsim <snapshot> -R
 ```
 
 ### CRITICAL: Include Directories
-- If ANY compiled file uses `` `include "sync_rtl/common/defines.vh" `` (or any relative include), add `-include_dirs .` to ALL `xvlog` invocations in that TCL
+- If ANY compiled file uses `` `include "sync_rtl/common/defines.vh" `` (or any relative include), add `-i .` to ALL `xvlog` invocations in that TCL
-- This ensures Vivado resolves paths relative to the project root
+- **Vivado 2019.2**: Use `-i .` (single dash)
+- **Vivado 2020+**: Use `-include_dirs .` (single or double dash)
 
 ## gen_vectors.py
 

run_tb.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# run_tb.sh - Run Vivado XSIM testbench for a module
+#
+# Usage: ./run_tb.sh <module>
+#        ./run_tb.sh mod_add
+#        ./run_tb.sh --list
+#
+# Prerequisites:
+#   Vivado 2019.2 at /opt/Xilinx/Vivado/2019.2/
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+VIVADO_SETTINGS="/opt/Xilinx/Vivado/2019.2/settings64.sh"
+
+if [ "$1" = "--list" ]; then
+    echo "Available modules:"
+    for d in "$SCRIPT_DIR"/sync_rtl/*/TB; do
+        if [ -f "$d/xsim_run.tcl" ]; then
+            name=$(basename "$(dirname "$d")")
+            echo "  $name"
+        fi
+    done
+    exit 0
+fi
+
+if [ -z "$1" ]; then
+    echo "Usage: $0 <module_name>"
+    echo "       $0 --list"
+    exit 1
+fi
+
+MODULE="$1"
+TB_DIR="$SCRIPT_DIR/sync_rtl/$MODULE/TB"
+TCL_FILE="$TB_DIR/xsim_run.tcl"
+
+if [ ! -f "$TCL_FILE" ]; then
+    echo "ERROR: No xsim_run.tcl found for module '$MODULE'"
+    echo "       Expected: $TCL_FILE"
+    echo "       Run '$0 --list' to see available modules"
+    exit 1
+fi
+
+# Source Vivado environment
+if [ -f "$VIVADO_SETTINGS" ]; then
+    source "$VIVADO_SETTINGS"
+else
+    echo "ERROR: Vivado settings not found at $VIVADO_SETTINGS"
+    exit 1
+fi
+
+# Fix ncurses compatibility for Vivado 2019.2 on modern Linux
+export LD_PRELOAD="${LD_PRELOAD}${LD_PRELOAD:+:}/usr/lib64/libtinfo.so.5"
+
+cd "$SCRIPT_DIR"
+echo "========================================"
+echo " Running testbench for: $MODULE"
+echo "========================================"
+
+# Run xvlog + xelab + xsim commands directly (not via vivado batch)
+# Extract and execute xvlog, xelab, xsim lines from the TCL
+grep -E '^xvlog ' "$TCL_FILE" | while read -r cmd; do
+    if [[ "$cmd" != \#* ]]; then
+        echo "  $cmd"
+        eval "$cmd" 2>&1 | grep -E "ERROR|WARNING|analyzing|Compiling|Built" || true
+    fi
+done
+
+grep -E '^xelab ' "$TCL_FILE" | while read -r cmd; do
+    if [[ "$cmd" != \#* ]]; then
+        echo "  $cmd"
+        eval "$cmd" 2>&1 | grep -E "ERROR|WARNING|Compiling|Built" || true
+    fi
+done
+
+echo ""
+echo "--- Running simulation ---"
+grep -E '^xsim ' "$TCL_FILE" | while read -r cmd; do
+    if [[ "$cmd" != \#* ]]; then
+        eval "$cmd" 2>&1
+    fi
+done

sync_rtl/comp_decomp/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script for comp_decomp_sync
 #
 # Compiles comp_decomp_sync RTL + dependencies + testbench and runs simulation.
@@ -31,10 +35,10 @@ set TB_DIR   sync_rtl/comp_decomp/TB
 puts "=== Compiling RTL sources for comp_decomp_sync ==="
 
 # Common dependency (pipeline register)
-xvlog -sv -include_dirs . ${RTL_DIR}/common/pipeline_reg.v
+xvlog -sv -i . ${RTL_DIR}/common/pipeline_reg.v
 
 # DUT (comp_decomp_sync) — uses `include "sync_rtl/common/defines.vh"
-xvlog -sv -include_dirs . ${DUT_DIR}/comp_decomp_sync.v
+xvlog -sv -i . ${DUT_DIR}/comp_decomp_sync.v
 
 # ================================================================
 # Step 2: Compile testbench
@@ -48,7 +52,7 @@ xvlog -sv ${TB_DIR}/tb_comp_decomp_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_comp_decomp_xsim -s tb_comp_decomp_xsim
+xelab tb_comp_decomp_xsim -s tb_comp_decomp_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/mod_add/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script for mod_add_sync
 #
 # Compiles mod_add_sync RTL plus the file-based vector testbench and runs simulation.
@@ -29,10 +33,10 @@ set COMMON_DIR sync_rtl/common
 puts "=== Compiling RTL sources ==="
 
 # Common pipeline register
-xvlog -sv -include_dirs . ${COMMON_DIR}/pipeline_reg.v
+xvlog -sv -i . ${COMMON_DIR}/pipeline_reg.v
 
 # mod_add_sync (includes defines.vh from common/)
-xvlog -sv -include_dirs . ${SRC_DIR}/mod_add_sync.v
+xvlog -sv -i . ${SRC_DIR}/mod_add_sync.v
 
 # ================================================================
 # Step 2: Compile testbench
@@ -47,7 +51,7 @@ xvlog -sv ${TB_DIR}/tb_mod_add_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_mod_add_xsim -s tb_mod_add_xsim
+xelab tb_mod_add_xsim -s tb_mod_add_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/ntt/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script for NTT
 #
 # Compiles all NTT RTL sources plus testbench and runs simulation.
@@ -49,7 +53,7 @@ xvlog -sv ${TB_DIR}/tb_ntt_core_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_ntt_core_xsim -s ntt_core_sim
+xelab tb_ntt_core_xsim -s ntt_core_sim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/poly_arith/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script for poly_arith_sync
 #
 # Compiles poly_arith_sync RTL + dependencies + testbench and runs simulation.
@@ -31,10 +35,10 @@ set TB_DIR   sync_rtl/poly_arith/TB
 puts "=== Compiling RTL sources for poly_arith_sync ==="
 
 # Common dependency (pipeline register)
-xvlog -sv -include_dirs . ${RTL_DIR}/common/pipeline_reg.v
+xvlog -sv -i . ${RTL_DIR}/common/pipeline_reg.v
 
 # DUT (poly_arith_sync) — uses `include "sync_rtl/common/defines.vh"
-xvlog -sv -include_dirs . ${DUT_DIR}/poly_arith_sync.v
+xvlog -sv -i . ${DUT_DIR}/poly_arith_sync.v
 
 # ================================================================
 # Step 2: Compile testbench
@@ -48,7 +52,7 @@ xvlog -sv ${TB_DIR}/tb_poly_arith_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_poly_arith_xsim -s tb_poly_arith_xsim
+xelab tb_poly_arith_xsim -s tb_poly_arith_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/poly_mul/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script for PolyMul
 #
 # Compiles all PolyMul RTL sources plus dependencies, then testbench,
@@ -56,7 +60,7 @@ xvlog -sv ${TB_DIR}/tb_poly_mul_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_poly_mul_xsim -s poly_mul_sim
+xelab tb_poly_mul_xsim -s poly_mul_sim --timescale 1ns/1ps
 
 # ================================================================
 # Step 5: Run simulation

sync_rtl/rng/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script for rng_sync
 #
 # Compiles rng_sync RTL plus the file-based vector testbench and runs simulation.
@@ -42,7 +46,7 @@ xvlog -sv ${TB_DIR}/tb_rng_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_rng_xsim -s tb_rng_xsim
+xelab tb_rng_xsim -s tb_rng_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/sample_cbd/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation for sample_cbd_sync
 #
 # Compiles sample_cbd_sync RTL + SHA3 dependencies + testbench and runs simulation.
@@ -44,7 +48,7 @@ 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
+xelab tb_sample_cbd_xsim -s tb_sample_cbd_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/sample_ntt/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation for sample_ntt_sync
 #
 # Compiles sample_ntt_sync RTL + SHA3 dependencies + testbench and runs simulation.
@@ -26,13 +30,13 @@ set TB_DIR       sync_rtl/sample_ntt/TB
 puts "=== Compiling RTL sources ==="
 
 # Keccak round (combinational, used by keccak_core)
-xvlog -sv -include_dirs . ${SHA3_DIR}/keccak_round.v
+xvlog -sv -i . ${SHA3_DIR}/keccak_round.v
 
 # Keccak core (24-round sequential core, used by sample_ntt_sync)
-xvlog -sv -include_dirs . ${SHA3_DIR}/keccak_core.v
+xvlog -sv -i . ${SHA3_DIR}/keccak_core.v
 
 # sample_ntt_sync (DUT) — uses `include "sync_rtl/common/defines.vh"
-xvlog -sv -include_dirs . ${SRC_DIR}/sample_ntt_sync.v
+xvlog -sv -i . ${SRC_DIR}/sample_ntt_sync.v
 
 # ================================================================
 # Step 2: Compile testbench
@@ -44,7 +48,7 @@ xvlog -sv ${TB_DIR}/tb_sample_ntt_xsim.v
 # Step 3: Elaborate snapshot (xelab)
 # ================================================================
 puts "=== Elaborating snapshot ==="
-xelab tb_sample_ntt_xsim -s tb_sample_ntt_xsim
+xelab tb_sample_ntt_xsim -s tb_sample_ntt_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/sha3/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script
 #
 # Compiles all SHA3 RTL sources plus testbenches and runs simulation.
@@ -62,13 +66,13 @@ xvlog -sv ${TB_DIR}/tb_sha3_xsim.v
 puts "=== Elaborating snapshots ==="
 
 # Simple sha3_top testbench (G mode, hardcoded vector)
-xelab tb_sha3_xsim_simple -s sha3_simple_sim
+xelab tb_sha3_xsim_simple -s sha3_simple_sim --timescale 1ns/1ps
 
 # Keccak core testbench (all-zero input)
-xelab tb_keccak_core_xsim -s keccak_core_sim
+xelab tb_keccak_core_xsim -s keccak_core_sim --timescale 1ns/1ps
 
 # File-based sha3_top testbench (reads vectors/g_basic_input.hex)
-xelab tb_sha3_xsim -s tb_sha3_xsim
+xelab tb_sha3_xsim -s tb_sha3_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulations

sync_rtl/sha3_chain/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script
 #
 # Compiles sha3_chain_top with all SHA3 dependencies plus testbench.
@@ -52,7 +56,7 @@ xvlog -sv ${TB_DIR}/tb_sha3_chain_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_sha3_chain_xsim -s tb_sha3_chain_xsim
+xelab tb_sha3_chain_xsim -s tb_sha3_chain_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation

sync_rtl/storage/TB/xsim_run.tcl

@@ -1,3 +1,7 @@
+# NOTE: On some systems, you may need:
+#   export LD_PRELOAD=/usr/lib64/libtinfo.so.5
+# before running this script.
+
 # xsim_run.tcl - Vivado xsim compilation and simulation script
 #
 # Compiles s_bram, sd_bram, and tb_storage_xsim testbench.
@@ -36,7 +40,7 @@ xvlog -sv ${TB_DIR}/tb_storage_xsim.v
 # ================================================================
 puts "=== Elaborating snapshot ==="
 
-xelab tb_storage_xsim -s tb_storage_xsim
+xelab tb_storage_xsim -s tb_storage_xsim --timescale 1ns/1ps
 
 # ================================================================
 # Step 4: Run simulation