gameboy-docs

name gameboy-docs description Complete Game Boy DMG hardware reference — all registers, timing, opcodes, PPU modes, APU circuits, MBC banking. Authoritative inline spec for emulator implementation. argument-hint optional topic: cpu|ppu|apu|mbc|timer|interrupts|memory|joypad|serial|boot You are implementing SvelteBoy, a Game Boy DMG emulator. This file contains authoritative hardware spec. if anything is missing or unclear, first check the pandoc .md files in pandocs/ directory, then prompt to see if you should search online. SPECS (DMG) CPU: SM83 (8080-like), 4.194304 MHz master clock, system clock = master/4 WRAM: 8 KiB; VRAM: 8 KiB; LCD: 160×144; OBJ: 8×8 or 8×16, max 40/screen 10/line Palettes (DMG): BG 1×4, OBJ 2×3; Colors: 4 shades of green; Vsync: 59.73 Hz APU: 4 channels, stereo output; Sound: DMG 4 channels Frame: ~16.74 ms (NOT exactly 60 Hz — 0.45% slow); 1 dot = 1 T-cycle = 2^22 Hz ≈ 4.194 MHz MEMORY MAP Range Description $0000–$3FFF ROM bank 00 (fixed) $4000–$7FFF ROM bank 01–NN (switchable via MBC) $8000–$9FFF VRAM (8 KiB) $A000–$BFFF External RAM (cartridge) $C000–$CFFF WRAM bank 0 (4 KiB) $D000–$DFFF WRAM bank 1 (4 KiB) $E000–$FDFF Echo RAM (mirror of C000–DDFF, prohibited) $FE00–$FE9F OAM (40 entries × 4 bytes) $FEA0–$FEFF Prohibited (DMG: reads trigger OAM corruption during mode 2, else $00) $FF00–$FF7F I/O Registers $FF80–$FFFE HRAM $FFFF IE (Interrupt Enable) Echo RAM : E000–FDFF mirrors C000–DDFF (only lower 13 address bits connected). Same effect as C000–DDFF reads/writes. Prohibited by Nintendo. Jump vectors : RST = $0000,$0008,$0010,$0018,$0020,$0028,$0030,$0038; Interrupts = $0040,$0048,$0050,$0058,$0060 VRAM layout : 384 tiles × 16 bytes = $8000–$97FF (tile data); two 32×32 tile maps at $9800–$9BFF and $9C00–$9FFF HARDWARE REGISTERS Addr Name R/W Description $FF00 P1/JOYP Mixed Joypad $FF01 SB R/W Serial transfer data $FF02 SC Mixed Serial transfer control $FF04 DIV R/W Divider (write resets to $00) $FF05 TIMA R/W Timer counter $FF06 TMA R/W Timer modulo $FF07 TAC R/W Timer control $FF0F IF R/W Interrupt flag $FF10–$FF26 NR10–NR52 Mixed Audio $FF30–$FF3F Wave RAM R/W CH3 waveform $FF40 LCDC R/W LCD control $FF41 STAT Mixed LCD status $FF42 SCY R/W BG viewport Y $FF43 SCX R/W BG viewport X $FF44 LY R LCD Y coordinate $FF45 LYC R/W LY compare $FF46 DMA R/W OAM DMA source/start $FF47 BGP R/W BG palette (DMG only) $FF48 OBP0 R/W OBJ palette 0 (DMG only) $FF49 OBP1 R/W OBJ palette 1 (DMG only) $FF4A WY R/W Window Y position $FF4B WX R/W Window X position +7 $FF50 BANK W Boot ROM disable $FFFF IE R/W Interrupt enable CPU Registers 16-bit Hi Lo Purpose AF A — Accumulator & Flags BC B C General purpose DE D E General purpose HL H L General purpose / indirect SP — — Stack Pointer PC — — Program Counter Flags (lower byte of AF) Bit Flag Set when 7 Z Result = 0 6 N Subtraction (BCD) 5 H Half-carry (BCD) 4 C Carry / borrow / shift-out 1 Carry set: 8-bit add > $FF, 16-bit add > $FFFF, sub/cmp < 0, rotate/shift outputs 1. BCD flags (N,H) used only by DAA. Instruction Encoding Placeholders : r8 = B/C/D/E/H/L/[HL]/A (0–7); r16 = BC/DE/HL/SP; r16stk = BC/DE/HL/AF; r16mem = BC/DE/HL+/HL-; cond = nz/z/nc/c; b3 = bit index 0–7; tgt3 = RST target/8; imm8 / imm16 = following bytes (little-endian) Block 0 : nop; ld r16,imm16 ; ld [r16mem],a ; ld a,[r16mem] ; ld [imm16],sp ; inc/dec r16 ; add hl,r16 ; inc/dec r8 ; ld r8,imm8 ; rlca/rrca/rla/rra/daa/cpl/scf/ccf; jr imm8 ; jr cond,imm8 ; stop Block 1 : ld r8,r8 — except ld [hl],[hl] = halt ($76) Block 2 : add/adc/sub/sbc/and/xor/or/cp a,r8 Block 3 : add/adc/sub/sbc/and/xor/or/cp a,imm8; ret cond; ret; reti; jp cond,imm16; jp imm16; jp hl; call cond,imm16; call imm16; rst tgt3; pop/push r16stk; $CB prefix; ldh [c],a; ldh [imm8],a; ld [imm16],a; ldh a,[c]; ldh a,[imm8]; ld a,[imm16]; add sp,imm8; ld hl,sp+imm8; ld sp,hl; di; ei Invalid opcodes (hard-lock CPU) : $D3,$DB,$DD,$E3,$E4,$EB,$EC,$ED,$F4,$FC,$FD $CB prefix : rlc/rrc/rl/rr/sla/sra/swap/srl r8; bit/res/set b3,r8 STOP : 2-byte instruction; second byte not always ignored. On DMG, must disable LCD before entering STOP or risk hardware damage (black line burned in). Terminated by P10–P13 low (button press). SM83 vs Z80 differences No IX/IY registers; no DD/FD/ED prefixes; no second register set; no dedicated I/O bus (use LDH instead); parity/sign/overflow flags removed; RETI replaces EXX ($D9); SWAP replaces SLL ($CB3x); ADD SP,dd replaces RET M ; autoincrement HL access added; all timings multiple of 4 T-cycles. Approx speed of 4 MHz Z80. Opcode Z80 SM83 $08 EX AF,AF LD (nn),SP $10 DJNZ STOP $22 LD (nn),HL LDI (HL),A $2A LD HL,(nn) LDI A,(HL) $32 LD (nn),A LDD (HL),A $3A LD A,(nn) LDD A,(HL) $D9 EXX RETI $E0 RET PO LD (FF00+n),A $E2 JP PO,nn LD (FF00+C),A $E8 RET PE ADD SP,dd $EA JP PE,nn LD (nn),A $F0 RET P LD A,(FF00+n) $F2 JP P,nn LD A,(FF00+C) $F8 RET M LD HL,SP+dd $FA JP M,nn LD A,(nn) $CB3x SLL SWAP HALT halt pauses CPU until IE & IF != 0 . IME must be set for interrupt to be serviced after wake. halt bug : When IME=0 and IE & IF != 0 at time of halt : halt exits immediately, but PC is not incremented — the byte after halt is read twice. If halt immediately after ei (IME still 0): interrupt serviced, handler returns to halt, waits again. If halt immediately before rst : RST return address points to RST itself (not byte after it). If ei before halt AND rst after halt: ei case wins. INTERRUPTS IME (Interrupt Master Enable) — write-only, internal flag ei : IME=1 (effect delayed one instruction) di : IME=0 reti : IME=1 + return Entering handler: IME=0 ei effect delayed by one instruction: ei followed immediately by di allows no interrupt. FF0F — IF: Interrupt Flag | $FFFF — IE: Interrupt Enable Both same bit layout: Bit Source Vector 0 VBlank $0040 1 STAT/LCD $0048 2 Timer $0050 3 Serial $0058 4 Joypad $0060 Bit 0 = highest priority. IF bit set = interrupt requested. Serviced only when IME=1 AND matching IE bit set. Interrupt Dispatch (5 M-cycles total) Reset IF bit and IME 2 wait states (2 M-cycles) Push current PC to stack (2 M-cycles) Set PC to handler address (1 M-cycle) Interrupt Sources VBlank ($0040): Fires when PPU enters VBlank (LY=144), ~59.7 Hz. VRAM freely accessible during VBlank (~1.1 ms). STAT ($0048): Rising edge on shared STAT interrupt line (OR of enabled sources: mode 0/1/2, LYC=LY). STAT blocking : if line already high, no interrupt fires for subsequent sources. Timer ($0050): Fires when TIMA overflows ($FF→$00+interrupt). Serial ($0058): Fires on completion of 8-bit serial transfer. Joypad ($0060): Fires when P10–P13 go high→low (button pressed). Switch bounce common. Useful mainly to exit STOP mode. TIMER Registers $FF04 DIV : Increments at 16384 Hz. Write any value → reset to $00. Also reset by stop . DIV is the visible upper 8 bits of the 16-bit system counter. $FF05 TIMA : Incremented at rate set by TAC. On overflow: reset to TMA, request timer interrupt. $FF06 TMA : Reload value for TIMA on overflow. $FF07 TAC : Bit 2: Timer enable (TIMA; DIV always counts) Bits 1–0 clock select: 00: every 256 M-cycles → 4096 Hz 01: every 4 M-cycles → 262144 Hz 10: every 16 M-cycles → 65536 Hz 11: every 64 M-cycles → 16384 Hz Obscure Behavior (DMG) System counter (full 16-bit) drives timer via falling-edge detector on selected bit: Writing DIV (resets counter to 0) can instantly trigger a timer tick if selected bit was 1. Changing TAC clock select from a set bit to a clear bit sends a timer tick. On DMG: disabling timer while selected bit is set sends one tick. TIMA overflow behavior: TIMA=0 for one M-cycle (cycle A), then TMA copied and IF set (cycle B). Writing TIMA during cycle A cancels the overflow (no TMA copy, no IF set). Writing TIMA during cycle B is ignored (TMA wins). Writing TMA during cycle B: same value copies to TIMA on same cycle. DIV-APU: APU events triggered by falling edge on bit 4 of system counter (512 Hz). PPU / GRAPHICS PPU Modes (per scanline, 456 dots total) Mode Action Duration CPU VRAM access CPU OAM access 2 OAM scan 80 dots Yes No 3 Pixel transfer 172–289 dots No No 0 HBlank 376 - mode3 dots Yes Yes 1 VBlank 4560 dots (lines 144–153) Yes Yes Frame: 154 scanlines × 456 dots = 70224 dots total. Mode 3 Length Penalties Default minimum: 172 dots (160px + 12 fixed). Penalties lengthen Mode 3, shorten Mode 0: SCX % 8 extra dots at start (pixel discard) +6 dots for window activation Per-object: 6–11 dots each (see OBJ penalty algorithm) OBJ at X=0: always 11 dots regardless of SCX OBJ penalty algorithm : For each OBJ's leftmost pixel ("The Pixel"): Find which BG/window tile contains The Pixel. If tile not yet seen by prior OBJ: penalty = max(0, pixels_right_of_Pixel_in_tile - 2) dots. +6 flat dots (OBJ tile fetch). FF40 — LCDC Bit Function 0 1 7 LCD+PPU enable Off On 6 Window tile map $9800 $9C00 5 Window enable Off On 4 BG+Window tile data $8800 ($9000 base, signed) $8000 (unsigned)