romdev-mcp 0.1.1

package/src/platforms/snes/lib/c/snes_sfx_data.asm

@@ -0,0 +1,25 @@
+; ── snes_sfx_data.asm — SPC700 driver + sample-bank + music bytes ───
+;
+; Embeds the prebuilt apu_blob.bin (driver code at ARAM $0200, padded
+; to $1000, sample bank at $1000, zero-padded to $5000, song table at
+; $5000) as a labeled byte array the C side accesses via
+; `extern const u8 apu_blob[]` plus a linker-defined end symbol so
+; sfx_init can compute the payload size at runtime — that way bumping
+; the song table size doesn't require updating a hardcoded length.
+;
+; Why .rodata1: the asset is read-only payload — never executed by
+; the 65816, just streamed via APUIO ports to the SPC700.
+;
+; To rebuild apu_blob.bin from sources see src/platforms/snes/lib/audio/
+; — the apu_blob.asm there is the asar input that assembles spc_driver
+; + sample_bank + music into a single upload payload.
+
+.include "hdr.asm"
+
+.section ".rodata1" superfree
+
+apu_blob:
+.incbin "apu_blob.bin"
+apu_blob_end:
+
+.ends

package/src/platforms/snes/lib/cgram_upload.asm

@@ -0,0 +1,43 @@
+; SNES — CGRAM (palette RAM) upload.
+;
+; CGRAM is 512 bytes = 256 colors × 2 bytes BGR555 little-endian.
+; Layout: byte 0 is the universal backdrop. Bytes 0..15 = BG palette 0
+; (for 4bpp: 16 colors; for 2bpp: 4 sub-palettes of 4 colors each).
+; Bytes 128..255 are the OBJ palettes (8 palettes × 16 colors in 4bpp).
+;
+; Color encoding: BGR555 little-endian. Each color is 2 bytes.
+;   low  byte = GGGRRRRR  (bits 0-4 R, 5-7 low bits of G)
+;   high byte = .BBBBBGG  (bits 0-1 high bits of G, 2-6 B, bit 7 unused)
+; To pack from 8-bit RGB:
+;   r5 = R >> 3
+;   g5 = G >> 3
+;   b5 = B >> 3
+;   word = (b5 << 10) | (g5 << 5) | r5
+;
+; Example: write 16 BG colors from a table at `bg_palette_data`:
+;
+;   stz $2121           ; CGADD — start at CGRAM index 0
+;   ldx #$0000
+; .loop:
+;   lda bg_palette_data, x
+;   sta $2122           ; CGDATA — write byte; pair counts as one color
+;   inx
+;   cpx #(bg_palette_end-bg_palette_data)
+;   bne .loop
+;
+; For OBJ palettes start at CGADD=$80 (= color index 128).
+;
+; DMA alternative (faster for big palettes):
+;   stz $2121           ; CGADD = 0
+;   lda #$00            ; mode 0: 1 byte to one register
+;   sta $4300
+;   lda #$22            ; B-bus = $2122 (CGDATA)
+;   sta $4301
+;   ldx #bg_palette_data
+;   stx $4302
+;   lda #bg_palette_data>>16
+;   sta $4304
+;   ldx #(bg_palette_end-bg_palette_data)
+;   stx $4305
+;   lda #$01
+;   sta $420B

package/src/platforms/snes/lib/lorom_header.asm

@@ -0,0 +1,47 @@
+; SNES — LoROM header + vectors.
+;
+; Every LoROM cartridge needs this exact layout in bank $00, mapped from
+; CPU $00:FFC0 onward. The 21-byte title is space-padded to fill exactly
+; that field. The byte at $FFD5=$20 declares LoROM/SlowROM; flip to $30
+; for FastROM.
+;
+; Native-mode vectors live at $FFE4-$FFEF. Critical: only NMI ($FFEA)
+; and IRQ ($FFEE) are typically used in practice. The 6 entries before
+; NMI are COP/BRK/ABORT/reserved/reserved which 99% of homebrew leaves
+; at $0000. (Common gotcha: if your `dw` list runs long here you'll cross
+; into $010000 = bank $01 and asar will emit an Ebank_border_crossed
+; error. Verified by bisection on this MCP server's own dev sessions.)
+;
+; Emulation-mode vectors at $FFF4-$FFFF. RESET at $FFFC is the one that
+; actually matters — it's where the CPU starts after power-on. Everything
+; else can be zero.
+
+org $00FFC0
+  db "MY GAME              "    ; 21 byte title, pad with spaces to fill
+  db $20                          ; map mode: LoROM, SlowROM
+  db $00                          ; cart type: ROM only
+  db $08                          ; ROM size 2^N KB → $08 = 256 KB
+  db $00                          ; SRAM size (0 = none)
+  db $01                          ; region: $01 = USA/NTSC, $00 = Japan
+  db $00                          ; dev id
+  db $00                          ; ROM version
+  dw $0000                        ; checksum complement (filled by tools)
+  dw $0000                        ; checksum
+
+; Native-mode vectors $FFE4-$FFEF
+org $00FFE4
+  dw $0000                        ; COP
+  dw $0000                        ; BRK
+  dw $0000                        ; ABORT
+  dw nmi                          ; NMI ($FFEA) ← define `nmi:` somewhere
+  dw $0000                        ; reserved
+  dw irq                          ; IRQ ($FFEE) ← define `irq:` (usually rti)
+
+; Emulation-mode vectors $FFF4-$FFFF
+org $00FFF4
+  dw $0000                        ; COP (emulation)
+  dw $0000                        ; BRK (emulation)
+  dw $0000                        ; ABORT (emulation)
+  dw $0000                        ; NMI (emulation)
+  dw reset                        ; RESET ($FFFC) ← entry point
+  dw $0000                        ; IRQ (emulation)

package/src/platforms/snes/lib/lorom_multibank.asm

@@ -0,0 +1,66 @@
+; SNES — LoROM multi-bank layout (canonical order).
+;
+; asar 1.x silently crashes (heap-pointer exit code, no diagnostic) when
+; `org` directives go to a higher bank and then rewind to a lower one.
+; The preflight checker now catches this, but the actual workaround is to
+; lay your `org`s out in MONOTONICALLY INCREASING bank order: header and
+; small fixed-position data FIRST, then code, then big data blobs in
+; higher banks.
+;
+; This template puts the LoROM header at $00FFC0 BEFORE any large incbin
+; that would push past it, then drops your CHR/audio/level data in
+; bank $01 ($018000+). Up to bank $07 ($038000..$07FFFF) is freely
+; available in a 256 KB ROM; bump the header byte at $FFD7 to allow
+; larger ROMs (see lorom_header.asm).
+;
+; If you need more than ~32 KB in bank $00 itself, you can't — bank $00
+; ends at $00FFFF and the header consumes $00FFC0..$00FFFF. Move data
+; to bank $01+.
+
+lorom
+
+; ===== bank $00: header FIRST, then code =====
+org $00FFC0
+  db "MY MULTIBANK GAME    "    ; 21 byte title
+  db $20, $00, $08, $00, $01, $00, $00
+  dw $0000, $0000                ; checksum complement + checksum
+
+org $00FFE4
+  dw $0000, $0000, $0000, nmi, $0000, irq
+
+org $00FFFC
+  dw reset                       ; emulation-mode RESET vector
+
+; ===== bank $00 code area =====
+org $008000
+reset:
+  sei
+  clc
+  xce                            ; switch to native mode
+  rep #$30
+  ldx #$1FFF
+  txs
+  ; ... your init + main loop here
+  jmp main
+
+nmi:
+  rti
+
+irq:
+  rti
+
+main:
+  wai
+  jmp main
+
+; ===== bank $01: CHR, audio samples, level data =====
+; All large `incbin`s go here. Bank $01 = file offset $008000..$00FFFF.
+; You get up to 32 KB per bank ($XX8000..$XXFFFF).
+org $018000
+chr_data:
+  ; incbin "title_chr.bin"      ; up to 32 KB
+; pad $01FFFF                    ; (uncomment to fill the bank if needed)
+
+; ===== bank $02+: more data if needed =====
+; org $028000
+;   incbin "level_data.bin"

package/src/platforms/snes/lib/nmi_safe.asm

@@ -0,0 +1,77 @@
+; SNES — safe NMI/VBlank handler skeleton.
+;
+; The 65816's NMI is ALWAYS native-mode + 16-bit-A/X when used from a
+; native-mode program. Two non-obvious gotchas this snippet handles:
+;
+; 1. **DB (data bank) preservation**. The CPU does NOT restore DB on RTI.
+;    If your main code is running in bank $80 and your NMI runs DMA
+;    relative to bank $00, you MUST push DB/restore DB. Forgetting this
+;    silently breaks the next "lda $1234" in main code (it reads from
+;    the wrong bank). 20-minute bug to track down with a "my DMA broke"
+;    symptom.
+;
+; 2. **M/X flag width preservation**. NMI doesn't reset M/X. If main code
+;    was running with 8-bit A (M=1) when the NMI fired, your 16-bit `lda
+;    #$1234` in the handler will silently load only $34. Always set
+;    M=X=0 (`rep #$30`) at the top of NMI, and restore via the pushed P
+;    on RTI.
+;
+; 3. **$4210 NMI flag**. The hardware NMI flag latches until $4210 is
+;    READ. Reading it acks the interrupt. If you don't, the next vblank
+;    won't re-fire NMI correctly on some hardware.
+;
+; 4. **Vblank-ready flag**. Main code's "wait for vblank" loop should
+;    test a software flag set BY the NMI, not poll $4212 directly —
+;    polling races with the NMI fire and you'll miss vblanks.
+;
+; This skeleton: pushes A/X/Y/D/B + P, sets 16-bit registers + bank $00,
+; acks NMI, runs whatever VBlank-time work you want (typically DMA),
+; sets the vblank flag for main code to consume, then pops everything.
+
+nmi:
+  ; ---- save full register state ----
+  php                       ; preserve P (M/X widths AND processor flags)
+  rep #$30                  ; force 16-bit A/X/Y so the pushes are wide
+  pha                       ; push A.W
+  phx                       ; push X.W
+  phy                       ; push Y.W
+  phd                       ; push DP
+  phb                       ; push DB (bank)
+  ; ---- normalize bank + DP for the handler ----
+  lda #$0000
+  tcd                       ; set DP = $0000
+  sep #$20                  ; 8-bit A for the bank store
+  pha                       ; A = $00 still in low byte; trick: actually load explicitly
+  lda #$00
+  pha
+  plb                       ; pull bank = $00
+  rep #$20                  ; back to 16-bit A
+
+  ; ---- ack NMI ----
+  lda $4210                 ; read clears NMI flag (8-bit read in 16-bit A is fine; low byte is the flag)
+
+  ; ---- your VBlank-time work here ----
+  ; common: OAM DMA, palette upload, VRAM tile transfers.
+  ; jsr do_oam_dma
+  ; jsr upload_pending_vram
+
+  ; ---- set the vblank-ready flag ----
+  lda #$0001
+  sta vblank_ready          ; main code's `wai` loop tests this
+
+  ; ---- restore ----
+  plb                       ; restore DB
+  pld                       ; restore DP
+  ply
+  plx
+  pla
+  plp                       ; restore P (and thus M/X widths)
+  rti
+
+; In your main loop:
+;   wait_vblank:
+;     wai
+;     lda vblank_ready
+;     beq wait_vblank       ; spurious wake — try again
+;     stz vblank_ready
+;     ; ... your per-frame logic here ...

package/src/platforms/snes/lib/oam_upload.asm

@@ -0,0 +1,45 @@
+; SNES — OAM (sprite list) upload.
+;
+; OAM is 544 bytes total: 512 byte "low table" (128 sprites × 4 bytes)
+; plus 32 byte "high table" (2 bits per sprite, packed).
+;
+; Low-table per sprite (4 bytes):
+;   +0  X position (low 8 bits)
+;   +1  Y position
+;   +2  tile number (low 8 bits)
+;   +3  attributes: VHOO PPCT
+;       V/H  = vertical/horizontal flip
+;       OO   = priority (0-3, higher draws on top of BG)
+;       PPP  = sprite palette (0-7, maps to CGRAM 128 + p*16)
+;       T    = tile number high bit (extends 0-255 → 0-511)
+;
+; High-table 2 bits per sprite, packed 4 sprites per byte:
+;   bit 0   = X position high bit (sprite X is 9-bit signed!)
+;   bit 1   = size select (small/large per OBSEL $2101)
+;
+; The simplest pattern — write the whole 544 bytes via DMA each frame
+; from a "shadow OAM" in WRAM at $0400-$0621. Update sprites by writing
+; to the shadow; the OAM DMA every NMI flushes.
+;
+; ALWAYS do OAM DMA during forced blank or vblank. Mid-frame OAM writes
+; cause sprite flicker. (Inside NMI handler is canonical.)
+;
+; OAM DMA via channel 0:
+;
+;   stz $2102           ; OAMADDL — start at OAM byte 0
+;   stz $2103           ; OAMADDH
+;   stz $4300           ; DMA mode 0 (1 byte to one register)
+;   lda #$04
+;   sta $4301           ; B-bus = $2104 (OAMDATA)
+;   ldx #oam_shadow     ; source address
+;   stx $4302
+;   lda #oam_shadow>>16
+;   sta $4304
+;   ldx #$0220          ; 544 bytes
+;   stx $4305
+;   lda #$01
+;   sta $420B           ; fire channel 0
+;
+; Tip: clear the shadow to {y=$F0, ...} at boot so unused slots stay
+; off-screen until you assign them. Otherwise the random WRAM contents
+; show as garbage sprites for frame 0.

package/src/platforms/snes/lib/pad_read.asm

@@ -0,0 +1,64 @@
+; SNES — controller read + edge detection.
+;
+; The SNES has auto-joypad-read built into the H/W: at the start of each
+; frame, the CPU reads both controller ports and latches the results
+; into $4218/$4219 (port 1) and $421A/$421B (port 2). The 16-bit value
+; mirrors the controller's serial protocol:
+;
+;   bit 15: B           bit 7: A
+;   bit 14: Y           bit 6: X
+;   bit 13: Select      bit 5: L
+;   bit 12: Start       bit 4: R
+;   bit 11: Up          bits 0-3: (device id padding; ignore)
+;   bit 10: Down
+;   bit  9: Left
+;   bit  8: Right
+;
+; Important: you can ONLY read these registers AFTER auto-joypad-read
+; completes (~$4210/$4211 status), but the typical pattern is to read
+; them once at the top of your main-loop logic (which runs AFTER
+; vblank). Read while $4212 bit 0 = 0 (auto-joypad idle).
+;
+; This snippet ALSO does edge detection: a `pressed` register that holds
+; "buttons newly pressed THIS frame" (= held now & NOT held last frame),
+; the standard "fire-once on press" pattern.
+
+read_pad:
+  rep #$20                  ; 16-bit A
+  ; wait for auto-joypad-read to finish (idle = bit 0 of $4212 clear)
+.wait:
+  sep #$20
+  lda $4212
+  and #$01
+  bne .wait
+  rep #$20
+
+  lda $4218                 ; 16-bit pad bits
+  tay                       ; stash in Y
+  ; pressed = current AND NOT previous
+  eor pad_held              ; XOR with prev = changed bits
+  and $0000,y               ; (re-anding with current via Y — alternative below)
+  ; cleaner: pressed = current AND NOT prev
+  tya
+  pha
+  lda pad_held
+  eor #$FFFF
+  and $01,s                 ; AND with current from stack
+  sta pad_pressed
+  pla
+  sta pad_held
+  rts
+
+; Usage in game code:
+;   lda pad_pressed
+;   bit #$1000                ; Start
+;   beq .no_start_press
+;   ; ... fire-once on Start press ...
+; .no_start_press:
+;   bit #$0800                ; Up held? (use pad_held for "is held")
+;   ...
+
+; ---- DP reservations ----
+; Place these in your DP area:
+;   pad_held:    .res 2     ; 16-bit, last frame's joypad bits
+;   pad_pressed: .res 2     ; 16-bit, bits newly down this frame

package/src/platforms/snes/lib/pvsneslib/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2012-2024 alekmaul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/platforms/snes/lib/pvsneslib/include/ctype.h

@@ -0,0 +1,6 @@
+int isdigit(int c);
+int isxdigit(int c);
+int islower(int c);
+int toupper(int c);
+int isspace(int c);
+int isprint(int c);

package/src/platforms/snes/lib/pvsneslib/include/float.h

@@ -0,0 +1,4 @@
+#define FLT_MIN __FLT_MIN__
+#define FLT_MAX __FLT_MAX__
+#define DBL_MIN FLT_MIN
+#define DBL_MAX FLT_MAX

package/src/platforms/snes/lib/pvsneslib/include/hdr.asm

@@ -0,0 +1,47 @@
+;==LoRom==      ; We'll get to HiRom some other time.
+
+.MEMORYMAP                      ; Begin describing the system architecture.
+  SLOTSIZE $8000                ; The slot is $8000 bytes in size. More details on slots later.
+  DEFAULTSLOT 0                 ; There's only 1 slot in SNES, there are more in other consoles.
+  SLOT 0 $8000                  ; Defines Slot 0's starting address.
+  SLOT 1 $0 $2000
+  SLOT 2 $2000 $E000
+  SLOT 3 $0 $10000
+.ENDME          ; End MemoryMap definition
+
+.ROMBANKSIZE $8000              ; Every ROM bank is 32 KBytes in size
+.ROMBANKS 8                     ; 2 Mbits - Tell WLA we want to use 8 ROM Banks
+
+.SNESHEADER
+  ID "SNES"                     ; 1-4 letter string, just leave it as "SNES"
+
+  NAME "snes-sdk default hdr "  ; Program Title - can't be over 21 bytes,
+  ;    "123456789012345678901"  ; use spaces for unused bytes of the name.
+
+  SLOWROM
+  LOROM
+
+  CARTRIDGETYPE $00             ; $00 = ROM only, see WLA documentation for others
+  ROMSIZE $08                   ; $08 = 2 Mbits,  see WLA doc for more..
+  SRAMSIZE $00                  ; No SRAM         see WLA doc for more..
+  COUNTRY $01                   ; $01 = U.S.  $00 = Japan, that's all I know
+  LICENSEECODE $00              ; Just use $00
+  VERSION $00                   ; $00 = 1.00, $01 = 1.01, etc.
+.ENDSNES
+
+.SNESNATIVEVECTOR               ; Define Native Mode interrupt vector table
+  COP EmptyHandler
+  BRK EmptyHandler
+  ABORT EmptyHandler
+  NMI VBlank
+  IRQ EmptyHandler
+.ENDNATIVEVECTOR
+
+.SNESEMUVECTOR                  ; Define Emulation Mode interrupt vector table
+  COP EmptyHandler
+  ABORT EmptyHandler
+  NMI EmptyHandler
+  RESET tcc__start                   ; where execution starts
+  IRQBRK EmptyHandler
+.ENDEMUVECTOR
+

package/src/platforms/snes/lib/pvsneslib/include/limits.h

@@ -0,0 +1,13 @@
+#define INT_MAX 32767
+#define INT_MIN -32768
+#define UINT_MAX 65535
+#define LONG_MAX INT_MAX
+#define LONG_MIN INT_MIN
+#define SCHAR_MAX 127
+#define SCHAR_MIN -128
+#define UCHAR_MAX 255
+#define SHRT_MAX 32767
+#define SHRT_MIN -32768
+#define USHRT_MAX 65535
+#define ULONG_MAX UINT_MAX
+#define CHAR_BIT __CHAR_BIT__

package/src/platforms/snes/lib/pvsneslib/include/math.h

@@ -0,0 +1,10 @@
+float modf(float x, float *fp);
+float ldexp(float x, int exp);
+float floor(float d);
+float ceil(float d);
+float exp(float arg);
+float frexp(float x, int *exp);
+float log(float arg);
+float log10(float arg);
+float pow(float arg1, float arg2);
+float fabs(float);

package/src/platforms/snes/lib/pvsneslib/include/setjmp.h

@@ -0,0 +1,4 @@
+typedef int jmp_buf[3];
+
+int setjmp(jmp_buf env);
+void longjmp(jmp_buf env, int val);