Game Boy Emulator: Designing the CPU

Registers

For starters, you have a number of registers at your disposal. As you may recall, the Z80 is an 8-bit processor with a 16-bit address bus. That means there has to be a way of operating on both 8-bit and 16-bit numbers, and the way to do both is using a clever design that lets you read some of the registers as either an 8-bit or 16-bit word depending on which register you’re reading.

If you go to pandocs’s CPU Registers and flags you’ll see a list of registers and their names:

1. AF, consisting of A, the accumulator register; and F, an internal register that holds the flags.

2. BC, a general purpose register

3. DE, a general purpose register

4. HL, a general purpose register and it has a large number of instructions that simplifies iterative code, like loops; 16-bit arithmetic; and data loading, bit manipulation, and more.

5. SP, the stack pointer. Used for call stacks and makes it possible for the CPU to natively support function calls and return values. Has a number of specialized instructions that makes it easier to do this.

6. PC, the Program Counter. Used to track the location of the next executing instruction. Refers to a memory address.

Of note is the concept of “high” and “low” registers. For instance, the general purpose register BC is composed of the high byte B and low byte C, as its name alludes to.

That means you can request the full 16 bit value from BC or just the upper or lower 8 bits with either B or C, respectively. That’s pretty nifty, and is a very useful way of operating selectively on part of a value instead of the whole one.

For instance, if you have the value BC = 0x1234 you can interpret it as that, or as B = 0x12 or C = 0x34.

Keep in mind that not all registers support this mode of operation, and one in particular is completely inaccessible, despite being named. That’s the F register; it’s only available for programmers indirectly through other instructions.

We need a way of storing and recalling the values of the Z80’s registers

So, we need a way of representing all these registers in Python. Luckily that is trivial for an emulator writer: we have variables. So we’ll need a variable for each register, but a method of reading and writing to the high and low parts of a 16-bit register also.

1;; snake.gb disassembly
20150 NOP
30151 DI
40152 LD       SP, 0xfffe
50155 LD       B, 0x80
60157 LD       C, 0x0
70159 LDH      A, (0x44)
8015B CP       0x90
9015D JR       NZ, 0xfa
10015F DEC      C
110160 LD       A, C
120161 LDH      (0x42), A
130163 DEC      B
140164 JR       NZ, 0xf3
150166 XOR      A
160167 LDH      (0x40), A
170169 LD       A, 0x0

Representing the Registers and Flags

As I mentioned earlier, you need to think of registers as nothing more than variables. However, the only two snags is the high and low concept of a 16-bit word, and that flags are bitfields stored in the low word of AF.

So if you have the 16-bit number 0xABCD and you wanted the high and low words separately, you’ll need to twiddle some bits, as the expression goes.

+-----+-----+-----+-----+-----+-----+-----+-----+
| 128 | 64  | 32  | 16  |  8  |  4  |  2  |  1  |
+-----+-----+-----+-----+-----+-----+-----+-----+ = 0xAB
|  1  |  0  |  1  |  0  |  1  |  0  |  1  |  1  |
+-----+-----+-----+-----+-----+-----+-----+-----+

>>> hex(0xAB >> 4)
'0xa'

+-----+-----+-----+-----+-----+-----+-----+-----+
| 128 | 64  | 32  | 16  |  8  |  4  |  2  |  1  |
+-----+-----+-----+-----+-----+-----+-----+-----+ = 0xA
|  0  |  0  |  0  |  0  |  1  |  0  |  1  |  0  |
+-----+-----+-----+-----+-----+-----+-----+-----+
Shift right 4 ->        \-----------------------/

>>> hex(0xA << 4)
'0xa0'

+-----+-----+-----+-----+
|  8  |  4  |  2  |  1  |  Bit
+-----+-----+-----+-----+
|  0  |  1  |  1  |  0  |  A
+-----+-----+-----+-----+  &
|  1  |  0  |  1  |  1  |  B
+-----+-----+-----+-----+  =
|  0  |  0  |  1  |  0  |  C
+-----+-----+-----+-----+

>>> 0b0110 & 0b1011
2

>>> 0b1111
1

>>> hex(0xAB & 0b1111)
'0xb'

+-----+-----+-----+-----+
|  8  |  4  |  2  |  1  |  Bit
+-----+-----+-----+-----+
|  0  |  0  |  1  |  0  |  A
+-----+-----+-----+-----+  |
|  1  |  0  |  1  |  1  |  B
+-----+-----+-----+-----+  =
|  1  |  0  |  1  |  1  |  C
+-----+-----+-----+-----+

>>> bin(0b0010 | 0b1011)
'0b1011'

+-----+-----+-----+-----+
|  8  |  4  |  2  |  1  |  Bit
+-----+-----+-----+-----+
|  0  |  0  |  1  |  0  |  A
+-----+-----+-----+-----+  ^
|  1  |  0  |  1  |  1  |  B
+-----+-----+-----+-----+  =
|  1  |  0  |  0  |  1  |  C
+-----+-----+-----+-----+

>>> bin(0b0010 ^ 0b1011)
'0b1001'

The Registers and Flags

OK, with a primer on bits it’s time to represent the registers. You can use a simple dictionary, or explicit variables or attributes on a class — it’s up to you.

I’m going to use a modified dictionary-style notation, as it makes it easy to read and reason about. But by all means, pick a method you think makes most sense to you.

Let’s start with some mappings of the registers and flags we need, and how they relate to one another.

REGISTERS_LOW = {"F": "AF", "C": "BC", "E": "DE", "L": "HL"}
REGISTERS_HIGH = {"A": "AF", "B": "BC", "D": "DE", "H": "HL"}
REGISTERS = {"AF", "BC", "DE", "HL", "PC", "SP"}
FLAGS = {"c": 4, "h": 5, "n": 6, "z": 7}

These constants map a low register, like C, to BC. That way our code can check if a register is low, high, a 16-bit register, or a flag, with a simple chain of if statements.

from collections.abc import MutableMapping

@dataclass
class Registers(MutableMapping):

    AF: int
    BC: int
    DE: int
    HL: int
    PC: int
    SP: int

    def values(self):
        return [self.AF, self.BC, self.DE, self.HL, self.PC, self.SP]

    def __iter__(self):
        return iter(self.values())

    def __len__(self):
        return len(self.values())

Here I’m laying out the groundwork for a custom dictionary-style class. I’m inheriting from MutableMapping, an abstract base class, that ensures I override all the right methods to provide dictionary-style access (registers["PC"] = 42.)

I also use a dataclass, and I make it so each main register is part of the constructor.

Next, it’s time to define the accessor:

def __getitem__(self, key):
    if key in REGISTERS_HIGH:
        register = REGISTERS_HIGH[key]
        return getattr(self, register) >> 8
    elif key in REGISTERS_LOW:
        register = REGISTERS_LOW[key]
        return getattr(self, register) & 0xFF
    elif key in FLAGS:
        flag_bit = FLAGS[key]
        return self.AF >> flag_bit & 1
    else:
        if key in REGISTERS:
            return getattr(self, key)
        else:
            raise KeyError(f"No such register {key}")

The code is didactic on purpose; but the intent is simple. I check each collection of registers in turn and, when I find it, I apply the correct bitwise operation as needed:

1. High registers are bit-shifted 8 bits to the right, which yields the value we want

2. Low registers are bitwise ANDed with the mask 0xFF as that matches the low 8 bits.

3. Flags are instead shifted by their position in AF so the bit we care about is put in the right-most position where I can bitwise AND with 1 to check if it is set or not.

4. Requests for 16-bit registers is a simple matter of returning that value, unmodified.

5. Everything else is a KeyError

Setting a register is more or less the same as getting, but the bitwise operators are now |.

def __setitem__(self, key, value):
    if key in REGISTERS_HIGH:
        register = REGISTERS_HIGH[key]
        current_value = self[register]
        setattr(self, register, (current_value & 0x00FF | (value << 8)) & 0xFFFF)
    elif key in REGISTERS_LOW:
        register = REGISTERS_LOW[key]
        current_value = self[register]
        setattr(self, register, (current_value & 0xFF00 | value) & 0xFFFF)
    elif key in FLAGS:
        assert value in (0, 1), f"{value} must be 0 or 1"
        flag_bit = FLAGS[key]
        if value == 0:
            self.AF = self.AF & ~(1 << flag_bit)
        else:
            self.AF = self.AF | (1 << flag_bit)
    else:
        if key in REGISTERS:
            setattr(self, key, value & 0xFFFF)
        else:
            raise KeyError(f"No such register {key}")

def __delitem__(self, key):
    raise NotImplementedError("Register deletion is not supported")

1. Setting a high register is a case of taking the value and shifting it to the high position 8 bits to the left and clearing the previous values with a mask. I use bitwise | to ensure we keep whatever else is in the register (current_value)

2. For low registers I simply apply bitwise OR, as there is no shifting required.

3. For 16-bit registers it’s a simple case of setting the value.

4. For flags, we shift the bit we want to unset (value == 0) to its correct position then use the complement (~) to flip all the bits before masking it with AF. If value == 1 then I use bitwise OR.

5. Everything else is a KeyError.

You may have noticed the & 0xFFFF at the end of each assignment. It’s a safe guard against values that may overflow the 16-bit size limit of the main registers. The emulator we’re writing has 16 bits per register, but Python does not care about that. Masking against 0xFFFF ensures we never overflow.

Now for some tests. I’m again using hypothesis to generate strategies:

import hypothesis.strategies as st
from hypothesis import given

@pytest.fixture(scope="session")
def make_registers():
    def make():
        return Registers(AF=0, BC=0, DE=0, HL=0, PC=0, SP=0)
    return make

@given(
    value=st.integers(min_value=0, max_value=0xFF),
    field=st.sampled_from(sorted(REGISTERS_HIGH.items())),
)
def test_registers_high(make_registers, field, value):
    registers = make_registers()
    high_register, full_register = field
    registers[high_register] = value
    assert registers[full_register] == value << 8

The test is simple. I create a Registers class and test that the value we set – which is randomly drawn by Hypothesis – is what we expect by manually shifting it and checking the 16-bit-sized register. (This is why it pays to keep the registers separate and easy to reuse in a test.)

Testing the low and full-sized registers is easy enough now that you’re familiar with the structure of the test and how to validate your results. Try writing them yourself.

Testing the flags is similarly simple:

@given(
    starting_value=st.integers(min_value=0, max_value=0xFF),
    field=st.sampled_from(sorted(FLAGS.items())),
)
def test_flags(make_registers, starting_value, field):
    flag, bit = field
    registers = make_registers()
    outcome = []
    for value in (0, 1):
        # Set attribute directly
        registers.AF = starting_value
        registers[flag] = value
        outcome.append(registers["F"])
        assert registers["F"] >> bit & 1 == value
    assert outcome.pop() != outcome.pop()

The end result is a simple dict-style class that lets you query low, high, flags and full registers using their name.

The CPU

The CPU is the, well, central part of the emulator, so it must be extensible, as we’ll be adding to it over time; it must be easy to swap components in or out, to facilitate testing; and it should encapsulate the state of the CPU, which will come to include a number of things we’ve not yet talked about.

You can do this with nothing but functions, but in keeping with the style so far, I’ll use a dataclass to represent the CPU.

class InstructionError(Exception):
    pass


@dataclass
class CPU:

    registers: Registers
    decoder: Decoder

    def execute(self, instruction: Instruction):
        # I'm using 3.10's pattern matching, but you can use a
        # dictionary to dispatch to functions instead, or a series of
        # if statements.
        match instruction:
            case Instruction(mnemonic="NOP"):
                pass
            case _:
                raise InstructionError(f"Cannot execute {instruction}")

    def run(self):
        while True:
            address = self.registers["PC"]
            try:
                next_address, instruction = self.decoder.decode(address)
            except IndexError:
                break
            self.registers["PC"] = next_address
            self.execute(instruction)

Pretty simple. I’m again using the dependency injection pattern. That means the CPU shouldn’t know how to create or instantiate extant classes that it depends on. To use it, you must pass the CPU constructor instances of the Decoder (that you created in the last chapter) and Registers.

I like this pattern because it separates the concerns so each class only knows exactly what it needs to know, and nothing more! So we could, if we wanted to, pass in FakeRegisters or a FakeDecoder that mimics certain behavior we want to test, or even alternative implementations.

But as you can see, the implementation is fairly sparse. And yet this is enough to start implementing instructions. There’s no memory bank controller yet, and no display or any other fancy features we need, but that’s fine. We’ll get to them later. But because we fastidiously implemented one piece at a time, it’s now a case of snapping together the pieces we’ve built so far:

Instruction fetching and decoding is (mostly) done

Thanks to a single decode method we can now fetch an instruction from a stream of bytes; decode the instruction; advance the stream to the next position; and return the decoded instruction.

The CPU is now in a prime position to make use of that information. We know the address of the next logical instruction (next_address) and can update the PC registers accordingly.

Instruction Execution is the next big step

I’m going to use Python 3.10’s match and case keywords but don’t fret if you don’t have that version or don’t want to use that feature. You can get by with many, many if statements or use a dictionary to dispatch to a function that does the execution.

Consider how you’re storing the instructions you loaded from the opcodes file. You now need a way of calling out to a function that can handle that instruction.

I’ve added a single instruction, NOP, that fittingly doesn’t do anything (it means No Operation)

The run() method has an infinite while loop: once we start we don’t stop unless we run out of instructions – hence the IndexError check – or if the CPU is told to stop by an instruction or a human.

There’s not much to test, so let’s see if we can execute an arbitrary sequence of NOP instructions:

@pytest.fixture(scope="session")
def make_cpu(make_registers, make_decoder):
    def make(data, pc=0):
        cpu = CPU(registers=make_registers(pc=pc), decoder=make_decoder(data=data))
        return cpu

    return make


@given(count=st.integers(min_value=0, max_value=100))
def test_cpu_execute_nop_and_advance(make_cpu, count):
    cpu = make_cpu(b"\x00" * count)
    assert cpu.registers["PC"] == 0
    cpu.run()
    assert cpu.registers["PC"] == count

And that’s it. Our skeleton CPU is complete. It can read and write to each register and flag as required; and it can execute instructions.