romdev-mcp 0.1.1

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

@@ -0,0 +1,157 @@
+# Genesis / Mega Drive — quickstart
+
+The compressed version of "everything I had to learn the hard way
+building a Genesis ROM with romdev."
+
+## Snippets shipped in this directory
+
+| File | Purpose |
+|---|---|
+| `header.s` | 256-byte ROM header + interrupt vector table. **Required** for every Genesis ROM — without it the cart is unbootable. |
+| `vdp_init.s` | Standard 320×224 VDP register init (plane bases, scroll, sprite table, etc.) — call from `_reset`. |
+| `wram.s` | How to declare WRAM variables WITHOUT exploding your ROM size to 16 MB. |
+| `pad_read.s` | 3-button controller read with edge detection (held / pressed / released). |
+| `vblank_wait.s` | Busy-wait pattern for syncing to VBlank without interrupts. |
+| `nmi_safe.s` | Full VINT (vblank interrupt) handler with register preservation. |
+| `sprite_table.s` | Soft-OAM staging + DMA upload pattern. |
+| `z80_bootstrap.s` | Z80 sound CPU bring-up + bus protocol. |
+
+Fetch any with `getStarterSnippet({platform:"genesis", name:"<file>"})`.
+Pull them all at once with `getAllStarterSnippets({platform:"genesis"})`.
+
+## The five gotchas that cost the most time
+
+### 1. vasm Motorola syntax: NO SPACES after commas
+
+```asm
+move.w #$2700, sr       ; ERROR: "number or identifier expected"
+move.w #$2700,sr        ; OK
+```
+
+vasm's Motorola syntax tokenizer treats the space as terminating the
+operand. This applies to ALL multi-operand instructions: `move`, `add`,
+`movem`, `lea`, etc. The starter snippets in this directory are all
+no-space; don't add spaces when editing them even if your editor
+auto-formats.
+
+### 2. WRAM variables: use `equ`, not `org`
+
+```asm
+org $00FF0000           ; BAD: pads ROM to 16 MB
+my_var:  dc.l 0         ;      and the var is not actually stored there
+
+my_var equ $00FF0000    ; GOOD: pure compile-time constant
+                        ;       CPU writes here at runtime; no ROM space used
+```
+
+The "your ROM is 16 MB and will not fit on a cart" surprise is one of
+the top three Genesis-newbie mistakes. See `wram.s` for the full pattern.
+
+### 3. Header byte counts: notes field is 32 bytes, NOT 40
+
+Several online references claim the "notes" field at $1D0 is 40 bytes.
+It is 32. ($1D0-$1EF, with region at $1F0-$1FF.) If you size it as
+40, region overlaps your code section at $200 and vasm yells
+"sections must not overlap." `header.s` has the authoritative layout
+in a prominent comment at the top.
+
+### 4. VDP control reads: bit 3 of LOW byte, address $C00005
+
+The VDP status register is a 16-bit big-endian word at $C00004. The
+"vblank in progress" flag is bit 3 of the LOW byte — accessed at
+$C00005, not $C00004. Lots of old Genesis tutorials test the wrong
+address and busy-wait forever. `vblank_wait.s` gets this right.
+
+### 5. m68k can't do memory-to-memory arithmetic
+
+```asm
+add.w lines_counter, total_lines    ; ERROR: "instruction not supported"
+                                    ; m68k arithmetic needs a register
+move.w lines_counter, d0
+add.w d0, total_lines               ; OK
+```
+
+The 68000's instruction set requires at least one operand of most
+arithmetic ops to be a register (D0-D7 or A0-A7). Coming from cc65 or
+asar (where memory-to-memory is sometimes legal) this catches you.
+The "instruction not supported on selected architecture" error from
+vasm is technically correct but cryptic — it means "this addressing-
+mode combination is invalid for the 68000," not "your CPU is too old."
+
+## Build + iterate workflow
+
+The fastest loop (works for most Genesis dev):
+
+```js
+runSource({
+  platform: "genesis",
+  source: /* your .s contents */,
+  frames: 60,                    // step 60 frames after load
+  holdInputs: [{ start: true }], // optional: hold a button
+})
+```
+
+Returns build status + final screenshot in one call (~500 ms cold,
+faster after the core is warm).
+
+For multi-file projects use the `sources` map:
+
+```js
+runSource({
+  platform: "genesis",
+  sources: { "main.s": mainText, "music.s": musicText },
+  frames: 60,
+})
+```
+
+For projects with binary assets (tiles, palettes, music data):
+
+```js
+buildSource({
+  platform: "genesis",
+  sourcePath: "/abs/path/main.s",
+  binaryIncludePaths: {
+    "tiles.bin":   "/abs/path/assets/tiles.bin",
+    "palette.bin": "/abs/path/assets/palette.bin",
+  },
+  outputPath: "out.gen",
+})
+```
+
+Source can then `incbin "tiles.bin"` directly.
+
+## Debugging tools available
+
+Genesis has full debugging parity with SNES — see `listCategories()`
+then `loadCategory({category:"debug"})`:
+
+| Tool | What it gives you |
+|---|---|
+| `inspectSprites({platform:"genesis"})` | 80-sprite linked-list decoded to {slot, x, y, tile, palette, priority, flipH, flipV, size, visible} |
+| `inspectPalette({platform:"genesis"})` | All 64 CRAM colors decoded to {r, g, b} + a PNG swatch sheet |
+| `getCPUState({platform:"genesis", cpu:"main"})` | 68K state: D0-D7, A0-A7, PC, flags NZVCXST, intMask |
+| `getPsgState({platform:"genesis"})` | PSG channels: 3 tone + 1 noise |
+| `getYm2612State({platform:"genesis"})` | YM2612 raw snapshot (decoder is limited; raw blob diff-able) |
+| `readMemory({region:"genesis_cram"})` | 128 B CRAM raw |
+| `readMemory({region:"genesis_vdp_regs"})` | 32 VDP registers |
+| `readMemory({region:"genesis_z80_ram"})` | 8 KB Z80 sound CPU RAM |
+| `dumpState({path})` | Full savestate blob for forensic inspection |
+
+Pair `screenshot({overlayBoxes:true})` with `inspectSprites` for
+"is the GPU rendering sprites where I think they are" visual debugging.
+
+## ROM file extension
+
+Default convention in this MCP: `.gen`. Genesis frontends
+(Batocera, ES-DE, RetroBat, RetroPie, ROCKNIX) all accept `.gen`,
+`.md`, `.bin`, `.smd`. `.gen` is unambiguous in 2026: `.md` collides
+with markdown, `.bin` is generic, `.smd` implies a header format
+we do not emit.
+
+## Open question: live Z80 driver state
+
+The YM2612 + Z80 sound CPU state is not currently as deeply
+introspectable as the SNES SPC700 + DSP — YM2612 in particular
+requires walking gpgx's internal struct which is version-fragile.
+If you hit a sound-debugging wall here, open an issue at
+https://github.com/monteslu/romdev/issues.

package/src/platforms/genesis/lib/c/genesis.ld

@@ -0,0 +1,44 @@
+/* genesis.ld — minimum-viable linker script for Sega Genesis ROMs.
+ *
+ * Memory layout:
+ *   rom  : $00000000 - $003FFFFF  (4 MB max cart size)
+ *   ram  : $00FF0000 - $00FFFFFF  (64 KB main work RAM)
+ *
+ * Section ordering: vectors at $0 (mandatory — 68000 reads SSP + reset
+ * vector from $000000/$000004), then ROM header at $100, then code,
+ * then read-only data. .bss + .data live in ram.
+ *
+ * Real Genesis projects use a more elaborate script (SGDK ships ~200
+ * lines covering multi-bank, .data init copy, etc.). This is enough
+ * for "bare main()" through the gcc pipeline.
+ */
+OUTPUT_FORMAT("elf32-m68k")
+OUTPUT_ARCH(m68k)
+ENTRY(_start)
+
+MEMORY {
+    rom (rx) : ORIGIN = 0x00000000, LENGTH = 4M
+    ram (rwx): ORIGIN = 0x00FF0000, LENGTH = 64K
+}
+
+SECTIONS {
+    .text 0x00000000 : {
+        KEEP(*(.text._vectors))
+        *(.text._rom_header)
+        *(.text._start)
+        *(.text*)
+        *(.rodata*)
+        . = ALIGN(2);
+    } > rom
+
+    .data : {
+        *(.data*)
+        . = ALIGN(2);
+    } > rom
+
+    .bss : {
+        *(.bss*)
+        *(COMMON)
+        . = ALIGN(2);
+    } > ram
+}

package/src/platforms/genesis/lib/c/genesis_sfx.c

@@ -0,0 +1,51 @@
+/* ── genesis_sfx.c — minimal Genesis PSG sound-effects wrapper ──────
+ *
+ * SGDK's PSG_* helpers do the byte-twiddling. We add:
+ *   - 4-channel per-channel "frames-left" countdown
+ *   - sfx_update() to tick it each frame and silence on zero
+ */
+
+#include "genesis_sfx.h"
+#include <psg.h>
+
+/* Frames remaining before each channel auto-silences. */
+static u8 sfx_remaining[4];
+
+void sfx_init(void) {
+    PSG_reset();
+    for (u8 i = 0; i < 4; i++) {
+        sfx_remaining[i] = 0;
+        PSG_setEnvelope(i, PSG_ENVELOPE_MIN);  /* PSG_ENVELOPE_MIN = 15 = silent */
+    }
+}
+
+void sfx_tone(u8 channel, u16 freq, u8 length_frames) {
+    if (channel > 2) return;
+    PSG_setFrequency(channel, freq);
+    PSG_setEnvelope(channel, PSG_ENVELOPE_MAX);   /* MAX = 0 = loudest */
+    sfx_remaining[channel] = length_frames;
+}
+
+void sfx_noise(u8 length_frames) {
+    PSG_setNoise(PSG_NOISE_TYPE_WHITE, PSG_NOISE_FREQ_CLOCK4);
+    PSG_setEnvelope(3, PSG_ENVELOPE_MAX);
+    sfx_remaining[3] = length_frames;
+}
+
+void sfx_update(void) {
+    for (u8 i = 0; i < 4; i++) {
+        if (sfx_remaining[i] > 0) {
+            sfx_remaining[i]--;
+            if (sfx_remaining[i] == 0) {
+                PSG_setEnvelope(i, PSG_ENVELOPE_MIN);
+            }
+        }
+    }
+}
+
+void sfx_off(void) {
+    for (u8 i = 0; i < 4; i++) {
+        PSG_setEnvelope(i, PSG_ENVELOPE_MIN);
+        sfx_remaining[i] = 0;
+    }
+}

package/src/platforms/genesis/lib/c/genesis_sfx.h

@@ -0,0 +1,49 @@
+/* ── genesis_sfx.h — minimal Genesis PSG sound-effects wrapper ──────
+ *
+ * Thin wrapper around SGDK's PSG API (SN76489) to match the NES/GB/GBA
+ * scaffold sound shape — sfx_init + sfx_tone + sfx_noise + sfx_update.
+ *
+ * Channel layout (PSG = 4 channels):
+ *   0, 1, 2 = square-wave tones (use sfx_tone)
+ *   3       = noise              (use sfx_noise)
+ *
+ * The PSG has NO automatic envelope. Real games drive envelopes by
+ * writing the envelope register each frame. This wrapper auto-silences
+ * a channel after `length_frames` frames — but you MUST call
+ * `sfx_update()` once per frame in your main loop for that to work.
+ * Forget it and notes ring forever.
+ *
+ * The YM2612 FM synth (the other half of Genesis audio) is NOT wrapped.
+ * For FM music + samples, use SGDK's XGM2 driver with a .xgm asset.
+ */
+
+#ifndef GENESIS_SFX_H
+#define GENESIS_SFX_H
+
+#include <types.h>
+
+/* Call once near the start of main() before any sfx_*. */
+void sfx_init(void);
+
+/* Play a square-wave tone.
+ *   channel: 0, 1, or 2 (3 is noise — use sfx_noise instead)
+ *   freq:    PSG 10-bit tone divider. Hz = 3579545 / (32 * freq).
+ *            Try 200 = high pew, 400 = mid blip, 800 = low thump.
+ *   length_frames: 1..127. Auto-silences after this many frames
+ *                  IF sfx_update() is called once per frame.
+ */
+void sfx_tone(u8 channel, u16 freq, u8 length_frames);
+
+/* Play a noise burst on channel 3.
+ *   length_frames: 1..127 (same auto-silence rule as sfx_tone). */
+void sfx_noise(u8 length_frames);
+
+/* Call once per frame (right before or after SYS_doVBlankProcess) to
+ * decrement the auto-silence countdown. Without this, notes never
+ * stop ringing. */
+void sfx_update(void);
+
+/* Power down all PSG channels immediately. */
+void sfx_off(void);
+
+#endif

package/src/platforms/genesis/lib/c/sega.s

@@ -0,0 +1,71 @@
+| ── sega.s — minimum Genesis crt0 / reset handler / ROM header ──
+|
+| Original code. Provides:
+|   - 256-byte vector table at $000000 (SSP + reset, plus 254 unused
+|     vectors mirroring _start so an errant jump is still recoverable)
+|   - Genesis ROM header at $000100..$0001FF (system name, copyright,
+|     ROM size, region flags, etc. The TMSS-bypass write at $A14000
+|     happens IN _start, not here)
+|   - _start handler that initializes SSP, calls main(), parks the CPU
+|
+| The header values below match SGDK/marsdev conventions. Real projects
+| customize ID strings + region flags. ROM size word (offsets $1A4..$1A7)
+| is patched by post-link tooling (gen_postlink or marsdev's makemd) —
+| we leave a placeholder.
+
+	.text
+	.globl	_vectors
+	.globl	_start
+
+| ──────────────────────────────────────────────────────────────────
+| Vector table at $000000 — 256 bytes, all 32-bit pointers.
+| ──────────────────────────────────────────────────────────────────
+_vectors:
+	.long	0x00FFE000        | initial SSP (stack at top of WRAM)
+	.long	_start            | reset PC
+	| Vectors 2..63 — 62 more 32-bit vectors fill out the 256-byte
+	| ($100) vector table. Point them all at _start so a bus error
+	| restarts the cart rather than locking up. Real projects
+	| install vblank/hblank/level-N interrupt handlers here.
+	.rept	62
+	.long	_start
+	.endr
+
+| ──────────────────────────────────────────────────────────────────
+| ROM header at $000100..$0001FF (256 bytes total).
+| ──────────────────────────────────────────────────────────────────
+_rom_header:
+	.ascii	"SEGA MEGA DRIVE "        | $100..$10F  system name
+	.ascii	"(C)ROMDEV 2026.MAY"      | $110..$121  copyright
+	.byte	0,0                       | $122..$123  pad
+	.ascii	"ROM-DEV-MCP C BUILD                             "  | $124..$153  domestic title (48 chars)
+	.ascii	"ROM-DEV-MCP C BUILD                             "  | $154..$183  overseas title (48 chars)
+	.ascii	"GM ROMDEV-01-00"         | $184..$192  serial number (game id + revision)
+	.byte	0,0                       | $193..$194  checksum (patched later)
+	.ascii	"J               "        | $195..$1A4  device support (joypad)
+	.long	0x00000000                | $1A4..$1A7  ROM start
+	.long	0x00100000                | $1A8..$1AB  ROM end  (1 MB; patcher fixes)
+	.long	0x00FF0000                | $1AC..$1AF  RAM start
+	.long	0x00FFFFFF                | $1B0..$1B3  RAM end
+	.ascii	"            "            | $1B4..$1BF  SRAM info (none)
+	.space	48, 0x20                  | $1C0..$1EF  modem info (none) — 48 spaces
+	.ascii	"JUE             "        | $1F0..$1FF  region (Japan/US/Europe)
+
+| ──────────────────────────────────────────────────────────────────
+| Reset handler — runs first when the console powers on.
+| ──────────────────────────────────────────────────────────────────
+_start:
+	move.w	#0x2700, %sr              | mask all interrupts
+	move.l	#0x00FFE000, %sp          | init stack at top of WRAM
+
+	| TMSS bypass: write "SEGA" to $A14000 to enable VDP access on
+	| later console revisions. Older consoles ignore the write.
+	move.l	#0x53454741, 0x00A14000   | "SEGA" — TMSS lock release
+
+	| Set up .bss zeroing + .data copy here in a real runtime. For
+	| the minimum-viable path we skip both — user code lives entirely
+	| in .text + uses no .bss/.data.
+
+	jsr	main                      | call C entry point
+1:
+	bra.s	1b                        | spin forever if main returns

package/src/platforms/genesis/lib/header.s

@@ -0,0 +1,96 @@
+; Genesis / Mega Drive — cartridge header.
+;
+; The 68000 reads the reset vector from $0000-$0007 (initial SSP at $00,
+; reset PC at $04). Immediately after is the 256-byte ROM header at $100
+; — every Genesis ROM needs this in a specific format or the BIOS will
+; refuse to boot the cart (some emulators are forgiving; real hardware
+; isn't).
+;
+; Fields below are positional and must be the exact byte counts shown.
+; vasm68k pads strings to their declared length with spaces if you use
+; .ascii "..." inside a fixed area, but it's safer to space-pad manually
+; to avoid subtle off-by-ones.
+
+  org $00000000
+
+; ---- 68K interrupt + exception vectors ($000-$0FF) -----------------------
+vector_table:
+  dc.l   $00FFE000          ; initial SSP — top of work RAM
+  dc.l   _reset             ; reset PC — your entry point
+  ; Vectors 2-63 (252 bytes) typically point to an exception handler.
+  ; The lazy version: all default to _reset; real games install real
+  ; handlers for bus error / address error / illegal instruction.
+  rept 62
+  dc.l   _exception_handler
+  endr
+
+; ---- ROM header ($100-$1FF) ----------------------------------------------
+;
+; The header is EXACTLY 256 bytes ($100-$1FF). Some online references
+; claim the "notes" field is 40 bytes (which would push region past
+; $1FF and overlap _reset at $200) — that's a transcription error.
+; Authoritative layout (verified against snes9x's snes9x-libretro
+; sister project genesis_plus_gx and Sega's original SDK docs):
+;
+;   $100-$10F  system name (16)
+;   $110-$11F  copyright   (16)
+;   $120-$14F  domestic title (48)
+;   $150-$17F  overseas title (48)
+;   $180-$18D  serial number  (14)
+;   $18E-$18F  checksum    (2)
+;   $190-$19F  device support (16)
+;   $1A0-$1A3  ROM start (4)
+;   $1A4-$1A7  ROM end   (4)
+;   $1A8-$1AB  RAM start (4)
+;   $1AC-$1AF  RAM end   (4)
+;   $1B0-$1BB  SRAM tag  (12)
+;   $1BC-$1BF  SRAM start (4)
+;   $1C0-$1C3  SRAM end   (4)
+;   $1C4-$1CF  modem info (12)
+;   $1D0-$1EF  notes      (32)    ← NOT 40
+;   $1F0-$1FF  region     (16)
+;
+; A label at _header_end (= $200) below would catch any miscount via
+; vasm's section-overlap detection (gives a more readable error than
+; "instruction at $1F8 collides with code at $200").
+  org $00000100
+  dc.b "SEGA MEGA DRIVE "                          ; $100 system name (16)
+  dc.b "(C)YOU 2026.JAN "                          ; $110 copyright (16)
+  dc.b "MY GAME                                         " ; $120 domestic title (48)
+  dc.b "MY GAME                                         " ; $150 overseas title (48)
+  dc.b "GM 00000000-00"                            ; $180 serial number (14)
+  dc.w $0000                                       ; $18E checksum — leave 0 for emulator dev
+  dc.b "J               "                          ; $190 device support: J=joypad (16)
+  dc.l $00000000                                   ; $1A0 ROM start address
+  dc.l ROM_END-1                                   ; $1A4 ROM end address (set by build)
+  dc.l $00FF0000                                   ; $1A8 RAM start
+  dc.l $00FFFFFF                                   ; $1AC RAM end
+  dc.b "            "                              ; $1B0 SRAM tag — 12 spaces if no SRAM
+  dc.l $00000000                                   ; $1BC SRAM start
+  dc.l $00000000                                   ; $1C0 SRAM end
+  dc.b "            "                              ; $1C4 modem info — 12 spaces ($1C4-$1CF)
+  dc.b "                                "          ; $1D0 notes  — 32 spaces ($1D0-$1EF) ** NOT 40 **
+  dc.b "JUE             "                          ; $1F0 region — 16 chars ($1F0-$1FF): J=Japan U=US E=EU
+
+  org $00000200
+_reset:
+  ; Your initialization code goes here.
+  ; Typical first steps:
+  ;   - Disable interrupts: move.w #$2700, sr
+  ;   - Init VDP (see vdp_init.s)
+  ;   - Init Z80 (see z80_bootstrap.s)
+  ;   - Build sprite table in WRAM
+  ;   - Enable VBlank, drop to main loop
+  move.w #$2700,sr           ; mask all interrupts during init
+  ; ... your init here ...
+.halt:
+  bra.s .halt
+
+_exception_handler:
+  ; In real games this would dump CPU state for diagnostics. For
+  ; debugging, having ANY exception handler beats the default "garbage
+  ; PC" experience; for production, install per-vector handlers that
+  ; reset the system or display an error.
+  rte
+
+ROM_END:

package/src/platforms/genesis/lib/nmi_safe.s

@@ -0,0 +1,79 @@
+; Genesis 68000 — safe VBlank interrupt handler skeleton.
+;
+; The 68K has 7 interrupt levels; the VDP fires:
+;   level 4 = HINT (horizontal blank — fires once per N scanlines, per VDP reg $0A)
+;   level 6 = VINT (vertical blank — fires once per frame)
+; The CPU's SR bits 8-10 hold the interrupt mask. While mask >= the
+; interrupt's level, the interrupt is held off. Most game init code sets
+; mask to 7 ($2700 in SR) to block everything, then drops to 1 or 0
+; once VBlank is wanted.
+;
+; Critical gotchas this skeleton handles:
+;
+; 1. **The vector table at $00-$0FF points at handlers.** vasm68k will
+;    happily build a ROM with random garbage at vector $78 (VINT vector)
+;    if you forget; the CPU will then jump to garbage on the first VBlank.
+;    See header.s for the vector table.
+;
+; 2. **You must save registers.** The 68K interrupt doesn't auto-save
+;    D0-D7/A0-A6 — only PC + SR. If your handler touches D0 without
+;    saving it, main code's D0 gets clobbered.
+;
+; 3. **VDP DMA during active display is unsafe.** The window of opportunity
+;    is during VBlank or HBlank — outside those, DMAing causes visible
+;    artifacts (snow on the screen as the VDP's own access is starved).
+;    The VINT handler is the safe place to do bulk VRAM transfers.
+;
+; 4. **Read VDP status to clear the interrupt.** Reading $C00004 (control
+;    port) returns the VDP status word AND acknowledges the interrupt.
+;    Without this read, the next VINT will fire immediately on return.
+;
+; 5. **Set a vblank_ready flag.** Main loop should test this flag rather
+;    than poll the VDP status directly — polling races with the VINT
+;    and you'll miss frames.
+
+VDP_CTRL = $C00004
+
+vint_handler:
+  ; ---- save full register state ----
+  movem.l d0-d7/a0-a6,-(sp)
+
+  ; ---- ack the interrupt by reading VDP status ----
+  move.w  VDP_CTRL,d0
+
+  ; ---- per-frame VBlank work goes here ----
+  ; common: DMA sprite table, palette updates, sound driver tick.
+  ; jsr     dma_sprite_table
+  ; jsr     update_palette_if_changed
+  ; jsr     sound_driver_tick
+
+  ; ---- set vblank_ready flag for main loop ----
+  st      vblank_ready          ; sets to $FF (any nonzero)
+
+  ; ---- restore registers + return ----
+  movem.l (sp)+,d0-d7/a0-a6
+  rte
+
+hint_handler:
+  ; HINT skeleton — typically used for raster effects (per-scanline
+  ; scroll change, palette swap, sprite multiplexing). Keep it FAST:
+  ; you have ~488 CPU cycles between HINTs at 320x224, less if HINT
+  ; counter is low.
+  movem.l d0/a0,-(sp)
+  move.w  VDP_CTRL,d0          ; ack
+  ; ... your per-scanline work ...
+  movem.l (sp)+,d0/a0
+  rte
+
+; ---- main loop pattern ----
+;   wait_vblank:
+;     tst.b   vblank_ready
+;     beq.s   wait_vblank
+;     clr.b   vblank_ready
+;     ; ... per-frame game logic ...
+;     bra.s   wait_vblank
+;
+; ---- BSS reservation ----
+;   .bss
+;   .align 2
+; vblank_ready: ds.b 1

package/src/platforms/genesis/lib/pad_read.s

@@ -0,0 +1,104 @@
+; Genesis — reading the 3-button controller with edge detection.
+;
+; Genesis controllers connect via TWO I/O ports: $A10003 (port 1) and
+; $A10005 (port 2). Each is a single byte, but the BITS you read depend
+; on the state of the TH select line (bit 6 of the corresponding control
+; register at $A10009 / $A1000B).
+;
+; **3-button pad layout, by TH state:**
+;
+;   TH=1 reads (set bit 6 of control reg high, then read data):
+;     bit 0: Up        bit 4: B
+;     bit 1: Down      bit 5: C
+;     bit 2: Left      bits 6,7: unused
+;     bit 3: Right
+;
+;   TH=0 reads:
+;     bit 0: Up        bit 4: A
+;     bit 1: Down      bit 5: Start
+;     bits 2,3: 0      bits 6,7: unused
+;
+; All bits are ACTIVE-LOW (pressed = 0). Most code inverts to make 1 =
+; pressed for sanity.
+;
+; **6-button pad** uses extra TH transitions to expose XYZ + Mode. Not
+; covered here — see Sega's official 6-button protocol doc. Most modern
+; homebrew supports 3-button and treats 6-button as "ignore extras."
+;
+; ** Important libretro gotcha: ** genesis_plus_gx (and most cores) read
+; the controller via setInput() ONCE PER FRAME via retro_input_poll +
+; retro_input_state. The hardware semantics above are emulated; the
+; first read on a fresh-loaded ROM may return all-zeros because the
+; agent's setInput hasn't been called yet. Don't bug-hunt this; just
+; step a frame after setInput before reading.
+
+PAD1_DATA  equ $A10003
+PAD1_CTRL  equ $A10009
+
+; ---- read_pad: snapshot one frame of controller 1 into d0 -----------
+;
+; Returns a packed 16-bit word in d0:
+;   bit  0: Up      bit  4: A       bit  8: Up      bit 12: B
+;   bit  1: Down    bit  5: Start   bit  9: Down    bit 13: C
+;   bit  2: 0       bit  6: 0       bit 10: Left    bit 14: 0
+;   bit  3: 0       bit  7: 0       bit 11: Right   bit 15: 0
+;
+; (Low byte = TH=0 read; high byte = TH=1 read. Caller can mask out
+; the bits they care about.)
+;
+; The values are ACTIVE-HIGH after this routine — 1 = pressed.
+read_pad:
+  movem.l d1/a0,-(sp)
+  lea     PAD1_DATA,a0
+  ; --- TH=0 read (UDxxASxx) ---
+  move.b  #$00,PAD1_CTRL
+  nop
+  nop
+  move.b  (a0),d0
+  not.b   d0                 ; invert: 1 = pressed
+  ; --- TH=1 read (UDLRBCxx) ---
+  move.b  #$40,PAD1_CTRL
+  nop
+  nop
+  move.b  (a0),d1
+  not.b   d1
+  ; --- pack into d0 high byte ---
+  lsl.w   #8,d1
+  or.w    d1,d0
+  ; --- mask off the unused bits (bits 2-3 in TH=0, bits 6-7) ---
+  ; Mask: %0111001111110011 = $73F3. Layout below for review:
+  ;   high byte (TH=1 read): 0111 0011 = $73 — bits 14,12,11,9,8 used; 15,13,10 unused
+  ;   low  byte (TH=0 read): 1111 0011 = $F3 — bits 7,6,5,4,1,0 used; 3,2 unused
+  and.w   #$73F3,d0
+  movem.l (sp)+,d1/a0
+  rts
+
+; ---- read_pad_with_edges: held + pressed + released, w/ d0/d1/d2 out -
+;
+; Requires WRAM at pad1_held (see wram.s for the layout).
+; After call:
+;   d0 = current held bits  (1=pressed)
+;   d1 = newly pressed bits (1=pressed THIS frame, was 0 LAST frame)
+;   d2 = newly released bits (1=released this frame)
+;
+; Typical use:
+;   jsr   read_pad_with_edges
+;   btst  #4, d1              ; A newly pressed?
+;   beq.s .no_a_press
+;   jsr   on_a_pressed
+; .no_a_press:
+read_pad_with_edges:
+  bsr     read_pad
+  move.w  pad1_held,d3
+  ; pressed = current AND NOT last
+  move.w  d0,d1
+  not.w   d3
+  and.w   d3,d1
+  ; released = NOT current AND last
+  not.w   d0
+  move.w  pad1_held,d2
+  and.w   d0,d2
+  not.w   d0                  ; restore d0 = current held
+  ; update held cache
+  move.w  d0,pad1_held
+  rts