Chip8

I’ve written an interpreter for Chip-8 as a stepping stone toward emulating some more complex real hardware.

This little project doesn’t have all the polish. Among the things missing are configuration options for selecting quirks. But the point of this was mostly as an exercise to explore some basic concepts to emulate more interesting hardware (like the Z80-like chip in the GameBoy).

Find the code on sourcehut: https://git.sr.ht/~jos/chip8-rs

Approach

I have tried implementing a Chip8 interpreter before and actually got pretty far into it. But I seemed to have had a bug somewhere and I had a lot of trouble figuring out what it was. Eventually I abandoned the project.

I was determined not to run into the same problems again, so this time I fell back on a more test-driven approach that could hopefully drive the implementation top-down, and give me more confidence that the code was free of bugs at each step of the way.

To that end, I started by writing a test for the clear screen instruction. Two things I was pretty sure of right off the bat: I’d need a struct Chip8 to hold the state of the registers, memory, program counter and all that, and I’d need a function that accepts an opcode and executes it. I called it step and wrote the beginnings of a test.

#[test]
fn test_cls() {
    // Arrange...
    let mut chip = Chip8::new();

    // Act.
    chip8.step(0x00E0);

    // Assert...
}

So now I needed a way to verify that clearing the screen had happened after executing the opcode for it. I know that a screen is just a 2D array of pixels, so if the Chip8 struct includes such an array, I could check that all of the pixels are clear (i.e. 0) after the instruction runs. However, since the pixel array will probably start initialized to all 0s, the test needs to write some pixels as part of the “Arrange” step, and then verify that they’re all clear in the “Assert” step. To wit:

#[test]
fn test_cls() {
    let mut chip8 = Chip8::new();
    chip8.display_buffer[14] = 23;
    chip8.step(0x00E0);
    assert!(chip8.display_buffer.iter().all(|x| *x == 0));
}

I followed this approach for each instruction as I implemented it. I implemented a few of the basic instructions like this, including an unconditional jump, call, and some of the skip instructions.

I then realized that I could very easily fall into the same trap as before: if I didn’t actually verify that everything was working by looking at it, then I couldn’t be sure it was. I needed to find some “ROMs” to actually test it out. So for most of the development, I used “Octojam 1 Title” from the CHIP-8 Archive to figure out which instructions to implement next until I got to the point of actually drawing on the screen.

Once I could get one of ROM running, I could move on to other ROMs until I’d covered most of the instructions.

I actually stuck to this approach pretty well until the very end. There were several unimplemented instructions because I guess some of them are more rarely used.

Managing the Stack

(Or how I learned the “as-if” rule).

One interesting thing I realized as I was implementing this was around the use of the stack. At first I had just blindly followed the cowgod description, and had a “stack pointer” register as well as a dedicated “stack” array of bytes (16 slots).

struct Chip8 {
    // ...
    sp: u8,
    stack: [u16; 16]
}

I implemented the CALL instruction just like it was described:

The interpreter increments the stack pointer, then puts the current PC on the top of the stack. The PC is then set to nnn.

fn call(&mut self, address: u16) {
    self.sp += 1;
    self.stack[self.sp as usize] = self.pc;
    self.pc = address;
}

But when it came time to implement RET to return from a subroutine, I realized that by implementing it this way, the zeroth element of the stack array was unused.

I thought about how I could implement this in such a way as to avoid this, but it dawned on me that a stack is a stack. Since the actual stack memory is inaccessible to the program, as far as I can tell, then there’s no observable difference between using an array with a “stack pointer” and just using a vector to push and pop elements.

The point here being that an emulator doesn’t need to be implemented exactly like the actual device as long as it behaves as if it were.

Tricky instructions

The trickiest thing for me to get a handle on (in part due to the fact that I was burning the midnight oil on this), was the instruction for drawing sprites.

Dxyn - DRW Vx, Vy, nibble
Display n-byte sprite starting at memory location I at (Vx, Vy), set VF = collision.

The part I didn’t immediately grok was what it means for bytes to be “displayed as sprites on screen”. In the end it’s actually quite simple, but since I struggled at first, I figure somebody might save some time and gain some insight.

Sprites are stored as a sequence of bytes, where each bit represents one pixel. If you stack the bytes, you get the shape of the stamp.

For example, the sprite for the number 3:

// As a sequence of bytes:
0xF0 0x10 0xF0 0x10 0xF0

// As bits
11110000 00010000 11110000 00010000 11110000

// Stacked
11110000
00010000
11110000
00010000
11110000

// using * for set pixels (blanks for unset) so it's clearer
****
   *
****
   *
****

So each byte (the instruction takes a number n for how many of these there are) represents a “line” of the sprite. For each of those lines, the code walks through each bit and draws it on the screen. This includes the zeroes on the side.

I know. It’s slightly embarrassing that it was as hard for me to grasp as it was. But I got there.

The actual implementation was a little tricky, with the wrap-around behavior and XOR-ing, but I understood the problem and it was a question of minutae. Since I knew what was going on, I could write a test to verify that it was working:

// Verify that the 0 sprite is drawn at 0, 0

// Vx, Vy: (0, 0)
chip8.v_[9].0 = 0;
chip8.v_[0xa].0 = 0;
chip8.i = 0; // sprites are stored starting at 0.

// Draw 5 bytes at (V[9], V[A])
chip8.step(0xd9a5);

// Verify that the 0 pattern is shown
// (edb = "expected display buffer")
let edb = [0; WIDTH * HEIGHT];

// Set our expectation for the 0 sprite's bit pattern on the screen
edb[0] = on; edb[1] = on; edb[2] = on; edb[3] = on;           // 1111
edb[64] = on; edb[65] = off; edb[66] = off; edb[67] = on;     // 1001
edb[128] = on; edb[129] = off; edb[130] = off; edb[131] = on; // 1001
edb[192] = on; edb[193] = off; edb[194] = off; edb[195] = on; // 1001
edb[256] = on; edb[257] = on; edb[258] = on; edb[259] = on;   // 1111

assert_eq!(chip8.display_buffer, edb);
assert_eq!(chip8.v_[0xf].0, 0); // no collisions since the screen was blank before

// Drawing the same sprite in the same place should cause it
// to zero itself out and the collision flag should be set.
chip8.step(0xd9a5);
assert!(chip8.display_buffer.iter().all(|x| *x == 0));
assert_eq!(chip8.v_[0xf].0, 1);

Other ROMs

Near the end I started trying other ROMs and eventually found one that actually tested out some of the functionality, including the buzzer. This is the “chip8-test-rom-with-audio” from here.