romdevtools 0.56.1 → 0.71.0

package/src/platforms/ps1/TROUBLESHOOTING.md

@@ -0,0 +1,55 @@
+# PlayStation (PS1) — troubleshooting
+
+Read `platform({op:'doc', platform:'ps1', name:'mental_model'})` first — PS1 renders
+by issuing **GPU primitives (GP0)** on the hardware renderer, not by writing a CPU
+framebuffer.
+
+## "ROM builds + boots but the screen is BLACK"
+
+1. **You're trying to write a raw framebuffer.** PS1's renderer is the hardware GPU
+   (`beetle_psx_hw`, `hwRender:true`) — it rasterizes the **GP0 command stream**, not
+   a CPU-written framebuffer. Draw with GPU primitives (the bundled `psx.c` emits
+   them); a CPU memset of "VRAM" won't show.
+2. **You never set the display area / drawing environment.** GP1 sets the display
+   mode + display start; GP0 `0xE1..0xE6` set the drawing area/offset. Without a valid
+   draw env + display env the GPU has nowhere to put pixels. The helper lib's
+   `gpu_init` does this — call it before drawing.
+3. **Nothing was actually submitted to GP0.** Confirm with `frame({op:'verify'})`
+   (nearlyBlank) + check you're writing the GP0 port (`0x1F80_1810`) / running a DMA
+   to it, not just touching VRAM.
+
+## "Rectangles stretch to the edge of the screen / primitives are garbage"
+
+`GP0 0x60` (and the rect family) is a **variable-size rectangle**: 3 words = color,
+top-left corner, size. If you feed it 4 polygon vertices it reads corner+size+garbage
+and stretches. Use the **triangle** family (`0x20`/`0x24`/`0x28`/`0x2C`) for polys and
+the **rect** family (`0x60`/`0x64`/`0x68`/`0x6C`) for rects. Match the command to the
+primitive and word count.
+
+## "Geometry is wrong / inside-out / clipped"
+
+Software-3D front-end math (the helper lib transforms before emitting GP0): check
+16.16 fixed-point throughout, back-face winding matches your vertex order, perspective
+divide before the GP0 vertex coords, and coords fit the 11-bit signed GPU range.
+
+## "disasm/decompile of a multi-function program returns junk (fcn.00000000)"
+
+Known rizin trap: for **absolute-addressed `jal`** (PS1 `jal 0x80010518`), rizin
+ignores `-B` on a raw `malloc://` buffer and addresses flat from 0, so cross-function
+discovery dangles outside the image. romdev fixes this by left-padding `.text` so the
+flat offset == the VA's low 20 bits, seeding analysis there, and rebasing the high bits
+back — so reported addresses are real VAs. If you see a lone `fcn.00000000`, you're on
+a path that bypassed the rebase; build a **multi-function** program to exercise it (a
+single-instruction smoke test hides this).
+
+## "breakpoint / watch return N/A"
+
+`cpu({op:'read'})` and `audioDebug({op:'inspect', chip:'spu'})` ARE wired on PS1 (the
+core exports `romdev_mips_regs_get` + `romdev_spu_get`). `breakpoint`/`watch` are not
+yet — those need interpreter-step + memory-path hooks patched into beetle (cpuState/
+audioDebug are plain reads). Use `cpu`/`audioDebug` + `memory` + `disasm`/`decompile`
+meanwhile.
+
+## "renderingContext returns N/A"
+
+Correct — PS1 is a 3D GPU machine with no 2D tile/sprite VDP for that op. Not a bug.

package/src/platforms/ps1/UPSTREAM_SOURCES.md

@@ -0,0 +1,54 @@
+# PlayStation (PS1) — source you can read
+
+Trust hierarchy (try in order before filing a feedback round):
+
+1. **Bundled examples** (`examples/ps1/{shmup,platformer,puzzle,racing,sports}/main.c` +
+   `sprite_move/`) — verified building + rendering on the GPU. Start here.
+2. **Bundled helper lib source** (`src/platforms/ps1/lib/c/psx.c` + `psx.h`) — the GPU
+   front end. Read this when a primitive renders wrong: it shows how the software-3D
+   transform feeds **GP0 GPU primitives** (the real console path — the GPU rasterizes the
+   command stream; this is NOT a software framebuffer). The GP0 `0x60` rect-vs-poly gotcha
+   is in here + TROUBLESHOOTING.
+3. **The core source** (NOT bundled — fetch on demand):
+
+   | What | Upstream |
+   |---|---|
+   | beetle-psx (Mednafen PSX, libretro, HW renderer) | https://github.com/libretro/beetle-psx-libretro |
+   | R3000A CPU / SPU / GPU internals | (in the beetle tree: `mednafen/psx/cpu.c`, `spu.c`, `gpu.cpp`) |
+
+   The cpuState/audioDebug exports we patch in (`romdev_mips_regs_get`,
+   `romdev_spu_get`) live in `scripts/patches/romdev-snippets/beetle-psx-regsnap.c` +
+   `beetle-psx-spu.c`.
+
+4. **The toolchain** — a from-scratch `mips-elf-gcc` cross-compiler (little-endian) built
+   to WASM (`scripts/build-mips-toolchain.sh` — one toolchain emits both N64 BE + PS1 LE):
+
+   | Component | Upstream |
+   |---|---|
+   | binutils | https://ftp.gnu.org/gnu/binutils/ |
+   | gcc | https://ftp.gnu.org/gnu/gcc/ |
+   | newlib | https://sourceware.org/pub/newlib/ |
+
+5. **Reverse engineering** — Rizin + Ghidra MIPS (R3000A):
+
+   | What | Upstream |
+   |---|---|
+   | Rizin | https://github.com/rizinorg/rizin |
+   | rz-ghidra | https://github.com/rizinorg/rz-ghidra |
+
+## PS1 hardware docs
+
+- **psx-spx** (Nocash, the canonical reference): https://psx-spx.consoledev.net/
+- **PSn00bSDK** (a real open PS1 SDK — read its GPU/GTE/SPU code for the standard GP0/GP1
+  encodings + SPU register layout): https://github.com/Lameguy64/PSn00bSDK
+
+## When to use what
+
+- "Why is my screen BLACK?" → MENTAL_MODEL + TROUBLESHOOTING (you must issue GP0
+  primitives + set the draw/display environment — a CPU memset won't show).
+- "My rectangles stretch to the edge" → the GP0 `0x60` variable-size-rect gotcha
+  (TROUBLESHOOTING).
+- "How does the helper emit a triangle?" → `psx.c` + psx-spx GPU section.
+- "audioDebug SPU volumes look off" → the SPU volume/sweep registers read processed
+  values; the decode reads the raw mirror (see `psx.c` / beetle `spu.c`).
+- "disasm returns a single `fcn.00000000`" → TROUBLESHOOTING (the absolute-`jal` rebase).

package/src/platforms/snes/TROUBLESHOOTING.md

@@ -261,6 +261,16 @@ synthesizes a fallback `issues[]` entry with a hint. The idioms to avoid:
   block where the layout expects it. Use
   `examples({op:'snippets', platform:"snes", mode:"get", snippetName:"lorom_header.asm"})`
   for the canonical layout (and `lorom_multibank.asm` for multi-bank).
+- **`readfile1`/`filesize`/`canreadfile` across MANY distinct files.** Converting
+  assets at assemble time (the commercial-disassembly idiom — e.g. an `incpal`
+  macro reading every `.pal` palette to emit 15-bit color) reads many *distinct*
+  files via the readfile API. asar-WASM can **abort with no diagnostic** above a
+  threshold of distinct files read that way (one file read 200× is fine — it's
+  the *count of distinct files*). `incbin` does NOT have this problem. The build
+  log carries an `[asar advisory]`/abort-hint when it sees a source over the
+  threshold. **Fix: pre-convert the assets to `.bin` blobs offline and `incbin`
+  them** — the output is byte-identical. (Put the converted blobs in a subdir;
+  `output:'project'` stages subdirectory assets recursively.)
 
 (This is the asar/asm path. The default PVSnesLib **C** path goes through
 tcc-65816 + wla-65816 and has its own C89 trap, above.)

package/src/toolchains/asar/asar.js

@@ -74,6 +74,17 @@ export async function runAsar(args) {
   });
   let { binary, log, exitCode } = first;
 
+  // asar exits a NORMAL error build via its C++ exception path (quit throws a
+  // numeric heap pointer, not a clean status), so the worker appends a generic
+  // `[worker] Abort in WASM: <ptr>` line even though asar DID write proper
+  // diagnostics (e.g. `…: error: (Elabel_not_found): …`). That line reads as a
+  // silent crash + the heap-pointer "<number>" looks like an OOM/trap — it cost
+  // real diagnosis time (v0.70.0 feedback #5). When the log already has a real
+  // asar diagnostic, this was an ordinary error exit: drop the misleading line.
+  if (exitCode !== 0 && /:\s*(error|warning)\s*:/i.test(log)) {
+    log = log.replace(/\n?\s*\[worker\] Abort in WASM:[^\n]*\n?/g, "\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+  }
+
   // Silent-fail recovery. When asar throws a numeric value through Emscripten's
   // C++-exception path, that "number" is a heap pointer to the thrown object,
   // not an exit code — and we've lost the actual error message. Under
@@ -101,9 +112,19 @@ export async function runAsar(args) {
 
     const hex = "0x" + (exitCode >>> 0).toString(16).toUpperCase();
     const looksLikeHeapPointer = exitCode > 1024;
-    const hint = looksLikeHeapPointer
+    // Count DISTINCT files touched via the readfile/filesize/canreadfile API.
+    // asar-WASM has a known resource issue where reading enough distinct files
+    // that way (the canonical commercial-disassembly asset-conversion idiom, e.g.
+    // an incpal macro converting many .pal palettes) can abort with no diagnostic
+    // (v0.70.0 feedback #1). Surfacing the count turns a silent dead-end into a
+    // lead. (incbin of the same files does NOT trip it — only readfile1/filesize.)
+    const distinctReadfileFiles = countReadfileFiles(source);
+    const readfileHint = distinctReadfileFiles >= READFILE_DISTINCT_WARN
+      ? ` This source reads ${distinctReadfileFiles} DISTINCT files via readfile1/filesize/canreadfile — asar-WASM can abort with no diagnostic above a threshold of distinct files read that way (a known limitation). If you're converting assets at assemble time (e.g. .pal -> 15-bit), pre-convert them to .bin blobs offline and incbin those instead (incbin does NOT leak) — the output is byte-identical.`
+      : "";
+    const hint = (looksLikeHeapPointer
       ? "Exit code looks like a heap pointer, not a real exit code — likely a C++ exception that escaped without writing to stderr. Common causes: bank-border-crossed, section overlap, ROM size exceeded, or out-of-memory while assembling."
-      : "asar exited non-zero with no output.";
+      : "asar exited non-zero with no output.") + readfileHint;
 
     const layoutText = formatLayout(summarizeWrittenRegions(verboseBinary, baseRom, { flatBinary }));
 
@@ -155,6 +176,20 @@ export async function runAsar(args) {
     includesInfo[name] = { size };
   }
 
+  // Proactive advisory: even when THIS build squeaked by, a source reading many
+  // distinct files via readfile1/filesize is at risk of the asar-WASM abort —
+  // surface it (non-fatal) so a growing disassembly doesn't dead-end later.
+  {
+    const distinct = countReadfileFiles(source);
+    if (distinct >= READFILE_DISTINCT_WARN && !/readfile.*distinct files/i.test(log)) {
+      log =
+        `[asar advisory] this source reads ${distinct} distinct files via readfile1/filesize — ` +
+        `asar-WASM can abort (no diagnostic) above a threshold of distinct files read that way. ` +
+        `If you're converting assets at assemble time, prefer pre-converting them to .bin and ` +
+        `'incbin' (byte-identical, no leak).\n` + log;
+    }
+  }
+
   // Try to read the symbol file that asar emitted, if any.
   let symbolsText = null;
   if (wantSymbols) {
@@ -346,20 +381,30 @@ function asarPreflight(source, { binaryIncludes = {}, includes = {} } = {}) {
   }
 
   // -----------------------------------------------------------------------
-  // Header-overlap detection: if an `incbin "foo.bin"` lands in a 32 KB
-  // bank window starting at $XX8000 and the file size would extend past
-  // $XXFFC0 (16 KB of usable area before the LoROM header), warn the user
-  // BEFORE asar happily clobbers the header during pass 2.
+  // Header-overlap detection: an `incbin "foo.bin"` whose span would reach
+  // $00FFC0 clobbers the LoROM header during pass 2. **The LoROM header lives
+  // ONLY in bank $00** ($00FFC0..$00FFFF) — for banks $01+, $XXFFC0 is ordinary
+  // ROM, and games (e.g. SMW's GFX banks 08-0B) legitimately fill across those
+  // boundaries under `check bankcross off`. So only flag BANK $00 (v0.70.0 #6:
+  // the old check false-positived on every bank as "$08FFC0 header"). Also honor
+  // `check bankcross off` (the user is explicitly opting into bank-crossing fills).
   //
-  // We only check incbin's pointing at files in binaryIncludes (where we
-  // know the size). We assume each incbin is preceded by an `org $XX8000`
-  // and that the file fits or doesn't from that base.
+  // We only check incbin's pointing at files in binaryIncludes (size known) and
+  // assume each is preceded by an `org $008000`. Note: this scans only the entry
+  // source — `incbin`s inside `incsrc`'d files aren't seen (so the check is a
+  // best-effort early warning, not full coverage).
   // -----------------------------------------------------------------------
   const incbinDirective = /^\s*incbin\s+"([^"]+)"/;
-  // Walk top-to-bottom, tracking the most recent org as the "cursor".
+  const bankcrossOffRe = /^\s*check\s+bankcross\s+off\b/i;
+  const bankcrossOnRe = /^\s*check\s+bankcross\s+(on|half)\b/i;
+  // Walk top-to-bottom, tracking the most recent org as the "cursor" and the
+  // current `check bankcross` state (off = the user opted into crossing fills).
   let cursor = null;
+  let bankcrossOff = false;
   for (let i = 0; i < lines.length; i++) {
     const line = stripComment(lines[i]);
+    if (bankcrossOffRe.test(line)) { bankcrossOff = true; continue; }
+    if (bankcrossOnRe.test(line)) { bankcrossOff = false; continue; }
     const orgMatch = line.match(orgDirective);
     if (orgMatch) {
       cursor = parseInt(orgMatch[1], 16);
@@ -373,15 +418,16 @@ function asarPreflight(source, { binaryIncludes = {}, includes = {} } = {}) {
     const size = blob instanceof Uint8Array ? blob.length : Buffer.from(blob, "base64").length;
     const bank = (cursor >>> 16) & 0xFF;
     const off = cursor & 0xFFFF;
-    const headerStart = 0xFFC0; // LoROM header lives at $XXFFC0..$XXFFFF
-    if (off >= 0x8000 && off + size > headerStart) {
+    const headerStart = 0xFFC0; // LoROM header lives at $00FFC0..$00FFFF (bank $00 ONLY)
+    if (!bankcrossOff && bank === 0x00 && off >= 0x8000 && off + size > headerStart) {
       const fmtAddr = (a) => "$" + a.toString(16).padStart(6, "0").toUpperCase();
       const endAddr = (bank << 16) | (off + size - 1);
       issues.push(
         `[asar preflight] line ${i + 1}: 'incbin "${name}"' (${size} bytes) starting at ` +
         `${fmtAddr(cursor)} would extend to ${fmtAddr(endAddr)}, overlapping the LoROM ` +
-        `header at $${bank.toString(16).padStart(2, "0").toUpperCase()}FFC0. Move this data ` +
-        `to a higher bank (e.g. 'org $018000') or shrink it below ${headerStart - off} bytes.`,
+        `header at $00FFC0. Move this data to a higher bank (e.g. 'org $018000') or ` +
+        `shrink it below ${headerStart - off} bytes. (Add 'check bankcross off' if this ` +
+        `crossing is intentional.)`,
       );
     }
     // Advance cursor so consecutive incbins in the same bank stack.
@@ -531,3 +577,27 @@ function asarPreflight(source, { binaryIncludes = {}, includes = {} } = {}) {
   }
   return null;
 }
+
+// asar-WASM aborts (no diagnostic) once readfile1/filesize/canreadfile touch
+// enough DISTINCT files — the canonical commercial-disassembly asset-conversion
+// idiom (an incpal-style macro converting many .pal palettes at assemble time).
+// We can't always predict the exact ceiling, so warn above this many distinct
+// files so the build doesn't silently dead-end (v0.70.0 feedback #1).
+const READFILE_DISTINCT_WARN = 40;
+
+/**
+ * Count DISTINCT file names passed to the readfile / filesize / canreadfile
+ * functions. Only literal string filenames are counted (computed names can't be
+ * resolved statically). Used for the readfile-leak advisory.
+ * @param {string} source
+ * @returns {number}
+ */
+function countReadfileFiles(source) {
+  const names = new Set();
+  // readfile1("x",..) / readfile2(...) / readfile3 / readfile4 / filesize("x")
+  // / canreadfile("x",..) / canreadfile1..4 — first string arg is the filename.
+  const re = /\b(?:readfile[1-4]|canreadfile[1-4]?|filesize)\s*\(\s*"([^"]+)"/gi;
+  let m;
+  while ((m = re.exec(source)) !== null) names.add(m[1]);
+  return names.size;
+}

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/mips-c/mips-c.js

@@ -77,9 +77,30 @@ function wrapN64Rom(text, entry = 0x80000400) {
 export async function buildMipsC(args) {
   const platform = args.platform;
   const endian = platform === "ps1" ? "little" : "big";
-  const headers = args.headers ?? {};
   const cc1Options = [...(args.cc1Options ?? []), "-O2", "-G0", "-ffreestanding", "-fno-builtin", "-Wall"];
   const sources = args.sources ?? (args.source != null ? { "main.c": args.source } : {});
+
+  // Auto-bundle the platform helper lib so `#include "n64.h"` / `#include "psx.h"`
+  // just works (parity with the Dreamcast sh-c path that auto-bundles dc.h). The
+  // header is added to the virtual headers; the matching .c is compiled + linked as
+  // an extra source — UNLESS the caller already provides their own (caller wins, and
+  // we skip auto-linking the .c if a same-named source is already present so there's
+  // no duplicate-symbol clash). The helper lives in platforms/<platform>/lib/c/.
+  const helperName = platform === "ps1" ? "psx" : platform === "n64" ? "n64" : null;
+  const headers = { ...(args.headers ?? {}) };
+  /** @type {Record<string,string>} */
+  let autoHelperSrc = null;
+  if (helperName) {
+    const helperDir = path.join(__dirname, "..", "..", "platforms", platform, "lib", "c");
+    const hPath = path.join(helperDir, `${helperName}.h`);
+    const cPath = path.join(helperDir, `${helperName}.c`);
+    if (headers[`${helperName}.h`] == null) {
+      const hSrc = await readFile(hPath, "utf-8").catch(() => null);
+      if (hSrc != null) headers[`${helperName}.h`] = hSrc;
+    }
+    const callerHasC = (args.sources && (args.sources[`${helperName}.c`] != null));
+    if (!callerHasC) autoHelperSrc = await readFile(cPath, "utf-8").catch(() => null);
+  }
   let log = "";
 
   /** @type {Record<string, Uint8Array>} */
@@ -93,6 +114,19 @@ export async function buildMipsC(args) {
     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;
   }
+  // Auto-bundled helper .c (n64.c / psx.c) — compiled with the SAME headers so it can
+  // see its own header, linked alongside the user objects. Skipped when the caller
+  // supplied their own helper .c (callerHasC) above.
+  if (autoHelperSrc != null) {
+    const cc = await runCc1mips({ source: autoHelperSrc, headers, options: cc1Options, endian });
+    log += `--- cc1 (${helperName}.c, bundled) ---\n${cc.log || "(ok)"}\n`;
+    if (cc.exitCode !== 0 || !cc.asmSource) return { ok: false, binary: null, log, exitCode: cc.exitCode || 1, stage: `cc1 (${helperName}.c bundled)`, ...(cc.crash ? { crash: cc.crash } : {}) };
+    const as = await runMipsAs({ source: cc.asmSource, endian });
+    log += `--- as (${helperName}.c, bundled) ---\n${as.log || "(ok)"}\n`;
+    if (as.exitCode !== 0 || !as.object) return { ok: false, binary: null, log, exitCode: as.exitCode || 1, stage: `as (${helperName}.c bundled)` };
+    userObjs[`${helperName}.o`] = as.object;
+  }
+
   // raw .s sources too
   for (const sName of Object.keys(sources).filter((n) => /\.(s|asm)$/i.test(n))) {
     const as = await runMipsAs({ source: sources[sName], endian });

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,152 @@
+/* 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 INTERLACED (480i). Non-interlace (240p)
+     * only displays 240 lines, so the top half of a 480-line framebuffer never shows.
+     * interlace=1 outputs the full 480-line image. */
+    PVR_REG(0x0D8) = (524u << 16) | 857u;   /* SPG_LOAD: vcount, hcount */
+    PVR_REG(0x0D0) = 0x00000050u;           /* SPG_CONTROL: NTSC, interlace=1 (bit4), PAL=0 */
+}
+
+/* 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) ─────────────────────────────────────
+ * Digital-button bits, matching Flycast's DC kcode (active-LOW on the wire — a bit
+ * is 0 when pressed). dc_pad() does a real Maple "Get Condition" DMA, inverts the
+ * kcode to active-HIGH, and masks to the real button bits. The romdev host's
+ * setInput drives the emulated pad. */
+#define DC_BTN_C      (1u << 0)
+#define DC_BTN_B      (1u << 1)
+#define DC_BTN_A      (1u << 2)
+#define DC_BTN_START  (1u << 3)
+#define DC_BTN_UP     (1u << 4)
+#define DC_BTN_DOWN   (1u << 5)
+#define DC_BTN_LEFT   (1u << 6)
+#define DC_BTN_RIGHT  (1u << 7)
+#define DC_BTN_Y      (1u << 9)
+#define DC_BTN_X      (1u << 10)
+/* only the bits above are real digital buttons; mask out reserved bits on read. */
+#define DC_BTN_MASK   0x06FFu
+
+/* Maple DMA registers (Holly system bus). */
+#define DC_SB(o)   (*(volatile u32 *)(0xA05F6C00u + (o)))
+#define DC_MDSTAR  0x04   /* command-table address */
+#define DC_MDEN    0x14   /* DMA enable */
+#define DC_MDST    0x18   /* DMA start */
+
+/* Read controller port 0 via a Maple "Get Condition" DMA. Builds a one-shot command
+ * frame (recipient = port-0 controller AP 0x20, cmd 0x09 GetCondition, function =
+ * controller 0x01000000), points the recv buffer at a scratch, kicks the DMA, then
+ * scans the response for the controller's function-id marker (0x01000000) and reads
+ * the 16-bit kcode that immediately follows. kcode is active-LOW on the wire, so we
+ * invert + mask to the real button bits → DC_BTN_* set == pressed.
+ *
+ * NOTE: the exact word offset of the kcode in the recv frame can vary; we locate it
+ * by the MFID marker rather than a fixed index, which is robust across the response
+ * framing. Returns 0 if no controller response is found. */
+static inline u32 dc_pad(void) {
+    static volatile u32 cmd[8] __attribute__((aligned(32)));
+    static volatile u32 rsp[16] __attribute__((aligned(32)));
+    u32 phys_cmd = ((u32)(unsigned long)cmd) & 0x1FFFFFFF;
+    u32 phys_rsp = ((u32)(unsigned long)rsp) & 0x1FFFFFFF;
+    int i;
+    for (i = 0; i < 16; i++) rsp[i] = 0;
+    cmd[0] = 0x80000000u;             /* last xfer (bit31), op=START(0), frame len-1=0 */
+    cmd[1] = phys_rsp;                /* receive address */
+    cmd[2] = (1u << 24)               /* data length in words (1) */
+           | (0x20u << 16)            /* sender address */
+           | (0x20u << 8)             /* recipient: port 0 controller (AP 0x20) */
+           | 0x09u;                   /* command: Get Condition */
+    cmd[3] = 0x01000000u;             /* function: controller */
+    DC_SB(DC_MDEN) = 1;
+    DC_SB(DC_MDSTAR) = phys_cmd;
+    DC_SB(DC_MDST) = 1;               /* synchronous under the romdev/HLE core */
+    /* find the controller function-id (0x01000000) in the response; the kcode is the
+     * next word's low half. The response data starts after the frame header word. */
+    for (i = 0; i < 15; i++) {
+        if (rsp[i] == 0x01000000u) {
+            u32 kcode = rsp[i + 1] & 0xFFFF;
+            return ((~kcode) & DC_BTN_MASK);
+        }
+    }
+    return 0;
+}
+static inline int dc_pressed(u32 mask) { return (dc_pad() & mask) ? 1 : 0; }
+
+#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 = .;
+}