run.sh: add the stub mode and document VT1200_IO_PATH_STUB as a non-faithful opt-in

harness/mame/run.sh

@@ -6,6 +6,8 @@
 #   ./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 stub            faithful, plus an opt-in stand-in for the level-0
+#                            keyboard-port test fixture -> reaches level 1
 #   ./run.sh <mode> -- <extra MAME options>
 #
 # Reboot the running machine with Shift+F3 (MAME's UI_RESET_MACHINE; plain F3 is a
@@ -21,6 +23,11 @@
 #   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.
+#   stub  supplies ten bytes on the keyboard port so the level-0 I/O data path test
+#         passes, so the faithful boot reaches level 1 instead of stopping at level 0.
+#         It is NOT a keyboard model: that test checks only the byte *count* and never
+#         compares the content, so the bytes are arbitrary.  It stands in for an
+#         unknown test fixture, and it is opt-in so the default stays honest.
 #
 # Modes other than 'headless' open a window at real speed, so you can watch.
 
@@ -44,7 +51,7 @@ fi
 MODE="${1:-faithful}"
 if [ $# -gt 0 ]; then shift; fi
 
-usage() { sed -n '2,25p' "$0"; }
+usage() { awk 'NR>1 && /^set -euo pipefail/{exit} NR>1{print}' "$0"; }
 
 # common: correct rompath, no sound (the driver has no audio), no licence screen
 COMMON=(-rompath "$ROMPATH" -sound none -skip_gameinfo)
@@ -76,6 +83,14 @@ case "$MODE" in
             -autoboot_script "$HERE/l1patch.lua" -autoboot_delay 0 "$@"
         ;;
 
+    stub)
+        # opt-in stand-in for the unknown level-0 keyboard-port test fixture.
+        # NOT a keyboard model -- that test checks only the byte count and never
+        # the content.  See reference/level0-10byte-puzzle.md.
+        exec env VT1200_IO_PATH_STUB=1 \
+            "$MAME" vt1200 "${COMMON[@]}" -window "$@"
+        ;;
+
     headless)
         N="${1:-600}"
         if [ $# -gt 0 ]; then shift; fi