Hardware & Timing

Clock Architecture

The Game Boy’s master clock runs at 4.194304 MHz (2²² Hz). All subsystem timing derives from this clock by division:

VBlank and the timer are phase-locked but at rates that never align into a clean integer ratio — VBlank is dictated by LCD timing (a non-power-of-2 cycle count), while the timer uses clean binary division.

VBlank: 70224 Cycles

The PPU draws the screen in a fixed cycle:

70224 is not a power of 2. It’s the product of LCD requirements: 154 scanlines (144 visible + 10 blanking) at 456 dots each. The horizontal and vertical blanking periods are necessary to give the hardware time to reset beam position — a constraint inherited from CRT-era display design.

This gives a frame rate of 4194304 / 70224 = 59.7275 Hz.

Timer Interrupt

The timer is configured via three registers:

TAC Clock Select

GB Studio Timer Configuration

GB Studio sets TAC = 0x07 (enabled, clock/256 = 16384 Hz). The TMA value differs by hardware:

• CGB: TMA = 0x80 → TIMA counts 128 ticks before overflow → 16384 / 128 = 128 Hz
• DMG: TMA = 0xC0 → TIMA counts 64 ticks before overflow → 16384 / 64 = 256 Hz

The music_play_isr() handler fires at this rate but only processes music every 4th call (++counter & 3), giving an effective 64 Hz for hUGE_dosound(). See Sound — hUGE Timing for details.

Why 64 Hz for Music?

The hUGE tracker driver runs at 64 Hz rather than VBlank’s ~59.7 Hz for three reasons:

1. Tempo accuracy. Tracker BPM calculations assume 64 ticks/second (powers of 2). At 59.7 Hz, every song would play ~7% too slow and drift over time.
2. Note table calibration. The 72-entry note table and subpattern timing are calibrated for 64 Hz. Running at VBlank rate would detune everything.
3. Clean binary division. 64 Hz divides from the master clock via powers of 2 (4194304 / 2¹⁶ = 64), giving exact, jitter-free timing. VBlank’s 70224-cycle period has no such clean relationship.

Interrupt Sources

The Game Boy CPU supports 5 interrupt sources, each with a fixed vector address:

In GB Studio, VBlank and Timer are always active. LCD STAT is used for scanline effects (parallax scrolling, split-screen via LYC). Serial and Joypad interrupts are rarely used.

Interrupt Nesting

By default, interrupts are disabled while an ISR executes (IME cleared on entry). GB Studio’s VBL_isr re-enables interrupts (ei) before calling into the GBDK runtime, allowing the timer ISR to fire during VBlank processing. This is how the music driver maintains its 64 Hz tick rate even during heavy VBlank work.

CPU Timing Basics

GB Studio runs the CGB in double-speed mode by default, giving twice the CPU budget per frame. However, PPU timing remains the same — VBlank is still ~59.7 Hz and scanlines are still 456 dots.

Memory Map Overview

Sound Register Range

0xFF10–0xFF3F — all sound channel control registers and wave RAM live in the I/O register space. See Sound — Channel Registers for the full breakdown.

VRAM Access Safety

VRAM (0x8000–0x9FFF) is only accessible to the CPU during specific PPU modes. Writing during Mode 3 (pixel transfer) silently fails on real hardware. Reading during Mode 3 returns 0xFF on DMG. Getting VRAM access right is one of the most common sources of hard-to-debug visual corruption.

PPU Modes and VRAM Access

Common Patterns — Ranked by Safety

1. Inside VBL_isr (Safest)

Code executing inside VBL_isr is guaranteed to be in VBlank. No checks needed.

void VBL_isr(void) NONBANKED {
    // ... stock GB Studio code ...
    VRAM[addr] = value;      // always safe
    val = VRAM[addr];        // always returns correct data
}

2. VBlank Wait with Interrupts Disabled (Safe for Setup)

Wait for VBlank by polling LY_REG with interrupts disabled. Gives 4560 dots (~1140 M-cycles on DMG, ~2280 on CGB double) of safe access.

__critical {
    while (LY_REG < 144);    // spin until VBlank starts
    val = VRAM[addr];         // safe: 4560 dots available
    VRAM[addr] = new_val;     // safe
}

__critical compiles to di / ei — prevents ISRs from firing between the LY check and the memory access. Without __critical, an ISR can preempt between the check and the access, leaving you in Mode 3 when you thought you were in VBlank.

3. wait_vram() — NOT Safe for Critical Operations

// DANGEROUS — ISR race condition
wait_vram();            // STAT says we're in HBlank...
                        // ← ISR fires here, PPU advances to Mode 3
val = VRAM[addr];       // returns 0xFF on DMG, stale data on CGB

// ALSO DANGEROUS — even with __critical, HBlank is too short
__critical {
    wait_vram();         // waits for Mode 0 (HBlank)
    val = VRAM[addr];    // SDCC generates extra instructions between check and access
}                        // HBlank is only ~204 dots — may overflow into Mode 2/3

The problem is worse during dialog: the VBlank ISR performs heavy work (text rendering, palette writes), widening the window where ISRs can preempt your STAT check.

Failure Symptoms