Process-Level Game Emulation

Scope

The process lane runs only the extracted AArch64 game/display target, game assets, extracted loader/library runtime, generated Mesa overlay, and clean-room machine model. It does not boot Buildroot and does not modify extracted evidence.

Implementation entry points:

spike3-emu
emulation/process/spike3_emu.py
emulation/process/config.default.json
emulation/process/Dockerfile

Generated state is confined to emulation/work/capsule/, emulation/work/runs/, and emulation/work/packs/; all three are excluded from Git.

Confirmed Static Runtime Contract

The launcher's dependency resolver was run against:

/games/pokemon_pro/game
/games/pokemon_pro/spike3/spike_menu/game
/games/pokemon_pro/spike3/bin/boot_display

It resolves 51 unique DT_NEEDED libraries with no unresolved SONAMEs. The highest required and provided version nodes both match: GLIBC_2.39 and GLIBCXX_3.4.32. This confirms that the extracted loader, glibc, and libstdc++ must remain the process runtime; substituting Debian bookworm's older libstdc++ would be incompatible.

The initial asset capsule retains the full read-only /games/pokemon_pro directory. trace inventories actual file opens, and pack --profile traced creates a generated minimal tree whose copied files are verified against the read-only source with SHA-256.

Runtime Architecture

Layer	Implementation
Host selection	Apple Silicon uses an ARM64 Linux container; AArch64 Linux uses native execution; x86-64 Linux uses qemu-user.
Isolation	Bubblewrap mounts game and target libraries read-only, creates an offline target network namespace, and binds only generated writable state.
Machine I/O	`libspike3machine_client.so` connects `/dev/spidev4.0`, `/dev/i2c-10`, GPIO, and netbridge calls to `emulation/work/machine.sock`.
Display	`libspike3emu_stub.so` writes XRGB frames to a generated regular `/dev/fb0`; ffplay loops the frame into Xvfb, then x11vnc/noVNC serves port 6081.
Controls	Dashboard port 8090 uses the private Unix RPC socket; loopback-only TCP port 8091 serves VPX and other external controllers.
Audio	ALSA is converted to fixed 48 kHz stereo S16LE file output and finalized as `audio.wav` per run.
Debugging	Native uses extracted `gdbserver`; qemu-user uses `-g`; generated helpers resolve the PIE slide and named Ghidra offsets.
System fallback	`--engine system` delegates to the existing `qemu-system-aarch64`/virtio-gpu/noVNC workbench.

Generated safe command replacements log and block reboot, halt, poweroff, shutdown, and hostname changes. OpenOCD is replaced by a controlled stub whose exit status defaults to success. The machine service implements no physical outputs; the launcher's hardware backend is deliberately refused.

Usage

./spike3-emu prepare
./spike3-emu run boot-display
./spike3-emu run spike-menu
./spike3-emu run game
./spike3-emu debug game
./spike3-emu trace game
./spike3-emu pack --profile traced
./spike3-emu clean --legacy-system
./spike3-emu clean --legacy-system --yes

Run artifacts include effective configuration, stdout, syscall trace, broker transactions, display-service logs, asset hashes, blocked commands, PCM/WAV capture, GDB setup, and exit status.

Verified Runtime Results (2026-07-11)

./spike3-emu prepare completed on Apple Silicon with 51 resolved libraries. A repeat preparation completed from the dependency/config fingerprint cache in 0.56 seconds. Docker inspection reported the image as linux/arm64, 340,201,729 content bytes (1.36 GB virtual size). No QEMU process is used in process mode.

The ARM64 Mesa smoke command completed with framebuffer status 0x8cd5, pixel 64,128,191,255, EGL 1.4, and no GL error. Live boot-display, spike-menu, and game runs loaded the HLE preload and executed the target. The menu/game accepted netbridge CRC 0x357f5327. Dashboard port 8090 returned broker state, and a direct JSONL request to 127.0.0.1:8091 returned a revisioned state.delta. Manual Start/launch/drain events changed the virtual lifecycle.

A one-shot docker stats --no-stream sample shortly after game startup was 129.78% CPU, 200.9 MiB resident usage, and 63 container processes. The native game reached its netbridge CRC check in about 5.1 seconds in that run. This is a startup sample, not a five-minute steady-state benchmark. docker top showed the extracted ld-linux-aarch64.so.1 launching /games/game under bubblewrap and no qemu-system-* or qemu-aarch64 process. The legacy cleaner dry-run reported 6,505,625,192 removable bytes (6 GiB rootfs plus a 63,173,402-byte macOS runtime cache); those files were deliberately not removed automatically. Changing-game FPS is not measurable until the connector failure is resolved.

The remaining display limit is confirmed: software EGL and the synthetic DRM resource inventory initialize, but the proprietary window helper reports failed to get DRM connector for display_number 1; GBM buffers are therefore not allocated. Current nonzero framebuffer captures are HLE diagnostic frames, not genuine changing game frames. Short runs produced no WAV data. Five-minute attract mode, a target-observed full three-ball game, live GDB attachment, and VPX round-trip remain open.

Unit verification is 14 launcher tests, 25 machine-model tests, and 3 dashboard tests. Two machine socket-bind tests skip only because the managed test sandbox denies AF_UNIX/AF_INET binds; the live Docker TCP and Unix paths were exercised.

VPX Bridge

emulation/vpx-plugin/ is pinned to VPX commit 215129065954d265100e4fa7ff063154c6fedf5d. Its build produced a Mach-O ARM64 ControllerPlugin dylib with Spike3ControllerPluginLoad and Spike3ControllerPluginUnload exports. It forwards standard cabinet actions, publishes SPIKE binary inputs/controlled devices, reconnects safely, and exposes the Spike3.Controller script API. example-spike3.vbs covers target, lane, trough, and drain events. VPX is not installed in /Applications on this host, so actual VPX loading and bidirectional table verification are not claimed.

6.0 KiB Raw Blame History