CHIP-8 to Pico 2

An emulator consists of a struct holding the machine's state and a loop that advances it. For CHIP-8, that state fits in a dozen 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.

The font, verbatim

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.

Suggested reading before you start

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 Petzold's text.

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

Six references and two community tools. Read Langhoff before writing code, and consult Cowgod and Mikolay during implementation.

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.

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.

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.

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 RP2350 is a genuinely nice target for this: dual Cortex-M33 at 150 MHz with 520 KB of SRAM, against a machine that needs 4 KB of RAM and 256 bytes of framebuffer. You are not resource-constrained — you have roughly 100× the headroom the original hardware had. What the port actually teaches you is whether your core/frontend boundary was real.

Pick a HAL

Either works. If the goal is understanding, start with rp235x-hal; if the goal is a working handheld, embassy will get you there faster.

The hardware decisions

• Display: an SSD1306 128×64 I²C OLED is the natural fit — exactly 2× 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 is the honest version and matches the VIP's real layout. A capacitive TTP229 or MPR121 board is the low-effort version. A PCF8574 I²C expander saves pins if you're short.
• Sound: PWM to a piezo. Set a square wave on a PWM slice and gate the output on sound_timer > 0. Ten lines, and it's the first time the emulator feels like a device.
• ROMs: include_bytes! a handful into flash for the first version. A menu reading from SD via embedded-sdmmc is the natural second version.

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 can put the display flush on core 1 and keep the interpreter on core 0, though for CHIP-8 that's a luxury rather than a necessity.

Embedded Rust prerequisites

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. The local repository is at commit e0b3888 from 13 August 2023.

What it gets right

• 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

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.

Three additional resources provide useful context outside standard CHIP-8 specifications:

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.