romdevtools 0.56.1 → 0.71.0

package/src/analysis/analyze.js

@@ -135,13 +135,14 @@ export function sniffPlatform(p) {
   if (/\.pce$/i.test(p)) return "pce";
   if (/\.(z64|n64|v64)$/i.test(p)) return "n64";
   if (/\.(psexe|psx)$/i.test(p)) return "ps1"; // .exe/.bin ambiguous — pass platform explicitly
+  if (/\.(cdi|gdi)$/i.test(p)) return "dreamcast"; // DC disc images; .elf is cross-platform — pass platform explicitly
   if (/\.(gen|md|bin)$/i.test(p)) return "genesis";
   return null;
 }
 
 /** rizin asm.bits per arch (analysis defaults; rizin's loader usually sets
  * these for recognized formats, but raw blobs need a hint). */
-const BITS = { arm: 32, m68k: 32, snes: 16, mips: 32 };
+const BITS = { arm: 32, m68k: 32, snes: 16, mips: 32, sh: 32 };
 
 /**
  * The rizin analysis-SEED command for a context. For the 8/16-bit platforms
@@ -154,7 +155,10 @@ const BITS = { arm: 32, m68k: 32, snes: 16, mips: 32 };
  * @returns {string} the seed command (no trailing semicolon)
  */
 function analysisSeed({ arch, codeStart }) {
-  if (arch === "mips") {
+  // MIPS (N64/PS1) and SH-4 (Dreamcast) are raw code images with no rizin-recognized
+  // entry, so `aaa` finds nothing — seed a function at the code start + recursively
+  // analyze its call graph (`af` + `aac`). The 8/16-bit bin formats self-seed via aaa.
+  if (arch === "mips" || arch === "sh") {
     const at = "0x" + (codeStart || 0).toString(16);
     return `af @ ${at}; aac @ ${at}`;
   }
@@ -167,8 +171,12 @@ function analysisSeed({ arch, codeStart }) {
  *  `rebase` so callers get real VAs that round-trip through the decompile
  *  VA→fileOffset math. N64 (.z64) keeps its absolute VAs baked into the code and is
  *  analyzed flat from codeStart, so no rebase. */
-function mipsAnalysisBase({ arch, platform, loadBase, codeStart }) {
-  const rebase = (arch === "mips" && platform === "ps1" && loadBase) ? (loadBase & 0xfff00000) >>> 0 : 0;
+function mipsAnalysisBase({ platform, loadBase, codeStart }) {
+  // PS1 (left-padded to the VA's low 20 bits) and Dreamcast (same, loadBase
+  // 0x8c010000) need the VA's HIGH bits added back so addresses round-trip. N64 runs
+  // flat with VAs already baked in (no rebase).
+  const padded = (platform === "ps1" || platform === "dreamcast") && loadBase;
+  const rebase = padded ? (loadBase & 0xfff00000) >>> 0 : 0;
   return { baddr: undefined, seedAt: codeStart, rebase };
 }
 
@@ -276,6 +284,39 @@ async function loadContext(romPath, platformOverride) {
       romBytes = text;
     }
   }
+  // Dreamcast SH-4: KOS produces an ELF (load base 0x8c010000) or a stripped flat
+  // binary. For an ELF, strip to the first PT_LOAD segment's bytes + take its vaddr
+  // as loadBase. Like PS1, SH-4 uses PC-relative + absolute addressing, so left-pad
+  // so flat offset == the VA's low bits and add the high bits back as rebase.
+  if (platform === "dreamcast") {
+    let text = romBytes, loadVa = 0x8c010000;
+    if (romBytes.length >= 0x34 && romBytes[0] === 0x7f && romBytes[1] === 0x45 &&
+        romBytes[2] === 0x4c && romBytes[3] === 0x46) { // "\x7fELF"
+      // ELF32 LE: e_phoff @0x1c, e_phentsize @0x2a, e_phnum @0x2c. Find first PT_LOAD.
+      const u32 = (o) => (romBytes[o] | (romBytes[o + 1] << 8) | (romBytes[o + 2] << 16) | (romBytes[o + 3] << 24)) >>> 0;
+      const u16 = (o) => romBytes[o] | (romBytes[o + 1] << 8);
+      const phoff = u32(0x1c), phentsize = u16(0x2a), phnum = u16(0x2c);
+      for (let i = 0; i < phnum; i++) {
+        const ph = phoff + i * phentsize;
+        if (u32(ph) === 1) { // PT_LOAD
+          const p_offset = u32(ph + 4), p_vaddr = u32(ph + 8), p_filesz = u32(ph + 16);
+          loadVa = p_vaddr >>> 0;
+          text = romBytes.subarray(p_offset, p_offset + p_filesz);
+          break;
+        }
+      }
+    }
+    loadBase = loadVa >>> 0;
+    const lowPad = loadBase & 0x000fffff;
+    if (lowPad > 0 && lowPad <= 0x200000) {
+      const padded = new Uint8Array(lowPad + text.length);
+      padded.set(text, lowPad);
+      romBytes = padded;
+      codeStart = lowPad;
+    } else {
+      romBytes = text;
+    }
+  }
 
   // A6: container/format sniff. Some dumps are interleaved/headered such that a
   // FLAT read scrambles every byte → fake "bad instruction" noise everywhere.
@@ -623,12 +664,26 @@ export async function analyzeDecompile(romPath, address, platformOverride) {
   // offset and decompile via the MIPS SLEIGH spec (MIPS:BE:32 for N64, MIPS:LE:32
   // for PS1). N64: normalize byte order, fileOff = vaddr - entryVaddr + 0x1000 (post
   // IPL3). PS1: strip PS-EXE, fileOff = vaddr - loadAddr.
-  if (platform === "n64" || platform === "ps1") {
+  if (platform === "n64" || platform === "ps1" || platform === "dreamcast") {
     let fileOff;
     if (platform === "n64") {
       romBytes = normalizeN64ByteOrder(romBytes).bytes;
       const entry = ((romBytes[0x08] << 24) | (romBytes[0x09] << 16) | (romBytes[0x0a] << 8) | romBytes[0x0b]) >>> 0;
       fileOff = ((address >>> 0) - entry + 0x1000) >>> 0;
+    } else if (platform === "dreamcast") {
+      // SH-4: strip the ELF to its first PT_LOAD segment (vaddr = loadBase), or treat
+      // a raw image as flat at 0x8c010000. fileOff = address - segment vaddr.
+      let loadVa = 0x8c010000;
+      if (romBytes.length >= 0x34 && romBytes[0] === 0x7f && romBytes[1] === 0x45 && romBytes[2] === 0x4c && romBytes[3] === 0x46) {
+        const u32 = (o) => (romBytes[o] | (romBytes[o + 1] << 8) | (romBytes[o + 2] << 16) | (romBytes[o + 3] << 24)) >>> 0;
+        const u16 = (o) => romBytes[o] | (romBytes[o + 1] << 8);
+        const phoff = u32(0x1c), phentsize = u16(0x2a), phnum = u16(0x2c);
+        for (let i = 0; i < phnum; i++) {
+          const ph = phoff + i * phentsize;
+          if (u32(ph) === 1) { loadVa = u32(ph + 8) >>> 0; romBytes = romBytes.subarray(u32(ph + 4), u32(ph + 4) + u32(ph + 16)); break; }
+        }
+      }
+      fileOff = ((address >>> 0) - loadVa) >>> 0;
     } else {
       let loadAddr = 0;
       if (romBytes.length >= 0x800 && romBytes[0] === 0x50 && romBytes[1] === 0x53 && romBytes[2] === 0x2d && romBytes[3] === 0x58) {

package/src/analysis/decompile.js

@@ -51,6 +51,9 @@ export const SLEIGH_LANGID = {
   // 32-bit MIPS III code). Ghidra ships both MIPS variants in its stock SLEIGH.
   ps1: "MIPS:LE:32:default",
   n64: "MIPS:BE:32:default",
+  // Dreamcast = SH-4 (SuperH), little-endian. Ghidra ships SuperH4 in its stock
+  // SLEIGH; we compile SuperH4_le.sla (see scripts/build-decompiler.sh).
+  dreamcast: "SuperH4:LE:32:default",
 };
 
 /**

package/src/analysis/rizin.js

@@ -59,14 +59,16 @@ export const RIZIN_ARCH = {
   // below — same arch, different byte order.
   ps1: "mips",
   n64: "mips",
+  dreamcast: "sh", // SH-4 (SuperH) — rizin's `sh` plugin covers it
 };
 
 /** 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. */
+ *  loader/arch default. PS1 is little, N64 is big. Dreamcast SH-4 is little. */
 export const RIZIN_ENDIAN = {
   ps1: "little",
   n64: "big",
+  dreamcast: "little",
 };
 
 /**

package/src/cores/capabilities.js

@@ -219,12 +219,17 @@ export const CAPABILITIES = {
     cpus: { main: "r3000", secondary: ["gte"] },
     audioChips: ["spu"],
     memoryRegions: [...GENERIC_REGIONS],
-    renderingKind: "framebuffer", introspection: "shallow",
+    renderingKind: "3d", 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.
+      // beetle_psx_hw: the GPU renders on the REAL GPU via the GLES3/WebGL2 hardware
+      // renderer through native-gles (like glide64-N64 + Flycast-DC), with OpenBIOS
+      // EMBEDDED (PCSX-Redux, MIT, region-free) — no Sony firmware to ship, no BIOS file.
+      // run/screenshot + cheats + cpuState + audioDebug live; disasm + decompile work
+      // (MIPS Capstone + the MIPS:LE:32 SLEIGH spec). cpuState (R3000A GPR_full/BACKED_PC)
+      // + audioDebug (SPU $1F801C00 register block) come from beetle-side
+      // romdev_mips_regs_get/romdev_spu_get exports patched into cpu.c (see
+      // scripts/patches/romdev-snippets/beetle-psx-regsnap.c). build needs a PS1
+      // toolchain (PSn00bSDK, not yet).
       build: true, run: true, screenshot: true,
       inspectSprites: false, inspectPalette: false, inspectBackground: false,
       renderingContext: false, cpuState: true, audioDebug: true,
@@ -248,6 +253,29 @@ export const CAPABILITIES = {
       cart: false, disasm: true, decompile: true,
     },
   },
+
+  dreamcast: {
+    cpuFamily: "sh", decompileQuality: "good", tier: "sh",
+    cpus: { main: "sh4", secondary: ["arm7"] }, // SH-4 main + ARM7 AICA sound CPU
+    audioChips: ["aica"],
+    memoryRegions: [...GENERIC_REGIONS],
+    renderingKind: "3d", introspection: "shallow",
+    ops: {
+      // Flycast WASM boots + RUNS homebrew .elf (reios HLE): the SH-4 executes guest
+      // code (run + memory introspection), and the PowerVR2 present-path works — flycast
+      // renders to the GL FBO and the host reads it back (verified: a framebuffer-writing
+      // program shows ~727k captured pixels). `build` lands with the sh-elf-gcc WASM
+      // toolchain. cpuState (SH-4 Sh4cntx regs) + audioDebug (AICA 64-channel register
+      // window) come from romdev_sh4_regs_get/romdev_aica_get patched into the flycast
+      // libretro entry (see scripts/patches/romdev-snippets/flycast-debug.c). The 3D
+      // renderer has no tile/sprite inspectors (N/A by hw). disasm/decompile = SH-4
+      // analysis slice (rizin `sh` + Ghidra SuperH4 SLEIGH).
+      build: true, run: true, screenshot: true,
+      inspectSprites: false, inspectPalette: false, inspectBackground: false,
+      renderingContext: false, cpuState: true, audioDebug: true,
+      cart: false, disasm: true, decompile: true,
+    },
+  },
 };
 
 /** The 32-bit MIPS tier (PS1/N64) — marked `tier:"mips"`. A PARTIAL tier: they
@@ -259,14 +287,22 @@ export const MIPS_TIER_PLATFORMS = Object.entries(CAPABILITIES)
   .filter(([, c]) => c.tier === "mips")
   .map(([p]) => p);
 
+/** The next-gen tiers (32-bit CPU families added after the canonical 14): MIPS
+ *  (PS1/N64) + SH (Dreamcast) + future. Any platform carrying a CPU-family `tier`
+ *  is held to its OWN conformance, not the "all 14" cross-checks; a new platform
+ *  starts here (analysis-first) and graduates as run/build/etc. land. */
+export const NEXTGEN_TIER_PLATFORMS = Object.entries(CAPABILITIES)
+  .filter(([, c]) => c.tier === "mips" || c.tier === "sh")
+  .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. */
+ *  screenshot. Excludes the partial next-gen tiers above. */
 export const CONTRACT_PLATFORMS = Object.keys(CAPABILITIES)
-  .filter((p) => !MIPS_TIER_PLATFORMS.includes(p));
+  .filter((p) => !NEXTGEN_TIER_PLATFORMS.includes(p));
 
 /** Does `platform` support `op`? Unknown platform/op → false. */
 export function supports(platform, op) {

package/src/cores/registry.js

@@ -57,14 +57,19 @@ export const CORES = {
   // 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" },
+  // parallel_n64 renders the RDP on the REAL GPU through glide64 (GL HLE) → native-gles
+  // (the host's WebGL2 bridge), same path as Flycast. The host forces the glide64 plugin
+  // via a core option. NOT software RDP (angrylion) — that was the old headless build.
+  n64: { platform: "n64", coreName: "parallel_n64", pkg: "romdev-core-parallel-n64", displayName: "Nintendo 64 (ParaLLEl N64, glide64 GL)", hwRender: true },
+  // beetle_psx_hw = mednafen PSX with the GLES3/WebGL2 HARDWARE renderer → rendered on
+  // the real GPU through native-gles (like glide64-N64 + Flycast-DC). Ships with OpenBIOS
+  // EMBEDDED (PCSX-Redux, MIT-licensed, region-free) so there's no copyrighted Sony
+  // firmware to ship and no BIOS file to supply — the GPU PS1 path with an open BIOS.
+  ps1: { platform: "ps1", coreName: "beetle_psx_hw", pkg: "romdev-core-beetle-psx-hw", displayName: "Sony PlayStation (Beetle PSX HW, OpenBIOS)", aka: "psx,playstation", hwRender: true },
+  // Flycast = full Dreamcast emulator, GLES3/WebGL2 HW-render (PowerVR2 is GPU-first,
+  // no software framebuffer path) → driven through the native-gles/webgl-node bridge
+  // like the GL N64 build. HLE BIOS (reios) on by default — no firmware to ship.
+  dreamcast: { platform: "dreamcast", coreName: "flycast", pkg: "romdev-core-flycast", displayName: "Sega Dreamcast (Flycast)", aka: "dc", hwRender: true },
 };
 
 /** Try to get {jsPath,wasmPath} for a core from its binary package. */

package/src/host/LibretroGL.js

@@ -174,13 +174,20 @@ export class LibretroGL {
 
   /**
    * Read back the rendered frame as RGBA pixels.
+   * @param {number} [cropW] active width the core reported (e.g. DC 640); when smaller
+   *   than the FBO, read back only that bottom-left region instead of the whole viewport
+   *   (the GL bottom-left origin puts the active framebuffer in the lower-left corner).
+   * @param {number} [cropH] active height the core reported (e.g. DC 480).
    * Returns { pixels, width, height } or null if not active.
    */
-  readbackFrame() {
+  readbackFrame(cropW, cropH) {
     if (!this.active) return null;
 
     gl.glFinish();
-    const w = this.fboW, h = this.fboH;
+    // Crop to the core's active resolution when it's a sub-region of the FBO; this
+    // strips the dead border a fixed-size GL FBO leaves around a smaller native frame.
+    const w = (cropW > 0 && cropW <= this.fboW) ? cropW : this.fboW;
+    const h = (cropH > 0 && cropH <= this.fboH) ? cropH : this.fboH;
     const GL_RGBA = 0x1908, GL_UNSIGNED_BYTE = 0x1401;
 
     if (!this._glPixels || this._glPixels.length !== w * h * 4) {
@@ -188,6 +195,7 @@ export class LibretroGL {
     }
 
     gl.glBindFramebuffer(0x8D40, 0); // GL_FRAMEBUFFER — read from default FBO
+    // x=0,y=0 is the bottom-left of the FBO, which is where the native frame is drawn.
     gl.glReadPixels(0, 0, w, h, GL_RGBA, GL_UNSIGNED_BYTE, this._glPixels);
 
 
@@ -225,32 +233,27 @@ export class LibretroGL {
       return this._procAddressCache.get(name);
     }
 
-    // Look up the function on native-gles
+    // PREFERRED: cores built with emscripten's own WebGL layer (GL_ENABLE_GET_PROC_
+    // ADDRESS=1, e.g. Flycast) resolve GL through emscripten_GetProcAddress, which
+    // returns a REAL function-table pointer into the WebGL JS implementation —
+    // correct signature, no stub. Use it when the core exports it. (The old
+    // native-gles `gl[name]` + addFunction(...,'i') stub path traps the moment the
+    // core calls a multi-arg GL fn through a 0-arg pointer — that's the
+    // context_reset "null function or function signature mismatch".)
+    if (typeof mod._emscripten_GetProcAddress === "function") {
+      const ptr = mod._emscripten_GetProcAddress(symPtr) >>> 0;
+      this._procAddressCache.set(name, ptr);
+      return ptr;
+    }
+
+    // Fallback (native-gles bridge cores, e.g. the glide64 N64 build): the GL fns
+    // are linked directly into the core, so a non-zero "available" marker suffices —
+    // the core calls its own linked function, not this pointer.
     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;