romdev-mcp 0.1.1

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

@@ -0,0 +1,40 @@
+/* sms_sfx.h — minimal SMS PSG sound-effects wrapper.
+ *
+ * SMS audio = SN76489 PSG (same chip as Genesis PSG, 4 channels):
+ *   ch 0, 1, 2 = square-wave tones
+ *   ch 3       = noise
+ *
+ * Accessed via I/O port $7F (write-only — reads return the H-counter).
+ *
+ * Same shape as nes_runtime / gb_runtime / gba_sfx / genesis_sfx:
+ *
+ *   sfx_init()
+ *   sfx_tone(channel, freq, length_frames)
+ *   sfx_noise(length_frames)
+ *   sfx_update()    // call once per frame to tick auto-silence
+ *   sfx_off()
+ *
+ * Game Gear shares the SAME chip + the same port $7F write path,
+ * so this wrapper works unchanged on GG. (GG adds a stereo register
+ * at port $06 that's optional — we don't touch it.)
+ *
+ * The PSG has NO automatic envelope. We hand-decrement a per-channel
+ * counter and silence on zero — that's what sfx_update does. Forget
+ * to call it once per frame and notes ring forever.
+ *
+ * Frequency on SMS is 10-bit (0..1023). Hz = 3579545 / 32 / freq.
+ * Useful values: 200 = high pew, 400 = mid blip, 800 = low thump.
+ */
+
+#ifndef SMS_SFX_H
+#define SMS_SFX_H
+
+#include <stdint.h>
+
+void sfx_init(void);
+void sfx_tone(uint8_t channel, uint16_t freq, uint8_t length_frames);
+void sfx_noise(uint8_t length_frames);
+void sfx_update(void);
+void sfx_off(void);
+
+#endif

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

@@ -0,0 +1,60 @@
+/* SMS sprite attribute table — shadow OAM in WRAM, DMA'd to SAT once
+ * per frame.
+ *
+ * SAT VRAM layout ($3F00):
+ *   $00-$3F:  64 Y bytes ($D0 in any slot = HARD TERMINATOR — see below)
+ *   $80-$FF:  64 (X, tile) pairs
+ *
+ * The $D0 terminator footgun:
+ *   The VDP stops scanning further sprite slots the moment it sees Y=$D0
+ *   in ANY OAM byte. If you populate slots 0..5 and slot 6 still has
+ *   $D0, slot 5 is the last sprite you'll ever see. Earlier rounds of
+ *   this runtime initialised every slot to $D0 — "hidden at boot" — but
+ *   that meant the FIRST gap in your sprite allocation killed the
+ *   renderer for everything past it. We now initialise unused slots to
+ *   $E0 instead: still off-screen (below the 192-line visible area on
+ *   SMS) but NOT the terminator. Slots you don't touch stay invisible;
+ *   slots you do touch render. Set a slot's Y to $D0 yourself if you
+ *   ACTUALLY want the renderer to stop there.
+ *
+ * Workflow:
+ *   sms_sprite_init();             // once
+ *   sms_sprite_set(0, x, y, 4);    // game logic
+ *   ...
+ *   sms_sat_upload();              // once per vblank
+ */
+#include "sms_hw.h"
+
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+/* Shadow OAM: matches the VDP's expected SAT layout. */
+uint8_t shadow_oam[256];
+
+/* Y value for "hidden but not terminator." 192-line mode is visible
+ * Y=0..191; $E0 (224) is below the visible area and won't render. */
+#define OAM_Y_HIDDEN  0xE0
+
+void sms_sprite_init(void) {
+  uint8_t i;
+  /* Park every slot off-screen with a non-terminator Y. The renderer
+   * keeps scanning past these (so any slot you later populate will
+   * actually draw); they just don't render themselves. */
+  for (i = 0; i < 64; i++) shadow_oam[i] = OAM_Y_HIDDEN;
+  for (i = 0; i < 128; i++) shadow_oam[0x80 + i] = 0;
+}
+
+void sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile) {
+  shadow_oam[slot] = y;
+  shadow_oam[0x80 + (uint16_t)slot * 2] = x;
+  shadow_oam[0x80 + (uint16_t)slot * 2 + 1] = tile;
+}
+
+void sms_sat_upload(void) {
+  uint8_t i;
+  /* Y bytes → VRAM $3F00. */
+  sms_vdp_set_addr(0x3F00, VDP_VRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = shadow_oam[i];
+  /* (X, tile) pairs → VRAM $3F80. */
+  sms_vdp_set_addr(0x3F80, VDP_VRAM_WRITE);
+  for (i = 0; i < 128; i++) PORT_VDP_DATA = shadow_oam[0x80 + i];
+}

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

@@ -0,0 +1,10 @@
+/* SMS vblank wait — polls VDP_CTRL bit 7.
+ *
+ * Reading $BF returns the status byte and CLEARS bit 7. Spin until set;
+ * the act of reading clears the flag for the next iteration.
+ */
+#include "sms_hw.h"
+
+void sms_vblank_wait(void) {
+  while ((PORT_VDP_CTRL & 0x80) == 0) { }
+}

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

@@ -0,0 +1,58 @@
+/* SMS VDP — minimum viable initialization (C).
+ *
+ * Writes the 11 mode-4 registers to a sane baseline:
+ *   display OFF, vblank IRQ off, 192-line mode 4, name table at $3800,
+ *   BG tile data at $0000, sprite attr table at $3F00, sprite tile data
+ *   at $0000 (R6=0xFB → SA13 clear → tiles read from $0000-$1FFF). Call
+ *   once after reset before uploading palette/tiles/map.
+ *
+ * Footgun: many SMS references say "R6=0xFB → sprite tiles at $2000"
+ * which is BACKWARDS. R6 bit 2 (the SA13 select) is CLEAR in 0xFB, so
+ * sprite tiles read from $0000 (sharing the bank with BG tiles). To
+ * separate sprite tiles to $2000, set R6 = 0xFF instead. The
+ * inspectSprites tool's spriteTileDataBase field will show you the
+ * real address the VDP is reading from.
+ *
+ * After loading assets, enable display by re-writing R1 with bit 6 set:
+ *   sms_vdp_display_on();
+ */
+#include "sms_hw.h"
+
+/* Write a value to a VDP register. SMS convention: data first, then
+ * (0x80 | reg). */
+void sms_vdp_write_reg(uint8_t reg, uint8_t value) {
+  PORT_VDP_CTRL = value;
+  PORT_VDP_CTRL = VDP_REG_WRITE | reg;
+}
+
+void sms_vdp_init(void) {
+  static const uint8_t regs[11] = {
+    0x36,  /* R0:  Mode 4 */
+    0x80,  /* R1:  display OFF, vblank IRQ off */
+    0xFF,  /* R2:  name table at $3800 */
+    0xFF,  /* R3:  color table (ignored in M4) */
+    0xFF,  /* R4:  BG tile data at $0000 */
+    0xFF,  /* R5:  sprite attr table at $3F00 */
+    0xFB,  /* R6:  sprite tile data at $0000 (set 0xFF for $2000) */
+    0x00,  /* R7:  border = sprite palette entry 0 */
+    0x00,  /* R8:  BG X scroll */
+    0x00,  /* R9:  BG Y scroll */
+    0xFF,  /* R10: line IRQ counter disabled */
+  };
+  uint8_t i;
+  for (i = 0; i < 11; i++) sms_vdp_write_reg(i, regs[i]);
+}
+
+void sms_vdp_display_on(void) {
+  sms_vdp_write_reg(1, 0xE0);  /* display on, vblank IRQ on, 192-line */
+}
+
+void sms_vdp_display_off(void) {
+  sms_vdp_write_reg(1, 0x80);
+}
+
+/* Set the VDP destination address (for the next data-port writes). */
+void sms_vdp_set_addr(uint16_t addr, uint8_t prefix) {
+  PORT_VDP_CTRL = (uint8_t)(addr & 0xFF);
+  PORT_VDP_CTRL = (uint8_t)((addr >> 8) & 0x3F) | prefix;
+}

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

@@ -0,0 +1,33 @@
+; SMS / Game Gear ROM header (TMR SEGA).
+;
+; Lives at $7FF0-$7FFF (last 16 bytes of bank 0). The BIOS verifies this
+; on power-on; without it, real hardware refuses to boot. Most emulators
+; (gpgx included) tolerate its absence, but ship the header anyway so
+; your ROM runs on real cartridges.
+;
+; Layout:
+;   $7FF0..$7FF7  "TMR SEGA"           — magic string
+;   $7FF8..$7FF9  reserved             — 0x00 0x00
+;   $7FFA..$7FFB  checksum (LE word)   — sum of bytes $0000-$7FEF
+;   $7FFC..$7FFE  product code         — 5 nibbles BCD (low at $7FFC,
+;                                         high nibble of $7FFE = high digit)
+;   $7FFE high   version               — 4-bit revision number
+;   $7FFF        region | rom_size     — bits 7-4 = region, bits 3-0 = size
+;
+; Region codes:
+;   3 = SMS Japan, 4 = SMS Export, 5 = GG Japan, 6 = GG Export, 7 = GG Int'l
+; ROM size codes (relevant for ≥32KB carts):
+;   $a = 8KB, $b = 16KB, $c = 32KB, $d = 48KB (rare),
+;   $e = 64KB, $f = 128KB, $0 = 256KB, $1 = 512KB
+
+        .org $7FF0
+        .ascii "TMR SEGA"
+        .db $00, $00
+        ; Checksum slot — most assemblers won't compute this for you;
+        ; either patch it post-build (sums of bytes $0000-$7FEF) or use
+        ; the BIOS-skip approach (most emulators don't enforce).
+        .db $00, $00
+        ; Product code (placeholder: 00001)
+        .db $01, $00, $00
+        ; Region (4 = SMS Export) and rom size ($c = 32 KB).
+        .db $4C

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

@@ -0,0 +1,40 @@
+; SMS joypad read.
+;
+; Port $DC = controller port A (P1 directions + buttons 1+2, P2 D-pad).
+; Port $DD = controller port B (P2 buttons + reset/cart inserted bits).
+;
+; Bit layout for port $DC (active LOW — pressed = 0):
+;   bit 0  P1 up
+;   bit 1  P1 down
+;   bit 2  P1 left
+;   bit 3  P1 right
+;   bit 4  P1 button 1 (TL)
+;   bit 5  P1 button 2 (TR)
+;   bit 6  P2 up
+;   bit 7  P2 down
+;
+; This routine reads $DC, inverts (so pressed = 1), and stores into
+; (_p1_state). The agent can then test individual bits.
+
+JOY_PORT_A equ $DC
+JOY_PORT_B equ $DD
+
+joypad_read:
+        in a,(JOY_PORT_A)
+        cpl                      ; invert: pressed=1
+        ld (_p1_state),a
+        in a,(JOY_PORT_B)
+        cpl
+        ld (_p2_state),a
+        ret
+
+; Convenience masks — combine into your own test code as needed:
+JOY_UP    equ $01
+JOY_DOWN  equ $02
+JOY_LEFT  equ $04
+JOY_RIGHT equ $08
+JOY_B1    equ $10
+JOY_B2    equ $20
+
+_p1_state .equ $C010
+_p2_state .equ $C011

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

@@ -0,0 +1,30 @@
+; SMS palette loader.
+;
+; CRAM has 32 entries (16 BG + 16 sprite), one byte each. Entry layout:
+;   bits 0-1 = R (2 bits)
+;   bits 2-3 = G
+;   bits 4-5 = B
+;
+; To write CRAM:
+;   1. Set the VDP address to CRAM via control port:
+;        send word (cram_offset | $C000) — the $C000 prefix tells the VDP
+;        "the next data-port write goes to CRAM at this address".
+;        Use $4000 prefix for VRAM writes instead.
+;   2. Write each color byte to VDP_DATA ($BE). Auto-increments the
+;      address pointer.
+;
+; CALLING: HL → 32-byte palette table; entry 0 written first.
+
+VDP_DATA equ $BE
+VDP_CTRL equ $BF
+
+load_palette:
+        ld a,$00                 ; LOW byte of CRAM dest addr ($0000)
+        out (VDP_CTRL),a
+        ld a,$C0                 ; HIGH byte: $C0 = CRAM write
+        out (VDP_CTRL),a
+
+        ld b,32                  ; 32 entries (16 BG + 16 sprite)
+        ld c,VDP_DATA
+        otir                     ; (HL)+ → out (C); B--; loop until B=0
+        ret

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

@@ -0,0 +1,50 @@
+; SMS tile loader — VRAM upload.
+;
+; SMS tiles are 32 bytes each (4bpp interleaved). VRAM is 16 KB at
+; $0000-$3FFF. Tile N lives at VRAM offset (N * 32).
+;
+; To write VRAM:
+;   1. Set VDP address: low byte first, then (high | $40) — the $40
+;      prefix in the high byte signals VRAM write.
+;   2. Write bytes to VDP_DATA — auto-increments.
+;
+; CALLING:
+;   HL  → source bytes
+;   BC  → byte count (= tileCount * 32)
+;   DE  → VRAM destination (e.g. $2000 = tile 256)
+; CLOBBERS: A, BC, HL, DE.
+
+VDP_DATA equ $BE
+VDP_CTRL equ $BF
+
+load_tiles:
+        ; Set VDP address: low(e), high(d) | $40
+        ld a,e
+        out (VDP_CTRL),a
+        ld a,d
+        or $40
+        out (VDP_CTRL),a
+
+        ; Bulk copy. OTIR transfers 1 byte at a time and loops on B until
+        ; B reaches 0, so we have to outer-loop over C.
+        ld d,c                   ; D = high-byte page count
+        inc d                    ; INC because OTIR-then-test-B-zero needs round-up
+        ld a,b
+        or a
+        jr nz,_lt_page
+
+_lt_check_partial:
+        ld a,c
+        or a
+        ret z                    ; nothing left
+        ld b,c
+        ld c,VDP_DATA
+        otir
+        ret
+
+_lt_page:
+        ld c,VDP_DATA
+        otir                     ; one full 256-byte page
+        ld c,VDP_DATA            ; restore C
+        djnz _lt_page            ; B was decremented
+        jr _lt_check_partial

package/src/platforms/sms/lib/sprite_table.s

@@ -0,0 +1,44 @@
+; SMS sprite attribute table (SAT) — populate from shadow OAM.
+;
+; SAT lives at VRAM $3F00 by default (set via VDP R5). Layout:
+;   $00-$3F:  64 Y bytes. $D0 in any slot = terminator (VDP stops rendering).
+;   $80-$FF:  64 (X, tile) pairs.
+;
+; Strategy: keep shadow OAM in WRAM (256 bytes), update it during your
+; game logic, then DMA-copy to VRAM once per vblank.
+;
+; CALLING: HL → shadow OAM bytes (256 bytes); writes Y entries 0-63 to
+; VRAM $3F00 then X/tile pairs to VRAM $3F80.
+
+VDP_DATA equ $BE
+VDP_CTRL equ $BF
+
+sat_upload:
+        ; Write Y bytes (slots 0-63 = first 64 bytes of shadow).
+        ld a,$00                 ; VRAM offset $3F00 low
+        out (VDP_CTRL),a
+        ld a,$3F | $40           ; $3F | $40 = VRAM write
+        out (VDP_CTRL),a
+        ld b,64
+        ld c,VDP_DATA
+        otir
+
+        ; Write (X, tile) pairs to $3F80.
+        ld a,$80
+        out (VDP_CTRL),a
+        ld a,$3F | $40
+        out (VDP_CTRL),a
+        ld b,128                 ; 64 sprites × 2 bytes
+        ld c,VDP_DATA
+        otir
+        ret
+
+; To set sprite N's position to (x, y) and tile T from your game code:
+;   ld a,y      ; shadow_oam + N
+;   ld (shadow_oam + N),a
+;   ld a,x      ; shadow_oam + 0x80 + N*2
+;   ld (shadow_oam + 0x80 + N*2),a
+;   ld a,t
+;   ld (shadow_oam + 0x80 + N*2 + 1),a
+;
+; To hide all sprites (init): fill shadow_oam[0..63] with $D0.

package/src/platforms/sms/lib/vblank_wait.s

@@ -0,0 +1,36 @@
+; SMS vblank — wait pattern.
+;
+; The VDP status flag (read from $BF) has bit 7 = vblank-frame interrupt
+; pending. Reading $BF clears the flag, so you can spin on it.
+;
+; Two patterns shipped here:
+;
+;   vblank_wait_poll  — busy-wait, reads $BF until bit 7 set. Use during
+;                       setup before you've enabled interrupts.
+;
+;   vblank_wait_irq   — assumes you've set up IM 1 with HL → an ISR that
+;                       toggles a flag in zero page; this just halts and
+;                       waits for the IRQ to fire. Cheaper on the CPU but
+;                       requires the IRQ wiring first.
+
+vblank_wait_poll:
+        in a,(VDP_CTRL)          ; read status; clears bit 7
+        bit 7,a                  ; was the flag set?
+        jr z,vblank_wait_poll
+        ret
+
+; IM 1 version — caller must:
+;   - set up IRQ vector at $38 to jr to a stub that writes a non-zero
+;     value to (_vblank_flag) and reti
+;   - call this with interrupts enabled (ei + im 1 done in init)
+vblank_wait_irq:
+        xor a
+        ld (_vblank_flag),a
+_vw_spin:
+        ld a,(_vblank_flag)
+        or a
+        jr z,_vw_spin
+        ret
+
+_vblank_flag .equ $C000          ; one byte in WRAM
+VDP_CTRL .equ $BF

package/src/platforms/sms/lib/vdp_init.s

@@ -0,0 +1,47 @@
+; SMS VDP — minimum viable initialization.
+;
+; The VDP exposes 11 registers (R0..R10). After power-on they're undefined
+; — programming the standard "Mode 4, display off" baseline is the first
+; thing any SMS ROM does before uploading tiles, palette, or name table.
+;
+; To write a VDP register from Z80: send a 16-bit value to the control
+; port ($BF) as two bytes. The HIGH byte encodes the register number with
+; the top bit set: $80 | reg_num. The LOW byte (written FIRST) is the
+; value. So to write R0 = $36: out ($BF),$36 / out ($BF),$80.
+;
+; CALLING CONVENTION: assumes interrupts already disabled (di) and SP set.
+; Returns with display still OFF — call your tile / palette / map loaders
+; first, then re-write R1 with bit 6 set to enable rendering.
+
+VDP_DATA equ $BE
+VDP_CTRL equ $BF
+
+vdp_init:
+        ld hl,_vdp_init_regs
+        ld b,11                  ; 11 regs to write
+        ld c,$BF                 ; VDP control port
+
+_vdp_init_loop:
+        ld a,(hl)                ; register value
+        out (c),a                ; write value (LSB)
+        ld a,$80
+        sub b                    ; reg number = 11 - B; first iteration B=11 → reg 0
+        add a,$0B
+        or a,$80                 ; set "this is a register write" bit
+        out (c),a
+        inc hl
+        djnz _vdp_init_loop
+        ret
+
+_vdp_init_regs:
+        .db $36                  ; R0: Mode 4, no scroll lock, mask col 0, line IRQ off
+        .db $80                  ; R1: display OFF, vblank IRQ off, 192-line mode
+        .db $FF                  ; R2: name table at $3800  (($3800 >> 10) | 0x01) — high bit ignored
+        .db $FF                  ; R3: color table — M4 ignores
+        .db $FF                  ; R4: BG tile data — M4: bit 2 selects $0000 vs $2000
+        .db $FF                  ; R5: sprite attr table base ($3F00 = $7E << 7)
+        .db $FB                  ; R6: sprite tile data — bit 2 selects bank ($2000 here)
+        .db $00                  ; R7: border color = sprite palette entry 0
+        .db $00                  ; R8: BG X scroll
+        .db $00                  ; R9: BG Y scroll
+        .db $FF                  ; R10: line IRQ counter (disabled)