From b99b7de62ebcf6dfd035a0d2bc5bda871af039ba Mon Sep 17 00:00:00 2001
From: SDD <sdd@local>
Date: Fri, 16 Oct 2026 13:21:51 +0300
Subject: [PATCH] harness: add run.sh launcher (faithful/skip/pie/headless
 modes, verified end to end)

---
 harness/mame/run.sh | 91 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100755 harness/mame/run.sh

diff --git a/harness/mame/run.sh b/harness/mame/run.sh
new file mode 100755
index 0000000..bdb2f16
--- /dev/null
+++ b/harness/mame/run.sh
@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# run.sh -- launch the VT1200 MAME harness.
+#
+#   ./run.sh                 faithful boot: POST + level 1, stops at HOST PORT - 15
+#   ./run.sh skip            skip ALL 15 level-1 tests (DUART1 IP3 high) -> OS
+#   ./run.sh pie             runtime-patch the failing checks -> level 1 RUNS (pie graph)
+#   ./run.sh headless [N]    no window; dump frame N (default 600) into this directory
+#   ./run.sh <mode> -- <extra MAME options>
+#
+# Reboot the running machine with Shift+F3 (MAME's UI_RESET_MACHINE; plain F3 is a
+# *machine* key on other drivers, not this one).  Tab opens MAME's menu.  Esc quits.
+#
+# No environment variables are needed for the faithful boot -- the working
+# configuration is the default.  This harness is a visibility tool, not an
+# accurate VT1200 emulation, so read the caveats:
+#
+#   skip  drives a MODELLED BOARD INPUT (DUART1 IP3).  The real machine reads IP3
+#         low, so a skipped run tells you about the OS, graphics and crash path --
+#         NOT about the real terminal's POST.
+#   pie   patches the ROM image IN MEMORY at runtime.  The on-disk ROM is never
+#         modified (hash it before and after if you like), but it is still a debug
+#         view: it shows which tests OUR MODEL fails, not what the hardware does.
+#
+# Modes other than 'headless' open a window at real speed, so you can watch.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MAME="${MAME:-/home/arti/code/k-space/mame0289/vt1200}"
+ROMPATH="$HERE/roms"
+ROM="$ROMPATH/vt1200/vt1200_v22.bin"
+
+if [ ! -x "$MAME" ]; then
+    echo "run.sh: no MAME binary at $MAME" >&2
+    echo "        set MAME=/path/to/vt1200, or build it with ./build.sh" >&2
+    exit 1
+fi
+if [ ! -e "$ROM" ]; then
+    echo "run.sh: ROM not found at $ROM" >&2
+    exit 1
+fi
+
+MODE="${1:-faithful}"
+if [ $# -gt 0 ]; then shift; fi
+
+usage() { sed -n '2,25p' "$0"; }
+
+# common: correct rompath, no sound (the driver has no audio), no licence screen
+COMMON=(-rompath "$ROMPATH" -sound none -skip_gameinfo)
+
+case "$MODE" in
+    faithful|"")
+        exec "$MAME" vt1200 "${COMMON[@]}" -window "$@"
+        ;;
+
+    skip)
+        # IP3 high -> the boot gate at 3F2042D0 jumps to the OS cold-start,
+        # skipping all 15 level-1 tests.  Also flips DUART1's IRQ to INT2, which
+        # is the routing the OS's DUART driver expects (POST uses INT1).
+        exec env VT1200_SKIP_LEVEL1=1 \
+            "$MAME" vt1200 "${COMMON[@]}" -window "$@"
+        ;;
+
+    pie)
+        # `-debug -debugger none` is required: l1patch.lua needs the debugger API.
+        exec env VT1200_L1PATCH=1 \
+            "$MAME" vt1200 "${COMMON[@]}" -window \
+            -debug -debugger none \
+            -autoboot_script "$HERE/l1patch.lua" -autoboot_delay 0 "$@"
+        ;;
+
+    headless)
+        N="${1:-600}"
+        if [ $# -gt 0 ]; then shift; fi
+        # enough emulated seconds to reach frame N at ~72 Hz
+        SECS=$(( N / 72 + 5 ))
+        exec env VT1200_DUMP_FRAME="$N" VT1200_DUMP_DIR="$HERE" \
+            "$MAME" vt1200 "${COMMON[@]}" -video none -nothrottle \
+            -seconds_to_run "$SECS" "$@"
+        ;;
+
+    -h|--help|help)
+        usage
+        ;;
+
+    *)
+        echo "run.sh: unknown mode '$MODE'" >&2
+        echo "        try: faithful | skip | pie | headless [N]" >&2
+        exit 2
+        ;;
+esac