romdevtools 0.13.0

package/src/platforms/gg/lib/c/gg_music.c

@@ -0,0 +1,155 @@
+/* gg_music.c — Game Gear SN76489 PSG music driver.
+ *
+ * Plays a hand-authored note table on a dedicated PSG channel, one note
+ * per frame-tick. Companion to gg_sfx (which keeps ch 0/1 free for
+ * fire-and-forget sound effects and ch 3 for noise — we own ch 2).
+ *
+ * Protocol recap (port $7F, write-only):
+ *   Tone latch: bit7=1, bits6-5=channel, bit4=0, bits3-0=freq_low
+ *   Tone data : bit7=0, bits5-0=freq_high
+ *   Vol  latch: bit7=1, bits6-5=channel, bit4=1, bits3-0=attenuation
+ *
+ * Attenuation: 0=loudest, 15=silent (2 dB steps).
+ *
+ * Song table format (see gg_music.h music_note_t):
+ *   - .note = 10-bit PSG divider (0 = rest), .dur = frame count
+ *   - sentinel row {0, 0} marks end-of-song
+ *
+ * The note table IS the song — no compression, no compiler — you can
+ * read the melody right in this file. Add or edit songs by appending
+ * a music_note_t[] array and bumping music_song_count.
+ */
+
+#include "gg_music.h"
+#include "gg_hw.h"
+
+#define MUSIC_CHANNEL 2  /* PSG ch 2 — ch 0/1 reserved for gg_sfx */
+#define MUSIC_VOLUME  3  /* attenuation; lower = louder, 3 ≈ -6 dB */
+
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;            /* port $7F = PSG write port */
+}
+
+static void psg_set_tone(uint8_t ch, uint16_t freq) {
+  /* Two-byte latch+data for tone frequency. */
+  psg_write((uint8_t)(0x80 | (ch << 5) | (freq & 0x0F)));
+  psg_write((uint8_t)((freq >> 4) & 0x3F));
+}
+
+static void psg_set_attn(uint8_t ch, uint8_t attn) {
+  psg_write((uint8_t)(0x90 | (ch << 5) | (attn & 0x0F)));
+}
+
+/* ── Song 0: arpeggiated C-major motif ─────────────────────────────
+ * Source-visible: this IS the song. Each row = one note (or rest)
+ * and how many 60Hz frames to hold it. 30 frames = 0.5 s.
+ * Pattern: C major chord arpeggio up + down, then a melodic flourish.
+ */
+static const music_note_t song0[] = {
+  { NOTE_C4, 18 }, { NOTE_E4, 18 }, { NOTE_G4, 18 }, { NOTE_C5, 36 },
+  { NOTE_G4, 18 }, { NOTE_E4, 18 }, { NOTE_C4, 36 },
+  { NOTE_REST, 12 },
+  { NOTE_D4, 18 }, { NOTE_F4, 18 }, { NOTE_A4, 18 }, { NOTE_D5, 36 },
+  { NOTE_A4, 18 }, { NOTE_F4, 18 }, { NOTE_D4, 36 },
+  { NOTE_REST, 18 },
+  /* Melodic flourish — "shave and a haircut" feel */
+  { NOTE_G4, 18 }, { NOTE_C5, 18 }, { NOTE_C5, 18 },
+  { NOTE_D5, 18 }, { NOTE_C5, 36 }, { NOTE_REST, 12 },
+  { NOTE_E5, 18 }, { NOTE_C5, 36 },
+  { 0, 0 }, /* end-of-song sentinel */
+};
+
+/* ── Song 1: minor / spooky arpeggio (A minor) ────────────────────── */
+static const music_note_t song1[] = {
+  { NOTE_A3, 24 }, { NOTE_C4, 24 }, { NOTE_E4, 24 }, { NOTE_A4, 48 },
+  { NOTE_E4, 24 }, { NOTE_C4, 24 }, { NOTE_A3, 48 },
+  { NOTE_REST, 12 },
+  { NOTE_G3, 24 }, { NOTE_B3, 24 }, { NOTE_D4, 24 }, { NOTE_G4, 48 },
+  { NOTE_F4, 24 }, { NOTE_D4, 24 }, { NOTE_B3, 24 }, { NOTE_G3, 48 },
+  { 0, 0 },
+};
+
+/* ── Song 2: short jingle / fanfare ────────────────────────────────── */
+static const music_note_t song2[] = {
+  { NOTE_C5, 12 }, { NOTE_C5, 12 }, { NOTE_C5, 12 }, { NOTE_E5, 36 },
+  { NOTE_G4, 12 }, { NOTE_E4, 24 }, { NOTE_G4, 36 },
+  { NOTE_REST, 6 },
+  { NOTE_C5, 12 }, { NOTE_G4, 12 }, { NOTE_E4, 12 }, { NOTE_C4, 48 },
+  { 0, 0 },
+};
+
+static const music_song_t songs[] = {
+  { song0, 1 },  /* arpeggio — loops */
+  { song1, 1 },  /* minor — loops */
+  { song2, 0 },  /* fanfare — one-shot */
+};
+const uint8_t music_song_count = 3;
+
+/* ── Engine state ─────────────────────────────────────────────────── */
+static const music_note_t *cur_song;
+static uint8_t cur_song_loop;
+static uint16_t cur_pos;
+static uint8_t cur_remaining;  /* frames left on the current row */
+static uint8_t playing;
+
+void music_init(void) {
+  cur_song = 0;
+  cur_song_loop = 0;
+  cur_pos = 0;
+  cur_remaining = 0;
+  playing = 0;
+  /* Silence the music channel up front. */
+  psg_set_attn(MUSIC_CHANNEL, 0x0F);
+}
+
+static void start_row(void) {
+  uint16_t note = cur_song[cur_pos].note;
+  uint8_t dur  = cur_song[cur_pos].dur;
+  if (dur == 0) {
+    /* End sentinel. */
+    if (cur_song_loop) {
+      cur_pos = 0;
+      note = cur_song[0].note;
+      dur  = cur_song[0].dur;
+      if (dur == 0) {
+        /* Empty song — bail. */
+        music_stop();
+        return;
+      }
+    } else {
+      music_stop();
+      return;
+    }
+  }
+  if (note == NOTE_REST) {
+    psg_set_attn(MUSIC_CHANNEL, 0x0F);  /* silent rest */
+  } else {
+    psg_set_tone(MUSIC_CHANNEL, note);
+    psg_set_attn(MUSIC_CHANNEL, MUSIC_VOLUME);
+  }
+  cur_remaining = dur;
+}
+
+void music_play(uint8_t song_idx) {
+  if (song_idx >= music_song_count) return;
+  cur_song = songs[song_idx].notes;
+  cur_song_loop = songs[song_idx].loop;
+  cur_pos = 0;
+  playing = 1;
+  start_row();
+}
+
+void music_stop(void) {
+  playing = 0;
+  psg_set_attn(MUSIC_CHANNEL, 0x0F);
+}
+
+void music_update(void) {
+  if (!playing) return;
+  if (cur_remaining == 0) return;  /* defensive */
+  cur_remaining--;
+  if (cur_remaining == 0) {
+    cur_pos++;
+    start_row();
+  }
+}

package/src/platforms/gg/lib/c/gg_music.h

@@ -0,0 +1,89 @@
+/* gg_music.h — minimal Game Gear PSG music engine.
+ *
+ * Companion to gg_sfx (sfx wrapper). Where sfx_tone() plays a single
+ * fire-and-forget tone with a countdown, music_play() runs an entire
+ * hand-authored song on a dedicated PSG channel, advancing one note
+ * per call to music_update() (call once per frame, 60 Hz).
+ *
+ * Same SN76489 PSG chip + same I/O port ($7F) as SMS, so the protocol
+ * is identical — only difference vs the (parallel) SMS driver is the
+ * file name. We intentionally keep gg_music/sms_music independent (no
+ * shared common-z80 lib), matching the existing gg_sfx / sms_sfx /
+ * genesis_sfx split. If somebody later wants to consolidate they can
+ * lift the byte-identical bits into a common file.
+ *
+ * Song format — see gg_music.c for the full breakdown. TL;DR each row
+ * is a (note, duration_frames) pair stored as 10-bit PSG freq divider
+ * and an 8-bit frame count. Duration 0 = end-of-song sentinel; the
+ * engine then either stops (one-shot) or restarts the song (loop).
+ *
+ *   music_init();                  // silence music channel
+ *   music_play(0);                 // start song 0 on the music channel
+ *   for (;;) {
+ *     gg_vblank_wait();
+ *     music_update();              // advance one frame of music
+ *   }
+ *
+ * The engine uses PSG channel 2 by default (leaves ch 0/1 free for
+ * gg_sfx tones and ch 3 for noise). Change MUSIC_CHANNEL in gg_music.c
+ * if you want a different one.
+ *
+ * Frequencies are pre-baked SN76489 register values (0..1023), NOT Hz,
+ * so the note table is exactly what the chip latches. The header below
+ * exposes the standard NOTE_* defines so songs can read as music.
+ */
+
+#ifndef GG_MUSIC_H
+#define GG_MUSIC_H
+
+#include <stdint.h>
+
+/* One row of a song. Note 0 + dur 0 = end sentinel. */
+typedef struct {
+  uint16_t note;   /* SN76489 10-bit freq divider, or 0 for rest */
+  uint8_t  dur;    /* duration in frames (60 Hz); 0 = end-of-song */
+} music_note_t;
+
+typedef struct {
+  const music_note_t *notes;
+  uint8_t loop;    /* 0 = one-shot, 1 = loop forever */
+} music_song_t;
+
+void music_init(void);
+void music_play(uint8_t song_idx);
+void music_stop(void);
+void music_update(void);
+
+/* Number of songs in the bundled bank (see gg_music.c). */
+extern const uint8_t music_song_count;
+
+/* ── SN76489 note table (10-bit freq dividers @ ~3.58 MHz) ────────
+ * Formula: divider = 3579545 / (32 * Hz). Higher divider = lower pitch.
+ * Octave indices roughly cover C3..C6 — comfortable handheld range.
+ */
+#define NOTE_REST 0
+
+#define NOTE_C3   855  /* 130.81 Hz */
+#define NOTE_D3   762
+#define NOTE_E3   679
+#define NOTE_F3   641
+#define NOTE_G3   571
+#define NOTE_A3   509
+#define NOTE_B3   453
+#define NOTE_C4   428  /* 261.63 Hz — middle C */
+#define NOTE_D4   381
+#define NOTE_E4   339
+#define NOTE_F4   320
+#define NOTE_G4   285
+#define NOTE_A4   254  /* 440 Hz concert A */
+#define NOTE_B4   226
+#define NOTE_C5   214
+#define NOTE_D5   190
+#define NOTE_E5   170
+#define NOTE_F5   160
+#define NOTE_G5   142
+#define NOTE_A5   127
+#define NOTE_B5   113
+#define NOTE_C6   107
+
+#endif

package/src/platforms/gg/lib/c/gg_sfx.c

@@ -0,0 +1,82 @@
+/* sms_sfx.c — SN76489 PSG driver for SMS / Game Gear.
+ *
+ * SN76489 latch protocol (write-only via port $7F):
+ *   Latch byte (bit 7 = 1):
+ *     bit 7    = 1 (latch)
+ *     bits 6-5 = channel (00=ch0, 01=ch1, 10=ch2, 11=ch3-noise)
+ *     bit 4    = 0 (frequency) | 1 (volume/attenuation)
+ *     bits 3-0 = low 4 bits of frequency, OR 4-bit attenuation (0=loud, 15=silent)
+ *   Data byte (bit 7 = 0):
+ *     bits 5-0 = high 6 bits of frequency
+ *
+ * To play a tone:
+ *   1. Latch: $80|chan<<5|0|(freq & 0x0F)
+ *   2. Data:  (freq >> 4) & 0x3F
+ *   3. Latch volume: $90|chan<<5|attenuation
+ *
+ * Noise uses a different latch (low 3 bits select shift rate / source):
+ *   $E0 | (mode_bit << 2) | rate
+ *   rate 0=clock/512, 1=clock/1024, 2=clock/2048, 3=use ch2 freq
+ *
+ * Attenuation is in 2 dB steps: 0=loudest, 15=off.
+ *
+ * Per-channel "frames-left" countdown drives auto-silence. sfx_update
+ * runs once per frame and silences a channel whose counter hits 0.
+ */
+
+#include "gg_sfx.h"
+#include "gg_hw.h"
+
+static uint8_t sfx_remaining[4];
+
+static void psg_write(uint8_t b) {
+  PORT_H_COUNTER = b;            /* port $7F is the PSG write port */
+}
+
+void sfx_init(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    sfx_remaining[i] = 0;
+    /* Silence channel i (latch volume = 0xF = off). */
+    psg_write(0x90 | (i << 5) | 0x0F);
+  }
+}
+
+void sfx_tone(uint8_t channel, uint16_t freq, uint8_t length_frames) {
+  if (channel > 2) return;
+  /* Latch + data byte for frequency. */
+  psg_write(0x80 | (channel << 5) | (freq & 0x0F));
+  psg_write((freq >> 4) & 0x3F);
+  /* Volume at max (attenuation 0). */
+  psg_write(0x90 | (channel << 5) | 0x00);
+  sfx_remaining[channel] = length_frames;
+}
+
+void sfx_noise(uint8_t length_frames) {
+  /* White noise, rate = clock/1024 (mid frequency). */
+  psg_write(0xE0 | 0x04 | 0x01);
+  /* Volume at max (channel 3 attenuation = 0). */
+  psg_write(0xF0);
+  sfx_remaining[3] = length_frames;
+}
+
+void sfx_update(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    if (sfx_remaining[i] > 0) {
+      sfx_remaining[i]--;
+      if (sfx_remaining[i] == 0) {
+        /* Silence channel i. */
+        psg_write(0x90 | (i << 5) | 0x0F);
+      }
+    }
+  }
+}
+
+void sfx_off(void) {
+  uint8_t i;
+  for (i = 0; i < 4; i++) {
+    psg_write(0x90 | (i << 5) | 0x0F);
+    sfx_remaining[i] = 0;
+  }
+}

package/src/platforms/gg/lib/c/gg_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/gg/lib/c/joypad_read.c

@@ -0,0 +1,22 @@
+/* GG joypad read — port $DC (D-pad + B1/B2) plus port $00 bit 7 for START.
+ *
+ * Active LOW on the hardware, we invert so pressed = 1. Returned byte
+ * layout matches the SMS layout PLUS bit 7 for START:
+ *
+ *   bit 0  UP
+ *   bit 1  DOWN
+ *   bit 2  LEFT
+ *   bit 3  RIGHT
+ *   bit 4  B1
+ *   bit 5  B2
+ *   bit 7  START   (read from GG-specific port $00 bit 7)
+ *
+ * Use the JOY_* and JOY_START masks from gg_hw.h.
+ */
+#include "gg_hw.h"
+
+uint8_t gg_joypad_read(void) {
+  uint8_t a = ~PORT_JOY_A;        /* D-pad + B1 + B2 (active low) */
+  uint8_t start = ~PORT_GG_INPUT; /* GG-specific port bit 7 = START */
+  return (uint8_t)((a & 0x3F) | (start & 0x80));
+}

package/src/platforms/gg/lib/c/load_palette.c

@@ -0,0 +1,20 @@
+/* GG palette loader — uploads 64-byte palette (32 entries × 2 bytes) to CRAM.
+ *
+ * GG CRAM: 32 entries × 2 bytes (4-4-4 BGR LE), 64 bytes total.
+ *   Entry layout: low byte = $GR (G=high nibble, R=low), high byte = $0B.
+ *   Pack with: low = (g << 4) | r, high = b.
+ *
+ *     extern const uint8_t my_palette[64];
+ *     gg_load_palette(my_palette);
+ *
+ * Entries 0-15 = BG palette, 16-31 = sprite palette.
+ */
+#include "gg_hw.h"
+
+extern void gg_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void gg_load_palette(const uint8_t *palette) {
+  uint16_t i;
+  gg_vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = palette[i];
+}

package/src/platforms/gg/lib/c/load_tiles.c

@@ -0,0 +1,32 @@
+/* SMS tile loader — upload bytes to VRAM at any destination.
+ *
+ * SMS tiles are 32 bytes each (4bpp interleaved). VRAM is 16 KB at
+ * $0000-$3FFF. Tile N lives at VRAM offset (N * 32).
+ *
+ *     extern const uint8_t my_tiles[];
+ *     gg_load_tiles(0x0000, my_tiles, sizeof(my_tiles));  // sprite bank
+ *
+ * Default R6=0xFB → sprite tiles read from $0000 (shared with BG tiles).
+ * If you want sprite tiles in their own bank at $2000, set R6=0xFF AND
+ * upload to $2000. Don't pick the address without checking R6.
+ */
+#include "gg_hw.h"
+
+extern void gg_vdp_set_addr(uint16_t addr, uint8_t prefix);
+
+void gg_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count) {
+  uint16_t i;
+  gg_vdp_set_addr(vram_dest, VDP_VRAM_WRITE);
+  for (i = 0; i < byte_count; i++) PORT_VDP_DATA = src[i];
+}
+
+/* Write a single name-table cell. Default name table at $3800.
+ *   tile_idx: 0..511 (low 9 bits)
+ *   attr:     hflip = bit 1, vflip = bit 2, palette = bit 3, priority = bit 4
+ */
+void gg_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr) {
+  uint16_t addr = 0x3800 + ((uint16_t)row * 32 + col) * 2;
+  gg_vdp_set_addr(addr, VDP_VRAM_WRITE);
+  PORT_VDP_DATA = tile_idx;
+  PORT_VDP_DATA = attr;
+}

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

@@ -0,0 +1,60 @@
+/* GG sprite attribute table — shadow OAM in WRAM, DMA'd to SAT once
+ * per frame. GG VDP is SMS-compatible so the SAT layout is identical.
+ *
+ * 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 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:
+ *   gg_sprite_init();             // once
+ *   gg_sprite_set(0, x, y, 4);    // game logic
+ *   ...
+ *   gg_sat_upload();              // once per vblank
+ */
+#include "gg_hw.h"
+
+extern void gg_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.
+ * Also below the GG visible viewport (hw-coord y∈[24,167]). */
+#define OAM_Y_HIDDEN  0xE0
+
+void gg_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 gg_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 gg_sat_upload(void) {
+  uint8_t i;
+  /* Y bytes → VRAM $3F00. */
+  gg_vdp_set_addr(0x3F00, VDP_VRAM_WRITE);
+  for (i = 0; i < 64; i++) PORT_VDP_DATA = shadow_oam[i];
+  /* (X, tile) pairs → VRAM $3F80. */
+  gg_vdp_set_addr(0x3F80, VDP_VRAM_WRITE);
+  for (i = 0; i < 128; i++) PORT_VDP_DATA = shadow_oam[0x80 + i];
+}

package/src/platforms/gg/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 "gg_hw.h"
+
+void gg_vblank_wait(void) {
+  while ((PORT_VDP_CTRL & 0x80) == 0) { }
+}

package/src/platforms/gg/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/GG 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
+ * sprites({op:'inspect'}) 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:
+ *   gg_vdp_display_on();
+ */
+#include "gg_hw.h"
+
+/* Write a value to a VDP register. SMS convention: data first, then
+ * (0x80 | reg). */
+void gg_vdp_write_reg(uint8_t reg, uint8_t value) {
+  PORT_VDP_CTRL = value;
+  PORT_VDP_CTRL = VDP_REG_WRITE | reg;
+}
+
+void gg_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++) gg_vdp_write_reg(i, regs[i]);
+}
+
+void gg_vdp_display_on(void) {
+  gg_vdp_write_reg(1, 0xE0);  /* display on, vblank IRQ on, 192-line */
+}
+
+void gg_vdp_display_off(void) {
+  gg_vdp_write_reg(1, 0x80);
+}
+
+/* Set the VDP destination address (for the next data-port writes). */
+void gg_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;
+}