CHIP-8 to Pico 2

Interpreter scope

CHIP-8 is a bytecode virtual machine created by Joseph Weisbecker in 1977 for the COSMAC VIP microcomputer, implemented as an interpreter on the RCA 1802. Writing a CHIP-8 emulator means writing an interpreter for a virtual machine rather than modeling hardware components. It lacks hardware interrupts, memory mapping, a bus cycle model, and dedicated video processors. Later projects like the Intel 8080 or Game Boy introduce those subsystems.

High level view of the emulator

The emulator consists of a struct holding the machine's state and a loop that advances it. For CHIP-8 the state fits in ten lines:

pc: u16          // program counter, starts at 0x200
i: u16           // index register (addresses, not values)
v: [u8; 16]      // V0..VF — VF doubles as the flag register
ram: [u8; 4096]  // font at 0x50, program from 0x200
stack: [u16; 16] // return addresses only, no frames
sp: u8
delay: u8        // both tick down at exactly 60 Hz
sound: u8        // beeps while nonzero
fb: [bool; 64*32]// naive form; §04 packs this to [u64; 32]
keys: [bool; 16] // hex keypad, not a keyboard

The loop executes three steps: fetch, decode, and execute. Read two bytes at pc (every instruction is 2 bytes, stored high byte first), advance pc by 2, split the 16 bits into four nibbles, and match.

Most bugs in this project come down to incorrect decoding or wrong timing.

Glyphs for text

The font contains sixteen glyphs of five bytes each, totaling 80 bytes. It is conventionally loaded at 0x50, below the program area. Only the high nibble of each byte is used, so each glyph is 4 pixels wide and each byte ends in 0. In binary, the bytes 0xF0, 0x90, 0x90, 0x90, 0xF0 form the digit 0:

0xF0 -> 1111 ....   ####
0x90 -> 1001 ....   #..#
0x90 -> 1001 ....   #..#
0x90 -> 1001 ....   #..#
0xF0 -> 1111 ....   ####

Instruction FX29 sets the index register I to a glyph's address, which DXYN then reads. The address is FONT_START + (VX & 0x0F) * 5. The mask is required because VX is an 8-bit register. Without masking, VX * 5 can point I to address 1355, nearly 1200 bytes past the 80-byte table and inside program memory. Games use this instruction to draw scores. The table:

0xF0,0x90,0x90,0x90,0xF0,  // 0
0x20,0x60,0x20,0x20,0x70,  // 1
0xF0,0x10,0xF0,0x80,0xF0,  // 2
0xF0,0x10,0xF0,0x10,0xF0,  // 3
0x90,0x90,0xF0,0x10,0x10,  // 4
0xF0,0x80,0xF0,0x10,0xF0,  // 5
0xF0,0x80,0xF0,0x90,0xF0,  // 6
0xF0,0x10,0x20,0x40,0x40,  // 7
0xF0,0x90,0xF0,0x90,0xF0,  // 8
0xF0,0x90,0xF0,0x10,0xF0,  // 9
0xF0,0x90,0xF0,0x90,0x90,  // A
0xE0,0x90,0xE0,0x90,0xE0,  // B
0xF0,0x80,0x80,0x80,0xF0,  // C
0xE0,0x90,0x90,0x90,0xE0,  // D
0xF0,0x80,0xF0,0x80,0xF0,  // E
0xF0,0x80,0xF0,0x80,0x80,  // F

Transcribing this table manually makes the sprite format clear, each set bit represents a lit pixel which is the mechanism DXYN relies on.

Three independent clocks

CHIP-8 has three separate clock rates that must not be coupled:

• CPU execution runs at roughly 500–700 instructions per second. This rate was never standardised, so it should be configurable.
• The delay and sound timers decrement at 60 Hz regardless of CPU speed. Games rely on the delay timer for wall-clock timing, so coupling it to instruction cycles will cause games to run at the wrong speed across platforms.
• Display refresh occurs at 60 Hz. On original hardware, DXYN blocked until vblank, which is handled as a quirk (see §02).

A standard loop structure uses a 60 Hz timer tick that executes N CPU cycles, decrements both timers by one, and presents the frame. On desktop, N ≈ 10 produces 600 Hz. On the RP2350 a hardware timer alarm drives that outer tick.

Isolating the core

Keep windowing, printing, and std dependencies out of the emulator core. The core should receive inputs through methods and expose its framebuffer through a borrowed slice. This separation allows the same crate to compile for desktop, WebAssembly, and the RP2350 without changes. Adding no_std compatibility from the beginning avoids major refactoring later.

Guides, References & Tools

Optional

This is optional if the model above is familiar. Readers who want a concrete grounding in registers, buses, and instruction decoding will find it in this text. Also it's a fantastic book if you haven't read it

Reading through the CPU construction chapters provides helpful context when starting, where binary data is first decoded into mnemonics.

There's two guides worth reading end to end, five references and two community tools below. Definitely start with Tobias V. Langhoff's "Guide to making a CHIP-8 emulator" before writing code, and consult Cowgod and Mikolay during implementation.

Guides

References

Tools

Embedded Rust docs

The quirks and test suites

CHIP-8 implementations diverged between 1977 and 1990 as new interpreters altered instruction behaviors. Software written for one platform frequently fails on another, meaning an emulator that decodes every opcode correctly can still fail to run specific games due to behavioural differences.

Six behaviours account for most compatibility issues. Store each as a bool field in a configuration struct early in development to avoid refactoring later.

Automated test suite

github.com/Timendus/chip8-test-suite provides ROMs that render visual pass/fail output directly to the screen once DXYN is functional. The suite contains eight ROMs, numbered in execution order: 1-chip8-logo, 2-ibm-logo, 3-corax+, 4-flags, 5-quirks, 6-keypad, 7-beep, and 8-scrolling (the last requires SUPER-CHIP or XO-CHIP support). Running 1-chip8-logo first is useful because it omits 7XNN and requires only byte-aligned sprite drawing. Running these ROMs headlessly in cargo test by stepping a fixed number of cycles and comparing a hash of the framebuffer provides reliable regression testing.

Implementation details

• The COSMAC VIP used a 4×4 hexadecimal keypad laid out 1 2 3 C / 4 5 6 D / 7 8 9 E / A 0 B F. Standard emulator implementations map these rows to 1234 / QWER / ASDF / ZXCV on modern keyboards. Games assume the physical key positions, so mapping key codes purely by digit label produces unintuitive controls.
• The wait-for-key instruction FX0A halts execution until an input event occurs. The standard approach decrements pc by 2 so the opcode repeats until satisfied. On original hardware, execution resumed on key release rather than initial keypress.
• Drawing with DXYN sets VF to 1 if any active pixel is cleared by the XOR operation, and 0 otherwise. Games use this mechanism as their primary collision detection.
• Sprites have a fixed width of 8 pixels and a variable height from 1 to 15 rows. Each row is defined by one byte, with the most significant bit mapped to the leftmost pixel.
• The stack stores only return addresses, with no concept of stack frames or arguments. Modern implementations generally support 16 levels, whereas the original VIP interpreter reserved space for 12. Opcode 2NNN pushes the return address, and 00EE pops it.

Build order

This sequence introduces debugging checkpoints at each milestone. Building verification tools before implementing the full opcode set helps isolate decode and timing errors early.

Diagnostic tools

A ring buffer recording recent (pc, opcode) pairs helps diagnose crashes by dumping trace history on panic or error states. Adding single-step execution and register inspection to the desktop frontend during M3 simplifies tracking bugs before running on microcontroller targets.

Rust workspace architecture

A three-crate Cargo workspace isolates platform-independent emulation logic from platform-specific I/O:

chip8/
├── chip8-core/      #![no_std], zero I/O, all the logic
├── chip8-desktop/   winit + pixels (or minifb)
└── chip8-pico/      #![no_std] + #![no_main], rp235x-hal or embassy-rp

The public API for the core crate requires only a minimal surface:

impl Chip8 {
    pub fn new(cfg: Quirks) -> Self;
    pub fn load_rom(&mut self, bytes: &[u8]);
    pub fn step(&mut self);                 // one instruction
    pub fn tick_timers(&mut self) -> bool;  // true = beep
    pub fn set_key(&mut self, k: u8, down: bool);
    pub fn framebuffer(&self) -> &[u64; 32]; // 1 bit per pixel
}

Implementation choices

• Instruction decoding using match (a, b, c, d) on the four nibbles is clearer than nested if branches, and the compiler flags unreachable patterns automatically.
• Representing the display as [u64; 32] stores one u64 per row, matching the 64-pixel width. XOR drawing for an 8-pixel sprite row becomes a bit shift and XOR operation. Collision detection evaluates as old & shifted_sprite != 0 before modifying the row. This layout occupies 256 bytes instead of 2048 bytes for a boolean array.
• Because the core is no_std, opcode CXNN cannot call standard rand functions that depend on an operating system entropy source. Instead, provide a deterministic generator inside the no_std core, such as a lightweight xorshift seeded by the caller. Avoiding rand or depending on an older release like rand 0.7 prevents pulling in unexpected dependencies. Microcontrollers like the RP2350 have a hardware TRNG, but abstracting RNG generation behind the core's API keeps the crate portable.
• Arithmetic operations require explicit overflow handling. Opcode 7XNN wraps without modifying VF, while 8XY4 sets VF on carry. Using wrapping_add and overflowing_add prevents debug-build overflow panics and ensures consistent behavior.
• Testing the core does not require a window or an event loop. Unit tests can load raw u16 opcode sequences into RAM, instantiate a Chip8 struct, and call step(), asserting on register and flag states directly.

Desktop frontends

The aquova guide uses sdl2, which requires linking external SDL2 development libraries. Alternatives include minifb, which manages a window and framebuffer without external C dependencies on macOS or Windows (though Linux requires libx11-dev), or pixels combined with winit for hardware-accelerated presentation.

The Pico 2 track

The Pico-2 with RP2350 is a nice target board for this, easy to get and this project doesn't need wifi/bt, plus Rust easily works with it. The board has dual ARM Cortex-M33 and/or Hazard3 RISC-V cores at 150 MHz with 520 KB of SRAM, and putting a state a machine that needs 4 KB of RAM and 256 bytes of framebuffer so plenty of headroom. If I come across a smaller μC that is easy to get and affordable I might put a guide to get CHIP-8 in Rust on that controller too.

Pick a HAL

Either works. If the goal is understanding, start with rp235x-hal, if the goal is a working handheld then embassy will get you there faster. I myself started with embassy because that's what I learned embedded Rust with.

Hardware choices

• Display: an SSD1306 128×64 I²C OLED is a good option, exactly twice the CHIP-8's resolution in both axes, so every CHIP-8 pixel is a 2×2 block and there is no scaling arithmetic at all. Drive it with the ssd1306 crate over embedded-graphics. If I²C's refresh rate annoys you, an ST7789 SPI LCD is much faster and gives you colour for a HUD.
• Input: 16 keys. A 4×4 tactile matrix scanned across 8 GPIOs matches the VIP's real layout. I can't believe there was a time when people punched in game's using hex, blew my mind when I realized it. A capacitive TTP229 or MPR121 board is an easy option.
• Sound: PWM to a piezo. Set a square wave on a PWM slice and gate the output on sound_timer > 0. Add some buzzing to give the project life
• ROMs: include_bytes! a handful into flash for the first version. A menu reading from SD via embedded-sdmmc is a good version 2.0 variant if you want to continue with the project.

Timing on bare metal

Do not build your loop out of delay_ms. Use the hardware timer to fire a 60 Hz alarm; on each fire, run your N CPU cycles, decrement the timers once, and push the framebuffer to the display. With two cores available you could put the display flush on core 1 and keep the interpreter on core 0 but that sorta feels like overkill for a CHIP-8. The hardware is there so I guess make use of it.

Sequencing advice

Get the desktop version passing the full Timendus suite before you touch the microcontroller. Debugging interpreter logic simultaneously with hardware abstractions via a 128×64 display without logging will be confusing. The port should be a frontend swap, nothing more — and if it isn't, that's useful information about your core.

The aquova book

An Introduction to Chip-8 Emulation using the Rust Programming Language by aquova contains nine chapters, a three-crate workspace (core, desktop, wasm), and bundled test ROMs.

Ideas to use from it

• The crate workspace structure cleanly separates core emulation logic from frontend presentation.
• The material targets readers who know Rust syntax but have not written an emulator, with full implementations for each opcode.
• The WebAssembly chapter provides a functional browser build using the same core crate.

What's stale or missing in 2026

Use chapters 1–6 as a structural guide while referencing Langhoff for opcode semantics and the Timendus test ROMs for validation. Implementing the core crate as #![no_std] and removing external rand dependencies early will avoid refactoring during the microcontroller port.

After CHIP-8

This guide covers simple interpretive execution, where an emulator decodes and executes instructions sequentially. While standard for CHIP-8 and introductory projects, other CPU emulation techniques exist along a performance spectrum, including direct-threaded dispatch, dynamic recompilation, and just-in-time (JIT) compilation. High-level emulation (HLE) forms another approach, replacing lower-level hardware execution with native reimplementations of system API calls.

Common subsequent hardware projects, ordered by complexity:

• Intel 8080 arcade hardware (such as Space Invaders, documented at emulator101.com) introduces real hardware features: paired 8-bit registers, condition flags, dedicated I/O ports via IN and OUT, memory-mapped video RAM, and display interrupts. Instruction cycle timing becomes necessary for correct game speed.
• The Game Boy (DMG) is a common second project. Documentation is centralized at Pan Docs with community tools at gbdev.io and comprehensive test ROMs by Blargg and Mooneye. Implementing the Sharp SM83 CPU core is straightforward, while accurately modeling the Pixel Processing Unit (PPU) scanline timing requires significantly more effort.
• The Nintendo Entertainment System (NES) introduces cartridge memory mappers and strict Picture Processing Unit (PPU) timing requirements. Technical reference material is maintained on the NESdev Wiki alongside the javidx9 video walkthrough.

The r/EmuDev subreddit and its Discord community maintain the emudev.org documentation and provide active technical discussion for verifying edge-case hardware behaviors and test results.