romdevtools 0.56.1 → 0.70.0

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;

package/src/host/LibretroHost.js

@@ -36,6 +36,17 @@ import {
  * to function headlessly (no menu = no user pick). Empty today — all
  * shipped cores load with their defaults.
  */
+// Core filename stem → platform, for the cores whose renderer (or other boot-time
+// behavior) is chosen from an option at retro_init. loadCore uses this to pre-seed
+// PLATFORM_CORE_OPTIONS before the core registers its variables, so the override
+// wins over the core's default (e.g. glide64-GL over angrylion-software for N64).
+const CORE_STEM_TO_PLATFORM = {
+  parallel_n64: "n64",
+  pcsx_rearmed: "ps1",
+  flycast: "dreamcast",
+  beetle_psx_hw: "ps1",
+};
+
 const PLATFORM_CORE_OPTIONS = {
   // blueMSX defaults its machine to "SEGA - SC-3000" (an SG-1000 clone, wrong for
   // MSX carts). Force the open MSX2+ C-BIOS machine — a superset that also runs
@@ -55,6 +66,24 @@ const PLATFORM_CORE_OPTIONS = {
   // beetle_psx_hw defaults to the software renderer; force hardware_gl so it
   // renders through the GL context the host set up (otherwise no FBO frames).
   ps1: { beetle_psx_hw_renderer: "hardware_gl" },
+  // Flycast defaults to THREADED rendering — the render thread + the main thread's
+  // wait on it makes retro_run unwind under emscripten pthreads (yields to the event
+  // loop, incompatible with our synchronous frame-step). Disable it so render() runs
+  // synchronously on the calling thread (Emulator::render → run(), no cross-thread
+  // wait). Also keep per-frame sync (no auto frame-skip) so one retro_run = one frame.
+  // hle_bios (reios) MUST be on: it's flycast's HLE BIOS, and only the reios boot
+  // path loads a raw homebrew .elf (reios_loadElf copies PT_LOAD segments to their
+  // vaddr + jumps). With it off (the default), flycast wants a real dc_boot.bin we
+  // don't ship → the .elf never loads (RAM stays empty, CPU never runs our code).
+  // emulate_framebuffer scans out the DC framebuffer directly on every VBlank (the 2D
+  // path, no TA list) — so simple homebrew that writes RGB565 pixels to VRAM presents
+  // reliably without building a full PowerVR2 tile list. (Threaded rendering is also
+  // force-disabled in the core itself; the option here is belt-and-suspenders.)
+  dreamcast: {
+    flycast_threaded_rendering: "disabled",
+    flycast_hle_bios: "enabled",
+    flycast_emulate_framebuffer: "enabled",
+  },
   // VICE mounts a .d64/.tap/.crt but, with autostart off, just sits at the BASIC
   // `READY.` prompt — the agent would see a blue boot screen, not the game. Force
   // autostart so a disk/tape image runs the first program automatically (same as
@@ -252,6 +281,16 @@ export class LibretroHost {
    *   optional native GL stack and creates a headless context BEFORE the core boots
    *   (GL calls happen during init/load). The 14 software cores omit this.
    */
+  /** Infer the platform from a core's js filename stem (e.g.
+   *  ".../parallel_n64_libretro.js" → "n64"), so loadCore can pre-seed that
+   *  platform's option overrides without the caller threading the platform
+   *  through. Covers the cores whose boot-time renderer choice depends on an
+   *  option; returns null otherwise (the overrides are then a no-op anyway). */
+  _platformForCore(jsPath) {
+    const stem = (jsPath.split("/").pop() || "").replace(/_libretro\.js$/, "");
+    return CORE_STEM_TO_PLATFORM[stem] ?? null;
+  }
+
   async loadCore(jsPath, wasmPath, opts = {}) {
     if (this.mod) throw new Error("core already loaded; create a new host");
 
@@ -287,6 +326,24 @@ export class LibretroHost {
     }
 
     registerCallbacks({ mod, state: this.state, log: this.log });
+
+    // Pre-seed per-platform core-option overrides BEFORE _retro_init. The core
+    // registers its variables (SET_VARIABLES) during retro_init and decides its
+    // renderer THEN — e.g. parallel_n64 reads `parallel-n64-gfxplugin` to pick
+    // glide64 (GL/HW-render) vs angrylion (software). Seeding the override here
+    // (not in loadMedia, which is too late) makes the SET_VARIABLES handler keep
+    // our value instead of the core's default, so HW render engages from boot.
+    const platform = opts.platform ?? this._platformForCore(jsPath);
+    if (platform) {
+      const overrides = PLATFORM_CORE_OPTIONS[platform];
+      if (overrides) {
+        for (const [key, value] of Object.entries(overrides)) {
+          this.state.coreVariables.set(key, { value });
+        }
+        this.state.variablesUpdated = true;
+      }
+    }
+
     mod._retro_init();
     this.status.corePath = jsPath;
   }
@@ -588,7 +645,9 @@ export class LibretroHost {
   _afterRun() {
     if (this.state.hwFramePending && this.hwRender?.active) {
       this.state.hwFramePending = false;
-      const frame = this.hwRender.readbackFrame();
+      // Crop the GL FBO to the core's reported active resolution (e.g. DC 640x480 in an
+      // 853x853 FBO) so screenshots don't carry the dead viewport border.
+      const frame = this.hwRender.readbackFrame(this.state.hwFrameW, this.state.hwFrameH);
       if (frame) {
         this.state.lastFrame = {
           width: frame.width, height: frame.height,

package/src/host/callbacks.js

@@ -172,6 +172,10 @@ export function registerCallbacks(args) {
     const uPtr = dataPtr >>> 0;
     if (uPtr === RETRO_HW_FRAME_BUFFER_VALID && state.hwRender?.active) {
       state.hwFramePending = true;
+      // Remember the core's reported active resolution (e.g. DC 640x480) so the
+      // readback can crop the (often larger, e.g. 853x853) GL FBO to just the
+      // rendered region instead of returning the whole viewport with dead borders.
+      if (w > 0 && h > 0) { state.hwFrameW = w; state.hwFrameH = h; }
       return;
     }
     if (dataPtr === 0 || uPtr === RETRO_HW_FRAME_BUFFER_VALID) return;

package/src/host/coreLoader.js

@@ -37,10 +37,15 @@ export async function loadLibretroCore(args) {
 
   /** @type {Record<string, unknown>} */
   const opts = {
-    noInitialRun: true,
-    print: () => {},
-    printErr: () => {},
+    print: process.env.ROMDEV_CORE_LOG ? (s) => console.error("[core]", s) : () => {},
+    printErr: process.env.ROMDEV_CORE_LOG ? (s) => console.error("[core:err]", s) : () => {},
   };
+  // The cores are linked with INVOKE_RUN=0, so main() never auto-runs regardless.
+  // Do NOT set noInitialRun on GL (canvas) cores: it suppresses the Emscripten GL
+  // runtime init, so `Module.GL` (and thus the WebGL2/native-gles context the core's
+  // SET_HW_RENDER path needs) is never created. For non-GL cores it's harmless either
+  // way; we set it only there to keep their startup identical to before.
+  if (!glCanvas) opts.noInitialRun = true;
 
   // HW-render cores: minified glue uses GLctx = canvas.getContext('webgl2'), so we
   // hand it a webgl-node mock canvas + install the WebGL2 globals Emscripten probes.
@@ -84,8 +89,16 @@ export async function loadLibretroCore(args) {
       });
       return {};
     };
-  } else if (wasmPath) {
+  } else if (wasmPath && !glCanvas) {
     opts.wasmBinary = await readFile(wasmPath);
+  } else if (wasmPath && glCanvas) {
+    // GL (canvas) cores: do NOT hand Emscripten a pre-read wasmBinary. Passing it
+    // routes instantiation through a path that skips the GL runtime init, so
+    // `Module.GL` (the WebGL2/native-gles context the SET_HW_RENDER path needs) is
+    // never created. Let Emscripten locate `<name>.wasm` next to the `.js` itself
+    // (via locateFile) — the same way retroemu loads parallel_n64/flycast.
+    const wasmDir = wasmPath.slice(0, wasmPath.lastIndexOf("/") + 1);
+    opts.locateFile = (file) => wasmDir + file;
   }
 
   const mod = await factory(opts);

package/src/mcp/tools/project.js

@@ -646,6 +646,22 @@ const TEMPLATES = {
       },
     };
   })(),
+
+  // ── Sega Dreamcast (sh-elf-gcc SH-4) — bare PowerVR2 framebuffer via the bundled
+  // dc.h helper; the output ELF boots DIRECTLY on Flycast's reios HLE BIOS (no GD-ROM
+  // image, no firmware) and renders on the real GPU through native-gles. dc.h is
+  // auto-bundled by the toolchain, so the example is a single main.c. No KallistiOS
+  // and no genre scaffolds yet — `hello` is the verified renderable starting point. ──
+  dreamcast: {
+    default: { main: "hello/main.c", runtime: [], lang: "C (sh-elf-gcc)", ext: ".elf",
+      describe: "DCHELLO — the canonical Dreamcast starter: bring up the PowerVR2 640x480 RGB565 framebuffer (via the auto-bundled dc.h: FB_R_CTRL/SIZE/SOF1 + SPG) and paint a test pattern (dark-blue field, red/green/blue bars, white frame). Proves the SH-4 build → Flycast reios HLE boot → native-gles GPU render pipeline end-to-end. The base to grow your own DC graphics from. Same as 'hello'." },
+    hello: { main: "hello/main.c", runtime: [], lang: "C (sh-elf-gcc)", ext: ".elf",
+      describe: "DCHELLO — a minimal Dreamcast homebrew. dc_video_init() programs the PowerVR2 framebuffer registers for 640x480 RGB565 at VRAM 0xA5000000; then dc_clear/dc_rect paint a recognizable pattern. Boots directly on Flycast's reios HLE BIOS (no firmware) and presents through native-gles with flycast_emulate_framebuffer — no TA display list needed.",
+      players: "1 (Dreamcast has 4 controller ports; the bare path doesn't wire the Maple bus yet)",
+      sram: "none in this starter — DC saves go to the VMU via the Maple bus; not wired in the bare path.",
+      mechanics: ["direct framebuffer paint (clear + solid rects)", "recognizable test pattern"],
+      techniques: ["PowerVR2 framebuffer bring-up (FB_R_CTRL/FB_R_SIZE/FB_R_SOF1 + SPG)", "640x480 RGB565 at VRAM 0xA5000000", "SH-4 bare crt0 (stack + .bss + main)", "boots on Flycast reios HLE — no firmware"] },
+  },
 };
 // R37: GBC has its own scaffold tree at examples/gbc/templates/ +
 // src/platforms/gbc/lib/c/. Same runtime files as GB (the APU + Z80 +

package/src/toolchains/index.js

@@ -91,6 +91,9 @@ const LANGUAGE_TOOLCHAIN = {
   n64: {
     c: { toolchain: "mips-elf-gcc", available: true, note: "C for N64 via gcc 14.2.0 + binutils + newlib (mips-elf, big-endian R4300), compiled to WASM. Bare path: minimal crt0 (stack + .bss + main()) → flat code image at 0x80000400. NOTE: a fully bootable N64 ROM needs the IPL3 bootcode + a libdragon-style header (libdragon SDK forthcoming) — this path exercises the toolchain + is the basis for the SDK." },
   },
+  dreamcast: {
+    c: { toolchain: "sh-elf-gcc", available: true, note: "C for Dreamcast via gcc 14.2.0 + binutils + newlib (sh-elf, little-endian SH-4, m4-single-only FP), compiled to WASM. Bare path: a minimal crt0 sets the stack + clears .bss + calls main(); the output is an ELF that Flycast's reios HLE BIOS boots DIRECTLY (no GD-ROM/CDI image, no firmware). No KallistiOS yet — bring up the PowerVR2 framebuffer yourself: program FB_R_CTRL/FB_R_SIZE/FB_R_SOF1 + SPG for 640x480 RGB565 at VRAM 0xA5000000, then write pixels (see the dc.h helper). With flycast_emulate_framebuffer on, a plain pixel-writing program presents — no TA list needed." },
+  },
 };
 
 /**
@@ -123,6 +126,7 @@ const PLATFORM_DEFAULT_LANGUAGE = {
   msx:        "c",
   ps1:        "c",
   n64:        "c",
+  dreamcast:  "c",
 };
 
 /**
@@ -502,6 +506,32 @@ export async function buildForPlatform(args) {
     };
   }
 
+  if (args.platform === "dreamcast") {
+    // Dreamcast SH-4 C: the bare gcc+newlib+libgcc path through the sh-elf-gcc WASM
+    // toolchain (cc1→as→ld). The output is an ELF that Flycast's reios HLE BIOS boots
+    // directly (no GD-ROM/CDI image). Bring up the PowerVR2 framebuffer yourself (see
+    // the dc.h helper); language defaults to "c".
+    const { buildShC } = await import("./sh-c/sh-c.js");
+    const r = await buildShC({
+      source: args.source,
+      sources: args.sources,
+      headers: args.includes,
+      cc1Options: args.options,
+    });
+    return {
+      ok: r.ok,
+      binary: r.binary,
+      listing: "",
+      symbols: r.symbols ?? "",
+      log: r.log,
+      issues: parseBuildLog(r.log),
+      exitCode: r.exitCode,
+      toolchain: "sh-elf-gcc",
+      stage: r.stage,
+      ...(r.crash ? { crash: r.crash } : {}),
+    };
+  }
+
   if (args.platform === "gba") {
     // R24 + R28: language:"c" routes through the arm-none-eabi gcc +
     // binutils WASM toolchain (cc1-arm → as → ld → objcopy). Three

package/src/toolchains/sh-c/lib/dc-crt0.s

@@ -0,0 +1,23 @@
+	.section .text.start, "ax"
+	.global _start
+_start:
+	mov.l stack_top, r15      ! stack = top of 16MB DC RAM
+	mov.l bss_start, r0       ! clear .bss
+	mov.l bss_end, r1
+	mov #0, r2
+1:	cmp/hs r1, r0
+	bt 2f
+	mov.l r2, @r0
+	add #4, r0
+	bra 1b
+	nop
+2:	mov.l main_addr, r0       ! call main()
+	jsr @r0
+	nop
+hang:	bra hang
+	nop
+	.align 4
+stack_top:	.long 0x8d000000
+bss_start:	.long __bss_start
+bss_end:	.long _end
+main_addr:	.long _main

package/src/toolchains/sh-c/lib/dc.h

@@ -0,0 +1,102 @@
+/* dc.h — minimal Dreamcast helper for romdev homebrew.
+ *
+ * Brings up the PowerVR2 video output for a plain 640x480 RGB565 framebuffer and
+ * exposes pixel/fill/rect primitives. No KallistiOS dependency — just the registers
+ * the Flycast (reios HLE) core needs to scan out a direct framebuffer.
+ *
+ * Memory map:
+ *   PVR/HOLLY registers : 0xA05F8000 (uncached)
+ *   VRAM (64-bit area)  : 0xA5000000 (16 MB) — the framebuffer lives here
+ *
+ * The DC has two VRAM views; the 64-bit area (0xA5000000) is the linear one we draw to.
+ */
+#ifndef ROMDEV_DC_H
+#define ROMDEV_DC_H
+
+typedef unsigned char  u8;
+typedef unsigned short u16;
+typedef unsigned int   u32;
+
+#define DC_W 640
+#define DC_H 480
+
+/* PVR register access */
+#define PVR_BASE 0xA05F8000u
+#define PVR_REG(off) (*(volatile u32 *)(PVR_BASE + (off)))
+
+/* The framebuffer we draw to (offset 0 in the 64-bit VRAM area). */
+#define DC_FB_OFFSET 0x000000u
+#define DC_VRAM ((volatile u16 *)(0xA5000000u + DC_FB_OFFSET))
+
+/* RGB565 helper */
+static inline u16 dc_rgb(u8 r, u8 g, u8 b) {
+    return (u16)(((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3));
+}
+
+/* Bring up 640x480 RGB565 video. Call once at start. The register values are the
+ * documented PowerVR2 settings for a progressive NTSC 640x480 RGB565 framebuffer;
+ * Flycast's reios + EmulateFramebuffer scanout reads FB_R_CTRL/FB_R_SIZE/FB_R_SOF1. */
+static inline void dc_video_init(void) {
+    /* FB_R_CTRL: fb_enable=1, fb_depth=1 (RGB565), fb_concat=4 (fill low bits). */
+    PVR_REG(0x044) = 0x00000001u | (1u << 2) | (4u << 4); /* = 0x45 */
+    /* FB_W_CTRL: fb_packmode=1 (RGB565). */
+    PVR_REG(0x048) = 0x00000001u;
+    /* FB_R_SOF1 / FB_W_SOF1: framebuffer start = DC_FB_OFFSET. */
+    PVR_REG(0x050) = DC_FB_OFFSET;          /* FB_R_SOF1 */
+    PVR_REG(0x060) = DC_FB_OFFSET;          /* FB_W_SOF1 */
+    /* FB_R_SIZE: fb_x_size = (line bytes / 4) - 1, fb_y_size = lines - 1, modulus = 1.
+     * 640px * 2 bytes = 1280 bytes/line -> 1280/4 - 1 = 319. */
+    PVR_REG(0x05C) = (u32)(DC_W * 2 / 4 - 1)        /* fb_x_size = 319 */
+                   | ((u32)(DC_H - 1) << 10)        /* fb_y_size = 479 */
+                   | ((u32)1u << 20);               /* fb_modulus = 1 */
+    /* FB_W_LINESTRIDE: line stride in 64-bit (8-byte) units = 1280/8 = 160. */
+    PVR_REG(0x11C) = (u32)(DC_W * 2 / 8);
+    /* VO_CONTROL: pixel double off, normal output. */
+    PVR_REG(0x0E8) = 0x00000000u;
+    /* VO_BORDER_COL: black border. */
+    PVR_REG(0x040) = 0x00000000u;
+    /* SPG_LOAD / SPG_CONTROL: NTSC 640x480 progressive timing. */
+    PVR_REG(0x0D8) = (524u << 16) | 857u;   /* SPG_LOAD: vcount, hcount */
+    PVR_REG(0x0D0) = 0x00000000u;           /* SPG_CONTROL: NTSC, non-interlace */
+}
+
+/* Plot a pixel (no bounds clamp on the hot path; caller keeps in range). */
+static inline void dc_plot(int x, int y, u16 c) {
+    DC_VRAM[y * DC_W + x] = c;
+}
+
+/* Fill the whole framebuffer with one color. */
+static inline void dc_clear(u16 c) {
+    int i;
+    for (i = 0; i < DC_W * DC_H; i++)
+        DC_VRAM[i] = c;
+}
+
+/* Fill an axis-aligned rectangle (clipped to the screen). */
+static inline void dc_rect(int x0, int y0, int w, int h, u16 c) {
+    int x, y;
+    if (x0 < 0) { w += x0; x0 = 0; }
+    if (y0 < 0) { h += y0; y0 = 0; }
+    if (x0 + w > DC_W) w = DC_W - x0;
+    if (y0 + h > DC_H) h = DC_H - y0;
+    for (y = 0; y < h; y++)
+        for (x = 0; x < w; x++)
+            DC_VRAM[(y0 + y) * DC_W + (x0 + x)] = c;
+}
+
+/* ── Controller input (Maple bus, port 0) ─────────────────────────────────────
+ * The DC Maple controller digital-button bit layout. Full Maple DMA setup is
+ * non-trivial; the romdev host injects input (setInput) that the core maps onto
+ * Maple, so these constants document the bit layout for game logic. */
+#define DC_BTN_C      0x0001
+#define DC_BTN_B      0x0002
+#define DC_BTN_A      0x0004
+#define DC_BTN_START  0x0008
+#define DC_BTN_UP     0x0010
+#define DC_BTN_DOWN   0x0020
+#define DC_BTN_LEFT   0x0040
+#define DC_BTN_RIGHT  0x0080
+#define DC_BTN_Y      0x0200
+#define DC_BTN_X      0x0400
+
+#endif /* ROMDEV_DC_H */

package/src/toolchains/sh-c/lib/dc.ld

@@ -0,0 +1,11 @@
+ENTRY(_start)
+MEMORY { ram (rwx) : ORIGIN = 0x8c010000, LENGTH = 0x800000 }
+SECTIONS {
+  .text : { *(.text.start) *(.text*) *(.rodata*) } > ram
+  .data : { *(.data*) } > ram
+  . = ALIGN(4);
+  __bss_start = .;
+  .bss  : { *(.bss*) *(COMMON) } > ram
+  . = ALIGN(4);
+  _end = .;
+}

package/src/toolchains/sh-c/sh-c.js

@@ -0,0 +1,101 @@
+// sh-c — Dreamcast (SH-4) C build driver.
+//
+//   buildShC({ source | sources, headers }) → { ok, binary (ELF), log, symbols }
+//
+// gcc-the-driver can't fork/exec under emscripten, so we orchestrate the stages
+// directly (cc1 → as → ld → objcopy-not-needed). The output is an ELF that Flycast's
+// reios HLE BIOS boots directly (no GD-ROM/CDI image, no scrambling): reios_loadElf
+// copies the PT_LOAD segments to their vaddr (0x8c010000) and jumps to _start.
+//
+// Bare path: a small crt0 sets the stack (top of 16 MB DC RAM), zeroes .bss, and
+// calls main(). newlib libc/libm + libgcc are linked (SH-4, little-endian). The
+// romdev DC helper (rom-games/dreamcast/.../dc.h) brings up the PowerVR2 framebuffer.
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { runCc1sh, runShAs, runShLd } from "../sh-elf-gcc/gcc.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const LIB = path.join(__dirname, "lib");
+
+/**
+ * Compile + link Dreamcast SH-4 C to a bootable ELF.
+ * @param {object} args
+ * @param {string} [args.source] single C source (shorthand for sources["main.c"])
+ * @param {Record<string,string>} [args.sources] name → source (.c and .s)
+ * @param {Record<string,string>} [args.headers] name → header text
+ * @param {string[]} [args.cc1Options] extra cc1 flags
+ */
+export async function buildShC(args) {
+  // The bundled DC helper (dc.h) is auto-available so `#include "dc.h"` just works —
+  // it brings up the PowerVR2 framebuffer (FB_R_CTRL/SIZE/SOF1 + SPG for 640x480 RGB565)
+  // that Flycast presents. A caller-supplied "dc.h" wins (override the bundled one).
+  const bundledDcH = await readFile(path.join(LIB, "dc.h"), "utf-8").catch(() => null);
+  const headers = { ...(bundledDcH != null ? { "dc.h": bundledDcH } : {}), ...(args.headers ?? {}) };
+  // -m4-single-only is passed by the cc1 wrapper; here the language/codegen knobs.
+  // Default to -O2, but let a user-supplied -O<level> win (gcc honors the LAST -O, so a
+  // default appended AFTER the user's would clobber it — only add -O2 if absent).
+  const userOpts = args.cc1Options ?? [];
+  const hasOpt = userOpts.some((o) => /^-O/.test(o));
+  const cc1Options = [...(hasOpt ? [] : ["-O2"]), ...userOpts, "-ffreestanding", "-fno-builtin", "-Wall"];
+  const sources = args.sources ?? (args.source != null ? { "main.c": args.source } : {});
+  let log = "";
+
+  /** @type {Record<string, Uint8Array>} */
+  const userObjs = {};
+  for (const cName of Object.keys(sources).filter((n) => /\.c$/i.test(n))) {
+    const cc = await runCc1sh({ source: sources[cName], headers, options: cc1Options });
+    log += `--- cc1 (${cName}) ---\n${cc.log || "(ok)"}\n`;
+    if (cc.exitCode !== 0 || !cc.asmSource)
+      return { ok: false, binary: null, log, exitCode: cc.exitCode || 1, stage: `cc1 (${cName})`, ...(cc.crash ? { crash: cc.crash } : {}) };
+    const as = await runShAs({ source: cc.asmSource });
+    log += `--- as (${cName}) ---\n${as.log || "(ok)"}\n`;
+    if (as.exitCode !== 0 || !as.object)
+      return { ok: false, binary: null, log, exitCode: as.exitCode || 1, stage: `as (${cName})`, ...(as.crash ? { crash: as.crash } : {}) };
+    userObjs[cName.replace(/\.c$/i, ".o")] = as.object;
+  }
+  // raw .s sources too
+  for (const sName of Object.keys(sources).filter((n) => /\.(s|asm)$/i.test(n))) {
+    const as = await runShAs({ source: sources[sName] });
+    log += `--- as (${sName}) ---\n${as.log || "(ok)"}\n`;
+    if (as.exitCode !== 0 || !as.object)
+      return { ok: false, binary: null, log, exitCode: as.exitCode || 1, stage: `as (${sName})`, ...(as.crash ? { crash: as.crash } : {}) };
+    userObjs[sName.replace(/\.(s|asm)$/i, ".o")] = as.object;
+  }
+
+  // crt0 (stack + .bss clear + main()).
+  const crt0Src = await readFile(path.join(LIB, "dc-crt0.s"), "utf-8");
+  const crt0As = await runShAs({ source: crt0Src });
+  log += `--- as (dc-crt0.s) ---\n${crt0As.log || "(ok)"}\n`;
+  if (crt0As.exitCode !== 0 || !crt0As.object)
+    return { ok: false, binary: null, log, exitCode: crt0As.exitCode || 1, stage: "as (crt0)", ...(crt0As.crash ? { crash: crt0As.crash } : {}) };
+
+  // link: crt0 + user objects + newlib (libc/libm) + libgcc.
+  const linkScript = await readFile(path.join(LIB, "dc.ld"), "utf-8");
+  const [libc, libm, libgcc] = await Promise.all([
+    readFile(path.join(LIB, "libc.a")),
+    readFile(path.join(LIB, "libm.a")),
+    readFile(path.join(LIB, "libgcc.a")),
+  ]);
+  const ld = await runShLd({
+    objects: { "crt0.o": crt0As.object, ...userObjs },
+    linkScript,
+    archives: {
+      "libc.a": new Uint8Array(libc),
+      "libm.a": new Uint8Array(libm),
+      "libgcc.a": new Uint8Array(libgcc),
+    },
+    libraries: ["c", "m", "gcc"],
+    libraryPaths: ["/work"],
+    options: ["--no-warn-rwx-segments"],
+  });
+  log += `--- ld ---\n${ld.log || "(ok)"}\n`;
+  if (ld.exitCode !== 0 || !ld.elf)
+    return { ok: false, binary: null, log, exitCode: ld.exitCode || 1, stage: "ld", ...(ld.crash ? { crash: ld.crash } : {}) };
+
+  // The ELF IS the deliverable — reios boots it directly.
+  return { ok: true, binary: ld.elf, log, exitCode: 0, stage: "done", ...(ld.map ? { symbols: ld.map } : {}) };
+}