romdev-mcp 0.1.1

package/src/platforms/gbc/lib/c/gb_runtime.c

@@ -0,0 +1,284 @@
+/* ── gb_runtime.c — GBDK-lite helper implementations ───────────────
+ * Auto-linked into every GB/GBC build that uses `language:"c"`.
+ * See gb_runtime.h for the function list.
+ */
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+/* When `enable_vblank_irq()` has been called, wait_vblank uses HALT +
+ * the vblank IRQ to sleep until the next vblank — fast on hardware
+ * AND on the WASM emulator (where the busy-poll fallback below spins
+ * through many WASM-time iterations per emulated LY tick, dropping
+ * the game loop to ~1/30 of intended speed — round 26 friction). */
+static uint8_t vblank_irq_enabled;
+
+void enable_vblank_irq(void) {
+  IF_REG = 0;            /* clear pending interrupts */
+  IE_REG = IE_VBLANK;    /* enable VBlank only */
+  vblank_irq_enabled = 1;
+  __asm__("ei");         /* allow IRQs to be serviced */
+}
+
+void wait_vblank(void) {
+  /* If the LCD is off, LY is frozen at 0 and we'd hang forever. Bail. */
+  if (!(LCDC & LCDC_LCD_ON)) return;
+  if (vblank_irq_enabled) {
+    /* HALT blocks the CPU until any enabled IRQ fires. With only the
+     * vblank IRQ enabled, this is "sleep until vblank, ~10 cycles
+     * total per wait." gb_crt0.s vectors $0040 to `reti` which is
+     * exactly what we need — no handler body required, just a wake.
+     *
+     * Round 27 defensive: explicitly NOP after HALT to dodge the
+     * famous DMG "HALT bug" — if IME=0 and (IF & IE) != 0 at the
+     * moment HALT executes, the CPU skips HALT and duplicates the
+     * BYTE that follows. With a NOP in that slot the duplication is
+     * harmless. We always run HALT with IME=1 here (enable_vblank_irq
+     * leaves IME enabled), so the bug shouldn't fire — but agents
+     * have reported "wait_vblank seems involved in long-running
+     * corruption" symptoms and this is a 1-byte insurance policy. */
+    __asm__("halt");
+    __asm__("nop");
+    return;
+  }
+  /* Polling fallback: spin on LY until it crosses into vblank. Fine on
+   * real hardware (the CPU is faster than the LCD), DRAMATICALLY slow
+   * on the WASM emulator (~1/30 of intended speed). Call
+   * `enable_vblank_irq()` once at boot to switch to the HALT path. */
+  while (LY >= 144) { }
+  while (LY <  144) { }
+}
+
+/* Read JOYP into a packed byte. Safe anytime — independent of LCD
+ * state, vblank, etc. Returns 1 = pressed, 0 = not (after inverting
+ * the hardware's active-low signal).
+ *
+ * Bit layout (matches the PAD_* masks):
+ *   bit 7 Down  bit 6 Up  bit 5 Left  bit 4 Right    ← d-pad HIGH nybble
+ *   bit 3 Start bit 2 Sel bit 1 B     bit 0 A        ← buttons LOW nybble
+ *
+ * Gotcha: d-pad is in the HIGH nybble (opposite of what you might
+ * intuit). `pad & PAD_RIGHT` works because PAD_RIGHT = 0x10.
+ */
+uint8_t joypad_read(void) {
+  uint8_t dpad, btns;
+  /* Select dpad row (bit 4 = 0). */
+  JOYP = 0x20;
+  /* Settle: re-read a few times so port wires reach the chip. */
+  dpad = JOYP; dpad = JOYP; dpad = JOYP;
+  dpad = (uint8_t)((~dpad) & 0x0F);
+
+  /* Select button row (bit 5 = 0). */
+  JOYP = 0x10;
+  btns = JOYP; btns = JOYP; btns = JOYP;
+  btns = (uint8_t)((~btns) & 0x0F);
+
+  /* Deselect both rows. */
+  JOYP = 0x30;
+  return (uint8_t)((dpad << 4) | btns);
+}
+
+/* ── OAM DMA — the HRAM-stub idiom (R55 fix) ────────────────────────
+ *
+ * The GB OAM DMA engine ($FF46) transfers 160 bytes from `$XX00` (high
+ * byte set by the write) to OAM at $FE00-$FE9F. It takes ~160 µs
+ * (~640 cycles) and during that window **the CPU can only access
+ * HRAM ($FF80-$FFFE) + a couple of I/O registers**. Reads from ROM /
+ * WRAM / VRAM during DMA return $FF on real hardware.
+ *
+ * The "$FF returned for instruction fetch" bug is nasty: $FF decodes
+ * as `rst $38`, which CALLs $0038. gb_crt0.s vectors $0038 to a bare
+ * `ret`, which pops the stack — but the stack just had the rst's
+ * return address pushed, so we return to PC+1. Effectively the CPU
+ * skips one byte. Eventually a misaligned fetch lands as the operand
+ * of an earlier instruction and you jump into garbage. Common symptom:
+ * LCDC silently flips to $FF (the byte the CPU "saw" off of ROM
+ * during a DMA window for an unrelated I/O write), BG VRAM at
+ * $9800-$9BFF gets a wild burst of zeros, etc. Many emulators (incl.
+ * gambatte) don't enforce the DMA-bus-conflict rule strictly which is
+ * why the broken pattern "worked" in light testing — but the bug
+ * shows up under longer / different code paths (round 27).
+ *
+ * The canonical fix: install a tiny stub in HRAM that does the DMA
+ * register write + spin + return, then CALL the HRAM stub. The stub
+ * itself executes from HRAM (allowed during DMA), so the fetch never
+ * hits ROM/WRAM. After the spin ends, control returns to wherever
+ * called us and normal bus access resumes.
+ *
+ * HRAM stub (placed at $FF80):
+ *   F0 46 / E0 46  ;   ldh ($46), a    — write DMA register (start)
+ *   3E 28         ;   ld  a, 40        — spin counter (160 / 4 = 40)
+ *   3D            ; - dec a
+ *   20 FD         ;   jr  nz, -3       — back to dec a
+ *   C9            ;   ret
+ * Total: 9 bytes. We install it at boot from `oam_dma_init_hram()`.
+ */
+
+#define HRAM_DMA_STUB ((uint8_t *)0xFF80)
+
+/* Install the OAM-DMA HRAM stub. Call once at boot (before any
+ * `oam_dma_flush()`). The bundled bootstrap can do this for you;
+ * games that bypass the bootstrap should call this themselves. */
+void oam_dma_init_hram(void) {
+  /* Stub bytes — see comment block above. */
+  static const uint8_t stub[] = {
+    0xE0, 0x46,             /* ldh ($46), a — start DMA from page in A */
+    0x3E, 0x28,             /* ld  a, 40    — spin counter */
+    0x3D,                   /* dec a        ─┐ */
+    0x20, 0xFD,             /* jr nz, -3    ─┘  spin while a != 0 */
+    0xC9,                   /* ret */
+  };
+  uint8_t i;
+  for (i = 0; i < sizeof(stub); i++) {
+    HRAM_DMA_STUB[i] = stub[i];
+  }
+}
+
+/* OAM DMA — copy 160 bytes from `src` to OAM ($FE00-$FE9F) via the
+ * HRAM stub installed by oam_dma_init_hram(). Caller passes the source
+ * pointer; we extract the high byte (DMA reads source as `src >> 8`)
+ * and CALL the HRAM stub. The stub executes from HRAM (the only
+ * memory the CPU can fetch from during DMA) so we don't trip the
+ * ROM-bus-conflict bug.
+ *
+ * Should be called during VBlank — DMA writes to OAM and OAM is
+ * inaccessible to the PPU during scanline drawing, so a mid-frame
+ * DMA flush will flash sprite glitches. */
+void oam_dma_copy(void *src) {
+  /* Build a function pointer to the HRAM stub. SDCC sm83 calling
+   * convention passes the first uint8_t arg in register A — which is
+   * what `ldh ($46), a` consumes inside the stub. */
+  void (*hram_dma)(uint8_t) = (void (*)(uint8_t))HRAM_DMA_STUB;
+  hram_dma((uint8_t)(((uint16_t)src) >> 8));
+}
+
+void memcpy_vram(void *dst, const void *src, uint16_t n) {
+  /* Safe VRAM access is in modes 0 (HBlank), 1 (VBlank), or with the LCD
+   * off. Caller is expected to ensure one of those — usually by calling
+   * wait_vblank() first. We just do the byte copy. */
+  uint8_t *d = (uint8_t *)dst;
+  const uint8_t *s = (const uint8_t *)src;
+  while (n) {
+    *d++ = *s++;
+    n--;
+  }
+}
+
+void lcd_init_default(void) {
+  /* Install the OAM-DMA HRAM stub. Idempotent — installing it more
+   * than once just rewrites the same bytes. Doing it here (rather
+   * than in crt0) means single-file projects that include this
+   * runtime get the fix without having to call it themselves. */
+  oam_dma_init_hram();
+
+  /* If the LCD is on, wait for vblank so it's safe to turn it off.
+   * If it's already off (typical at boot — DMG/CGB power-up has LCDC=0x91
+   * on Nintendo-bootrom paths but LCDC=0 in many homebrew startups), skip
+   * the wait — LY is frozen at 0 with the LCD off, so a blind
+   * `while (LY < 144)` would hang the whole game. */
+  if (LCDC & LCDC_LCD_ON) {
+    while (LY < 144) { }
+  }
+  LCDC = 0;
+  BGP  = 0xE4;
+  OBP0 = 0xE0;
+  OBP1 = 0xE0;
+  SCY  = 0;
+  SCX  = 0;
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+}
+
+/* ── OAM helpers ──────────────────────────────────────────────────
+ * shadow_oam mirrors hardware OAM ($FE00, 40 sprites × 4 bytes). Build
+ * your sprite list here each frame, then call oam_dma_flush() in
+ * vblank to push to the LCD.
+ *
+ * Hardware OAM byte layout per sprite:
+ *   +0  Y position (real Y = this - 16; 0 hides, 16 = top of screen)
+ *   +1  X position (real X = this - 8;  0 hides, 8  = left of screen)
+ *   +2  Tile index
+ *   +3  Attributes (palette / flip / priority / CGB palette + VRAM bank)
+ *
+ * Round 26 footgun fix: shadow_oam MUST be page-aligned. The OAM DMA
+ * engine takes ONLY the high byte of the source address — it always
+ * copies 160 bytes from `$XX00` to OAM. If shadow_oam happens to land
+ * at e.g. $C017, oam_dma_copy(&shadow_oam) latches DMA = $C0 and the
+ * hardware DMA's $C000..$C09F (NOT $C017..$C0B6). Result: silent
+ * garbage in OAM, sprites never appear where you put them.
+ *
+ * We pin shadow_oam at $C100 with SDCC's `__at` attribute. WRAM is
+ * 8 KB at $C000-$DFFF on DMG, so $C100..$C19F leaves $C000-$C0FF for
+ * static initialisers + the first 256 bytes of stack growth, and the
+ * gsinit region in gb_crt0.s lives in ROM. No conflict.
+ *
+ * If your game needs a custom OAM buffer location, declare your own
+ * with `__at(0xCXYZ)` where Y in 0..F, ZX = 0, and pass it to
+ * oam_dma_copy() directly. Whatever address you pick, the low byte
+ * MUST be $00.
+ */
+__at (0xC100) uint8_t shadow_oam[160];
+
+void oam_clear(void) {
+  uint16_t i;
+  for (i = 0; i < 160; i++) shadow_oam[i] = 0;
+}
+
+void oam_set(uint8_t slot, uint8_t y, uint8_t x, uint8_t tile, uint8_t attr) {
+  uint16_t off = (uint16_t)slot << 2;  /* slot * 4 */
+  shadow_oam[off + 0] = y;
+  shadow_oam[off + 1] = x;
+  shadow_oam[off + 2] = tile;
+  shadow_oam[off + 3] = attr;
+}
+
+void oam_dma_flush(void) {
+  oam_dma_copy(shadow_oam);
+}
+
+/* ── Sound ──────────────────────────────────────────────────────── */
+
+void sound_init(void) {
+  /* APU off → on sequence per nesdev wiki "Sound startup":
+   *   NR52 = 0x00 → power off all channels (clears NR10-NR41 to 0)
+   *   NR52 = 0x80 → power on
+   *   NR50 = 0x77 → max volume both speakers (3 bits per side)
+   *   NR51 = 0xFF → all 4 channels routed to both speakers
+   */
+  NR52 = 0x00;
+  NR52 = 0x80;
+  NR50 = 0x77;
+  NR51 = 0xFF;
+}
+
+void sound_play_tone(uint8_t channel, uint16_t freq_period, uint8_t length_frames) {
+  /* freq_period is the 11-bit GB frequency code. Lower = higher pitch.
+   * Length register (NR11/NR21) sets a 64-step countdown; we map
+   * `length_frames` (~4ms each) to that scale: 64 - min(length_frames, 63).
+   */
+  uint8_t len_code = (length_frames >= 63) ? 0 : (uint8_t)(64 - length_frames);
+  uint8_t lo = (uint8_t)(freq_period & 0xFF);
+  uint8_t hi = (uint8_t)((freq_period >> 8) & 0x07);
+  if (channel == 1) {
+    NR10 = 0x00;                       /* no sweep */
+    NR11 = (uint8_t)(0x80 | len_code); /* 50% duty + length */
+    NR12 = 0xF0;                       /* full volume, no envelope */
+    NR13 = lo;
+    NR14 = (uint8_t)(0xC0 | hi);       /* trigger + length-enable + hi 3 bits */
+  } else {
+    NR21 = (uint8_t)(0x80 | len_code);
+    NR22 = 0xF0;
+    NR23 = lo;
+    NR24 = (uint8_t)(0xC0 | hi);
+  }
+}
+
+void sound_play_noise(uint8_t length_frames) {
+  uint8_t len_code = (length_frames >= 63) ? 0 : (uint8_t)(64 - length_frames);
+  NR41 = len_code;
+  NR42 = 0xF0;          /* full volume, no envelope */
+  NR43 = 0x33;          /* mid-pitch noise */
+  NR44 = 0xC0;          /* trigger + length-enable */
+}
+
+void sound_off(void) {
+  NR52 = 0x00;
+}

package/src/platforms/gbc/lib/c/gb_runtime.h

@@ -0,0 +1,145 @@
+/* ── gb_runtime.h — GBDK-lite helpers (auto-included on gb/gbc C builds) ──
+ * Function declarations only; implementations are in gb_runtime.c which
+ * the build wires in automatically. Pair with gb_hardware.h for the I/O
+ * register names.
+ *
+ * Functions:
+ *   void     wait_vblank(void);
+ *       Busy-wait until the next vblank starts. SAFE WHEN LCD IS OFF —
+ *       returns immediately rather than hanging (LY is frozen at 0 with
+ *       LCD off; a blind LY-wait would never exit).
+ *
+ *   uint8_t  joypad_read(void);
+ *       Read JOYP into a packed byte. SAFE ANYTIME.
+ *
+ *   void     oam_dma_copy(void *src);
+ *       DMA-copy 160 bytes from `src` to OAM ($FE00). Caller should
+ *       have built the 40-sprite shadow buffer in WRAM/HRAM first. Best
+ *       called during vblank; works outside vblank too but the sprite
+ *       table will glitch for one frame.
+ *
+ *   void     memcpy_vram(void *dst, const void *src, uint16_t n);
+ *       memcpy with no special timing. Caller is responsible for
+ *       picking a VRAM-safe window (vblank, hblank, or LCD off).
+ *
+ *   void     lcd_init_default(void);
+ *       DMG defaults: BGP=$E4, OBP0/1=$E0, SCY/SCX=0, then turn LCD on
+ *       with BG + OBJ enabled. SAFE TO CALL WHEN LCD IS OFF — checks
+ *       LCDC.7 first instead of blindly waiting for vblank.
+ *
+ *   void     oam_clear(void);
+ *       Zero the 160-byte `shadow_oam` array. Call once at boot to make
+ *       sure all 40 slots are off-screen.
+ *
+ *   void     oam_set(uint8_t slot, uint8_t y, uint8_t x, uint8_t tile, uint8_t attr);
+ *       Write one slot of the shadow OAM. `slot` is 0..39. `y` and `x`
+ *       are screen coords + 16 / + 8 respectively (the hardware quirk:
+ *       Y=0 hides the sprite, Y=16 is the top edge of the screen;
+ *       X=0 hides, X=8 is the left edge). `oam_dma_flush` to push to HW.
+ *
+ *   void     oam_dma_flush(void);
+ *       DMA `shadow_oam` → real OAM ($FE00). Call once per frame in
+ *       vblank, AFTER you've staged sprites with `oam_set`.
+ *
+ * Globals:
+ *   extern uint8_t shadow_oam[160];
+ *       40 sprites × 4 bytes (Y, X, tile, attr). Cleared by oam_clear,
+ *       populated by oam_set, copied to hardware by oam_dma_flush.
+ *
+ * Joypad packed-byte layout (1 = pressed, after inverting hw active-low):
+ *   bit 7 Down  bit 6 Up  bit 5 Left  bit 4 Right    ← d-pad HIGH nybble
+ *   bit 3 Start bit 2 Sel bit 1 B     bit 0 A        ← buttons LOW nybble
+ */
+#ifndef GB_RUNTIME_H
+#define GB_RUNTIME_H
+
+#include <stdint.h>
+
+void    wait_vblank(void);
+
+/* Switch wait_vblank() from busy-poll-LY to HALT-driven (interrupt
+ * wake). Strongly recommended — busy-poll wait_vblank runs at ~1/30
+ * intended speed on the WASM emulator because LY only updates at
+ * stepFrames quantum boundaries. Call once at boot after lcd_init_*.
+ * Safe to call before lcd_init_default (the HALT path checks LCDC
+ * before sleeping).
+ *
+ * Once enabled, wait_vblank() sleeps the CPU until the vblank IRQ
+ * fires (~10 cycles per wait instead of thousands of LY-polls). The
+ * IRQ handler in gb_crt0.s is just `reti` — its job is to wake the
+ * CPU, not to do any work.
+ *
+ * Implementation: writes IE_REG = IE_VBLANK + clears IF_REG + executes
+ * EI. After that, every wait_vblank() compiles to a HALT instead of
+ * the LY-polling busy loop. */
+void    enable_vblank_irq(void);
+
+uint8_t joypad_read(void);
+void    oam_dma_copy(void *src);
+void    memcpy_vram(void *dst, const void *src, uint16_t n);
+void    lcd_init_default(void);
+
+/* Install the OAM-DMA HRAM stub at $FF80. Call ONCE at boot before
+ * any `oam_dma_flush()` / `oam_dma_copy()`. `lcd_init_default()` calls
+ * it for you; only call directly if you're bypassing lcd_init_default.
+ *
+ * Why this is mandatory (R55 fix): during OAM DMA the CPU can only
+ * fetch from HRAM. Pre-r55 oam_dma_copy spun in main code, fetching
+ * $FF (the bus-conflict default) for every instruction — that decodes
+ * as `rst $38` which corrupts the stack. Symptom under long-running
+ * code: LCDC flips to $FF, BG tile map wiped to zeros, sprites jump.
+ * The HRAM stub fixes it by running the spin from HRAM where DMA
+ * doesn't conflict. */
+void    oam_dma_init_hram(void);
+
+void    oam_clear(void);
+void    oam_set(uint8_t slot, uint8_t y, uint8_t x, uint8_t tile, uint8_t attr);
+void    oam_dma_flush(void);
+
+/* shadow_oam is page-aligned at $C100 because OAM DMA uses only the
+ * high byte of the source address and always copies 160 bytes from
+ * `$XX00`. The `__at` annotation MUST appear on BOTH the extern AND
+ * the definition (in gb_runtime.c) — without it SDCC raises "extern
+ * definition mismatches". Round 26 footgun fix; see gb_runtime.c. */
+extern __at (0xC100) uint8_t shadow_oam[160];
+
+/* ── Sound (Game Boy 4-channel APU) ────────────────────────────── */
+/*
+ * sound_init()
+ *     Power on the APU (NR52 bit 7), set master volume to max,
+ *     route both speakers. Call once at boot. Safe anytime.
+ *
+ * sound_play_tone(channel, freq_period, length_frames)
+ *     Trigger a square-wave note on channel 1 (sweep ch) or 2.
+ *     `freq_period` is the 11-bit GB frequency code: lower = higher
+ *     pitch. Common notes:
+ *       A4 = 1750   C5 = 1798   G5 = 1953   C6 = 1923
+ *       (formula: 2048 - (131072 / Hz))
+ *     `length_frames` ≈ N×4ms playback duration before envelope cuts off.
+ *     Channels are { 1 = sweep square, 2 = plain square }.
+ *
+ * sound_play_noise(length_frames)
+ *     Trigger a short noise burst on channel 4 — useful for hit/explosion
+ *     SFX. Length in frame-equivalents.
+ *
+ * sound_off()
+ *     Power down the APU (NR52 = 0). All 4 channels go silent.
+ *
+ * These helpers are fire-and-forget — the APU plays autonomously
+ * after one trigger. No per-frame upkeep needed.
+ */
+void    sound_init(void);
+void    sound_play_tone(uint8_t channel, uint16_t freq_period, uint8_t length_frames);
+void    sound_play_noise(uint8_t length_frames);
+void    sound_off(void);
+
+#define PAD_DOWN    0x80
+#define PAD_UP      0x40
+#define PAD_LEFT    0x20
+#define PAD_RIGHT   0x10
+#define PAD_START   0x08
+#define PAD_SELECT  0x04
+#define PAD_B       0x02
+#define PAD_A       0x01
+
+#endif /* GB_RUNTIME_H */

package/src/platforms/gbc/lib/c/hUGEDriver.c

@@ -0,0 +1,191 @@
+/* ── hUGEDriver.c — compact SDCC-native music driver for Game Boy ──
+ *
+ * See hUGEDriver.h for the song-format contract. This file is the
+ * implementation. ~150 lines, C89 (SDCC sm83 friendly).
+ *
+ * What it does each tick:
+ *   1. Decrement `tick_counter`. If still > 0, return.
+ *   2. tick_counter <- ticks_per_row, advance to next row.
+ *   3. For each enabled channel:
+ *        a. Read the (note, flags) pair for this row from the current pattern.
+ *        b. If note is 0..71 and flags bit 7 = 0 → trigger that note on that channel.
+ *        c. If flags bit 7 = 1 (sustain) → leave APU alone.
+ *        d. If note == 0xFF (rest) → silence the channel (NRx2 = 0).
+ *   4. If row index hits HUGE_ROWS_PER_PATTERN, advance order index.
+ *      If order index hits order_cnt, wrap to 0 (loop forever).
+ *
+ * What it deliberately does NOT do (vs. upstream hUGEDriver):
+ *   - No instruments (envelope/sweep/duty are hard-coded per channel).
+ *   - No effects (vibrato, slide, arpeggio, etc.).
+ *   - No subpatterns.
+ *   - No wave channel (CH3) — silent for now.
+ *
+ * Swap in upstream by replacing this .c + the .h's struct definitions with
+ * the upstream .h and the `rgb2sdas.py`-converted hUGEDriver.o.
+ */
+
+#include "gb_hardware.h"
+#include "hUGEDriver.h"
+
+/* ── 72-entry note table (C3..B8), copied from upstream hUGE_note_table.inc.
+ * Each entry is the 11-bit GB frequency period; lower = lower pitch.
+ * https://github.com/SuperDisk/hUGEDriver/blob/master/include/hUGE_note_table.inc */
+static const uint16_t hUGE_note_table[72] = {
+    44, 156, 262, 363, 457, 547, 631, 710, 786, 854, 923, 986,
+  1046,1102,1155,1205,1253,1297,1339,1379,1417,1452,1486,1517,
+  1546,1575,1602,1627,1650,1673,1694,1714,1732,1750,1767,1783,
+  1798,1812,1825,1837,1849,1860,1871,1881,1890,1899,1907,1915,
+  1923,1930,1936,1943,1949,1954,1959,1964,1969,1974,1978,1982,
+  1985,1988,1992,1995,1998,2001,2004,2006,2009,2011,2013,2015
+};
+
+/* ── Driver state ──────────────────────────────────────────────── */
+
+static const huge_song_t * cur_song;
+static uint8_t   tick_counter;     /* counts down to next row */
+static uint8_t   row_index;        /* 0 .. HUGE_ROWS_PER_PATTERN-1 */
+static uint8_t   order_index[4];   /* per-channel order list cursor */
+static uint8_t   mute_mask;        /* bit n = channel n+1 muted */
+
+/* ── Helpers ───────────────────────────────────────────────────── */
+
+static void trigger_square(uint8_t channel, uint16_t period) {
+  uint8_t lo;
+  uint8_t hi;
+  lo = (uint8_t)(period & 0xFFu);
+  hi = (uint8_t)((period >> 8) & 0x07u);
+  if (channel == HT_CH1) {
+    NR10 = 0x00;                  /* no sweep */
+    NR11 = 0x80;                  /* 50% duty, length 0 (so length counter never silences) */
+    NR12 = 0xF0;                  /* full volume, no envelope */
+    NR13 = lo;
+    NR14 = (uint8_t)(0x80 | hi);  /* trigger, length disable */
+  } else {                        /* HT_CH2 */
+    NR21 = 0x80;
+    NR22 = 0xF0;
+    NR23 = lo;
+    NR24 = (uint8_t)(0x80 | hi);
+  }
+}
+
+static void silence_square(uint8_t channel) {
+  /* Setting NRx2 (volume/envelope) to 0 with bits 3..7 clear is the
+   * canonical "DAC off" — instantly silences the channel. */
+  if (channel == HT_CH1) {
+    NR12 = 0x00;
+    NR14 = 0x80;   /* re-trigger so the silence takes effect immediately */
+  } else {
+    NR22 = 0x00;
+    NR24 = 0x80;
+  }
+}
+
+static void trigger_noise(uint8_t note) {
+  /* Map low note index to a noise frequency. The noise channel's NR43
+   * "shift clock" controls pitch; we let the song supply a coarse 0..7
+   * range via the low 3 bits of note. */
+  uint8_t shift;
+  shift = (uint8_t)(note & 0x07u);
+  NR41 = 0x00;                                /* length 0 */
+  NR42 = 0xF0;                                /* full volume, no envelope */
+  NR43 = (uint8_t)((shift << 4) | 0x03u);     /* mid divisor */
+  NR44 = 0x80;                                /* trigger, length disable */
+}
+
+static void silence_noise(void) {
+  NR42 = 0x00;
+  NR44 = 0x80;
+}
+
+/* Process one row for one channel. */
+static void channel_step(uint8_t channel, const huge_channel_t * ch) {
+  const huge_row_t * pattern;
+  uint8_t           note;
+  uint8_t           flags;
+  uint8_t           muted;
+  uint8_t           oi;
+
+  if (!ch->enabled || ch->order_cnt == 0) return;
+  muted = (uint8_t)(mute_mask & (1u << channel));
+  oi = order_index[channel];
+  if (oi >= ch->order_cnt) oi = 0;
+  pattern = ch->orders[oi];
+  note  = pattern[row_index].note;
+  flags = pattern[row_index].flags;
+  if (flags & 0x80u) return;        /* sustain — leave APU alone */
+
+  if (note == HUGE_NOTE_REST) {
+    if (channel == HT_CH1 || channel == HT_CH2) silence_square(channel);
+    else if (channel == HT_CH4)                 silence_noise();
+    return;
+  }
+  if (muted) return;
+  if (note >= 72) return;
+
+  if (channel == HT_CH1 || channel == HT_CH2) {
+    trigger_square(channel, hUGE_note_table[note]);
+  } else if (channel == HT_CH4) {
+    trigger_noise(note);
+  }
+  /* CH3 (wave) intentionally silent in this compact driver. */
+}
+
+/* ── Public API ───────────────────────────────────────────────────── */
+
+void hUGE_init(const huge_song_t * song) {
+  uint8_t i;
+  cur_song     = song;
+  tick_counter = 1;          /* fire row 0 on the very first hUGE_dosound */
+  row_index    = 0;
+  mute_mask    = 0;
+  for (i = 0; i < 4; i++) order_index[i] = 0;
+  /* Stop any lingering tones. */
+  silence_square(HT_CH1);
+  silence_square(HT_CH2);
+  silence_noise();
+}
+
+void hUGE_dosound(void) {
+  if (cur_song == 0) return;
+  tick_counter--;
+  if (tick_counter != 0) return;
+  tick_counter = cur_song->ticks_per_row;
+  if (tick_counter == 0) tick_counter = 1;
+
+  channel_step(HT_CH1, &cur_song->ch1);
+  channel_step(HT_CH2, &cur_song->ch2);
+  channel_step(HT_CH3, &cur_song->ch3);
+  channel_step(HT_CH4, &cur_song->ch4);
+
+  row_index++;
+  if (row_index >= HUGE_ROWS_PER_PATTERN) {
+    row_index = 0;
+    order_index[0]++;
+    order_index[1]++;
+    order_index[2]++;
+    order_index[3]++;
+    if (cur_song->ch1.order_cnt && order_index[0] >= cur_song->ch1.order_cnt) order_index[0] = 0;
+    if (cur_song->ch2.order_cnt && order_index[1] >= cur_song->ch2.order_cnt) order_index[1] = 0;
+    if (cur_song->ch3.order_cnt && order_index[2] >= cur_song->ch3.order_cnt) order_index[2] = 0;
+    if (cur_song->ch4.order_cnt && order_index[3] >= cur_song->ch4.order_cnt) order_index[3] = 0;
+  }
+}
+
+void hUGE_mute_channel(enum hUGE_channel_t ch, enum hUGE_mute_t mute) {
+  uint8_t bit;
+  bit = (uint8_t)(1u << (uint8_t)ch);
+  if (mute == HT_CH_MUTE) {
+    mute_mask = (uint8_t)(mute_mask | bit);
+    if (ch == HT_CH1 || ch == HT_CH2) silence_square((uint8_t)ch);
+    else if (ch == HT_CH4)            silence_noise();
+  } else {
+    mute_mask = (uint8_t)(mute_mask & (uint8_t)~bit);
+  }
+}
+
+void hUGE_set_position(uint8_t order_index_) {
+  uint8_t i;
+  row_index    = 0;
+  tick_counter = 1;
+  for (i = 0; i < 4; i++) order_index[i] = order_index_;
+}