Debugging Guide
This guide covers techniques for debugging NES emulation issues in x-nes, from CPU bugs to PPU rendering glitches, mapper problems, and APU timing.
Quick Diagnostic Commands
Run ROM headless (check if it boots)
cargo run --example main -- "path/to/rom.nes"
Watch the PC values. If they cycle predictably and you see Frame complete messages, the game is executing code and generating frames.
Run with window (see visuals)
cargo run --example window -- "path/to/rom.nes"
Run test suite
cargo test # Unit tests
cargo test --test accuracy_coin # AccuracyCoin (comprehensive)
Debugging CPU Issues
Inspect CPU State
Add this to the main loop for per-instruction tracing:
#![allow(unused)]
fn main() {
println!(
"{:04X} A:{:02X} X:{:02X} Y:{:02X} P:{:02X} SP:{:02X} CYC:{}",
cpu.pc(), cpu.a(), cpu.x(), cpu.y(), cpu.sr(), cpu.st(),
bus.cpu_cycle
);
}
Check Reset Vectors
The NES boots by reading the reset vector at $FFFC-$FFFD. Verify these addresses contain valid ROM data:
#![allow(unused)]
fn main() {
let lo = bus.read(0xFFFC);
let hi = bus.read(0xFFFD);
println!("Reset vector: ${:02X}{:02X} → ${:04X}", hi, lo, (hi as u16) << 8 | lo as u16);
}
If the reset vector points to $0000 or a non-ROM address, the ROM isn’t loading correctly.
Trace PC history
Keep a rolling window of last N PCs to see code flow:
#![allow(unused)]
fn main() {
let mut pc_history = [0u16; 64];
let mut pc_idx = 0;
// In the tick loop:
pc_history[pc_idx % 64] = cpu.pc();
pc_idx += 1;
// Print on crash/detection:
for i in 0..64.min(pc_idx) {
let idx = (pc_idx - 1 - i) % 64;
println!(" [-{}] PC=${:04X}", i, pc_history[idx]);
}
}
Detect Infinite Loops
If the game hangs, it’s often in a tight loop. Watch for the same PC repeating:
#![allow(unused)]
fn main() {
let mut last_pc = 0u16;
let mut repeat_count = 0u32;
// In tick:
if cpu.pc() == last_pc {
repeat_count += 1;
if repeat_count > 1_000_000 {
eprintln!("HANG DETECTED at PC=${:04X}", cpu.pc());
break;
}
} else {
repeat_count = 0;
last_pc = cpu.pc();
}
}
Illegal Opcodes
If the CPU hits an unofficial opcode, it may crash or behave unexpectedly. x-nes implements all official and unofficial opcodes. Verify the opcode table covers the full 256 entries:
#![allow(unused)]
fn main() {
// Check if any slot is missing:
for i in 0..256 {
// TABLE[i] should always be a valid function pointer
}
}
Debugging PPU / Graphics Issues
See the Graphics Debugging chapter for a dedicated guide.
Quick PPU State Dump
#![allow(unused)]
fn main() {
fn dump_ppu(ppu: &Ppu) {
println!("Scanline: {} Cycle: {} Frame: {}",
ppu.scanline, ppu.cycle, ppu.frame_complete);
println!("CTRL: {:02X} MASK: {:02X} STATUS: {:02X}",
ppu.ctrl, ppu.mask, ppu.status);
println!("v: ${:04X} t: ${:04X} fine_x: {} w: {}",
ppu.v, ppu.t, ppu.fine_x, ppu.w);
println!("NMI: output={} latched={} vblank={} deferred={}",
ppu.nmi_output, ppu.nmi_latched,
ppu.nmi_from_vblank, ppu.nmi_deferred_pending);
}
}
Dump Frame to PPM
Save the frame buffer as a viewable image for offline analysis:
#![allow(unused)]
fn main() {
fn save_ppm(frame: &[u8; 61440], path: &str, palette: &[u32; 64]) {
use std::io::Write;
let mut f = std::fs::File::create(path).unwrap();
writeln!(f, "P6\n256 240\n255").unwrap();
for y in 0..240 {
for x in 0..256 {
let idx = y * 256 + x;
let color = palette[(frame[idx] & 0x3F) as usize];
let r = ((color >> 16) & 0xFF) as u8;
let g = ((color >> 8) & 0xFF) as u8;
let b = (color & 0xFF) as u8;
f.write_all(&[r, g, b]).unwrap();
}
}
// View with: ffplay path.ppm or convert to PNG
}
}
Debugging Mapper Issues
Verify Mapper Detection
#![allow(unused)]
fn main() {
let rom = Rom::new(&data).unwrap();
println!("Mapper: {} Mirroring: {} PRG: {}KB CHR: {}KB CHR-RAM: {}",
rom.mapper_id, rom.mirroring,
rom.prg.len()/1024, rom.chr.len()/1024, rom.has_chr_ram);
}
Log Mapper Register Writes
Add conditional logging for your mapper:
#![allow(unused)]
fn main() {
// In MMC5 cpu_write, add:
if addr >= 0x5100 && addr <= 0x5117 {
eprintln!("MMC5 write ${:04X} = ${:02X} (PC=${:04X})", addr, val, cpu_pc);
}
}
This reveals what the game writes to configuration registers.
Check Bank Mapping
Verify PRG banks are being set correctly:
#![allow(unused)]
fn main() {
fn dump_mmc5_banks(mmc5: &Mmc5) {
println!("PRG mode: {} Banks: {:02X} {:02X} {:02X} {:02X}",
mmc5.prg_mode,
mmc5.prg_reg[0], mmc5.prg_reg[1],
mmc5.prg_reg[2], mmc5.prg_reg[3]);
println!("CHR mode: {} NT mapping: {:02X}",
mmc5.chr_mode, mmc5.nt_mapping_reg);
println!("ExRAM mode: {} IRQ: scanline={} enabled={} pending={}",
mmc5.ex_ram_mode, mmc5.irq_scanline,
mmc5.irq_enable, mmc5.irq_pending_flag);
}
}
Verify PRG RAM Protection Logic
A common bug is inverted PRG RAM protection. Check:
#![allow(unused)]
fn main() {
// After reset ($5102=0, $5103=0), writes to $6000-$7FFF should be ALLOWED
// When $5102=2, $5103=1, writes should be BLOCKED
// Correct:
fn prg_ram_is_protected(&self) -> bool {
self.prg_ram_protect1 == 0x02 && self.prg_ram_protect2 == 0x01
}
// Call site: if !self.prg_ram_is_protected() { /* allow write */ }
}
Debugging IRQ Issues
IRQ bugs cause screen splits to be at the wrong position, audio glitches, or game hangs.
Log IRQ Events
#![allow(unused)]
fn main() {
// In notify_scanline:
if scanline < 240 && irq_enabled && scanline as u8 == irq_scanline {
eprintln!("MMC5 IRQ FIRED at scanline {} (target={})", scanline, irq_scanline);
}
}
Verify Scanline Counter
Check that the IRQ fires at the expected scanline. For Castlevania III, the status bar split should be at a consistent scanline (around 200-210 depending on the screen).
Check IRQ Acknowledgment
After the game handles an IRQ, it must read $5204 (or write $5204 with bit 7 clear) to acknowledge. If acknowledgment doesn’t clear irq_pending_flag, the CPU will re-enter the IRQ handler immediately, causing a crash.
Debugging APU / Audio Issues
Check APU Sample Output
Log audio samples to detect silence, clipping, or DC offset:
#![allow(unused)]
fn main() {
let mut max_sample = 0i16;
let mut min_sample = 0i16;
for &s in &apu.audio_samples[..apu.sample_count] {
max_sample = max_sample.max(s);
min_sample = min_sample.min(s);
}
eprintln!("Audio: {} samples, range [{}, {}]", apu.sample_count, min_sample, max_sample);
}
Verify APU Channel States
#![allow(unused)]
fn main() {
fn dump_apu(apu: &Apu) {
println!("Pulse1: enabled={} duty={} vol={} timer={} len={}",
apu.p1.enabled, apu.p1.duty, apu.p1.vol,
apu.p1.timer_val, apu.p1.length_counter);
println!("Pulse2: enabled={} duty={} vol={} timer={} len={}",
apu.p2.enabled, apu.p2.duty, apu.p2.vol,
apu.p2.timer_val, apu.p2.length_counter);
println!("Triangle: enabled={} timer={} lin_ctr={}",
apu.triangle.enabled, apu.triangle.timer_val,
apu.triangle.linear_counter);
println!("Noise: enabled={} vol={} mode={} period={}",
apu.noise.enabled, apu.noise.vol,
apu.noise.mode, apu.noise.period_index);
}
}
Test ROMs for Validation
| ROM | Tests |
|---|---|
nestest.nes | CPU instructions (all official + unofficial) |
instr_test-v5/ | Per-instruction CPU tests |
blargg_ppu_tests/ | PPU timing, VBlank, NMI |
AccuracyCoin | Comprehensive (CPU, PPU, APU, DMA, controllers) |
| Any NROM game | Basic mapper + PPU integration |
Crashes: First Steps
When a game crashes, check in this order:
- PC valid? Is it in the ROM range ($8000-$FFFF)?
- Opcode valid? Print the opcode at PC
- Stack overflow? Check if SP is near 0
- IRQ storm? Check if
poll_irq()returns true repeatedly - Mapper config? Dump mapper register state
- NMI timing? Check if NMI fires at the right scanline
Quick Crash Checklist
□ PC = ${:04X} — in ROM range?
□ Opcode at PC = ${:02X} — valid instruction?
□ Stack SP = ${:02X} — not near overflow?
□ Mapper ID = {} — correct for this ROM?
□ PPU scanline {} cycle {} — stuck in VBlank?
□ IRQ pending? {} — stuck in interrupt handler?