test: add board FFT validation and VCD capture

doc/reports/system/tools/run_report_tests.sh

@@ -50,11 +50,16 @@ Commands:
   prepare       Create evidence directories and Vivado project if absent
   lint          Run the project-aware Verilator lint check
   build         Build asm, fft, fft_dma, mlkem_test and mlkem_hello
-  soc           Build all five; simulate all except board-only asm
+  soc           Build all five; simulate mlkem_test and mlkem_hello
+  soc-fft       Explicitly run the long fft and fft_dma simulations
   implement     Run Vivado implementation and collect PPA/CDC/DRC reports
   refresh       Parse collected evidence, regenerate figures and build the PDF
   quick         Run lint and refresh only; does not run Vivado implementation
 
+Set SAVE_VCD=1 for SoC simulations to write evidence/soc/<example>.vcd.
+Set VCD_SCOPE to a Vivado hierarchy glob to limit waveform size.
+Set SIM_RUN_TIME only for bounded waveform diagnostics; regressions use 'all'.
+
 Board-only tests (matmul official 5000-group timing and reset behavior) are
 listed in REPORT_RERUN_CHECKLIST.md and are intentionally not automated here.
 EOF
@@ -95,21 +100,31 @@ build() {
 
 run_soc_case() {
   local example="$1"
+  local vcd_path="$EVIDENCE_DIR/soc/$example.vcd"
   require_vivado
   build_example "$example"
-  (cd "$ROOT/fpga" && "$VIVADO_BIN" -mode batch \
+  if [[ "${SAVE_VCD:-0}" != "0" ]]; then
+    echo "VCD output: $vcd_path (scope: ${VCD_SCOPE:-top-level control signals})"
+  fi
+  (cd "$ROOT/fpga" && SOC_VCD_PATH="$vcd_path" "$VIVADO_BIN" -mode batch \
     -source "$SCRIPT_DIR/run_soc_sim.tcl") 2>&1 | tee "$EVIDENCE_DIR/soc/$example.log"
 }
 
 soc() {
   prepare
   build_example asm
-  run_soc_case fft
-  run_soc_case fft_dma
+  build_example fft
+  build_example fft_dma
   run_soc_case mlkem_test
   run_soc_case mlkem_hello
 }
 
+soc_fft() {
+  prepare
+  run_soc_case fft
+  run_soc_case fft_dma
+}
+
 implement() {
   prepare
   require_vivado
@@ -130,6 +145,7 @@ case "${1:-}" in
   lint) lint ;;
   build) build ;;
   soc) soc ;;
+  soc-fft) soc_fft ;;
   implement) implement ;;
   refresh) refresh ;;
   quick) lint; refresh ;;

doc/reports/system/tools/run_soc_sim.tcl

@@ -5,6 +5,17 @@ set script_dir [file dirname [file normalize [info script]]]
 set repo_root [file normalize [file join $script_dir ../../../..]]
 set xpr [file join $repo_root fpga project Loongson_Soc.xpr]
 
+set save_vcd 0
+if {[info exists ::env(SAVE_VCD)]} {
+    set value [string tolower [string trim $::env(SAVE_VCD)]]
+    set save_vcd [expr {$value ni {"" "0" "false" "no" "off"}}]
+}
+
+set sim_run_time "all"
+if {[info exists ::env(SIM_RUN_TIME)] && $::env(SIM_RUN_TIME) ne ""} {
+    set sim_run_time $::env(SIM_RUN_TIME)
+}
+
 # xelab inherits this when compiling generated C files with the host gcc.
 set ::env(CCACHE_DISABLE) 1
 
@@ -31,11 +42,58 @@ set simset [get_filesets sim_1]
 set_property top tb_top $simset
 set_property incremental false $simset
 set_property xsim.elaborate.mt_level off $simset
-set_property xsim.elaborate.debug_level off $simset
+set_property xsim.elaborate.debug_level [expr {$save_vcd ? "typical" : "off"}] $simset
 set_property xsim.simulate.log_all_signals false $simset
+if {$save_vcd} {
+    # launch_simulation normally runs 1000 ns before returning. Start at 0 ns
+    # so the VCD includes power-on reset and reset release.
+    set_property xsim.simulate.runtime 0ns $simset
+}
 update_compile_order -fileset sim_1
 launch_simulation
-run all
+
+if {$save_vcd} {
+    if {![info exists ::env(SOC_VCD_PATH)] || $::env(SOC_VCD_PATH) eq ""} {
+        puts stderr "ERROR: SAVE_VCD requires SOC_VCD_PATH"
+        close_sim
+        close_project
+        exit 4
+    }
+
+    set vcd_path [file normalize $::env(SOC_VCD_PATH)]
+    set vcd_patterns [list \
+        /tb_top/clk \
+        /tb_top/reset \
+        /tb_top/UART_TX \
+        /tb_top/uart_wen \
+        /tb_top/uart_data \
+        /tb_top/debug_wb_pc]
+    if {[info exists ::env(VCD_SCOPE)] && $::env(VCD_SCOPE) ne ""} {
+        set vcd_patterns [list $::env(VCD_SCOPE)]
+        set vcd_objects [get_objects -quiet -r {*}$vcd_patterns]
+    } else {
+        # Keep the default trace small. Recursive collection is only enabled
+        # when the caller explicitly supplies VCD_SCOPE.
+        set vcd_objects [get_objects -quiet {*}$vcd_patterns]
+    }
+    if {[llength $vcd_objects] == 0} {
+        puts stderr "ERROR: VCD scope matched no simulation objects: $vcd_patterns"
+        close_sim
+        close_project
+        exit 5
+    }
+
+    file mkdir [file dirname $vcd_path]
+    puts "Recording VCD: $vcd_path (scope: $vcd_patterns)"
+    open_vcd $vcd_path
+    log_vcd $vcd_objects
+}
+
+puts "Running simulation for: $sim_run_time"
+run $sim_run_time
+if {$save_vcd} {
+    close_vcd
+}
 close_sim
 close_project
 exit 0

doc/reports/system/tools/update_report_metrics.py

@@ -144,6 +144,7 @@ def update_matmul(metrics: str, log: str) -> str:
 def main() -> None:
     metrics = METRICS.read_text(encoding="utf-8")
     vivado = REPORT_DIR / "evidence" / "vivado"
+    board = REPORT_DIR / "evidence" / "board"
     legacy = ROOT / "fpga" / "vivado_reports_nodsp"
     metrics = update_timing(metrics, read_first(vivado / "timing_summary_full.rpt", legacy / "timing_summary_full.rpt"))
     metrics = update_util(metrics, read_first(vivado / "utilization.rpt", legacy / "utilization.rpt"))
@@ -153,10 +154,10 @@ def main() -> None:
     metrics = update_mlkem(metrics, read_first(soc / "mlkem_test.log", ROOT / "sdk/software/examples/mlkem_test/result.txt"))
     metrics = update_fft(
         metrics,
-        read_first(soc / "fft.log", ROOT / "sdk/software/examples/fft/result.txt"),
-        read_first(soc / "fft_dma.log", ROOT / "sdk/software/examples/fft_dma/result.txt"),
+        read_first(board / "fft.log", soc / "fft.log", ROOT / "sdk/software/examples/fft/result.txt"),
+        read_first(board / "fft_dma.log", soc / "fft_dma.log", ROOT / "sdk/software/examples/fft_dma/result.txt"),
     )
-    metrics = update_matmul(metrics, read_first(REPORT_DIR / "evidence" / "board" / "matmul_official.log"))
+    metrics = update_matmul(metrics, read_first(board / "matmul_official.log"))
 
     try:
         revision = subprocess.check_output(