romdevtools 0.13.0

package/src/platforms/sms/image-to-tilemap.js

@@ -0,0 +1,260 @@
+// SMS / Game Gear image-to-tilemap converter (4bpp mode 4).
+//
+// SMS resolution: 256×192 (32 × 24 cells). 4bpp interleaved tile layout:
+//   tile = 32 bytes = 8 rows × 4 bytes/row
+//   each row = p0, p1, p2, p3 in that order (one byte per plane)
+//
+// SMS palette: 32 entries × 6-bit BGR (1 byte each).
+//   Entries 0..15 = BG palette
+//   Entries 16..31 = sprite palette
+//
+// Name table format: each cell is 2 bytes little-endian:
+//   bit 0-8: tile index (0..511)
+//   bit 9:   horizontal flip
+//   bit 10:  vertical flip
+//   bit 11:  palette (0 = BG, 1 = sprite)
+//   bit 12:  priority (1 = above sprites)
+
+import { PNG } from "pngjs";
+
+const W = 256;
+const H = 192;
+
+/** RGB → SMS 6-bit BGR byte (2 bits per channel). */
+function rgbToSmsByte(r, g, b) {
+  const r2 = (r >> 6) & 0x03;
+  const g2 = (g >> 6) & 0x03;
+  const b2 = (b >> 6) & 0x03;
+  return r2 | (g2 << 2) | (b2 << 4);
+}
+
+/** SMS 6-bit byte → RGB triple. */
+function smsByteToRgb(byte) {
+  const r2 = byte & 0x03;
+  const g2 = (byte >> 2) & 0x03;
+  const b2 = (byte >> 4) & 0x03;
+  const expand = (v) => (v << 6) | (v << 4) | (v << 2) | v;
+  return [expand(r2), expand(g2), expand(b2)];
+}
+
+/**
+ * @param {Object} args
+ * @param {Buffer | Uint8Array} args.pngBytes  256×192 PNG, ideally pre-dithered to ≤16 colors.
+ * @returns {{
+ *   chr: Uint8Array,
+ *   nametable: Uint8Array,
+ *   attr: Uint8Array,
+ *   palette: Uint8Array,
+ *   uniqueTilesBeforeMerge: number,
+ *   uniqueTiles: number,
+ *   imageColors: number,
+ *   previewPng: Buffer,
+ * }}
+ */
+export function smsImageToTilemap(args) {
+  const png = PNG.sync.read(Buffer.from(args.pngBytes));
+  if (png.width !== W || png.height !== H) {
+    throw new Error(`SMS image must be ${W}×${H}, got ${png.width}×${png.height}`);
+  }
+
+  // 1) Quantize to ≤16 distinct colors.
+  /** @type {Map<number, number>} */
+  const colorIndex = new Map();
+  const pxIdx = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const k = i * 4;
+    const c = rgbToSmsByte(png.data[k], png.data[k + 1], png.data[k + 2]);
+    let idx = colorIndex.get(c);
+    if (idx === undefined) {
+      idx = colorIndex.size;
+      if (idx >= 16) {
+        throw new Error(
+          `SMS 4bpp BG layer takes ≤16 colors; image quantizes to more. ` +
+          `Use \`magick … -colors 16 -dither FloydSteinberg\` first, or ` +
+          `pre-remap against getPlatformPalettePng({platform:"sms"}).`
+        );
+      }
+      colorIndex.set(c, idx);
+    }
+    pxIdx[i] = idx;
+  }
+
+  // 2) Build 32-byte palette (BG only — sprites stay zero).
+  const palette = new Uint8Array(32);
+  for (const [c, idx] of colorIndex) palette[idx] = c;
+
+  // 3) Encode each 8×8 tile. Dedupe + detect h/v flips.
+  const tilesAcross = W / 8;   // 32
+  const tilesDown = H / 8;     // 24
+
+  const makeTile = (tx, ty) => {
+    const t = new Uint8Array(32);
+    for (let row = 0; row < 8; row++) {
+      let p0 = 0, p1 = 0, p2 = 0, p3 = 0;
+      for (let col = 0; col < 8; col++) {
+        const c = pxIdx[(ty * 8 + row) * W + (tx * 8 + col)];
+        if (c & 1) p0 |= 1 << (7 - col);
+        if (c & 2) p1 |= 1 << (7 - col);
+        if (c & 4) p2 |= 1 << (7 - col);
+        if (c & 8) p3 |= 1 << (7 - col);
+      }
+      t[row * 4 + 0] = p0;
+      t[row * 4 + 1] = p1;
+      t[row * 4 + 2] = p2;
+      t[row * 4 + 3] = p3;
+    }
+    return t;
+  };
+
+  const flipH = (tile) => {
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      let b = tile[i];
+      // Reverse bits in this byte (this row's plane).
+      b = ((b >> 1) & 0x55) | ((b & 0x55) << 1);
+      b = ((b >> 2) & 0x33) | ((b & 0x33) << 2);
+      b = ((b >> 4) & 0x0F) | ((b & 0x0F) << 4);
+      out[i] = b & 0xFF;
+    }
+    return out;
+  };
+  const flipV = (tile) => {
+    const out = new Uint8Array(32);
+    for (let row = 0; row < 8; row++) {
+      const srcRow = 7 - row;
+      out[row * 4 + 0] = tile[srcRow * 4 + 0];
+      out[row * 4 + 1] = tile[srcRow * 4 + 1];
+      out[row * 4 + 2] = tile[srcRow * 4 + 2];
+      out[row * 4 + 3] = tile[srcRow * 4 + 3];
+    }
+    return out;
+  };
+
+  const tileBytesByKey = new Map();   // raw-tile-key → tile-index in chr
+  const chr = [];
+  const nametable = new Uint8Array(tilesAcross * tilesDown * 2);
+
+  const toKey = (t) => {
+    // Hex string of 32 bytes — small enough for Map keys.
+    let s = "";
+    for (let i = 0; i < 32; i++) s += t[i].toString(16).padStart(2, "0");
+    return s;
+  };
+
+  let uniqueBeforeMerge = 0;
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const base = makeTile(tx, ty);
+      uniqueBeforeMerge++;
+      const baseKey = toKey(base);
+      let flipBits = 0;
+      let chosenKey = null;
+      if (tileBytesByKey.has(baseKey)) {
+        chosenKey = baseKey;
+      } else {
+        const h = flipH(base);
+        const v = flipV(base);
+        const hv = flipV(h);
+        const hKey = toKey(h);
+        const vKey = toKey(v);
+        const hvKey = toKey(hv);
+        if (tileBytesByKey.has(hKey))  { chosenKey = hKey; flipBits = 0x02; }      // hflip bit 9
+        else if (tileBytesByKey.has(vKey))  { chosenKey = vKey; flipBits = 0x04; } // vflip bit 10
+        else if (tileBytesByKey.has(hvKey)) { chosenKey = hvKey; flipBits = 0x06; }
+        else {
+          chosenKey = baseKey;
+          tileBytesByKey.set(baseKey, chr.length);
+          chr.push(base);
+        }
+      }
+      const tileIdx = tileBytesByKey.get(chosenKey);
+      // Name table entry (little-endian):
+      //   bit 0-8: tile index (0..511)
+      //   bit 9:   hflip
+      //   bit 10:  vflip
+      //   bit 11:  palette (0 = BG)
+      //   bit 12:  priority
+      const cellOff = (ty * tilesAcross + tx) * 2;
+      nametable[cellOff + 0] = tileIdx & 0xFF;
+      nametable[cellOff + 1] = ((tileIdx >> 8) & 0x01) | flipBits;
+    }
+  }
+
+  // 4) Flatten chr.
+  const chrFlat = new Uint8Array(chr.length * 32);
+  for (let i = 0; i < chr.length; i++) chrFlat.set(chr[i], i * 32);
+
+  // 5) Preview PNG — re-render from the encoded data so the agent can
+  // sanity-check what the SMS will actually display.
+  const preview = new PNG({ width: W, height: H });
+  for (let ty = 0; ty < tilesDown; ty++) {
+    for (let tx = 0; tx < tilesAcross; tx++) {
+      const cellOff = (ty * tilesAcross + tx) * 2;
+      const lo = nametable[cellOff];
+      const hi = nametable[cellOff + 1];
+      const tileIdx = lo | ((hi & 0x01) << 8);
+      const hflip = !!(hi & 0x02);
+      const vflip = !!(hi & 0x04);
+      const tileBase = tileIdx * 32;
+      for (let row = 0; row < 8; row++) {
+        const srcRow = vflip ? 7 - row : row;
+        const p0 = chrFlat[tileBase + srcRow * 4 + 0];
+        const p1 = chrFlat[tileBase + srcRow * 4 + 1];
+        const p2 = chrFlat[tileBase + srcRow * 4 + 2];
+        const p3 = chrFlat[tileBase + srcRow * 4 + 3];
+        for (let col = 0; col < 8; col++) {
+          const srcBit = hflip ? col : 7 - col;
+          const pi = ((p0 >> srcBit) & 1)
+                  | (((p1 >> srcBit) & 1) << 1)
+                  | (((p2 >> srcBit) & 1) << 2)
+                  | (((p3 >> srcBit) & 1) << 3);
+          const [r, g, b] = smsByteToRgb(palette[pi] ?? 0);
+          const o = ((ty * 8 + row) * W + (tx * 8 + col)) * 4;
+          preview.data[o + 0] = r;
+          preview.data[o + 1] = g;
+          preview.data[o + 2] = b;
+          preview.data[o + 3] = 0xff;
+        }
+      }
+    }
+  }
+
+  return {
+    chr: chrFlat,
+    nametable,
+    attr: new Uint8Array(0),  // SMS attributes are per-cell in the nametable
+    palette,
+    uniqueTilesBeforeMerge: uniqueBeforeMerge,
+    uniqueTiles: chr.length,
+    imageColors: colorIndex.size,
+    previewPng: PNG.sync.write(preview),
+  };
+}
+
+/**
+ * Generate a PNG containing every distinct SMS color (64 swatches).
+ * Used as the -remap target for imagemagick dithering.
+ */
+export function smsPalettePng() {
+  const cell = 16;
+  const cols = 8;
+  const rows = 8;
+  const w = cols * cell;
+  const h = rows * cell;
+  const png = new PNG({ width: w, height: h });
+  for (let i = 0; i < 64; i++) {
+    const cx = (i % 8) * cell;
+    const cy = Math.floor(i / 8) * cell;
+    const [r, g, b] = smsByteToRgb(i);
+    for (let y = 0; y < cell; y++) {
+      for (let x = 0; x < cell; x++) {
+        const o = ((cy + y) * w + (cx + x)) * 4;
+        png.data[o + 0] = r;
+        png.data[o + 1] = g;
+        png.data[o + 2] = b;
+        png.data[o + 3] = 0xff;
+      }
+    }
+  }
+  return PNG.sync.write(png);
+}

package/src/platforms/sms/lib/README.md

@@ -0,0 +1,117 @@
+# SMS / Game Gear — quickstart
+
+The compressed version of "everything I had to learn the hard way
+building an SMS ROM with romdev."
+
+## Language: C is the default
+
+SDCC 4.4.0 + the bundled SMS-specific crt0 (`c/sms_crt0.s`) give you a
+clean C development path. `build({output:'rom', platform:"sms", source: <C>})`
+auto-injects the crt0 so your `main()` runs as the cartridge reset
+handler with a proper vector table + IM 1 + SP=$DFF0.
+
+C-side hardware access uses SDCC's `__sfr __at <port>` declarations —
+see `c/sms_hw.h` for the standard port set. Reading the variable
+compiles to `in a,(port)`; writing compiles to `out (port),a`.
+
+ASM is also first-class — pass a `.s` source and it routes through
+sdasz80. The asm snippets below are the canonical implementations the
+C helpers wrap.
+
+### SDCC 4.4.0 quirks
+
+SDCC sm83/z80 is **C89-only** — no inline `for (int i = 0; ...)`, no
+mid-block declarations, no compound literals. The pre-flight linter
+catches these with the right file:line before SDCC's own (misleading)
+error messages get a chance to confuse you. See
+[`../../gb/lib/c/SDCC_GOTCHAS.md`](../../gb/lib/c/SDCC_GOTCHAS.md).
+
+The previously-documented "register-allocator crash family"
+(`dbuf_append_str NULL` assertion on for-loops with function calls,
+parallel array writes, multi-array indexed reads, etc.) was diagnosed
+on 2026-05-25 as the emscripten 64 KB default stack overflowing past
+`__data_end` and zeroing out the static `sm83_regs[]` table. Fixed by
+bumping the WASM stack to 8 MB. Those patterns compile cleanly now —
+no workarounds needed.
+
+## Snippets shipped in this directory
+
+| File | Purpose |
+|---|---|
+| `header.s` | The 16-byte TMR SEGA cartridge header at $7FF0. Required on real hardware; most emulators forgive its absence. |
+| `vdp_init.s` | Mode 4, 192-line, display OFF baseline VDP setup. Call once after reset; then upload palette/tiles/map, then enable display. |
+| `vblank_wait.s` | Two flavors: polling on `in a,($BF)` bit 7, and an IM 1 IRQ pattern with a WRAM flag. |
+| `joypad_read.s` | Reads ports $DC + $DD, inverts so pressed=1, stores in `_p1_state`/`_p2_state`. Includes button masks. |
+| `load_palette.s` | Bulk OTIR of 32 CRAM bytes (16 BG + 16 sprite) via the control-port $C0 prefix. |
+| `load_tiles.s` | Bulk OTIR into VRAM at an arbitrary destination. Handles >256 byte transfers (loops on outer page count). |
+| `sprite_table.s` | Uploads shadow OAM (256 bytes WRAM) → SAT VRAM region. Includes the (X,tile) pairs layout at $3F80. |
+
+Fetch any with `getStarterSnippet({platform:"sms", name:"<file>"})`.
+Pull them all at once with `getAllStarterSnippets({platform:"sms"})`.
+
+## The five gotchas that cost the most time
+
+### 1. VDP register writes need TWO out-of-order bytes
+
+To write VDP register `R`, you send a 16-bit value to control port $BF
+as two bytes:
+- FIRST byte = the value
+- SECOND byte = `$80 | R` (high bit signals "register write")
+
+If you reverse them you'll set the VRAM address pointer instead — a
+subtle bug that produces "the display works but later writes go to the
+wrong place." Always: `out ($BF), value` then `out ($BF), $80 | reg`.
+
+### 2. CRAM address-set prefix is $C0, VRAM is $40
+
+The VDP control port distinguishes destinations via the high bits of
+the second byte:
+- `$40 | hi` → VRAM write
+- `$00 | hi` → VRAM read
+- `$80 | reg` → register write
+- `$C0` → CRAM write (the LOW byte first must be the CRAM offset)
+
+Mixing these is the most common cause of "I uploaded my palette but the
+screen is still black" — you probably wrote to VRAM by accident.
+
+### 3. SAT terminator $D0
+
+If any Y byte in the sprite attribute table is $D0, the VDP stops
+processing sprites at that index and renders only the ones before it.
+Hide unused sprites with `Y = $D0`, not by setting them off-screen.
+Setting `Y = $FF` won't terminate, just put the sprite somewhere
+invisible — you waste a sprite slot.
+
+### 4. SMS palette is 6-bit, not 8-bit
+
+CRAM bytes are 2-2-2 BGR. So $3F is white (all channels max), $3 is
+pure red, $C is pure green, $30 is pure blue. Don't pass 0xFFFFFF and
+expect white — it'll truncate to $3F. Use `palette({source:'platformMaster', platform:"sms"})`
+to see all 64 distinct colors and dither input art against them with
+imagemagick.
+
+### 5. Game Gear CRAM is 4-4-4 (12-bit BGR), 2 bytes per entry
+
+GG palettes are NOT swappable with SMS palettes. If you're writing
+cross-target code, use a `#ifdef GG` / `#ifdef SMS` switch in your
+asset pipeline. The image-to-tilemap tool dispatches on platform, but
+hand-authored palette tables need the platform-correct encoding.
+
+## VDP register reference (the 11 that matter)
+
+| Reg | Purpose | Common value |
+|---|---|---|
+| R0 | Mode control 1 | $36 (M4 on, line IRQ off, mask col 0) |
+| R1 | Mode control 2 | $E0 to enable display ($80 disables, bit 6 enables, bit 5 enables vblank IRQ) |
+| R2 | Name table base | $FF → $3800 (formula: `(reg & 0x0E) << 10`) |
+| R3 | Color table (M4 ignored) | $FF |
+| R4 | BG tile data base | $FF → $0000 (bit 2 selects $0000 vs $2000) |
+| R5 | Sprite attribute table | $7E → $3F00 (formula: `(reg & 0x7E) << 7`) |
+| R6 | Sprite tile data base | $FB → $2000 (bit 2 selects $0000 vs $2000) |
+| R7 | Border color | $00 = sprite palette entry 0 |
+| R8 | BG X scroll | 0 = no scroll |
+| R9 | BG Y scroll | 0 = no scroll |
+| R10 | Line IRQ counter | $FF = disabled |
+
+Decode the live values via `background({view:'renderState'})` — it returns the
+fully-shifted base addresses so you don't redo the math.

package/src/platforms/sms/lib/c/joypad_read.c

@@ -0,0 +1,33 @@
+/* SMS joypad read — port $DC + $DD, inverted so pressed=1.
+ *
+ *     uint8_t p1 = sms_joypad_read();
+ *     if (p1 & JOY_RIGHT) { ... }
+ *     if (p1 & JOY_B1)    { fire(); }
+ */
+#include "sms_hw.h"
+
+uint8_t sms_joypad_read(void) {
+  uint8_t a = ~PORT_JOY_A;
+  return a & 0x3F;            /* low 6 bits = P1 D-pad + B1 + B2 */
+}
+
+/*
+ * Player 2's hardware layout is awkward — SMS splits P2 across two ports:
+ *   PORT_JOY_A bits 6-7  = P2 UP, P2 DOWN
+ *   PORT_JOY_B bits 0-3  = P2 LEFT, P2 RIGHT, P2 B1, P2 B2
+ * We reassemble into the same bit layout the agent already knows for P1:
+ *   bit 0 = UP, 1 = DOWN, 2 = LEFT, 3 = RIGHT, 4 = B1, 5 = B2.
+ * Returns 0 when no P2 controller is plugged in (all bits read high =
+ * "released" = 0 after inversion).
+ */
+uint8_t sms_joypad_read_p2(void) {
+  uint8_t a = ~PORT_JOY_A;          /* P2 UP in bit 6, DOWN in bit 7 */
+  uint8_t b = ~PORT_JOY_B;          /* P2 LEFT bit 0, RIGHT 1, B1 2, B2 3 */
+  uint8_t up    = (a >> 6) & 0x01;  /* bit 6 -> bit 0 */
+  uint8_t down  = (a >> 6) & 0x02;  /* bit 7 -> bit 1 */
+  uint8_t left  = (b << 2) & 0x04;  /* bit 0 -> bit 2 */
+  uint8_t right = (b << 2) & 0x08;  /* bit 1 -> bit 3 */
+  uint8_t b1    = (b << 2) & 0x10;  /* bit 2 -> bit 4 */
+  uint8_t b2    = (b << 2) & 0x20;  /* bit 3 -> bit 5 */
+  return (uint8_t)(up | down | left | right | b1 | b2);
+}

package/src/platforms/sms/lib/c/load_palette.c

@@ -0,0 +1,24 @@
+/* SMS palette loader — bulk upload to CRAM.
+ *
+ * SMS CRAM: 32 entries × 1 byte (2-2-2 BGR). White = 0x3F.
+ * GG CRAM:  32 entries × 2 bytes (4-4-4 BGR LE).
+ *
+ *     extern const uint8_t my_palette[32];
+ *     sms_load_palette(my_palette);
+ */
+#include "sms_hw.h"
+
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void sms_load_palette(const uint8_t *palette) {
+  uint8_t i;
+  sms_vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = palette[i];
+}
+
+/* Game Gear variant — uploads 64 bytes (32 entries × 2). */
+void gg_load_palette(const uint8_t *palette) {
+  uint8_t i;
+  sms_vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = palette[i];
+}

package/src/platforms/sms/lib/c/load_tiles.c

@@ -0,0 +1,32 @@
+/* SMS tile loader — upload bytes to VRAM at any destination.
+ *
+ * SMS tiles are 32 bytes each (4bpp interleaved). VRAM is 16 KB at
+ * $0000-$3FFF. Tile N lives at VRAM offset (N * 32).
+ *
+ *     extern const uint8_t my_tiles[];
+ *     sms_load_tiles(0x0000, my_tiles, sizeof(my_tiles));  // sprite bank
+ *
+ * Default R6=0xFB → sprite tiles read from $0000 (shared with BG tiles).
+ * If you want sprite tiles in their own bank at $2000, set R6=0xFF AND
+ * upload to $2000. Don't pick the address without checking R6.
+ */
+#include "sms_hw.h"
+
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count) {
+  uint16_t i;
+  sms_vdp_set_addr(vram_dest, VDP_VRAM_WRITE);
+  for (i = 0; i < byte_count; i++) PORT_VDP_DATA = src[i];
+}
+
+/* Write a single name-table cell. Default name table at $3800.
+ *   tile_idx: 0..511 (low 9 bits)
+ *   attr:     hflip = bit 1, vflip = bit 2, palette = bit 3, priority = bit 4
+ */
+void sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr) {
+  uint16_t addr = 0x3800 + ((uint16_t)row * 32 + col) * 2;
+  sms_vdp_set_addr(addr, VDP_VRAM_WRITE);
+  PORT_VDP_DATA = tile_idx;
+  PORT_VDP_DATA = attr;
+}

package/src/platforms/sms/lib/c/sms_crt0.s

@@ -0,0 +1,101 @@
+;; SMS / Game Gear crt0 for SDCC.
+;;
+;; Replaces SDCC's stock z80 crt0 (which assumes a host runtime that
+;; handles I/O via rst $08 — not what an SMS cartridge needs). This
+;; one boots cleanly into a real cartridge: vector table at $0000,
+;; standard SMS interrupt vectors, sets SP to $DFF0, calls main().
+;;
+;; Use via:
+;;   build({output:'rom'})({
+;;     platform: "sms",
+;;     sources: {
+;;       "main.c": ...,
+;;       "sms_crt0.s": ...this file...,
+;;     },
+;;     crt0: ".module empty\n",  // <-- empty stock crt0
+;;   })
+;;
+;; OR pass the contents of this file as `crt0` to runSdld.
+
+        .module sms_crt0
+        .globl  _main
+        .globl  l__INITIALIZER
+        .globl  s__INITIALIZER
+        .globl  s__INITIALIZED
+
+;; ─── Reset vector at $0000 ────────────────────────────────────────
+        .area _HEADER (ABS)
+        .org    0x0000
+        di                          ; interrupts off until we're ready
+        im      1                   ; mode 1 — IRQs jump to $0038
+        ld      sp, #0xDFF0         ; SMS stack (top of WRAM minus 16)
+        jp      gsinit              ; skip the interrupt vector table
+
+;; ─── RST handlers (default = return) ──────────────────────────────
+        .org    0x0008
+        ret
+        .ds     0x08 - 1
+        .org    0x0010
+        ret
+        .ds     0x08 - 1
+        .org    0x0018
+        ret
+        .ds     0x08 - 1
+        .org    0x0020
+        ret
+        .ds     0x08 - 1
+        .org    0x0028
+        ret
+        .ds     0x08 - 1
+        .org    0x0030
+        ret
+        .ds     0x08 - 1
+
+;; ─── IRQ vector at $0038 (IM 1) ───────────────────────────────────
+;; SMS hits this on vblank IF VDP R1 bit 5 is set. Default = clear the
+;; VDP status flag and return. User code that wants a real ISR can
+;; install one by writing to (vdp_isr_ptr) and a `ld hl,(vdp_isr_ptr) /
+;; jp (hl)` shim — but for now a bare ei/reti keeps things simple.
+        .org    0x0038
+        push    af
+        in      a, (#0xBF)          ; read VDP status — clears IRQ flag
+        pop     af
+        ei
+        reti
+
+;; ─── NMI vector at $0066 (Pause button on SMS) ────────────────────
+        .org    0x0066
+        retn
+
+;; ─── crt0 body ────────────────────────────────────────────────────
+;; Standard SDCC pattern: jump to a code area, run initializers, then
+;; call main. The initializer area is filled by sdcc when it sees
+;; global initializations.
+
+        .area   _HOME
+        .area   _CODE
+        .area   _GSINIT
+        .area   _GSFINAL
+
+        .area   _DATA
+        .area   _INITIALIZED
+        .area   _BSEG
+        .area   _BSS
+        .area   _HEAP
+
+        .area   _CODE
+
+gsinit:
+        ld      bc, #l__INITIALIZER
+        ld      a, b
+        or      a, c
+        jr      Z, gsinit_done
+        ld      de, #s__INITIALIZED
+        ld      hl, #s__INITIALIZER
+        ldir
+
+gsinit_done:
+        call    _main
+hang:
+        halt
+        jr      hang

package/src/platforms/sms/lib/c/sms_hw.h

@@ -0,0 +1,53 @@
+/* SMS / Game Gear hardware register declarations for SDCC.
+ *
+ * SDCC's __sfr __at <PORT> declares a Z80 I/O port. Reading the variable
+ * compiles to `in a,(port)`; writing compiles to `out (port),a`. So you
+ * can write port I/O as plain C assignments:
+ *
+ *     PORT_VDP_CTRL = 0x80;       // out ($BF), a   ; reg-write prefix
+ *     uint8_t status = PORT_VDP_CTRL;  // in a, ($BF)
+ *
+ * Include this from your main.c. The declarations are __sfr — they don't
+ * allocate storage, just bind a name to a port number. Multiple translation
+ * units including this header is safe.
+ */
+#ifndef SMS_HW_H
+#define SMS_HW_H
+
+#include <stdint.h>
+
+/* ─── VDP ───────────────────────────────────────────────────────── */
+__sfr __at 0xBE PORT_VDP_DATA;   /* data port — read VRAM/CRAM, write VRAM/CRAM/REG */
+__sfr __at 0xBF PORT_VDP_CTRL;   /* control port — address-set + register write */
+
+/* ─── PSG / counters ────────────────────────────────────────────── */
+__sfr __at 0x7E PORT_V_COUNTER;  /* read = V-counter */
+__sfr __at 0x7F PORT_H_COUNTER;  /* read = H-counter; write = PSG (overloaded) */
+
+/* ─── Controllers ───────────────────────────────────────────────── */
+__sfr __at 0xDC PORT_JOY_A;      /* P1 D-pad + buttons 1+2, P2 D-pad */
+__sfr __at 0xDD PORT_JOY_B;      /* P2 buttons + reset/cart inserted */
+
+/* ─── Memory / cart control ─────────────────────────────────────── */
+__sfr __at 0x3E PORT_MEMORY_CTRL;
+__sfr __at 0x3F PORT_IO_CTRL;
+
+/* ─── Game Gear extras ($00-$06 + $C0..) ────────────────────────── */
+__sfr __at 0x00 PORT_GG_INPUT;
+__sfr __at 0x06 PORT_GG_PSG_STEREO;
+
+/* ─── Joypad bit masks (active LOW on the port — invert after read) ── */
+#define JOY_UP    0x01
+#define JOY_DOWN  0x02
+#define JOY_LEFT  0x04
+#define JOY_RIGHT 0x08
+#define JOY_B1    0x10
+#define JOY_B2    0x20
+
+/* ─── VDP address-set high-byte prefixes ────────────────────────── */
+#define VDP_VRAM_WRITE 0x40
+#define VDP_VRAM_READ  0x00
+#define VDP_REG_WRITE  0x80
+#define VDP_CRAM_WRITE 0xC0
+
+#endif /* SMS_HW_H */