vt1200/harness/mame/run.sh

#!/usr/bin/env bash
# run.sh -- launch the VT1200 MAME harness.
#
#   ./run.sh                 faithful boot: POST, then fails level 0's I/O data path
#                            test (nothing attached) -> diagnostics menu
#   ./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 tablet          skip + VSXXX-AB tablet: interactive GUI with ABSOLUTE
#                            pointing (the cursor follows the host pointer)
#   ./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.
#   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.
#   tablet selects the VSXXX-AB tablet instead of the mouse (VT1200_TABLET=1).  It is
#         ABSOLUTE: the host pointer position maps directly to where the cursor is,
#         rather than being integrated from deltas, and it does not grab the pointer.
#         The mouse stays the default device.  Compose it with any mode by setting the
#         variable yourself, e.g.  VT1200_TABLET=1 ./run.sh skip
#
# 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() { awk 'NR>1 && /^set -euo pipefail/{exit} NR>1{print}' "$0"; }

# common: correct rompath, no sound (the driver has no audio), no licence screen.
# The lightgun options give MAME an absolute host pointer for the VSXXX-AB tablet
# (VT1200_TABLET=1); they are harmless when the tablet is not selected, and they do
# NOT grab the pointer.
COMMON=(-rompath "$ROMPATH" -sound none -skip_gameinfo -lightgun -lightgun_device mouse)

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).
        #
        # DUART2 (keyboard/mouse) is modelled as well, and is REQUIRED for the OS:
        # with it unmodelled the board write-back latch echoes the OS's IWR write
        # when the OS reads DUART2's ISR (0x06200005), producing a phantom
        # interrupt that can never clear -- the OS spins forever at the X11 weave.
        # With it real, the Terminal Manager appears.
        exec env VT1200_SKIP_LEVEL1=1 VT1200_DUART2=1 \
            "$MAME" vt1200 "${COMMON[@]}" -window "$@"
        ;;

    tablet)
        # the useful combination: the OS is only reachable through the skip gate, and
        # the tablet gives absolute pointing, so the cursor follows the host pointer
        # positionally instead of through relative deltas.  The OS distinguishes tablet
        # from mouse by the device-code nibble in its "T" self-test reply, and then
        # frames 5-byte absolute reports (3-byte relative for the mouse).
        exec env VT1200_SKIP_LEVEL1=1 VT1200_TABLET=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 "$@"
        ;;

    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
        # 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