romdev-mcp 0.1.1

package/src/platforms/nes/lib/c/nes_runtime.c

@@ -0,0 +1,347 @@
+/* ── nes_runtime.c — runtime impl auto-linked into NES C builds ──
+ *
+ * See nes_runtime.h for the API. The crt0 (chr-ram.crt0.s) wires in
+ * the NMI handler that calls vram_queue_flush + commits scroll_x /
+ * scroll_y / ppuctrl_value. Shadow OAM lives at $0200 (defined in the
+ * crt0's OAM segment, exported as _shadow_oam).
+ */
+
+#include "nes_runtime.h"
+
+/* ── PPU register addresses — define here rather than depend on cc65's
+ * nes.h, since the chr-ram preset's reduced lib set doesn't pull it. */
+#define PPUCTRL   (*(volatile uint8_t *)0x2000)
+#define PPUMASK   (*(volatile uint8_t *)0x2001)
+#define PPUSTATUS (*(volatile uint8_t *)0x2002)
+#define OAMADDR   (*(volatile uint8_t *)0x2003)
+#define OAMDATA   (*(volatile uint8_t *)0x2004)
+#define PPUSCROLL (*(volatile uint8_t *)0x2005)
+#define PPUADDR   (*(volatile uint8_t *)0x2006)
+#define PPUDATA   (*(volatile uint8_t *)0x2007)
+#define OAMDMA    (*(volatile uint8_t *)0x4014)
+#define APUSTATUS (*(volatile uint8_t *)0x4015)
+#define JOY1      (*(volatile uint8_t *)0x4016)
+#define JOY2      (*(volatile uint8_t *)0x4017)
+/* JOY2 doubles as APU frame counter when written. */
+#define APUFRAMECTR (*(volatile uint8_t *)0x4017)
+
+/* APU pulse 1 ($4000-$4003) */
+#define PULSE1_VOL   (*(volatile uint8_t *)0x4000)
+#define PULSE1_SWEEP (*(volatile uint8_t *)0x4001)
+#define PULSE1_LO    (*(volatile uint8_t *)0x4002)
+#define PULSE1_HI    (*(volatile uint8_t *)0x4003)
+/* APU pulse 2 ($4004-$4007) */
+#define PULSE2_VOL   (*(volatile uint8_t *)0x4004)
+#define PULSE2_SWEEP (*(volatile uint8_t *)0x4005)
+#define PULSE2_LO    (*(volatile uint8_t *)0x4006)
+#define PULSE2_HI    (*(volatile uint8_t *)0x4007)
+/* APU triangle ($4008-$400B) */
+#define TRI_LINEAR   (*(volatile uint8_t *)0x4008)
+#define TRI_LO       (*(volatile uint8_t *)0x400A)
+#define TRI_HI       (*(volatile uint8_t *)0x400B)
+/* APU noise ($400C-$400F) */
+#define NOISE_VOL    (*(volatile uint8_t *)0x400C)
+#define NOISE_LO     (*(volatile uint8_t *)0x400E)
+#define NOISE_HI     (*(volatile uint8_t *)0x400F)
+
+/* ── State the crt0's NMI reads (exported globals) ───────────────── */
+uint8_t scroll_x = 0;
+uint8_t scroll_y = 0;
+/* Default PPUCTRL: NMI on (bit 7), sprite pattern $0000, BG pattern $1000,
+ * VRAM-increment 1, base nametable $2000. Game can override via ppu_*. */
+uint8_t ppuctrl_value = 0x90;
+volatile uint8_t nmi_counter = 0;
+
+/* OAM bookkeeping. shadow_oam itself is declared in chr-ram.crt0.s
+ * (so OAM segment placement at $0200 is linker-enforced). oam_index
+ * tracks the next free slot for oam_spr(). */
+static uint8_t oam_index = 0;
+
+/* ── VRAM write queue ─────────────────────────────────────────────
+ * Each entry is { hi, lo, byte }. NMI walks the queue, writes
+ * PPUADDR(hi); PPUADDR(lo); PPUDATA(byte) for each, then clears the
+ * length. Length is capped at QUEUE_MAX entries; if game code overflows
+ * it, we busy-wait for an NMI to flush and continue. */
+#define QUEUE_MAX 24
+static struct {
+  uint8_t addr_hi;
+  uint8_t addr_lo;
+  uint8_t value;
+} vram_queue[QUEUE_MAX];
+static uint8_t vram_queue_len = 0;
+
+/* Called from the NMI handler in chr-ram.crt0.s. PPU is unlocked
+ * (we're in vblank), so writes to $2006/$2007 are safe. */
+void __fastcall__ vram_queue_flush(void) {
+  uint8_t i;
+  if (vram_queue_len == 0) return;
+  /* Reset the address latch by reading $2002 — even though the NMI
+   * trampoline already did this when it ran the scroll-reset
+   * sequence, that came AFTER we ran. Cheap insurance. */
+  (void)PPUSTATUS;
+  for (i = 0; i < vram_queue_len; i++) {
+    PPUADDR = vram_queue[i].addr_hi;
+    PPUADDR = vram_queue[i].addr_lo;
+    PPUDATA = vram_queue[i].value;
+  }
+  vram_queue_len = 0;
+}
+
+/* Queue one byte. If full, wait for NMI to drain then enqueue. */
+static void vram_queue_push(uint16_t ppu_addr, uint8_t v) {
+  while (vram_queue_len >= QUEUE_MAX) {
+    ppu_wait_nmi();
+  }
+  vram_queue[vram_queue_len].addr_hi = (uint8_t)(ppu_addr >> 8);
+  vram_queue[vram_queue_len].addr_lo = (uint8_t)(ppu_addr & 0xFF);
+  vram_queue[vram_queue_len].value = v;
+  ++vram_queue_len;
+}
+
+/* ── PPU control ──────────────────────────────────────────────── */
+
+void ppu_off(void) {
+  PPUMASK = 0;
+  PPUCTRL = ppuctrl_value & 0x7F;   /* disable NMI too */
+  ppuctrl_value &= 0x7F;
+}
+
+void ppu_on_all(void) {
+  ppuctrl_value |= 0x80;            /* NMI enable */
+  PPUMASK = 0x1E;                   /* show BG + sprites + leftmost cols */
+  PPUCTRL = ppuctrl_value;
+}
+
+void ppu_on_bg(void) {
+  ppuctrl_value |= 0x80;
+  PPUMASK = 0x0A;                   /* show BG + leftmost BG col */
+  PPUCTRL = ppuctrl_value;
+}
+
+void ppu_on_spr(void) {
+  ppuctrl_value |= 0x80;
+  PPUMASK = 0x14;                   /* show sprites + leftmost sprite col */
+  PPUCTRL = ppuctrl_value;
+}
+
+void ppu_wait_vblank(void) {
+  /* Setup-time wait — polls $2002 directly. Safe when NMI is disabled. */
+  while ((PPUSTATUS & 0x80) == 0) { /* spin */ }
+}
+
+void ppu_wait_nmi(void) {
+  uint8_t target = (uint8_t)(nmi_counter + 1);
+  while (nmi_counter != target) { /* spin */ }
+}
+
+uint8_t ppu_system(void) {
+  /* Cheap heuristic: count vblanks per CPU loop. Punt for v1 — return
+   * NTSC. Real PAL detection is a frame-rate measurement we don't
+   * need until anyone asks for PAL builds. */
+  return 0;
+}
+
+/* ── Palettes ─────────────────────────────────────────────────── */
+
+void palette_load(const uint8_t *pal32) {
+  uint8_t i;
+  /* Caller must call this with PPU off (so it's a direct write).
+   * If we wanted to support runtime palette swaps we'd need a
+   * dedicated palette queue, but for v1 the init-only contract is
+   * documented in the header. */
+  (void)PPUSTATUS;
+  PPUADDR = 0x3F;
+  PPUADDR = 0x00;
+  for (i = 0; i < 32; i++) {
+    PPUDATA = pal32[i];
+  }
+}
+
+/* ── OAM ──────────────────────────────────────────────────────── */
+
+void oam_clear(void) {
+  uint16_t i;
+  for (i = 0; i < 256; i += 4) {
+    shadow_oam[i] = 0xFF;             /* Y off-screen */
+    shadow_oam[i + 1] = 0;            /* tile */
+    shadow_oam[i + 2] = 0;            /* attr */
+    shadow_oam[i + 3] = 0;            /* X */
+  }
+  oam_index = 0;
+}
+
+void oam_spr(uint8_t x, uint8_t y, uint8_t tile, uint8_t attr) {
+  /* OAM byte order: Y, tile, attr, X. Y - 1 for the off-by-one PPU
+   * convention so the caller can pass "screen Y" and have it land
+   * where they expect. */
+  shadow_oam[oam_index + 0] = (uint8_t)(y - 1);
+  shadow_oam[oam_index + 1] = tile;
+  shadow_oam[oam_index + 2] = attr;
+  shadow_oam[oam_index + 3] = x;
+  oam_index += 4;
+  /* Wraps at 256 back to 0 — game code calling oam_spr more than 64
+   * times will overwrite earlier slots. That's fine; hardware caps
+   * at 64 anyway. */
+}
+
+/* ── Input ────────────────────────────────────────────────────── */
+
+uint8_t pad_poll(uint8_t which) {
+  uint8_t i, bit;
+  uint8_t out = 0;
+  /* Strobe — write 1 then 0 to $4016. */
+  JOY1 = 1;
+  JOY1 = 0;
+  if (which == 0) {
+    for (i = 0; i < 8; i++) {
+      bit = JOY1 & 0x01;
+      out = (uint8_t)((out << 1) | bit);
+    }
+  } else {
+    for (i = 0; i < 8; i++) {
+      bit = JOY2 & 0x01;
+      out = (uint8_t)((out << 1) | bit);
+    }
+  }
+  return out;
+}
+
+/* ── CHR-RAM upload ────────────────────────────────────────────── */
+
+void chr_ram_upload(uint16_t ppu_addr, const uint8_t *src, uint16_t n) {
+  /* Caller must call with PPU off. Writes are sequential — PPUADDR
+   * auto-increments by 1 per write (since PPUCTRL bit 2 = 0). */
+  uint16_t i;
+  (void)PPUSTATUS;
+  PPUADDR = (uint8_t)(ppu_addr >> 8);
+  PPUADDR = (uint8_t)(ppu_addr & 0xFF);
+  for (i = 0; i < n; i++) {
+    PPUDATA = src[i];
+  }
+}
+
+/* ── Direct VRAM write (init-only) ────────────────────────────── */
+
+void vram_unsafe_set(uint16_t ppu_addr, uint8_t b) {
+  (void)PPUSTATUS;
+  PPUADDR = (uint8_t)(ppu_addr >> 8);
+  PPUADDR = (uint8_t)(ppu_addr & 0xFF);
+  PPUDATA = b;
+}
+
+/* ── Queued VRAM writes (safe during rendering) ────────────────── */
+
+void vram_set(uint16_t ppu_addr, uint8_t v) {
+  vram_queue_push(ppu_addr, v);
+}
+
+/* Compute nametable cell address. Nametables are 32 tiles wide × 30
+ * tall; nt 0 = $2000, 1 = $2400, 2 = $2800, 3 = $2C00. */
+void tile_set(uint8_t nt, uint8_t x, uint8_t y, uint8_t tile) {
+  uint16_t base = 0x2000 + ((uint16_t)(nt & 3) << 10);
+  uint16_t off  = (uint16_t)((uint16_t)y * 32 + x);
+  vram_queue_push((uint16_t)(base + off), tile);
+}
+
+/* Attribute table is one byte per 4×4 tile group, at nametable + $3C0.
+ * Each byte holds 4 quadrants of 2 bits each: top-left bits 0-1,
+ * top-right 2-3, bottom-left 4-5, bottom-right 6-7.
+ *
+ * NES homebrew typically batches a whole row of attributes at once via
+ * a hand-rolled RMW. For a single tile change in C we have to read the
+ * current byte, mask the right 2 bits, and re-write. Since the queue
+ * is fire-and-forget (we can't read back from VRAM), we maintain a
+ * shadow attribute table in WRAM that's kept in sync.
+ *
+ * Memory cost: 4 nametables × 64 bytes = 256 bytes of WRAM.
+ */
+static uint8_t shadow_attr[4][64];
+
+void tile_set_palette(uint8_t nt, uint8_t x, uint8_t y, uint8_t palette) {
+  uint8_t nt_idx = (uint8_t)(nt & 3);
+  uint8_t row = (uint8_t)(y >> 2);
+  uint8_t col = (uint8_t)(x >> 2);
+  uint8_t attr_idx = (uint8_t)(row * 8 + col);
+  uint8_t shift = (uint8_t)(((y & 2) << 1) | (x & 2));  /* 0, 2, 4, or 6 */
+  uint8_t mask = (uint8_t)(0x03 << shift);
+  uint8_t b = shadow_attr[nt_idx][attr_idx];
+  uint16_t addr;
+  b = (uint8_t)((b & ~mask) | ((palette & 0x03) << shift));
+  shadow_attr[nt_idx][attr_idx] = b;
+  addr = (uint16_t)(0x23C0 + ((uint16_t)nt_idx << 10) + attr_idx);
+  vram_queue_push(addr, b);
+}
+
+/* ── Scroll ───────────────────────────────────────────────────── */
+
+void ppu_scroll(uint16_t x, uint16_t y) {
+  /* PPUCTRL bits 0-1 select the base nametable. Bit 0 = X >= 256,
+   * bit 1 = Y >= 240. The low 8 bits of X/Y go straight into
+   * PPUSCROLL. */
+  uint8_t nt = (uint8_t)((ppuctrl_value & 0xFC));
+  if (x & 0x100) nt |= 0x01;
+  if (y & 0x100) nt |= 0x02;
+  ppuctrl_value = nt;
+  scroll_x = (uint8_t)(x & 0xFF);
+  scroll_y = (uint8_t)(y & 0xFF);
+  /* Take effect at next NMI — the crt0 NMI writes scroll_x, scroll_y,
+   * and ppuctrl_value to PPUSCROLL/PPUCTRL. */
+}
+
+/* ── Sound ──────────────────────────────────────────────────────
+ * The NES APU has 5 channels: 2 pulse, 1 triangle, 1 noise, 1 DMC.
+ * sound_init() enables the first four. DMC stays off (it needs a
+ * sample, which most homebrew doesn't want to deal with).
+ */
+
+/* APU length-counter table. The 5-bit value written to the length
+ * counter latch (high nybble of $4003/$4007/$400B/$400F) indexes into
+ * this table to set how many frames the channel plays. Pulled from
+ * nesdev wiki "APU Length Counter". */
+static const uint8_t length_table[32] = {
+  10, 254, 20,  2, 40,  4, 80,  6, 160,  8, 60, 10, 14, 12, 26, 14,
+  12,  16, 24, 18, 48, 20, 96, 22, 192, 24, 72, 26, 16, 28, 32, 30,
+};
+
+void sound_init(void) {
+  APUSTATUS = 0x0F;        /* enable pulse1 + pulse2 + triangle + noise */
+  APUFRAMECTR = 0x40;      /* 4-step frame counter, disable frame IRQ */
+}
+
+void sound_play_tone(uint8_t channel, uint16_t period, uint8_t vol_4bit, uint8_t length_frames) {
+  uint8_t len5 = length_frames & 0x1F;
+  uint8_t v = vol_4bit & 0x0F;
+  uint8_t lo = (uint8_t)(period & 0xFF);
+  uint8_t hi_period = (uint8_t)((period >> 8) & 0x07);
+  /* high byte format: bits 7-3 = length-counter latch, bits 2-0 = timer hi */
+  uint8_t hi = (uint8_t)((len5 << 3) | hi_period);
+
+  if (channel == 0) {
+    PULSE1_VOL   = (uint8_t)(0xB0 | v);   /* duty 10 (50%), const vol, vol=v */
+    PULSE1_SWEEP = 0x08;                  /* sweep disabled */
+    PULSE1_LO    = lo;
+    PULSE1_HI    = hi;
+  } else if (channel == 1) {
+    PULSE2_VOL   = (uint8_t)(0xB0 | v);
+    PULSE2_SWEEP = 0x08;
+    PULSE2_LO    = lo;
+    PULSE2_HI    = hi;
+  } else {
+    /* triangle — no volume control, no envelope */
+    TRI_LINEAR   = 0xFF;                  /* linear counter max */
+    TRI_LO       = lo;
+    TRI_HI       = hi;
+  }
+}
+
+void sound_play_noise(uint8_t period_4bit, uint8_t vol_4bit, uint8_t length_frames) {
+  uint8_t len5 = length_frames & 0x1F;
+  NOISE_VOL = (uint8_t)(0x30 | (vol_4bit & 0x0F));  /* const vol */
+  NOISE_LO  = (uint8_t)(period_4bit & 0x0F);
+  NOISE_HI  = (uint8_t)(len5 << 3);
+  (void)length_table;  /* documentation; not used directly */
+}
+
+void sound_off(void) {
+  APUSTATUS = 0x00;
+}

package/src/platforms/nes/lib/c/nes_runtime.h

@@ -0,0 +1,153 @@
+/* ── nes_runtime.h — neslib-shaped runtime for cc65 NES builds ───
+ * Auto-included on every `buildSource({platform:"nes", language:"c"})`.
+ *
+ * API mirrors Shiru's neslib so existing tutorials port cleanly:
+ *
+ *   PPU control
+ *     ppu_off()            — disable rendering. Safe anytime.
+ *     ppu_on_all()         — enable BG + sprites. Use after init.
+ *     ppu_on_bg()          — enable BG only.
+ *     ppu_on_spr()         — enable sprites only.
+ *     ppu_wait_vblank()    — poll $2002 for vblank flag. Use during INIT,
+ *                            before rendering is enabled. Do not call in
+ *                            the game loop — use ppu_wait_nmi instead.
+ *     ppu_wait_nmi()       — wait until the next NMI fires (vblank-driven).
+ *                            Returns within ~1 frame. Use as the heartbeat
+ *                            of your game loop.
+ *
+ *   Palettes
+ *     palette_load(p32)    — write 32 bytes to $3F00. PPU must be off.
+ *
+ *   OAM (shadow buffer at $0200; NMI auto-DMAs each frame)
+ *     oam_clear()          — set all 64 sprites Y=$FF (off-screen).
+ *     oam_spr(x,y,tile,attr) — push one sprite to the next free slot.
+ *
+ *     ⚠ FRAME ORDER — the #1 NES footgun. Stage sprites (oam_clear +
+ *     oam_spr) BEFORE ppu_wait_nmi(), never after. The NMI handler DMAs
+ *     this shadow buffer → real OAM at the START of vblank, copying
+ *     whatever it holds at that instant. Correct loop:
+ *         for (;;) {
+ *             oam_clear();  oam_spr(...);  // stage FIRST
+ *             ppu_wait_nmi();              // NMI DMAs what you just staged
+ *             update_game();               // logic AFTER the wait
+ *         }
+ *     Flip it (wait, then stage) and the visible frame lags one frame /
+ *     shows stale or empty sprites. Every genre template uses this order.
+ *
+ *   Input (Shiru bit layout: A=$80, B=$40, ...)
+ *     pad_poll(0|1)        — read controller, return packed byte.
+ *
+ *   CHR-RAM (only in chr-ram preset — the default for C builds)
+ *     chr_ram_upload(ppu_addr, src, n) — copy tiles to pattern table.
+ *                            PPU must be off (rendering disabled). Set
+ *                            ppu_addr = 0x0000 for sprite tiles, 0x1000
+ *                            for BG tiles (or wherever your LCDC config
+ *                            points).
+ *
+ *   Nametable / VRAM queue (writes batched + flushed by NMI)
+ *     vram_set(ppu_addr, tile)       — queue a single byte write.
+ *     tile_set(nt, x, y, tile)       — queue write to nametable cell.
+ *     tile_set_palette(nt, x, y, p)  — queue attribute-table RMW.
+ *     vram_unsafe_set(ppu_addr, byte) — write directly (PPU must be off).
+ *     ppu_scroll(x, y)               — set scroll (NMI commits it).
+ *
+ *   System
+ *     ppu_system()         — 0 = NTSC, 1 = PAL. Detected at boot.
+ *
+ * Globals (live in BSS / ZP — read at your peril):
+ *
+ *   shadow_oam[256]   — at $0200. NMI DMAs this to $2003.
+ *   nmi_counter       — increments each NMI. Useful for "wait N frames".
+ */
+#ifndef NES_RUNTIME_H
+#define NES_RUNTIME_H
+
+#include <stdint.h>
+
+/* cc65 lacks <stdbool.h>; provide the basics. */
+typedef uint8_t bool;
+#define true  1
+#define false 0
+
+/* ── PPU control ──────────────────────────────────────────────── */
+void ppu_off(void);
+void ppu_on_all(void);
+void ppu_on_bg(void);
+void ppu_on_spr(void);
+void ppu_wait_vblank(void);
+void ppu_wait_nmi(void);
+uint8_t ppu_system(void);
+
+/* ── Palettes ─────────────────────────────────────────────────── */
+void palette_load(const uint8_t *pal32);
+
+/* ── OAM ──────────────────────────────────────────────────────── */
+void oam_clear(void);
+void oam_spr(uint8_t x, uint8_t y, uint8_t tile, uint8_t attr);
+
+/* ── Input ────────────────────────────────────────────────────── */
+uint8_t pad_poll(uint8_t which);
+
+/* Shiru bit layout — d-pad in LOW nybble, buttons in HIGH nybble. */
+#define PAD_A       0x80
+#define PAD_B       0x40
+#define PAD_SELECT  0x20
+#define PAD_START   0x10
+#define PAD_UP      0x08
+#define PAD_DOWN    0x04
+#define PAD_LEFT    0x02
+#define PAD_RIGHT   0x01
+
+/* ── CHR-RAM upload ────────────────────────────────────────────── */
+void chr_ram_upload(uint16_t ppu_addr, const uint8_t *src, uint16_t n);
+
+/* ── Nametable + VRAM queue ────────────────────────────────────── */
+/* Direct writes — PPU must be off (rendering disabled). Use during init. */
+void vram_unsafe_set(uint16_t ppu_addr, uint8_t byte);
+
+/* Queued writes — committed by the NMI handler next vblank. Safe during
+ * rendering. Queue holds 16 entries; flushes itself on overflow by
+ * waiting for the next NMI. */
+void vram_set(uint16_t ppu_addr, uint8_t tile);
+void tile_set(uint8_t nt, uint8_t x, uint8_t y, uint8_t tile);
+void tile_set_palette(uint8_t nt, uint8_t x, uint8_t y, uint8_t palette);
+
+/* Scroll. NMI commits these to PPUSCROLL/PPUCTRL at end of vblank. */
+void ppu_scroll(uint16_t x, uint16_t y);
+
+/* ── Sound (NES APU — pulse/triangle/noise channels) ──────────── */
+/*
+ * sound_init()
+ *     Enable the APU channels (writes $0F to $4015 — pulse1+pulse2+
+ *     triangle+noise on, DMC off) + set frame counter to 4-step mode
+ *     (writes $40 to $4017 to disable frame IRQ). Call once at boot.
+ *
+ * sound_play_tone(channel, period, vol_4bit, length_frames)
+ *     Trigger a tone on `channel` (0 = pulse1, 1 = pulse2, 2 = triangle).
+ *     `period` is the 11-bit NES timer value (lower = higher pitch):
+ *       A4 = $0FD   C5 = $1AA   G5 = $0FE   C6 = $0D6
+ *       (formula: 1789773 / (16 * Hz) - 1)
+ *     `vol_4bit` (0-15) is volume — ignored for triangle (always max).
+ *     `length_frames` (0-31) maps into the APU length-counter table
+ *     (roughly N * 16ms).
+ *
+ * sound_play_noise(period, vol_4bit, length_frames)
+ *     Trigger a noise burst on channel 3. `period` is 0-15 (rate index);
+ *     8-15 = lower-pitched noise, 0-7 = high. Good for hit/explosion SFX.
+ *
+ * sound_off()
+ *     Silences all channels (writes $00 to $4015).
+ *
+ * These are fire-and-forget — the APU's length counter cuts off the
+ * note after `length_frames`. No per-frame upkeep needed.
+ */
+void sound_init(void);
+void sound_play_tone(uint8_t channel, uint16_t period, uint8_t vol_4bit, uint8_t length_frames);
+void sound_play_noise(uint8_t period_4bit, uint8_t vol_4bit, uint8_t length_frames);
+void sound_off(void);
+
+/* ── Globals ──────────────────────────────────────────────────── */
+extern uint8_t shadow_oam[256];       /* at $0200, DMA'd by NMI */
+extern volatile uint8_t nmi_counter;  /* increments each NMI */
+
+#endif /* NES_RUNTIME_H */

package/src/platforms/nes/lib/c/nmi_handler.c

@@ -0,0 +1,51 @@
+/* nmi_handler.c — install a C-level NMI handler for NES.
+ *
+ * REQUIRES: linkerConfig:"chr-ram" AND `nmi_trampoline.s` (paste both).
+ *
+ * Pattern: the chr-ram crt0's default `nmi: rti` is overridden by the
+ * trampoline .s in this snippet pair, which calls into your C function.
+ * The trampoline saves/restores A/X/Y around the call (the C function
+ * uses cc65's __fastcall__ convention, which is reg-clobbering).
+ *
+ * PITFALLS:
+ *   - DO NOT include this when also using the chr-ram crt0's default
+ *     stub — they both define `nmi:`. The trampoline below assumes
+ *     you've also dropped the crt0's `nmi: rti` (or replaced the
+ *     whole crt0 with a custom one — see the comments in
+ *     src/toolchains/cc65/presets/nes/chr-ram.crt0.s).
+ *
+ *     Easiest path: don't override the default crt0 here. Instead just
+ *     don't include nmi_trampoline.s, and put your "wait for vblank"
+ *     pattern in main() using `bit $2002 / bpl` via inline asm or by
+ *     polling `*(volatile uint8_t*)0x2002`. The default `nmi: rti`
+ *     still fires (so PPU vblank flag DOES tick) — you just won't run
+ *     custom code at that moment.
+ *
+ *   - If you do install a real NMI handler, keep it SHORT. Vblank is
+ *     ~2270 cycles; cc65 prologue/epilogue eats ~50; OAM DMA eats 513.
+ *     That leaves ~1700 for the rest of your vblank work.
+ *
+ *   - The `vblank_ready` flag below lets main() wait for the NMI:
+ *       while (!vblank_ready) { }
+ *       vblank_ready = 0;
+ *       // now safe to write PPU regs
+ */
+
+#include <stdint.h>
+
+volatile uint8_t vblank_ready;
+volatile uint8_t nmi_count;
+
+/* This is the C-side handler the trampoline jumps to. Name + signature
+ * are coupled to nmi_trampoline.s — change both together. */
+void __fastcall__ nmi_c_main(void) {
+    /* 1. OAM DMA: shadow OAM at $0200..$02FF → sprite RAM. 513 cycles. */
+    *(volatile uint8_t*)0x2003 = 0;       /* OAMADDR = 0 */
+    *(volatile uint8_t*)0x4014 = 0x02;    /* OAMDMA from $0200 */
+
+    /* 2. Bump frame counter and signal main(). */
+    nmi_count++;
+    vblank_ready = 1;
+
+    /* 3. ADD MORE HERE: palette upload, scroll, nametable updates. */
+}

package/src/platforms/nes/lib/c/nmi_trampoline.s

@@ -0,0 +1,25 @@
+; nmi_trampoline.s — paste together with nmi_handler.c.
+;
+; Replaces the chr-ram preset crt0's default `nmi: rti` stub by
+; exporting `nmi` here and calling into the C-side handler. ALSO
+; REQUIRES: remove the `nmi: rti` line from the preset crt0 (paste
+; the crt0 into your own sources, edit, and include it instead of
+; relying on the auto-included preset). Otherwise ca65 errors with
+; "symbol `nmi` already defined".
+
+.export nmi
+.import _nmi_c_main
+
+nmi:
+    pha
+    txa
+    pha
+    tya
+    pha
+    jsr _nmi_c_main
+    pla
+    tay
+    pla
+    tax
+    pla
+    rti

package/src/platforms/nes/lib/cc65-src/Makefile.inc

@@ -0,0 +1,9 @@
+../target/nes/drv/tgi/nes-64-56-2.tgi:  \
+                ../libwrk/nes/clrscr.o  \
+                ../libwrk/nes/cputc.o   \
+                ../libwrk/nes/get_tv.o  \
+                ../libwrk/nes/gotoxy.o  \
+                ../libwrk/nes/popa.o    \
+                ../libwrk/nes/ppu.o     \
+                ../libwrk/nes/ppubuf.o  \
+                ../libwrk/nes/setcursor.o

package/src/platforms/nes/lib/cc65-src/_scrsize.s

@@ -0,0 +1,24 @@
+;
+; Ullrich von Bassewitz, 2003-04-14
+; Stefan Haubenthal, 2011-05-11
+;
+; Screen size function
+;
+
+        .export         screensize
+
+        .include        "nes.inc"
+        .include        "get_tv.inc"
+
+
+.proc   screensize
+
+        jsr     _get_tv
+        ldx     #charsperline
+        ldy     #screenrows
+        cmp     #TV::PAL
+        beq     pal
+        dey             ; NTSC rows
+pal:    rts
+
+.endproc

package/src/platforms/nes/lib/cc65-src/cclear.s

@@ -0,0 +1,29 @@
+;
+; Ullrich von Bassewitz, 08.08.1998
+;
+; void cclearxy (unsigned char x, unsigned char y, unsigned char length);
+; void cclear (unsigned char length);
+;
+
+        .export         _cclearxy, _cclear
+        .import         gotoxy, cputdirect
+        .importzp       tmp1
+
+_cclearxy:
+        pha                     ; Save the length
+        jsr     gotoxy          ; Call this one, will pop params
+        pla                     ; Restore the length and run into _cclear
+
+_cclear:
+        cmp     #0              ; Is the length zero?
+        beq     L9              ; Jump if done
+        sta     tmp1
+L1:     lda     #$20            ; Blank - screen code
+        jsr     cputdirect      ; Direct output
+        dec     tmp1
+        bne     L1
+L9:     rts
+
+
+
+

package/src/platforms/nes/lib/cc65-src/chline.s

@@ -0,0 +1,31 @@
+;
+; Ullrich von Bassewitz, 08.08.1998
+;
+; void chlinexy (unsigned char x, unsigned char y, unsigned char length);
+; void chline (unsigned char length);
+;
+
+        .export         _chlinexy, _chline
+        .import         gotoxy, cputdirect
+        .importzp       tmp1
+
+        .include        "nes.inc"
+
+_chlinexy:
+        pha                     ; Save the length
+        jsr     gotoxy          ; Call this one, will pop params
+        pla                     ; Restore the length
+
+_chline:
+        cmp     #0              ; Is the length zero?
+        beq     L9              ; Jump if done
+        sta     tmp1
+L1:     lda     #CH_HLINE       ; Horizontal line, screen code
+        jsr     cputdirect      ; Direct output
+        dec     tmp1
+        bne     L1
+L9:     rts
+
+
+
+