From 638656bd0524000c9f5867f784e20d23c9061218 Mon Sep 17 00:00:00 2001 From: Arti Zirk Date: Sun, 1 Nov 2026 11:24:59 +0200 Subject: [PATCH] docs(badapple): current MAME demo quick start --- bad-apple/README.md | 45 ++++++++++++++++++++++++++++----- bad-apple/REPORT.md | 8 +++--- bad-apple/tools/run_mame_gui.sh | 39 ++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 9 deletions(-) create mode 100755 bad-apple/tools/run_mame_gui.sh diff --git a/bad-apple/README.md b/bad-apple/README.md index 9add77b..961c214 100644 --- a/bad-apple/README.md +++ b/bad-apple/README.md @@ -13,6 +13,35 @@ Design: [`../docs/superpowers/specs/2026-10-31-bad-apple-vector-design.md`](../d Plan: [`../docs/superpowers/plans/2026-11-01-bad-apple-vector.md`](../docs/superpowers/plans/2026-11-01-bad-apple-vector.md) Measurements and gaps: [`REPORT.md`](REPORT.md) +## Quick start — current MAME demo + +From the repository root: + +```sh +# 1. video -> data/movie.bin +cd bad-apple +python3 -m pipeline.build \ + --video /tmp/opencode/badapple-real/hd60.mp4 \ + --out data --duration 30 +cd .. + +# 2. payload +bad-apple/player/build.sh + +# 3. watch it +bad-apple/tools/run_mame_gui.sh +``` + +`run_mame_gui.sh` starts MAME with `VT1200_SKIP_LEVEL1=1`, boots the OS, loads +the payload at frame 2500, lets it take over, writes the movie into low RAM, +and plays it in a window. Expect the 30 s clip at full screen, upright. +`BA_END` (default 8000) is the MAME frame at which the loader script exits; +raise it if your run is slower. + +The **network path is currently disabled in practice**: the OS heap cannot +provide one contiguous 2.4 MB `malloc_` block, so `tools/load.sh` stops before +it binds UDP. Use the debugger path above. See `REPORT.md`. + ## Build the 30 s stream ```sh @@ -47,21 +76,24 @@ The 1987 TI TMS34010 SDK runs under DOSBox. The C sources are K&R C: the ## Run in MAME (debugger path) +For a window, use `tools/run_mame_gui.sh` (above). For scripted/headless +checks: + ```sh # one frame, then dump VRAM at MAME frame 2700 VT1200_DUMP_VRAM_FRAMES=2700 VT1200_DUMP_DIR=/tmp/ba-one \ bad-apple/tools/run_mame.sh one -# 5 s slice, paced +# 5 s slice, paced (headless) BA_MOVIE=bad-apple/data5/movie.bin BA_START=0 BA_COUNT=300 \ bad-apple/tools/run_mame.sh play -# full 30 s, paced +# full 30 s, paced (headless) BA_MOVIE=bad-apple/data/movie.bin BA_MOVIE_BASE=0x00080000 \ BA_WAIT=1 BA_PACE=1 bad-apple/tools/run_mame.sh play ``` -`run_mame.sh` exits when the payload sets its status marker. The debugger +`run_mame.sh` runs with `-video none`; it exits at `BA_END`. The debugger loader writes the movie into high RAM (`0x01D00000`) for small slices; for the full 30 s it uses `BA_WAIT=1`, lets the payload take over, then writes low RAM at `0x00080000` — the same ordering as the real delivery path. @@ -76,9 +108,10 @@ disables interrupts and plays. bad-apple/tools/load.sh --host --movie bad-apple/data/movie.bin ``` -This path is implemented but **not yet verified on the unit or over MAME's -tap** in this worktree: the tap was down. The OS socket API it uses is the one -already proven by `harness/udpstream/udpstream.c`. See `REPORT.md`. +**This path is currently blocked** at `malloc_(2401942)`: the OS heap does not +give one contiguous 2.4 MB block, so the payload never binds UDP. The debugger +path above is the working demo. A fixed low-RAM staging receive or raw-LANCE +loader is the next step. See `REPORT.md`. ## Data format diff --git a/bad-apple/REPORT.md b/bad-apple/REPORT.md index 7151873..5fa08d5 100644 --- a/bad-apple/REPORT.md +++ b/bad-apple/REPORT.md @@ -83,9 +83,11 @@ refuses to jump unless the whole-file checksum matches. Out-of-range packets are dropped without reading or writing outside the buffer. Status: the packet format, header offset, checksum path and sender are -unit-tested; the MAME tap was down in this worktree, so the UDP receive was -not exercised end-to-end. The same OS socket API is already proven on the unit -by `harness/udpstream/udpstream.c`. This is the one delivery-path gap. +unit-tested. The live MAME tap test reaches the payload but stops before UDP +bind: the marker shows `status=0x20` and no socket is open. The suspect is +`malloc_(2401942)` — the OS heap does not provide one contiguous block that +size. The debugger path is the working demo. A fixed low-RAM staging receive +or raw-LANCE loader is the next step. This is the one delivery-path gap. ## Regression diff --git a/bad-apple/tools/run_mame_gui.sh b/bad-apple/tools/run_mame_gui.sh new file mode 100755 index 0000000..67c6de3 --- /dev/null +++ b/bad-apple/tools/run_mame_gui.sh @@ -0,0 +1,39 @@ +#!/bin/sh +# Run the current debugger-path demo in a MAME window. +# +# bad-apple/tools/run_mame_gui.sh +# M=/path/to/vt1200 BA_MOVIE=/path/to/movie.bin bad-apple/tools/run_mame_gui.sh +# +# The payload is loaded at frame BA_AT, takes over, and plays the full movie. +# Close the window or let it exit at BA_END. Recovery after takeover is a +# power cycle (in MAME: Shift+F3 or close the window). +set -eu + +HERE=$(cd "$(dirname "$0")" && pwd) +ROOT=$(cd "$HERE/../.." && pwd) +M=${M:-/home/arti/code/k-space/mame0289/vt1200} +BA_MOVIE=${BA_MOVIE:-$ROOT/bad-apple/data/movie.bin} +BA_AT=${BA_AT:-2500} +BA_END=${BA_END:-8000} + +if [ ! -x "$M" ]; then + echo "run_mame_gui.sh: no MAME binary at $M" >&2 + exit 1 +fi +if [ ! -f "$BA_MOVIE" ]; then + echo "run_mame_gui.sh: no movie at $BA_MOVIE" >&2 + echo " build it with: cd bad-apple && python3 -m pipeline.build ..." >&2 + exit 1 +fi +if [ ! -f "$ROOT/bad-apple/player/build/player.bin" ]; then + echo "run_mame_gui.sh: no payload; run bad-apple/player/build.sh" >&2 + exit 1 +fi + +cd "$ROOT" +VT1200_SKIP_LEVEL1=1 \ +BA_MOVIE="$BA_MOVIE" BA_MOVIE_BASE=0x00080000 BA_WAIT=1 BA_PACE=1 \ +BA_AT="$BA_AT" BA_END="$BA_END" \ +"$M" vt1200 -rompath harness/mame/roms -sound none -skip_gameinfo -window \ + -debug -debugger none \ + -autoboot_script "$ROOT/bad-apple/tools/load_mame.lua" -autoboot_delay 0