romdev-mcp 0.1.1

package/src/platforms/gb/lib/c/README.md

@@ -0,0 +1,120 @@
+# GB / GBC C runtime + headers
+
+These are the source files that back the GB/GBC C templates. They're
+**not** auto-injected at build time — `createProject({platform:"gb"|"gbc",
+template:"..."})` copies them into your project directory so the
+project is self-describing. Build calls then point at your project's
+copy of these files via `sourcesPaths` / `includePaths` / `crt0Path`.
+
+| File           | Copied as | What's in it |
+|---|---|---|
+| `gb_hardware.h` | header `gb_hardware.h` in include path | Symbolic names for every GB / GBC I/O register (`LCDC`, `BGP`, `JOYP`, `BCPS`, etc.) plus LCDC bit masks. Uses SDCC's `__sfr __at 0xFFNN` form (full 16-bit address, not port number). |
+| `gb_runtime.h` | header `gb_runtime.h` in include path | Declarations for the helper functions below. |
+| `gb_runtime.c` | extra translation unit, linked automatically | `wait_vblank()`, `joypad_read()`, `oam_dma_copy()`, `memcpy_vram()`, `lcd_init_default()`, plus the OAM helpers `oam_clear()`, `oam_set(slot,y,x,tile,attr)`, `oam_dma_flush()` driving the 160-byte `shadow_oam[]` global. |
+| `gb_crt0.s` | replaces stock SDCC sm83 crt0 (assembled internally) | Lays out a real cartridge: reset/IRQ vectors at $0000-$0060, entry stub at $0100, reserves $0104-$014F as the header window, puts `init:` in `_CODE` at $0150. |
+| `unroll.h` | header `unroll.h` in include path | `UNROLL_2..UNROLL_64` macros for manual loop unrolling. Originally a workaround for the now-fixed sm83 register-allocator crash family; left in for code that still uses it. You don't need it for new code. |
+
+Just `#include "gb_hardware.h"` and (optionally) `#include "gb_runtime.h"` —
+both work in any GB/GBC C build the agent submits. Caller-supplied files
+of the same name win on collision, so you can override.
+
+**Cart header is auto-fixed at build time.** `buildSource` / `runSource`
+run rgbfix on the linked GB/GBC ROM — valid Nintendo logo at $0104,
+header checksum at $014D, global checksum at $014E, cartridge-type /
+RAM-size bytes, and the CGB flag at $0143 ($00 for `.gb`, $80/$C0 for
+`.gbc`). A freshly built ROM boots on hardware and strict cores with
+**no extra step** — you do not call `patchGbHeader` after a normal build.
+
+Reach for header tooling only when working with a ROM the build pipeline
+didn't produce, or to override a field:
+
+- `patchGbHeader({path: "out.gb"})` — MCP tool (loadCategory:"project").
+  Fixes up / overrides the header of an existing ROM on disk (title, cart
+  type, ROM/RAM size, CGB flag, etc.).
+- `node patch-header.js out.gb` — standalone Node script, copied into
+  every GB project by `createProject`. Same logic, no MCP needed.
+- `rgbfix -v -p 0 out.gb` — what the build pipeline runs under the hood;
+  RGBDS asm projects can invoke it directly.
+
+## Companion docs
+
+- **[`../../TROUBLESHOOTING.md`](../../TROUBLESHOOTING.md)** — symptom →
+  fix table. Start here when your ROM compiles but doesn't render right
+  ("screen blank", "sprite invisible", "wrong colors", "freezes").
+- **[`../../MENTAL_MODEL.md`](../../MENTAL_MODEL.md)** — one-page
+  architecture overview: VRAM banks, palettes (DMG vs CGB), sprite
+  hardware, OAM DMA timing, joypad layout. Read this before your first
+  GB/GBC project.
+
+## Project templates
+
+Bootstrap a working game-loop skeleton with `createProject`:
+
+```js
+createProject({
+  platform: "gbc",
+  template: "tile_engine",   // or "hello_sprite", or "default"
+  name:     "mygame",
+  path:     "/abs/path",
+})
+```
+
+Templates ship in `examples/{gb,gbc}/templates/`:
+
+| Template | What you get |
+|---|---|
+| `default` | Minimal palette-cycle hello-world. Use when you're not sure what to build yet. |
+| `hello_sprite` | LCD init + 16-byte tile upload + 4-color OBJ palette + sprite slot 0 + d-pad movement. ~80 lines, tested end-to-end. |
+| `tile_engine` | 20×18 BG map render from a `room[]` array + collision + multi-room transitions via doors. ~200 lines. Covers the Adventure / Zelda-1 / Sokoban shape. |
+
+## SDCC 4.4.0 quirks
+
+**Read first: [`SDCC_GOTCHAS.md`](./SDCC_GOTCHAS.md).** Short doc —
+mostly covers C89 syntax requirements. The big "register allocator
+crash family" that motivated this whole document originally was
+diagnosed as an emscripten stack overflow on 2026-05-25; fixed at the
+build level. Patterns that used to require `unroll.h` workarounds
+compile cleanly now.
+
+`buildSource` runs a **pre-flight linter** that catches C89 violations
+(mid-block declarations, C99 inline for-loop counters) before SDCC's
+own misleading error messages. Hits come back as warnings in the
+`issues[]` array tagged `stage: "lint"`.
+
+Pass `lint: "strict"` to fail the build on any lint hit. Default is
+advisory.
+
+## Splitting into multiple `.c` files (optional)
+
+Not required for correctness anymore, but still useful for iteration
+speed: smaller TUs rebuild faster. Use `sourcesPaths` (or `sources` for
+inline text) when it helps:
+
+```js
+buildSource({
+  platform: "gbc",
+  language: "c",
+  sourcesPaths: {
+    "main.c":    "./src/main.c",      // game state, vblank loop
+    "render.c":  "./src/render.c",    // VRAM writes, sprite list
+    "objects.c": "./src/objects.c",   // game-object logic
+    "data.c":    "./src/data.c",      // const tables
+  },
+  outputPath: "./mygame.gbc",
+})
+```
+
+Each `.c` becomes its own SDCC translation unit. The linker glues
+them together; `extern` globals tie shared state across files.
+
+When a multi-TU build fails, the response includes `failedTU` (the
+file that died) and `compiledOK` (the TUs that compiled cleanly
+before the failure). That tells you exactly which file to bisect
+without grepping the log.
+
+## Stock GBDK alternative
+
+The bundled runtime is intentionally minimal (~10 helpers). If you
+need the full GBDK-2020 surface (sprites, tile sets, font, sound driver),
+write asm-level RGBDS code via `language: "asm"` or pull the runtime
+code you need into your project's `sources`.

package/src/platforms/gb/lib/c/SDCC_GOTCHAS.md

@@ -0,0 +1,189 @@
+# SDCC sm83 / z80 — known gotchas
+
+> **2026-05-25: The big one — `dbuf_append_str(NULL)` crashes — is FIXED.**
+>
+> What was reported across many sessions as "SDCC sm83 register
+> allocator crash on for-loops with function calls", patterns #37/#38/#39,
+> the entire #1..#10 family — none of that was an SDCC codegen bug.
+> The WASM build's default 64KB stack was overflowing past `__data_end`
+> into the static `sm83_regs[]` table, zeroing out the register-name
+> pointers, which then propagated to `aopGet → dbuf_append_str(NULL)`.
+>
+> Fix: `-s STACK_SIZE=8388608` (8 MB) in the emscripten link flags.
+> Now compiles for-loops, parallel array writes, function calls in
+> loops, nested ifs, multi-array indexed reads, etc. — every previously
+> documented "crash pattern" — without complaint.
+>
+> The `unroll.h` macros are still around if you find a case that needs
+> them, but you almost certainly don't.
+
+What's left in this doc:
+
+1. C89-only — SDCC's parser doesn't accept C99 (mid-block decls, etc.)
+2. Generic "if you find a new crash" workflow.
+
+## SDCC sm83 is C89
+
+SDCC's sm83 frontend is **C89 only**. None of these work:
+
+```c
+/* WRONG — C99 features SDCC rejects */
+for (int i = 0; i < 10; i++) { ... }    // inline-declared loop counter
+int x = 5;                              // mid-block declarations
+{ ... ; int y = ...; }                  // declarations after code
+
+struct foo p = (struct foo){ .x = 1 };  // compound literals
+struct foo p = { .x = 1, .y = 2 };      // designated initializers
+// single-line comments after non-comment code on same line
+```
+
+```c
+/* RIGHT — C89 form everything must use */
+int i;
+for (i = 0; i < 10; i++) { ... }        // declare i above
+
+{
+  int x;
+  int y;
+  x = 5;
+  /* ... code here ... */
+  y = something();                       /* declarations at TOP only */
+}
+
+struct foo p;                           /* declare, then assign */
+p.x = 1;
+p.y = 2;
+```
+
+**Misleading SDCC error message:** when you have a mid-block decl, SDCC
+reports the syntax error pointing at the line AFTER the offense:
+
+```
+/work/main.c:42: syntax error: token -> 'base' ; column 10
+```
+
+Line 42 looks fine. The real problem is **the FIRST declaration that
+follows a non-declaration statement** somewhere earlier in the block.
+Scan backwards from the reported line for code-then-decl mixing.
+
+The pre-flight linter (`src/toolchains/sdcc/preflight-lint.js`) catches
+mid-block decls with the correct file:line before SDCC runs.
+
+## Found a new crash?
+
+If you hit a build failure that isn't C89-related and isn't an obvious
+extern undefined / typo:
+
+1. Bisect by deleting code chunks (halve the file, repeat).
+2. Reduce to a minimal 4–10 line repro.
+3. Capture the exact SDCC error message + the .i (preprocessed) input.
+4. Open an issue with the repro at https://github.com/monteslu/romdev/issues
+   so we can investigate. **Don't paper over it with workarounds** — with the
+   stack-overflow fix in place, real codegen bugs are much rarer and
+   each one is worth chasing to root cause.
+
+## Writes to VRAM / OAM / I/O regs need `volatile` (or use the bundled helpers)
+
+SDCC's sm83 optimizer treats a write-only loop to an unanalyzable
+absolute address (a raw `(uint8_t*)0x8000` cast) as dead code and may
+elide the stores entirely. Pattern that bites:
+
+```c
+uint8_t *dst = (uint8_t *)0x8000;     // VRAM
+for (uint8_t i = 0; i < 16; i++) dst[i] = tile_data[i];
+// ↑ may compile to literally nothing. VRAM stays empty.
+```
+
+The bundled `memcpy_vram(dst, src, n)` in `gb_runtime.c` works because
+it walks the source/dest as plain `uint8_t *` parameters (which SDCC
+can't prove are dead). The bundled `gb_hardware.h` declares every
+hardware register as `volatile`-typed via `__sfr __at 0xFFNN`, so
+direct writes like `BGP = 0xE4;` are fine.
+
+If you need to write a custom VRAM block-copy:
+- **Use `memcpy_vram(dst, src, n)` from `gb_runtime.h`** (recommended).
+- **OR** cast the destination through `volatile`:
+  `volatile uint8_t *dst = (volatile uint8_t *)0x8000;` — the
+  `volatile` qualifier disables the dead-store optimization.
+- **OR** mark the writes as side-effecting another way (e.g. read
+  the value back). This is fragile.
+
+This is independent of the R26 OAM-alignment fix (`shadow_oam __at
+(0xC100)`) and the header CGB-flag fix (now applied automatically by
+`buildSource` / `runSource`, not a manual `patchGbHeader` step). All
+three are silent-failure bugs that look like "did my changes even
+land?" and need different fixes.
+
+## OAM DMA must run from HRAM (R55 fix — applies to ALL GB code, not just SDCC)
+
+This isn't an SDCC issue — it's a GB hardware rule that any bundled
+OAM DMA wrapper must respect:
+
+During the ~160 µs OAM DMA transfer, the CPU can ONLY fetch
+instructions from HRAM ($FF80-$FFFE). Reads from ROM / WRAM / VRAM
+return $FF on real hardware. $FF decodes as `rst $38` which CALLs
+$0038; gb_crt0.s vectors $0038 to `ret`, which pops the stack — but
+the stack just had the rst's return address pushed, so PC ends up
+PC+1 (one byte past the original fetch). Over a few hundred bytes
+of "fetching from a $FF bus" the misalignment lands as the operand
+of a multi-byte instruction and the CPU jumps into garbage. Classic
+symptoms: LCDC = $FF (every bit set — Window enabled, BG map base
+flipped), BG VRAM at $9800-$9BFF wiped to zeros, sprite glitches.
+
+The fix is the canonical GB idiom: install a tiny stub in HRAM at
+boot, then CALL the HRAM stub from any DMA-driving code. The stub
+fetches its own instructions from HRAM (allowed during DMA).
+
+The bundled `gb_runtime.c` does this via `oam_dma_init_hram()`,
+called automatically by `lcd_init_default()`. If you bypass
+`lcd_init_default` you MUST call `oam_dma_init_hram()` yourself
+before any `oam_dma_flush()` / `oam_dma_copy()`. Otherwise sprites
+will appear to work, then corrupt VRAM after a few hundred frames
+under load — diagnosis time ~3 hours per agent who hits this
+(round 27).
+
+If you write your own OAM DMA path, the same rule applies: the
+spin-loop bytes MUST be in HRAM. Don't spin in ROM. Don't spin in
+WRAM. ONLY HRAM.
+
+## gb_crt0.s zeros BSS correctly (R55 — bundled fix; only matters if you bring your own crt0)
+
+Pre-r55's `gsinit:` had a typo that zeroed `_INITIALIZED` (the
+runtime shadow of init-value statics) instead of `_DATA` (actual
+BSS). The copy loop right after overwrote `_INITIALIZED` with the
+`_INITIALIZER` ROM image anyway — making the zero a no-op. Net
+effect: every `static uint8_t flag;` in your code booted with
+whatever WRAM byte was there at power-on. Hard to spot because
+your initialized statics (`static uint8_t lives = 3;`) WORK
+correctly; only the uninitialized ones boot with garbage.
+
+The fixed crt0 zeros `s__DATA..s__DATA + l__DATA` (the actual BSS).
+If you bring your own crt0, model the gsinit on the bundled one —
+and at minimum add a test like:
+
+```c
+static uint8_t test_flag;  /* uninitialized — must be 0 at boot */
+void main(void) {
+  if (test_flag != 0) { /* boom — your crt0 doesn't zero BSS */ }
+}
+```
+
+## Multi-TU builds are still a good idea
+
+Independent of any compiler issues, splitting your project into
+multiple `.c` files via `sourcesPaths` helps with iteration speed
+(fewer lines for sdcc to re-parse on each rebuild) and makes the code
+easier to navigate. It's not a workaround anymore, just good hygiene.
+
+```js
+buildSource({
+  platform: "gbc",
+  language: "c",
+  sourcesPaths: {
+    "main.c":     "/path/to/main.c",
+    "render.c":   "/path/to/render.c",
+    "data.c":     "/path/to/data.c",
+    "objects.c":  "/path/to/objects.c",
+  },
+})
+```

package/src/platforms/gb/lib/c/gb_crt0.s

@@ -0,0 +1,163 @@
+;; Game Boy / Game Boy Color crt0 for SDCC.
+;;
+;; Replaces SDCC's stock sm83 crt0 (designed for a host-runtime that
+;; handles I/O via rst $08 — useless on a real cartridge). This one
+;; lays out a real cartridge image:
+;;
+;;   $0000-$0060  reset + interrupt vectors (default = ret/reti)
+;;   $0100-$0103  entry point (nop; jp init)
+;;   $0104-$014F  cartridge header window — host pipeline patches in
+;;                Nintendo logo + checksum after link
+;;   $0150+       _CODE segment (the build is configured with
+;;                -b _CODE=0x0150 so user code can't pack into the
+;;                header window)
+;;
+;; The host pipeline in src/toolchains/index.js (search "NINTENDO_LOGO")
+;; writes the canonical logo bytes + header checksums into the patched
+;; output binary.
+
+        .module gb_crt0
+        .globl  _main
+        .globl  l__INITIALIZER
+        .globl  s__INITIALIZER
+        .globl  s__INITIALIZED
+        .globl  l__INITIALIZED
+        .globl  s__DATA
+        .globl  l__DATA
+        .globl  init
+
+;; ─── Reset vectors at $0000-$0060 ─────────────────────────────────
+        .area _HEADER0 (ABS)
+        .org    0x0000
+        ret
+
+        .area _HEADER1 (ABS)
+        .org    0x0008
+        ret
+
+        .area _HEADER2 (ABS)
+        .org    0x0010
+        ret
+
+        .area _HEADER3 (ABS)
+        .org    0x0018
+        ret
+
+        .area _HEADER4 (ABS)
+        .org    0x0020
+        ret
+
+        .area _HEADER5 (ABS)
+        .org    0x0028
+        ret
+
+        .area _HEADER6 (ABS)
+        .org    0x0030
+        ret
+
+        .area _HEADER7 (ABS)
+        .org    0x0038
+        ret
+
+;; ─── Interrupt vectors at $0040-$0060 (default = return) ───────────
+        .area _HEADER8 (ABS)
+        .org    0x0040            ; vblank
+        reti
+
+        .area _HEADER9 (ABS)
+        .org    0x0048            ; lcd stat
+        reti
+
+        .area _HEADERa (ABS)
+        .org    0x0050            ; timer
+        reti
+
+        .area _HEADERb (ABS)
+        .org    0x0058            ; serial
+        reti
+
+        .area _HEADERc (ABS)
+        .org    0x0060            ; joypad
+        reti
+
+;; ─── Entry point at $0100: jump to init ───────────────────────────
+        .area _HEADERd (ABS)
+        .org    0x0100
+        nop
+        jp      init
+
+;; ─── Header bytes at $0104-$014F — host pipeline fills these ──────
+        .area _HEADERe (ABS)
+        .org    0x0104
+        ;; 76 bytes total: Nintendo logo (48) + title (16) + flags+checksums (12)
+        .ds     0x4C
+
+;; ─── init: real boot code, lives in _CODE starting at $0150 ────────
+        .area   _CODE
+init::
+        di
+        ld      sp, #0xE000             ; top of WRAM
+        call    ___sdcc_external_startup
+        or      a, a
+        call    Z, gsinit
+        call    _main
+1$:
+        halt
+        jr      1$
+
+        .area   _HOME
+        .area   _INITIALIZER
+        .area   _GSINIT
+        .area   _GSFINAL
+
+        .area   _DATA
+        .area   _INITIALIZED
+        .area   _BSEG
+        .area   _BSS
+        .area   _HEAP
+
+        .area   _GSINIT
+gsinit::
+        ;; ── Zero the BSS segment (`_DATA`). ──────────────────────────
+        ;; Round 27 fix: pre-r55 this loop targeted `s__INITIALIZED` for
+        ;; `l__INITIALIZER` bytes — but `_INITIALIZED` is the runtime
+        ;; shadow of the `_INITIALIZER` ROM image and gets overwritten
+        ;; by the copy loop below anyway, so it was a no-op. The actual
+        ;; BSS at `s__DATA..s__DATA+l__DATA` (where every uninitialised
+        ;; `static` global in your C lands) was left as power-on WRAM
+        ;; garbage. Symptom: `static coin_t coins[4]; ... if (coins[1].active)`
+        ;; would spuriously fire at boot because `coins[1].active` was
+        ;; some random byte from gambatte's WRAM init pattern.
+        ld      hl, #s__DATA
+        ld      bc, #l__DATA + 0x0101         ; +1 per byte, +256 per page
+        xor     a, a
+        jr      gsinit_data_check
+gsinit_data_loop:
+        ld      (hl+), a
+gsinit_data_check:
+        dec     c
+        jr      NZ, gsinit_data_loop
+        dec     b
+        jr      NZ, gsinit_data_loop
+
+        ;; ── Copy `_INITIALIZER` (ROM) → `_INITIALIZED` (RAM). ────────
+        ;; This is the value-initialised-statics path: `static uint8_t
+        ;; lives = 3;` lives in _INITIALIZED at runtime; its initial
+        ;; value (the `3`) sits in _INITIALIZER in ROM.
+        ld      de, #s__INITIALIZED
+        ld      hl, #s__INITIALIZER
+        ld      bc, #l__INITIALIZER + 0x0101
+        jr      gsinit_init_check
+gsinit_init_loop:
+        ld      a, (hl+)
+        ld      (de), a
+        inc     de
+gsinit_init_check:
+        dec     c
+        jr      NZ, gsinit_init_loop
+        dec     b
+        jr      NZ, gsinit_init_loop
+        ret
+
+        .area   _GSFINAL
+        ret

package/src/platforms/gb/lib/c/gb_hardware.h

@@ -0,0 +1,113 @@
+/* ── Game Boy hardware register names (SDCC sm83 port) ──────────────
+ * Standard `__sfr __at(addr)` declarations for the GB / GBC I/O space.
+ * Layer-1 GBDK substitute: gives you LCDC / BGP / OBP / scroll / sound
+ * regs without pulling in the full GBDK runtime.
+ *
+ * Use:
+ *   #include "gb_hardware.h"
+ *   void main(void) {
+ *     LCDC = 0x91;             // turn LCD on, BG on, OBJ off
+ *     BGP  = 0xE4;             // default DMG palette
+ *     while (1) { }
+ *   }
+ *
+ * SDCC's __sfr __at syntax binds a 1-byte memory-mapped register to a
+ * scope-local volatile. Reads / writes compile to inline ld a,(addr) /
+ * ldh (n),a. No runtime cost.
+ */
+#ifndef GB_HARDWARE_H
+#define GB_HARDWARE_H
+
+/* ── LCD ──────────────────────────────────────────────────────────── */
+/* SDCC sm83 __sfr __at takes the full 16-bit address, not the $FF00-relative
+ * I/O port number. ldh-vs-ld is chosen by the compiler from the address.   */
+__sfr __at 0xFF40 LCDC;        /* LCD control */
+__sfr __at 0xFF41 STAT;        /* LCD status */
+__sfr __at 0xFF42 SCY;         /* scroll Y */
+__sfr __at 0xFF43 SCX;         /* scroll X */
+__sfr __at 0xFF44 LY;          /* current scanline */
+__sfr __at 0xFF45 LYC;         /* scanline compare */
+__sfr __at 0xFF46 DMA;         /* OAM DMA */
+__sfr __at 0xFF47 BGP;         /* BG palette (DMG) */
+__sfr __at 0xFF48 OBP0;        /* OBJ palette 0 (DMG) */
+__sfr __at 0xFF49 OBP1;        /* OBJ palette 1 (DMG) */
+__sfr __at 0xFF4A WY;          /* window Y */
+__sfr __at 0xFF4B WX;          /* window X (-7) */
+
+/* LCDC bits */
+#define LCDC_LCD_ON          0x80
+#define LCDC_WINDOW_MAP_HI   0x40    /* 0 = $9800, 1 = $9C00 */
+#define LCDC_WINDOW_ON       0x20
+#define LCDC_TILE_DATA_LO    0x10    /* 0 = $9000 signed, 1 = $8000 unsigned */
+#define LCDC_BG_MAP_HI       0x08
+#define LCDC_OBJ_8x16        0x04
+#define LCDC_OBJ_ON          0x02
+#define LCDC_BG_ON           0x01
+
+/* ── Sound (NR10-NR52) ────────────────────────────────────────────── */
+__sfr __at 0xFF10 NR10;
+__sfr __at 0xFF11 NR11;
+__sfr __at 0xFF12 NR12;
+__sfr __at 0xFF13 NR13;
+__sfr __at 0xFF14 NR14;
+__sfr __at 0xFF16 NR21;
+__sfr __at 0xFF17 NR22;
+__sfr __at 0xFF18 NR23;
+__sfr __at 0xFF19 NR24;
+__sfr __at 0xFF1A NR30;
+__sfr __at 0xFF1B NR31;
+__sfr __at 0xFF1C NR32;
+__sfr __at 0xFF1D NR33;
+__sfr __at 0xFF1E NR34;
+__sfr __at 0xFF20 NR41;
+__sfr __at 0xFF21 NR42;
+__sfr __at 0xFF22 NR43;
+__sfr __at 0xFF23 NR44;
+__sfr __at 0xFF24 NR50;        /* master volume */
+__sfr __at 0xFF25 NR51;        /* channel routing */
+__sfr __at 0xFF26 NR52;        /* sound on/off */
+
+/* ── Joypad + serial + IE + IF ────────────────────────────────────── */
+__sfr __at 0xFF00 JOYP;        /* joypad */
+__sfr __at 0xFF01 SB;          /* serial data */
+__sfr __at 0xFF02 SC;          /* serial control */
+__sfr __at 0xFF04 DIV;
+__sfr __at 0xFF05 TIMA;
+__sfr __at 0xFF06 TMA;
+__sfr __at 0xFF07 TAC;
+__sfr __at 0xFF0F IF_REG;      /* interrupt flag — IF is reserved */
+
+/* IE is at $FFFF — not addressable via __sfr __at (that's the 8-bit-port
+ * space at $FF00-$FF7F). Read/write via:
+ *   *(volatile unsigned char *)0xFFFF = 0x01;
+ */
+#define IE_REG  (*(volatile unsigned char *)0xFFFF)
+#define IE_VBLANK   0x01
+#define IE_LCDSTAT  0x02
+#define IE_TIMER    0x04
+#define IE_SERIAL   0x08
+#define IE_JOYPAD   0x10
+
+/* ── GBC extras (only meaningful with CGB compatibility byte $0143=$80/C0) */
+__sfr __at 0xFF4D KEY1;        /* speed switch */
+__sfr __at 0xFF4F VBK;         /* VRAM bank */
+__sfr __at 0xFF51 HDMA1;
+__sfr __at 0xFF52 HDMA2;
+__sfr __at 0xFF53 HDMA3;
+__sfr __at 0xFF54 HDMA4;
+__sfr __at 0xFF55 HDMA5;
+__sfr __at 0xFF68 BCPS;        /* BG palette spec */
+__sfr __at 0xFF69 BCPD;        /* BG palette data */
+__sfr __at 0xFF6A OCPS;        /* OBJ palette spec */
+__sfr __at 0xFF6B OCPD;        /* OBJ palette data */
+__sfr __at 0xFF70 SVBK;        /* WRAM bank */
+
+/* ── Memory map bases ─────────────────────────────────────────────── */
+#define VRAM_BASE  ((unsigned char *)0x8000)   /* tile data + maps */
+#define BG_MAP_0   ((unsigned char *)0x9800)   /* 32×32 = 1024 bytes */
+#define BG_MAP_1   ((unsigned char *)0x9C00)
+#define OAM_BASE   ((unsigned char *)0xFE00)   /* 40 sprites × 4 bytes */
+#define WRAM_BASE  ((unsigned char *)0xC000)
+#define HRAM_BASE  ((unsigned char *)0xFF80)
+
+#endif /* GB_HARDWARE_H */