romdevtools 0.27.0 → 0.28.0

package/src/host/LibretroHost.js

@@ -776,6 +776,18 @@ export class LibretroHost {
     return mod._retro_get_memory_size(id) || 0;
   }
 
+  /** gpgx stores 68k work RAM as 16-bit words in host-LE order — the CPU's
+   *  byte at $FF0000+A physically lives at work_ram[A^1] (core/macros.h
+   *  READ_BYTE/WRITE_BYTE on little-endian builds). Normalize the system_ram
+   *  region to CPU byte order here so offset X IS the byte the 68k sees at
+   *  $FF0000+X — otherwise every byte-granular tool (search, diff, write,
+   *  classify) is off-by-XOR-1 vs disassembly addresses and cheat-DB maps
+   *  (self-consistent within raw-only loops, which is why it hid; poisonous
+   *  the moment an address crosses to/from the CPU view). */
+  _byteSwapRegion(region) {
+    return region === "system_ram" && this.status.platform === "genesis";
+  }
+
   readMemory(region, offset, length) {
     const mod = this._needMod();
     const id = MemoryRegionToRetro[region];
@@ -786,6 +798,12 @@ export class LibretroHost {
     if (offset < 0 || offset + length > size) {
       throw new RangeError(`read out of bounds: offset=${offset} len=${length} size=${size}`);
     }
+    if (this._byteSwapRegion(region)) {
+      const heap = mod.HEAPU8;
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = heap[ptr + ((offset + i) ^ 1)];
+      return out;
+    }
     return new Uint8Array(mod.HEAPU8.buffer, ptr + offset, length).slice();
   }
 
@@ -804,6 +822,11 @@ export class LibretroHost {
     if (offset < 0 || offset + bytes.length > size) {
       throw new RangeError(`write out of bounds: offset=${offset} len=${bytes.length} size=${size}`);
     }
+    if (this._byteSwapRegion(region)) {
+      const heap = mod.HEAPU8;
+      for (let i = 0; i < bytes.length; i++) heap[ptr + ((offset + i) ^ 1)] = bytes[i];
+      return;
+    }
     mod.HEAPU8.set(bytes, ptr + offset);
   }
 
@@ -1263,6 +1286,161 @@ export class LibretroHost {
     return !!(this.mod && typeof this.mod._romdev_watchdog_set === "function");
   }
 
+  /** True when this core build exposes the at-hit register snapshot (gpgx). */
+  regSnapSupported() {
+    return !!(this.mod && typeof this.mod._romdev_regsnap_get === "function");
+  }
+
+  /**
+   * Read the at-hit register snapshot: the FULL register file frozen by the
+   * core hook at the instant a pc-break / watchdog / write-watch / read-watch
+   * fired. The live register file keeps running after a hit (per-scanline CPU
+   * scheduling / next-frame re-entry), so post-hit register reads drift —
+   * this snapshot is the truth. Shipped by ALL patched cores (all 14
+   * platforms). Returns { kind, named } or null when no hit has been
+   * snapshotted (or the core build predates the export). kind:
+   * 1=pc-break/step, 2=watchdog, 3=write-watch, 4=read-watch. `named` keys
+   * follow each CPU's own register file; `pc` is always the EXECUTING
+   * instruction (ARM: its pipeline PC, the same convention breakpoint
+   * addresses use). Pass clear to reset the kind.
+   */
+  getRegSnapshot(clear = false) {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_regsnap_get !== "function") return null;
+    const ptr = mod._malloc(21 * 4);
+    try {
+      mod._romdev_regsnap_get(ptr, clear ? 1 : 0);
+      const u = new Uint32Array(mod.HEAPU8.buffer, ptr, 21);
+      const kind = u[0];
+      if (!kind) return null;
+      const r = Array.from(u.subarray(2, 2 + Math.min(u[1] >>> 0, 19)));
+      const platform = this.status.platform;
+      const h2 = (v) => "$" + (v & 0xFF).toString(16).toUpperCase();
+      const h4 = (v) => "$" + (v & 0xFFFF).toString(16).toUpperCase();
+      const hx = (v) => "$" + (v >>> 0).toString(16).toUpperCase();
+      let named;
+      if (platform === "genesis") {
+        // m68k regId order: D0-7, A0-7, PC(instr start), SR, SP.
+        named = {};
+        for (let i = 0; i < 8; i++) named["d" + i] = hx(r[i]);
+        for (let i = 0; i < 8; i++) named["a" + i] = hx(r[8 + i]);
+        named.pc = hx(r[16]);
+        named.sr = h4(r[17]);
+        named.sp = hx(r[18]);
+      } else if (platform === "gba") {
+        // ARM regId order: r0-r15 raw, CPSR at 16, instr pipeline PC at 17, SP at 18.
+        named = {};
+        for (let i = 0; i < 16; i++) named["r" + i] = hx(r[i]);
+        named.cpsr = hx(r[16]);
+        named.pc = hx(r[17]);   // EXECUTING instruction's pipeline PC (pc-break convention)
+        named.sp = hx(r[18]);
+      } else if (platform === "snes") {
+        // 65816 regId order: A, X, Y, P, S, DB, D, …, PBPC(instr start).
+        named = {
+          a: h4(r[0]), x: h4(r[1]), y: h4(r[2]), p: h4(r[3]), s: h4(r[4]),
+          db: h2(r[5]), d: h4(r[6]), pc: hx(r[16]),
+        };
+      } else if (platform === "gb" || platform === "gbc") {
+        named = {
+          a: h2(r[0]), f: h2(r[1]), b: h2(r[2]), c: h2(r[3]),
+          d: h2(r[4]), e: h2(r[5]), h: h2(r[6]), l: h2(r[7]),
+          pc: h4(r[16]), sp: h4(r[18]),
+        };
+      } else if (platform === "sms" || platform === "gg" || platform === "msx") {
+        named = {
+          a: h2(r[0]), f: h2(r[1]), b: h2(r[2]), c: h2(r[3]),
+          d: h2(r[4]), e: h2(r[5]), h: h2(r[6]), l: h2(r[7]),
+          ix: h4(r[8]), iy: h4(r[9]), pc: h4(r[16]), sp: h4(r[18]),
+        };
+      } else {
+        // 6502 family (nes, atari2600, atari7800, c64, lynx, pce/huc6280):
+        // regId order A, X, Y, P, S, …, PC(instr start).
+        named = {
+          a: h2(r[0]), x: h2(r[1]), y: h2(r[2]), p: h2(r[3]), s: h2(r[4]),
+          pc: h4(r[16]),
+        };
+      }
+      return { kind, named };
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /** True when this core build exposes the pure-CPU run (gpgx). */
+  runPureSupported() {
+    return !!(this.mod && typeof this.mod._romdev_run_pure === "function");
+  }
+
+  /** True when this core build exposes the interrupt block (the pure-call
+   *  primitive on cores without a separable CPU loop). */
+  irqBlockSupported() {
+    return !!(this.mod && typeof this.mod._romdev_irqblock_set === "function");
+  }
+
+  /** Suppress (or restore) interrupt DELIVERY to the active CPU. While
+   *  blocked, pending IRQ/NMI lines stay pending and no game handler can run
+   *  — the mechanism behind pure calls on cores whose CPU/video loops are
+   *  interleaved (everything except gpgx, which steps the CPU alone). */
+  setIrqBlock(on) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_irqblock_set !== "function") {
+      throw new Error("this core build does not expose the interrupt block (rebuild with romdev_irqblock_set).");
+    }
+    mod._romdev_irqblock_set(on ? 1 : 0);
+  }
+
+  /** True when a pure call is possible on this platform by ANY mechanism:
+   *  a separable CPU run (gpgx), an interrupt block, or hardware with no
+   *  interrupts at all (the 2600's 6507 has no IRQ/NMI lines wired — every
+   *  call is inherently pure). */
+  pureCallSupported() {
+    return this.runPureSupported() || this.irqBlockSupported() || this.status.platform === "atari2600";
+  }
+
+  /** True when this core build exposes the VRAM-port copy trace (port-based
+   *  video memory: NES/SNES/PCE/MSX/SMS/GG/Genesis). Direct-mapped platforms
+   *  answer the same question through watchRange on the CPU-visible VRAM. */
+  vramWatchSupported() {
+    const mod = this.mod;
+    return !!(mod && typeof mod._romdev_vramwatch_set === "function" && typeof mod._romdev_vramwatch_get === "function");
+  }
+
+  /**
+   * Run `frames` frames logging every data-port write landing in the VRAM
+   * address window [lo,hi] — {vramAddr, pc, value} per event, pc being the
+   * EXECUTING instruction (during DMA on SNES, the instruction that triggered
+   * it). The "where does this graphic come from?" primitive for port-based
+   * video memory. Returns { events, total, stored, truncated }.
+   */
+  watchVram(lo, hi, frames, perFrame) {
+    const mod = this._needMod();
+    this._needMedia();
+    if (!this.vramWatchSupported()) throw new Error("VRAM copy trace not supported by this core.");
+    mod._romdev_vramwatch_set(lo >>> 0, hi >>> 0, 1);
+    try {
+      this._runFramesExclusive(perFrame ?? (() => false), frames);
+    } finally {
+      // drained below; disarm after
+    }
+    const CAP = 1024;
+    const outPtr = mod._malloc(CAP * 3 * 4);
+    const out2Ptr = mod._malloc(8);
+    try {
+      const n = mod._romdev_vramwatch_get(outPtr, CAP, out2Ptr);
+      const u = new Uint32Array(mod.HEAPU8.buffer, outPtr, n * 3);
+      const u2 = new Uint32Array(mod.HEAPU8.buffer, out2Ptr, 2);
+      const events = [];
+      for (let i = 0; i < n; i++) {
+        events.push({ vramAddr: u[i * 3], pc: u[i * 3 + 1], value: u[i * 3 + 2] & 0xFF });
+      }
+      return { events, total: u2[0], stored: u2[1], truncated: u2[0] > u2[1] };
+    } finally {
+      mod._free(outPtr);
+      mod._free(out2Ptr);
+      mod._romdev_vramwatch_set(0, 0, 0);
+    }
+  }
+
   /** Arm/disarm the read watchpoint on a CPU address. */
   setReadWatch(address, enabled = true) {
     const mod = this._needMod();
@@ -1488,6 +1666,13 @@ export class LibretroHost {
     const {
       pc, regs = {}, spReg = prof.spReg, pcReg = prof.pcReg, sentinelPC = prof.defaultSentinel,
       sentinelBytes = prof.retBytes, maxFrames = 600, sandbox = true, capture,
+      // pure: step ONLY the active CPU (no frame machinery — VDP lines, co-CPU,
+      // interrupt raising). Without it, each "frame" of the call runs the
+      // game's OWN per-frame logic concurrently (VBlank handlers via RAM
+      // vectors etc.), which can stomp the buffer the driven routine is
+      // writing — a real session diffed a CORRECT codec reimplementation
+      // against that poisoned output for hours. gpgx (Genesis/SMS/GG) only.
+      pure = false,
       // presetMemory: [{addr, bytes}] CPU-space writes applied before the call
       // (codecs that read a global from RAM — a dest stride, a mode flag, etc).
       presetMemory = [],
@@ -1523,6 +1708,7 @@ export class LibretroHost {
 
     const snapshot = sandbox ? this.serializeState() : null;
     let captured, returned = false, framesRun = 0, watchdogTripped = false, stoppedAtPC = false;
+    let pureMode = null;
     try {
       // Apply pre-call memory writes (CPU-space).
       for (const m of presetMemory) {
@@ -1575,19 +1761,67 @@ export class LibretroHost {
       const target = (stopAtPC !== undefined ? stopAtPC : sentinelPC) >>> 0;
       this.setPCBreak(target, true, false);
       let finalState = null;
+      let irqBlocked = false;
       try {
-        framesRun = this._runFramesExclusive(() => {
-          const st = this.getPCBreak(false);
-          if (st.hit) {
-            finalState = st;
-            if (st.watchdog) watchdogTripped = true;
-            else if (stopAtPC !== undefined) stoppedAtPC = true;
-            else returned = true;
-            return true;
+        if (pure && this.runPureSupported()) {
+          // STRONGEST pure mode (gpgx): step ONLY the CPU — no frame machinery
+          // at all. Mask m68k interrupts so a PENDING VINT raised before the
+          // call can't redirect entry (no NEW interrupts are raised — the
+          // system loop never runs). The sandbox restore (or the game's own
+          // RTE discipline) makes the IPL change invisible afterward.
+          pureMode = "cpu-only";
+          if (this.status.platform === "genesis") {
+            this.setReg(17, (this.getReg(17) | 0x0700) & 0xFFFF);
           }
-          return false;
-        }, maxFrames);
+          // Drive the CPU in cycle chunks, checking the sentinel/watchdog
+          // between chunks. The watchdog bounds total instructions; the chunk
+          // cap is only a backstop against a watchdog-less older core.
+          const CHUNK_CYCLES = 1_000_000;
+          const maxChunks = 512;
+          for (let i = 0; i < maxChunks; i++) {
+            this.mod._romdev_run_pure(CHUNK_CYCLES);
+            const st = this.getPCBreak(false);
+            if (st.hit) {
+              finalState = st;
+              if (st.watchdog) watchdogTripped = true;
+              else if (stopAtPC !== undefined) stoppedAtPC = true;
+              else returned = true;
+              break;
+            }
+          }
+        } else {
+          if (pure) {
+            // INTERRUPT-BLOCKED pure mode (every other core): the frame
+            // machinery still runs (video/timers advance — harmless, they
+            // don't write game RAM), but interrupt DELIVERY is suppressed, so
+            // no game handler can execute. The only running game code is the
+            // routine we called — the same guarantee that matters for the
+            // output buffer. The 2600's 6507 has no interrupt lines at all,
+            // so every call there is pure by hardware.
+            if (this.irqBlockSupported()) {
+              this.setIrqBlock(true);
+              irqBlocked = true;
+              pureMode = "irq-blocked";
+            } else if (this.status.platform === "atari2600") {
+              pureMode = "no-interrupts";
+            } else {
+              throw new Error("cpu({op:'call', pure:true}) not supported by this core build (needs the romdev_irqblock_set export — update the core package).");
+            }
+          }
+          framesRun = this._runFramesExclusive(() => {
+            const st = this.getPCBreak(false);
+            if (st.hit) {
+              finalState = st;
+              if (st.watchdog) watchdogTripped = true;
+              else if (stopAtPC !== undefined) stoppedAtPC = true;
+              else returned = true;
+              return true;
+            }
+            return false;
+          }, maxFrames);
+        }
       } finally {
+        if (irqBlocked) { try { this.setIrqBlock(false); } catch { /* core gone */ } }
         this.setPCBreak(0, false, false);
         this.setWatchdog(0);
         if (!finalState) finalState = this.getPCBreak(true); else this.getPCBreak(true);
@@ -1607,6 +1841,7 @@ export class LibretroHost {
     const fin = this._lastCallResult || {};
     return {
       returned, framesRun,
+      ...(pure ? { pure: true, pureMode } : {}),
       ...(watchdogTripped ? { watchdog: true, reason: "watchdog: hit the instruction budget (likely a runaway loop — wrong A0/regs, a needed preset, or legitimately huge; raise maxInstructions or check the entry setup)" } : {}),
       ...(stoppedAtPC ? { stoppedAtPC: "$" + (stopAtPC >>> 0).toString(16).toUpperCase() } : {}),
       ...(fin.finalPC != null ? { finalPC: "$" + fin.finalPC.toString(16).toUpperCase(), finalPCRaw: fin.finalPC } : {}),

package/src/mcp/server.js

@@ -418,6 +418,12 @@ async function main() {
     log.info(`optional observer:      http://${bannerHost}:${port}/livestream`);
     log.info("");
     log.info("connect your coding agent: https://github.com/monteslu/romdev#connect");
+    // One conditional line so an agent knows the constraint BEFORE promising a
+    // playtest window to a human (the op itself still errors with the full fix).
+    if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+      log.info("");
+      log.info("note: no display detected (headless) — playtest({op:'open'}) is unavailable; all other tools work.");
+    }
   });
   const extraServers = [];
   for (const h of bindHosts.slice(1)) {