fix(gpu): sync the GPU to the 68000 on writes into GPU local RAM (Pitfall crash, #138)

[JoeMatt]

Closes the third and final defect behind #138. Pitfall: The Mayan Adventure went permanently black ~16 s into level 1 and stayed frozen; with the two earlier fixes (#212) in place, the remaining failure was gpu_pc_escape frame=5615.

Not a GPU interrupt bug — a scheduling-order bug

The task premise (a leaking GPU ISR stack pointer) turned out to be three layers downstream. Measurements that killed the obvious hypotheses:

• Dispatch rate: disp == irq0 at every sample, so nothing re-dispatches — the latch is being cleared correctly.
• Nesting: the ISR clears IMASK at $F03022 (unmask + clear the int0 latch), which per docs/jtrm-gpu-dsp.md is exactly what silicon permits — so the nesting we perform is legitimate.
• Push/pop stayed balanced for 5407 frames (320 executions each of the ISR entry and its epilogue). The 1-per-frame dispatch rate after that is the consequence, not the cause.

What actually happens: from frame 5408 the epilogue count drops to zero while the ISR body's palette-fade loop runs 73,422 times in five frames. Its iteration count comes from LOADW ($00044036), and that word had been overwritten with $FE7C (65,148) — so one invocation can no longer finish inside a frame. Every subsequent int0 nests, pushes 4 more bytes, never returns, and r31 walks 4 KB down GPU local RAM until it overwrites the GPU's own code at $F03CBC.

The corruption is the GPU's own object-list builder, driven through a mailbox the 68000 writes. Traced ordering on frame 5407:

68kpc $031FF4  p5 $F03E14 = $00043C68
68kpc $031FFE  mailbox    = $00F03080      (kick)
68kpc $004A02  p3 $F03E0C = $0000031F      (interrupt clobbers the count)
GPU            enters $F03080 with p3 = $0000031F

Store-pass table: pass 0 writes 213 stores over $43C68-$43FB8 (correct); pass 1 writes 800, flooding $043FBC-$0448E8 — which is where the fade parameter block lives, and where the odd pointer behind the address error fixed in #212 also lived.

Why the old ordering is wrong per hardware

docs/jtrm-clocks-timing.md: the GPU runs at the full system clock (26.590906 MHz) and the 68000 at half — exactly 2:1 — and the bus-priority table puts the CPU last of 11, below GPU normal. A GPU spinning on its own local RAM cannot lag the CPU by ~200 cycles. JaguarExecuteNew() ran m68k_execute(whole slice) and only then GPUExec(whole slice), so it did.

The fix

GPUSyncToM68K() advances the GPU to the 68000's position inside the current slice (m68k_cycles_run() * 2, clamped to the slice budget) on a 68000 write into GPU local RAM. GPUBeginSlice()/GPUSliceRemaining() make the end-of-slice call run only the remainder, so total RISC cycles per slice are unchanged — only when they are spent moves. m68k_cycles_run() was a stub returning 0 with no callers; it is now real.

Two failed attempts worth recording: an unclamped GPUExec(64) per write let the GPU run ~30x its budget and broke boot at frame 75 (the clamp is the fix, not an optimisation); and hooking GPUWriteWord fired between the two word writes a MOVE.L decomposes into, so the guest's poll loop read a partial pointer and jumped into the TOM register file. The hook therefore sits at the 68000 access boundary with in-long-write suppression.

Gates

1. Pitfall: 10,800 frames (3x the old crash window), both blitter modes — clean. Alive at the end, not merely un-crashed: 89.5% non-black, 25.97% frame-to-frame motion, RMS 808, and the frame-10800 screenshot shows real gameplay (score 000580, 27 items, 3 lives, Harry on a jungle ledge). Control: stock gives gpu_pc_escape frame=5615 on the same command.
2. 40-title A/B: 33/40 bit-identical, and the trigger table explains the rest — 19 titles run the sync yet only 7 diverge (the title with the most sync runs, 10,332, is bit-identical). Four of the seven are video bit-identical with audio counts moving ≤0.0075%. The three with real video changes were behaviour-validated instead: Power Drive Rally and jagniccc are pixel-identical at frame 2400; Doom differs only in attract-demo phase (same scene, same HUD — AMMO 28 / HEALTH 100% / AREA 6 — a few frames further along). Many titles have thousands of calls and zero runs because their GPU is halted while the 68000 writes (Theme Park 202831/0, Tempest 2000 66511/0, Super Burnout 1183/0).
3. CD titles — gap closed since the original run. cd_wedge_probe at 3000 frames: BrainDead 13 clean in both boot modes — this was the specific open question, since BD13 is the title whose lost-wakeup bug motivated the event-scheduled CPUINT delivery this touches. Battle Morph, Iron Soldier 2, Myst and Primal Rage signature sets byte-identical to stock. Hover Strike HLE wedges at frame 2025 — identically on stock develop, byte-for-byte the same signature, so pre-existing and untouched.
4. make TEST_EXPORTS=1 test exit 0; audio triple at documented baselines (Skyhammer 3079.8, IS2 2599.3, IS1 presence 1175.7); c89-lint clean on all three touched files; benchmark within noise.

Reviewer note: after m68k_end_timeslice(), m68k_cycles_run() returns the unspent count, so the clamp hands the GPU its whole remaining slice — harmless, since the 68000 has already stopped for that slice. The DSP still runs end-of-slice unchanged (deliberately out of scope).

🤖 Generated with Claude Code

[github-actions]

Regression: linux-x64

Regression Test Results

ROM	Status	Details	Diff
jagniccc	🆕 NEW	no baseline	-
yarc	🆕 NEW	no baseline	-
jagniccc (determinism)	✅ PASS	identical across runs	-
yarc (determinism)	✅ PASS	identical across runs	-
jagniccc (frameskip)	✅ PASS	skip=0 matches skip=3	-
yarc (frameskip)	✅ PASS	skip=0 matches skip=3	-
jagniccc (save state)	✅ PASS	round-trip matches	-
yarc (save state)	✅ PASS	round-trip matches	-
jagniccc (rewind)	✅ PASS	rewind matches	-
yarc (rewind)	✅ PASS	rewind matches	-

Platform: Linux x86_64

_{Updated by CI at 2026-07-31T20:25:55.784Z}

[github-actions]

Regression: macos-arm64

Regression Test Results

ROM	Status	Details	Diff
jagniccc	🆕 NEW	no baseline	-
yarc	🆕 NEW	no baseline	-
jagniccc (determinism)	✅ PASS	identical across runs	-
yarc (determinism)	✅ PASS	identical across runs	-
jagniccc (frameskip)	✅ PASS	skip=0 matches skip=3	-
yarc (frameskip)	✅ PASS	skip=0 matches skip=3	-
jagniccc (save state)	✅ PASS	round-trip matches	-
yarc (save state)	✅ PASS	round-trip matches	-
jagniccc (rewind)	✅ PASS	rewind matches	-
yarc (rewind)	✅ PASS	rewind matches	-

Platform: Darwin arm64

_{Updated by CI at 2026-07-31T20:25:41.246Z}

[github-actions]

Regression: linux-arm64

Regression Test Results

ROM	Status	Details	Diff
jagniccc	🆕 NEW	no baseline	-
yarc	🆕 NEW	no baseline	-
jagniccc (determinism)	✅ PASS	identical across runs	-
yarc (determinism)	✅ PASS	identical across runs	-
jagniccc (frameskip)	✅ PASS	skip=0 matches skip=3	-
yarc (frameskip)	✅ PASS	skip=0 matches skip=3	-
jagniccc (save state)	✅ PASS	round-trip matches	-
yarc (save state)	✅ PASS	round-trip matches	-
jagniccc (rewind)	✅ PASS	rewind matches	-
yarc (rewind)	✅ PASS	rewind matches	-

Platform: Linux aarch64

_{Updated by CI at 2026-07-31T20:25:55.848Z}

[Copilot]

Pull request overview

This PR addresses Pitfall: The Mayan Adventure’s GPU PC-escape/black-screen crash (#138) by improving CPU↔GPU concurrency modeling: the GPU is advanced mid-slice when the 68000 writes into GPU local RAM, closing an ordering gap created by coarse slice scheduling in JaguarExecuteNew().

Changes:

• Added GPU slice bookkeeping (GPUBeginSlice, GPUSliceRemaining) and a mid-slice catch-up hook (GPUSyncToM68K) driven by 68K cycle progress.
• Hooked the 68000 memory-write boundary to sync the GPU on writes into GPU local RAM, with suppression across the two halves of a MOVE.L longword write.
• Implemented m68k_cycles_run() and adjusted the main scheduler to only run the GPU for the remaining slice budget after any mid-slice sync.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/tom/gpu.h	Exposes new GPU slice/sync APIs used by the scheduler and 68K write boundary.
src/tom/gpu.c	Implements slice budget tracking and GPUSyncToM68K() mid-slice GPU advancement.
src/m68000/m68kinterface.c	Implements m68k_cycles_run() to report cycle progress for GPU catch-up.
src/core/jaguar.c	Hooks 68K writes into GPU local RAM and adjusts JaguarExecuteNew() to run only remaining GPU slice cycles.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.