romdevtools 0.44.0 → 0.56.1

package/src/analysis/rizin.js

@@ -54,6 +54,19 @@ export const RIZIN_ARCH = {
   // DECOMPILER uses the proper HuC6280 SLEIGH spec — so CFG/xrefs/functions are
   // approximate on PCE while decompile is accurate.
   pce: "6502",
+  // 32-bit MIPS tier (analysis-first; the MIPS plugin ships in rizin.wasm). PS1 =
+  // R3000 little-endian; N64 = R4300 big-endian. Endianness comes from RIZIN_ENDIAN
+  // below — same arch, different byte order.
+  ps1: "mips",
+  n64: "mips",
+};
+
+/** Byte order per platform, for shared-arch families that ship both (MIPS). Only
+ *  platforms NOT matching their arch default need an entry; absent → use the
+ *  loader/arch default. PS1 is little, N64 is big. */
+export const RIZIN_ENDIAN = {
+  ps1: "little",
+  n64: "big",
 };
 
 /**
@@ -77,13 +90,21 @@ export const RIZIN_ARCH = {
  * @returns {Promise<{exitCode:number, output:string, log:string, crash?:object}>}
  */
 export async function runRizin(opts) {
-  const { romPath, romBytes, commands, arch, bits, baddr, writeable, timeoutMs } = opts;
+  const { romPath, romBytes, commands, arch, bits, baddr, writeable, timeoutMs, endian } = opts;
   if (!commands) throw new Error("runRizin: commands required");
   const bytes = romBytes ?? new Uint8Array(await readFile(romPath));
 
   const pre = ["e scr.color=0", "e scr.interactive=false", "e scr.prompt=false"];
   if (arch) pre.push(`e asm.arch=${arch}`);
   if (bits) pre.push(`e asm.bits=${bits}`);
+  // Endianness matters for shared-arch families that ship both byte orders — most
+  // pressingly MIPS: PS1 (R3000) is little-endian, N64 (R4300) is big-endian, same
+  // `mips` plugin. Set both asm + cfg so the disasm AND the analysis loader agree.
+  if (endian === "big" || endian === "little") {
+    // `cfg.bigendian` is the rizin config var (there is NO `asm.bigendian` —
+    // setting it errors). cfg.bigendian drives BOTH the disasm and the analysis.
+    pre.push(`e cfg.bigendian=${endian === "big" ? "true" : "false"}`);
+  }
 
   // Split trailing command off so its output (only) goes to the file. Earlier
   // commands (aaa, config) print nothing we need. Rizin's `cmd > file` writes

package/src/cores/capabilities.js

@@ -202,10 +202,71 @@ export const CAPABILITIES = {
       cart: false, disasm: true, decompile: true,
     },
   },
+
+  // ── 32-bit MIPS tier — ANALYSIS-FIRST (no run-side core yet) ──────────────
+  // disasm/decompile are wired through the shipped rizin.wasm MIPS plugin (PS1 =
+  // R3000 LE, N64 = R4300 BE). Everything run-side (build/run/screenshot/the
+  // tile/sprite inspectors) is FALSE: there is no emulator core in this slice, and
+  // the tile/nametable/OAM inspectors are MEANINGLESS on a framebuffer (PS1) / 3D
+  // (N64) renderer anyway — so an agent gets the uniform unsupported() signal
+  // instead of blindly calling inspectBackground on a polygon machine.
+  // disasm/cfg/xrefs/functions WORK (rizin's Capstone MIPS plugin). decompile is
+  // FALSE: the rz-ghidra decompiler ships only the 8 SLEIGH specs for the current
+  // tier (no MIPS.sla) — adding it is a romdev-analysis-decompiler rebuild, a later
+  // step. decompileQuality records the EXPECTED quality once that spec ships.
+  ps1: {
+    cpuFamily: "mips", decompileQuality: "good", tier: "mips",
+    cpus: { main: "r3000", secondary: ["gte"] },
+    audioChips: ["spu"],
+    memoryRegions: [...GENERIC_REGIONS],
+    renderingKind: "framebuffer", introspection: "shallow",
+    ops: {
+      // pcsx_rearmed: software render + HLE BIOS (no firmware, no GL). run/screenshot
+      // + cpuState (R3000 regsnap) + cheats live; disasm + decompile work (MIPS
+      // Capstone + the MIPS:LE:32 SLEIGH spec). build needs a PS1 toolchain
+      // (PSn00bSDK, not yet). The framebuffer renderer has no tile/sprite inspectors.
+      build: true, run: true, screenshot: true,
+      inspectSprites: false, inspectPalette: false, inspectBackground: false,
+      renderingContext: false, cpuState: true, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
+  n64: {
+    cpuFamily: "mips", decompileQuality: "good", tier: "mips",
+    cpus: { main: "r4300", secondary: ["rsp"] },
+    audioChips: ["ai"], // AI = the audio OUTPUT interface (RSP-mixed; no per-voice chip)
+    memoryRegions: [...GENERIC_REGIONS],
+    renderingKind: "3d", introspection: "shallow",
+    ops: {
+      // parallel_n64: HW (GL) render via the optional native-gles bridge.
+      // run/screenshot + cpuState (R4300 regsnap) + cheats + breakpoint/watch +
+      // audioDebug(AI) live; disasm + decompile work; build via mips-elf-gcc.
+      // The 3D renderer has no tile/sprite inspectors (N/A by hardware).
+      build: true, run: true, screenshot: true,
+      inspectSprites: false, inspectPalette: false, inspectBackground: false,
+      renderingContext: false, cpuState: true, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
 };
 
-/** All platform ids in the contract. */
-export const CONTRACT_PLATFORMS = Object.keys(CAPABILITIES);
+/** The 32-bit MIPS tier (PS1/N64) — marked `tier:"mips"`. A PARTIAL tier: they
+ *  run + screenshot + disasm, but don't yet have the full op surface of the canonical
+ *  14 (no build toolchain, no MIPS decompile/cpuState, framebuffer/3D renderers have
+ *  no tile/sprite inspectors). They're held to their OWN conformance, not the
+ *  "all 14" cross-checks. They graduate to CONTRACT_PLATFORMS as the gaps close. */
+export const MIPS_TIER_PLATFORMS = Object.entries(CAPABILITIES)
+  .filter(([, c]) => c.tier === "mips")
+  .map(([p]) => p);
+
+/** Back-compat: the analysis-only set is now empty (PS1/N64 gained run/screenshot
+ *  in the run-side wiring). Kept so the name still resolves for older imports. */
+export const ANALYSIS_ONLY_PLATFORMS = [];
+
+/** The canonical tier-1 platforms (the 14): full op surface, universal build/run/
+ *  screenshot. Excludes the partial MIPS tier above. */
+export const CONTRACT_PLATFORMS = Object.keys(CAPABILITIES)
+  .filter((p) => !MIPS_TIER_PLATFORMS.includes(p));
 
 /** Does `platform` support `op`? Unknown platform/op → false. */
 export function supports(platform, op) {
@@ -216,3 +277,30 @@ export function supports(platform, op) {
 export function capabilitiesFor(platform) {
   return CAPABILITIES[platform] ?? null;
 }
+
+// Why an op is unsupported, grounded in the HARDWARE — so `unsupported()`'s reason
+// distinguishes "N/A by hardware, permanent" from "a decoder we haven't wired."
+// Keyed on renderingKind: a framebuffer (PS1) / 3D (N64) renderer has no tile,
+// sprite-attribute, nametable, or palette tables for the tile-era inspectors to
+// read — those ops are MEANINGLESS on the hardware, not merely absent.
+const RENDERING_NA = {
+  framebuffer: "this platform renders to a flat framebuffer — there are no tile/sprite-attribute/nametable/palette tables to inspect (the GPU draws pixels/polys directly). Read the raw framebuffer via memory({region:'video_ram'}).",
+  "3d": "this platform is a 3D (polygon) renderer — there are no tile/sprite-attribute/nametable/palette tables to inspect (geometry is transformed + rasterized, not composed from tile maps). Inspect the scene via memory({region:'system_ram'}) / cpu state.",
+};
+const NA_OPS = new Set(["inspectSprites", "inspectPalette", "inspectBackground", "renderingContext"]);
+
+/** A hardware-grounded reason an op is unsupported on a platform, or null if the
+ *  op isn't one of the hardware-N/A introspection ops. Drives unsupported().reason
+ *  so agents see "N/A by hardware" (don't retry / don't request a decoder) rather
+ *  than a generic "no decoder for this platform". */
+export function naReason(platform, op) {
+  const cap = CAPABILITIES[platform];
+  if (!cap || cap.ops?.[op]) return null;            // supported → no N/A reason
+  if (op === "cart") {
+    return cap.renderingKind === "framebuffer"
+      ? "this platform is disc-based (no cartridge ROM to inspect/patch as a cart)."
+      : null;
+  }
+  if (NA_OPS.has(op)) return RENDERING_NA[cap.renderingKind] ?? null;
+  return null;
+}

package/src/cores/registry.js

@@ -53,6 +53,18 @@ export const CORES = {
   c64: { platform: "c64", coreName: "vice_x64", pkg: "romdev-core-vice", displayName: "Commodore 64 (VICE x64)" },
   pce: { platform: "pce", coreName: "geargrafx", pkg: "romdev-core-geargrafx", displayName: "PC Engine / TurboGrafx-16 (Geargrafx)", aka: "turbografx,tg16,pcengine" },
   msx: { platform: "msx", coreName: "bluemsx", pkg: "romdev-core-bluemsx", displayName: "MSX / MSX2 (blueMSX)", aka: "msx2" },
+  // 32-bit MIPS tier. These cores HW-render (GL): the host lazy-loads the OPTIONAL
+  // webgl-node bridge only when one of these boots (hwRender:true). The other 14 are
+  // software-rendered and never touch GL, so a headless user without the GPU module
+  // is unaffected.
+  // parallel_n64 built headless-angrylion (software RDP + VI scanout, no GL) so raw
+  // CPU-rendered homebrew framebuffers display — the clean no-GL-dependency N64 path,
+  // like pcsx_rearmed for PS1. (The GL/glide64 build only presents RDP display-lists.)
+  n64: { platform: "n64", coreName: "parallel_n64", pkg: "romdev-core-parallel-n64", displayName: "Nintendo 64 (ParaLLEl N64, software)", hwRender: false },
+  // pcsx_rearmed = SOFTWARE renderer + built-in HLE BIOS (no firmware to ship, no
+  // GL dependency) — the clean no-dependency PS1 path, like the other 14. The GL
+  // beetle_psx_hw (+ real BIOS) stays available as a higher-fidelity alternative.
+  ps1: { platform: "ps1", coreName: "pcsx_rearmed", pkg: "romdev-core-pcsx-rearmed", displayName: "Sony PlayStation (PCSX-ReARMed, HLE)", aka: "psx,playstation" },
 };
 
 /** Try to get {jsPath,wasmPath} for a core from its binary package. */

package/src/host/LibretroGL.js

@@ -0,0 +1,270 @@
+// LibretroGL.js — Hardware-rendered libretro core support
+//
+// Handles RETRO_ENVIRONMENT_SET_HW_RENDER by creating an EGL context via
+// native-gles and providing the three required callbacks:
+//   context_reset, get_current_framebuffer, get_proc_address
+//
+// The core renders to an FBO. After retro_run(), we readback via glReadPixels
+// and send the pixels to VideoOutput (same as wasmcart GL carts).
+
+import {
+  RETRO_HW_CONTEXT_OPENGLES2,
+  RETRO_HW_CONTEXT_OPENGLES3,
+  RETRO_HW_CONTEXT_OPENGLES_VERSION,
+  RETRO_HW_CONTEXT_OPENGL,
+  RETRO_HW_CONTEXT_OPENGL_CORE,
+} from './retroConstants.js';
+import { loadNativeGles } from './glOptionalDep.js';
+
+// `native-gles` is an OPTIONAL native dependency — only the HW-render cores
+// (n64/ps1) need it. It's loaded lazily at setup() so the 14 software-rendered
+// cores and headless installs without the GPU module are completely unaffected.
+let gl = null;
+
+// retro_hw_render_callback struct offsets (WASM32):
+//   +0   i32  context_type
+//   +4   ptr  context_reset       (set by frontend)
+//   +8   ptr  get_current_framebuffer (set by frontend)
+//   +12  ptr  get_proc_address    (set by frontend)
+//   +16  u8   depth
+//   +17  u8   stencil
+//   +18  u8   bottom_left_origin
+//   +20  u32  version_major       (aligned)
+//   +24  u32  version_minor
+//   +28  u8   cache_context
+//   +32  ptr  context_destroy     (set by core)
+//   +36  u8   debug_context
+
+export class LibretroGL {
+  constructor() {
+    this.active = false;
+    this.contextType = 0;
+    this.bottomLeftOrigin = true;
+    this.fbo = 0;
+    this.fboW = 0;
+    this.fboH = 0;
+    this.contextResetPtr = 0;    // WASM function pointer
+    this.contextDestroyPtr = 0;  // WASM function pointer
+    this._mod = null;
+    this._glPixels = null;
+    this._flipped = null;
+
+    // GL function name → addFunction wrapper pointer (cached)
+    this._procAddressCache = new Map();
+  }
+
+  /**
+   * Load the optional native GL module (lazy). MUST be awaited before the core
+   * boots, since the 14 software cores never call this and the module is an
+   * optional dependency. Populates the module-level `gl` used by
+   * createContext/readbackFrame/destroy.
+   * @returns {Promise<void>}
+   */
+  async ensureGl() {
+    if (!gl) gl = await loadNativeGles();
+  }
+
+  /** Make this core's GL context current. Called before each _retro_run so the
+   *  core renders into OUR FBO (a multi-host server may have switched contexts). */
+  makeCurrent() {
+    if (this.active && gl) gl.makeCurrent();
+  }
+
+  /**
+   * Handle RETRO_ENVIRONMENT_SET_HW_RENDER.
+   * Reads the struct, creates EGL context, writes callback pointers back.
+   * @param {object} mod - Emscripten module
+   * @param {number} dataPtr - pointer to retro_hw_render_callback
+   * @returns {boolean} true if HW render is supported
+   */
+  setup(mod, dataPtr) {
+    this._mod = mod;
+
+    // Read struct fields set by the core
+    const contextType = mod.getValue(dataPtr, 'i32');
+    const depth = mod.HEAPU8[dataPtr + 16];
+    const stencil = mod.HEAPU8[dataPtr + 17];
+    this.bottomLeftOrigin = !!mod.HEAPU8[dataPtr + 18];
+    const versionMajor = mod.getValue(dataPtr + 20, 'i32');
+    const versionMinor = mod.getValue(dataPtr + 24, 'i32');
+    this.contextDestroyPtr = mod.getValue(dataPtr + 32, 'i32');
+
+    // Validate: we only support GL ES contexts
+    const supported = [
+      RETRO_HW_CONTEXT_OPENGLES2,
+      RETRO_HW_CONTEXT_OPENGLES3,
+      RETRO_HW_CONTEXT_OPENGLES_VERSION,
+      RETRO_HW_CONTEXT_OPENGL,
+      RETRO_HW_CONTEXT_OPENGL_CORE,
+    ];
+    if (!supported.includes(contextType)) {
+      console.error(`[libretro-gl] Unsupported HW context type: ${contextType}`);
+      return false;
+    }
+
+    this.contextType = contextType;
+    console.error(`[libretro-gl] HW render requested: type=${contextType} version=${versionMajor}.${versionMinor} depth=${depth} stencil=${stencil} bottomLeft=${this.bottomLeftOrigin}`);
+
+    // Create callback wrappers the WASM core can call
+
+    // get_current_framebuffer() → returns FBO 0 (default framebuffer)
+    // The core renders through Emscripten's GL which manages its own FBOs.
+    // We read back from FBO 0 after retro_run.
+    const getFBCb = mod.addFunction(() => {
+      return 0;
+    }, 'i');
+
+    // get_proc_address(const char* sym) → returns function pointer
+    const getProcCb = mod.addFunction((symPtr) => {
+      return this._getProcAddress(symPtr);
+    }, 'ii');
+
+    // Write our callback pointers into the struct
+    // context_reset at +4 — we'll call the core's context_reset after context creation
+    // For now, store the core's context_reset so we can call it later
+    this.contextResetPtr = mod.getValue(dataPtr + 4, 'i32');
+    // We don't write context_reset back — the core already set it.
+    // We only need to write get_current_framebuffer and get_proc_address.
+    mod.setValue(dataPtr + 8, getFBCb, 'i32');
+    mod.setValue(dataPtr + 12, getProcCb, 'i32');
+
+    this.active = true;
+    return true;
+  }
+
+  /**
+   * Create FBO for the core to render into. Called after retro_load_game succeeds
+   * and AV info is available.
+   *
+   * @param {number} width
+   * @param {number} height
+   * @param {boolean} contextExists - if true, EGL context was already created externally
+   */
+  createContext(width, height, contextExists = false) {
+    this.fboW = width;
+    this.fboH = height;
+
+    if (contextExists) {
+      // Context already created by LibretroHost before core loading.
+      // Resize if needed and ensure it's current.
+      gl.resizeContext(width, height);
+      gl.makeCurrent();
+    } else {
+      // Create pbuffer EGL context
+      if (!gl.createContext(width, height)) {
+        console.error('[libretro-gl] Failed to create EGL context');
+        return false;
+      }
+      gl.makeCurrent();
+    }
+
+    // Core renders to default FBO (0). We read back from there after retro_run.
+    // The Emscripten GL layer manages its own FBO tracking — we don't create one.
+    this.fbo = 0;
+    gl.glViewport(0, 0, width, height);
+    console.error(`[libretro-gl] Using default FBO: ${width}x${height}`);
+
+    // Call the core's context_reset callback
+    if (this.contextResetPtr) {
+      this._mod.dynCall('v', this.contextResetPtr, []);
+    }
+
+    return true;
+  }
+
+  /**
+   * Read back the rendered frame as RGBA pixels.
+   * Returns { pixels, width, height } or null if not active.
+   */
+  readbackFrame() {
+    if (!this.active) return null;
+
+    gl.glFinish();
+    const w = this.fboW, h = this.fboH;
+    const GL_RGBA = 0x1908, GL_UNSIGNED_BYTE = 0x1401;
+
+    if (!this._glPixels || this._glPixels.length !== w * h * 4) {
+      this._glPixels = new Uint8Array(w * h * 4);
+    }
+
+    gl.glBindFramebuffer(0x8D40, 0); // GL_FRAMEBUFFER — read from default FBO
+    gl.glReadPixels(0, 0, w, h, GL_RGBA, GL_UNSIGNED_BYTE, this._glPixels);
+
+
+    // Flip vertically if bottom-left origin (GL convention)
+    let pixels;
+    if (this.bottomLeftOrigin) {
+      if (!this._flipped || this._flipped.length !== w * h * 4) {
+        this._flipped = new Uint8Array(w * h * 4);
+      }
+      const rowBytes = w * 4;
+      for (let y = 0; y < h; y++) {
+        const srcOff = (h - 1 - y) * rowBytes;
+        const dstOff = y * rowBytes;
+        this._flipped.set(this._glPixels.subarray(srcOff, srcOff + rowBytes), dstOff);
+      }
+      pixels = this._flipped;
+    } else {
+      pixels = this._glPixels;
+    }
+
+    return { pixels, width: w, height: h };
+  }
+
+  /**
+   * Resolve a GL function name to a WASM-callable function pointer.
+   * The core calls get_proc_address("glClear") and gets back a function
+   * table index it can call via indirect call.
+   */
+  _getProcAddress(symPtr) {
+    const mod = this._mod;
+    const name = mod.UTF8ToString(symPtr);
+
+    // Check cache
+    if (this._procAddressCache.has(name)) {
+      return this._procAddressCache.get(name);
+    }
+
+    // Look up the function on native-gles
+    const fn = gl[name];
+    if (!fn) {
+      // Not found — some cores probe for extension functions
+      this._procAddressCache.set(name, 0);
+      return 0;
+    }
+
+    // We need to create an Emscripten addFunction wrapper that bridges
+    // the WASM call to the native GL call. The challenge is that each
+    // GL function has a different signature.
+    //
+    // For libretro cores compiled with Emscripten, they typically call
+    // GL functions directly (linked at compile time) rather than through
+    // get_proc_address. get_proc_address is mainly used for extension
+    // functions. We return 0 for now if they're probing — the core's
+    // Emscripten build should have the GL functions linked directly.
+    //
+    // If a core truly needs runtime-resolved GL, we'd need a signature
+    // table mapping GL function names to their parameter types.
+
+    // For common GL functions, return a stub that indicates "available"
+    // The actual calls go through the Emscripten-linked GL functions.
+    // Returning non-zero tells the core the function exists.
+    // We create a minimal no-op wrapper since the core will call the
+    // directly-linked version, not this pointer.
+    const stub = mod.addFunction(() => { return 0; }, 'i');
+    this._procAddressCache.set(name, stub);
+    return stub;
+  }
+
+  destroy() {
+    if (this.contextDestroyPtr && this._mod) {
+      try {
+        this._mod.dynCall('v', this.contextDestroyPtr, []);
+      } catch { /* ignore */ }
+    }
+    if (this.active) {
+      gl.destroyContext();
+      this.active = false;
+    }
+  }
+}