Star Wars Episode I: The Phantom Menace on the Tab5 (statically recompiled)

[finger563]

Summary

Runs Star Wars Episode I: The Phantom Menace (PSX, USA Rev 1, SLUS-00884) natively on the Tab5 (ESP32-P4) as a cart, from the disc image on the microSD card. No decompilation existed, so the game is statically recompiled: esp-cpp/tpm-decomp (new, MIT) translates the executable's MIPS code to C at build time (tools/recomp.py) and runs it on its own runtime (BIOS, interrupts, DMA, CD-ROM, GPU ports, GTE, MDEC), with psyz's software rasterizer and SPU. Nothing derived from the game is committed; the build reads your own SLUS_008.84 (and, for the movies, your disc image).

What works: the whole boot chain with its movies (LucasArts and Big Ape logos, the opening crawl), the title, menus and the levels, with music, speech and sound effects; pause, reset and quit from the emulator menu; save and load states; USB and built-in gamepads.

Gameplay runs at about 27 game fps in the first level (the game's cap is 30) with frameskip 2; movies play at their full 15 fps with their audio; a level loads in about 4 s.

tab5-tpm-save-states-compressed-2.mp4

Recompiled, not (yet) decompiled

Unlike the JK and MGS carts, TPM does not run from decompiled source:

• tools/recomp.py translates each MIPS instruction of the executable into C mechanically. That output is the game's code in another form (Sony's copyrighted executable), so it is never committed or distributed. It is generated in the build directory from the builder's own SLUS_008.84 (CONFIG_TPM_EXE_PATH) and disc image (CONFIG_TPM_DISC_PATH, for the movie overlay).
• So a playable TPM firmware can't be shared: each user builds their own. CI builds without the executable, so the CI firmware's TPM cart is only the load-screen viewer.
• tpm-decomp holds only original work: the recompiler, the runtime, HLE replacements, and config naming addresses.

The goal is a real, matching decompilation, as mgs_reversing is for MGS: hand-written C that rebuilds the byte-identical executable with PSY-Q's GCC 2.8.1. tpm-decomp has started it: the executable is split with splat and rebuilds byte-identical, the PSY-Q functions are identified, and main and the file layer are in C. Decompiled functions can replace recompiled ones one at a time, so the port keeps working while the decompilation grows. Once it is complete, TPM can build from source like the MGS cart. Contributions welcome. The READMEs (top level, components/tpm, tpm-decomp) now say all of this.

Port layer (this repo)

• components/tpm: the cart (launch, pause at the game's next loop back-edge, reset, quit without reboot), LCD present, audio task, disc reads with a 64 KB DMA-able read-ahead, a load-screen viewer when no executable was given.
• The recompiled game and runtime build as one relocatable object (tpm_rt.ld, tpm_rt.keep): only the runtime's API stays global (MGS links its own psyz under the same names), its statics go to PSRAM and are reset on relaunch. Built -O2 -fsched-pressure -fomit-frame-pointer -ffixed-s11: s11 holds guest RAM's address for the generated code.
• Everything the runtime allocates is one PSRAM arena (with the game task's stack in it), kept across quits and released for other carts, so its addresses stay put for save states.
• The GPU's command stream goes to a worker on core 1 through a lock-free queue (a DMA packet per entry); frameskip drops a frame's primitives and clears into display buffers when the game is two vblanks ahead.
• Save states: .data, .bss, the arena (minus the drained GPU queue and an idle transfer buffer) and the live part of the game stack: 3.6 MB, about 1.5 s to save and 0.6 s to load. A state loads into the firmware build that wrote it.
• Kconfig: the executable and disc paths, movies, frameskip, GPU workers, and bring-up aids (scripted presses, profiler, benchmarks, serial screenshots, a save-state replay test).
• Small shared changes: CI checks out the tpm-decomp submodule; CONFIG_TAB5_EMU_AUTOSTART_MATCH picks the auto-started game by name; rom_info knows the cart; the factory partition is 12 MB (the recompiled game is large).

In the submodules

• tpm-decomp: the recompiler (register liveness and clobber analysis, a value flow that proves scratchpad accesses and narrows local returns, GTE FLAG liveness, per-command-word GTE calls), the runtime, the MDEC, and the movies: the game's movie player only keeps up at the hardware's exact pace (its stream ring holds one frame), so its play function is replaced by a native one that reads the STR sectors, runs the game's own VLC decoder and the MDEC's decode (a fast integer IDCT for the standard table) into VRAM, and decodes the XA audio into the SPU's CD input. Start or Cross skips.
• psyz (components/mgs/psyz, now at esp-cpp/psyz tpm): rasterizer speedups (per-triangle row loops, pre-modulated 4bpp palettes, exact small divides, texture windows) and SPU speedups (voices mixed per block, envelope work only when it can change, silent voices not mixed), all verified frame- and sample-identical on TPM's desktop runs.

Measuring

A deterministic desktop runner (make -C recomp, then tpm-host with a scripted press list) gives the same frames and audio on every machine; every optimisation was checked identical over 3000 frames, with the debug build verifying the recompiler's proofs and the GTE checked in lockstep against psyz's. On the board, an unpaced benchmark over a fixed stretch of the first level times the game thread's work (23.8 s at the start of the performance work, 16.2 s now) and a sampling profiler covers both cores.

Known open items

• Both cores are near full in the level (game thread ~95%, GPU worker ~93%); the game's hand-written terrain renderer is the biggest remaining piece of the game thread (~27%).
• Memory-card saves are not implemented (the game says so and carries on; use save states).
• MGS was not re-tested on this branch. The psyz changes are output-identical on TPM, but MGS uses the same rasterizer and SPU; a quick run through the dock before merging would be worth it.

Testing

Played on a Tab5 through the intro movies, the title and the first level; save and load states from the menu (and an automated save-at-2000 / load-at-2400 replay that matches guest RAM for 120 of 120 vblanks); pause, reset and quit. Desktop regressions as above.

🤖 Generated with Claude Code

[finger563]

MGS re-test: the opening's audio was a little choppier with the updated psyz. Bisected on the board: the SPU's new block-a-voice-at-a-time mixer makes MGS's SPU-interrupt clock (voice 23, which the sound driver and its streamed audio run on) irregular, with about a third of the beats re-armed late instead of a tenth. 793d242 puts MGS back on psyz's per-sample mixer. The rasterizer speedups stay, and MGS's boot sequence actually runs faster with them (frame 1320 at vblank 4824 instead of 5426). TPM keeps the block mixer (it doesn't use SPU interrupts).

[github-actions]

ESP-IDF Size Report for 'Tab5 Emu'

Metric	Base	PR	Delta
FLASH	0 bytes (0.00%)	0 bytes (0.00%)	0 bytes (0.00%)
DRAM	266,374 bytes (60.36%)	266,582 bytes (60.41%)	🔺 +208 bytes (+0.05%)
IRAM	0 bytes	0 bytes	0 bytes
RAM (DRAM+IRAM)	266,374 bytes	266,582 bytes	🔺 +208 bytes (+0.05%)

_{FLASH uses app .bin size or json2 flash sum. RAM sums DRAM+IRAM via idf_size. Percentages shown when totals are available.
DRAM/IRAM usage does not include memory used by the heap allocator at runtime.
This report was generated by esp-idf-size-delta.}