Implement timer, some IO operations and more CPU instructions

https://github.com/AllenDang/cimgui-go

.gitignore

@@ -1,2 +1,2 @@
 rom.gb
-
+imgui.ini

README.md

@@ -1,3 +1,5 @@
 # gb-player
 
-Fun with Go and GameBoy cartridges
+Learning the Go Programming Language by making a Game Boy emulator.
+
+https://hacktheplanet.be/2025/08/29/game-boy-emulator-in-go/

gb/bus.go

@@ -0,0 +1,92 @@
+package gb
+
+import (
+	"fmt"
+)
+
+// 0x0000 - 0x3FFF : ROM Bank 0
+// 0x4000 - 0x7FFF : ROM Bank 1 - Switchable
+// 0x8000 - 0x97FF : CHR RAM
+// 0x9800 - 0x9BFF : BG Map 1
+// 0x9C00 - 0x9FFF : BG Map 2
+// 0xA000 - 0xBFFF : Cartridge RAM
+// 0xC000 - 0xCFFF : RAM Bank 0
+// 0xD000 - 0xDFFF : RAM Bank 1-7 - switchable - Color only
+// 0xE000 - 0xFDFF : Reserved - Echo RAM
+// 0xFE00 - 0xFE9F : Object Attribute Memory
+// 0xFEA0 - 0xFEFF : Reserved - Unusable
+// 0xFF00 - 0xFF7F : I/O Registers
+// 0xFF80 - 0xFFFE : Zero Page
+
+type Bus struct {
+	Cart *Cartridge
+	RAM  *RAM
+}
+
+func NewBus(cart *Cartridge) *Bus {
+	bus := Bus{Cart: cart, RAM: NewRAM()}
+
+	return &bus
+}
+
+func (bus *Bus) Read(address uint16) byte {
+	if address < 0x8000 {
+		// ROM data
+		value, err := bus.Cart.Read(address)
+		if err != nil {
+			fmt.Printf("Error reading from bus address %X: %s\n", address, err)
+			return 0
+		}
+		return value
+	} else if address < 0xE000 {
+		//WRAM (Working RAM)
+		return bus.RAM.WRAMRead(address)
+	} else if address < 0xFF80 {
+		//IO Registers
+		return IORead(address)
+	} else {
+		fmt.Printf("Reading from bus address %X not implemented!\n", address)
+		return 0
+	}
+}
+
+func (bus *Bus) Read16(address uint16) uint16 {
+	lo := bus.Read(address)
+	hi := bus.Read(address + 1)
+
+	return uint16(lo) | uint16(hi)<<8
+}
+
+func (bus *Bus) Write(address uint16, value byte) error {
+	if address < 0x8000 {
+		// ROM data
+		err := bus.Cart.Write(address, value)
+		if err != nil {
+			return fmt.Errorf("Error writing to bus address %X: %s", address, err)
+		}
+		return nil
+	} else if address < 0xE000 {
+		//WRAM (Working RAM)
+		bus.RAM.WRAMWrite(address, value)
+		return nil
+	} else if address < 0xFF80 {
+		//IO Registers
+		IOWrite(address, value)
+		return nil
+	} else {
+		return fmt.Errorf("Writing to bus address %X not implemented!", address)
+	}
+}
+
+func (bus *Bus) Write16(address uint16, value uint16) error {
+	err := bus.Write(address+1, byte((value>>8)&0xFF))
+	if err != nil {
+		return err
+	}
+	err = bus.Write(address, byte(value&0xFF))
+	if err != nil {
+		return err
+	}
+
+	return nil
+}

gb/cartridge.go

@@ -1,23 +1,13 @@
 package gb
 
 import (
+	"bytes"
 	"encoding/binary"
-	"io"
-	"log"
+	"fmt"
 	"os"
 )
 
-// See https://gbdev.io/pandocs/The_Cartridge_Header.html#0104-0133--nintendo-logo
-var expectedLogo = [48]byte{
-	0xCE, 0xED, 0x66, 0x66, 0xCC, 0x0D, 0x00, 0x0B,
-	0x03, 0x73, 0x00, 0x83, 0x00, 0x0C, 0x00, 0x0D,
-	0x00, 0x08, 0x11, 0x1F, 0x88, 0x89, 0x00, 0x0E,
-	0xDC, 0xCC, 0x6E, 0xE6, 0xDD, 0xDD, 0xD9, 0x99,
-	0xBB, 0xBB, 0x67, 0x63, 0x6E, 0x0E, 0xEC, 0xCC,
-	0xDD, 0xDC, 0x99, 0x9F, 0xBB, 0xB9, 0x33, 0x3E,
-}
-
-// Cartridge types
+// Cartridge types aka Mappers
 // See https://gbdev.io/pandocs/The_Cartridge_Header.html#0147--cartridge-type
 var cartridgeTypes = map[byte]string{
 	0x00: "ROM ONLY",
@@ -53,7 +43,7 @@ var cartridgeTypes = map[byte]string{
 // RAM sizes
 // https://gbdev.io/pandocs/The_Cartridge_Header.html#0149--ram-size
 var ramSizes = map[byte]string{
-	0x00: "0 - No RAM ",
+	0x00: "0 - No RAM",
 	0x01: "UNUSED VALUE",
 	0x02: "8 KiB - 1 bank",
 	0x03: "32 KiB - 4 banks of 8 KiB each",
@@ -214,6 +204,7 @@ var oldLicensees = map[byte]string{
 }
 
 type ROMHeader struct {
+	_          [256]byte
 	EntryPoint [4]byte
 	Logo       [48]byte
 	// NOTE(m): Assuming "old" cartridges here. This may cause problems with newer cartridges.
@@ -227,11 +218,13 @@ type ROMHeader struct {
 	DestinationCode      byte
 	OldLicenseeCode      byte
 	MaskROMVersionNumber byte
-	HeaderChecksum       byte
+	Checksum             byte
 	GlobalChecksum       [2]byte
 }
 
 type Cartridge struct {
+	Header      *ROMHeader
+	Data        []byte
 	Filename    string
 	Mapper      string
 	Title       string
@@ -241,59 +234,67 @@ type Cartridge struct {
 	RAMSize     string
 	Destination string
 	Version     int
+	Checksum    byte
 }
 
-func Insert(filename string) Cartridge {
-	file, err := os.Open("rom.gb")
-	if err != nil {
-		log.Fatal(err)
-	}
-	defer file.Close()
-	cartridge := Cartridge{Filename: file.Name()}
+func InsertCartridge(filename string) (*Cartridge, error) {
+	cart := Cartridge{Filename: filename}
 
-	// Jump to start of header
-	_, err = file.Seek(0x0100, io.SeekStart)
+	data, err := os.ReadFile(filename)
 	if err != nil {
-		log.Fatal(err)
+		return &cart, err
 	}
+	cart.Data = data
 
 	// Read header
 	var header ROMHeader
-	err = binary.Read(file, binary.LittleEndian, &header)
+	buffer := bytes.NewReader(cart.Data)
+	err = binary.Read(buffer, binary.LittleEndian, &header)
 	if err != nil {
-		log.Fatal(err)
-	}
-
-	// Validate the ROM by checking presence of the Nintendo logo
-	if header.Logo != expectedLogo {
-		log.Fatal("Invalid ROM file: No valid logo found!")
+		return &cart, nil
 	}
+	cart.Header = &header
 
 	// Convert some header values
-	cartridge.Title = string(header.Title[:])
-	cartridge.Mapper = cartridgeTypes[header.CartridgeType]
+	cart.Title = string(bytes.Trim(header.Title[:], "\x00"))
+	cart.Mapper = cartridgeTypes[header.CartridgeType]
 	if header.OldLicenseeCode == 0x33 {
 		// FIXME(m): Support new licensee codes
-		cartridge.Licensee = "Indicates that the New licensee code should be used instead."
+		cart.Licensee = "Indicates that the New licensee code should be used instead."
 	} else {
-		cartridge.Licensee = oldLicensees[header.OldLicenseeCode]
+		cart.Licensee = oldLicensees[header.OldLicenseeCode]
 	}
-	cartridge.SGBSupport = (header.SGBFlag == 0x03)
-	cartridge.ROMSize = 32 * (1 << header.ROMSize)
-	cartridge.RAMSize = ramSizes[header.RAMSize]
-	if header.DestinationCode == 0x00 {
-		cartridge.Destination = "Japan (and possibly overseas)"
-	} else if header.DestinationCode == 0x01 {
-		cartridge.Destination = "Overseas only"
-	} else {
-		cartridge.Destination = "UNKNOWN"
+	cart.SGBSupport = (header.SGBFlag == 0x03)
+	cart.ROMSize = 32 * (1 << header.ROMSize)
+	cart.RAMSize = ramSizes[header.RAMSize]
+	switch header.DestinationCode {
+	case 0x00:
+		cart.Destination = "Japan (and possibly overseas)"
+	case 0x01:
+		cart.Destination = "Overseas only"
+	default:
+		cart.Destination = "UNKNOWN"
 	}
-	cartridge.Version = int(header.MaskROMVersionNumber)
+	cart.Version = int(header.MaskROMVersionNumber)
 
-	// TODO(m): Verify header checksum
+	// Calculate and verify checksum
+	for address := uint16(0x0134); address <= uint16(0x014C); address++ {
+		cart.Checksum = cart.Checksum - cart.Data[address] - 1
+	}
+	if cart.Checksum != header.Checksum {
+		return &cart, fmt.Errorf("ROM checksum failed: %X does not equal %X", cart.Checksum, header.Checksum)
+	}
 
 	// NOTE(m): Ignoring global checksum which is not used, except by one emulator.
 	// See https://gbdev.io/pandocs/The_Cartridge_Header.html#014e-014f--global-checksum
 
-	return cartridge
+	return &cart, nil
+}
+
+func (cart *Cartridge) Read(address uint16) (byte, error) {
+	return cart.Data[address], nil
+}
+
+func (cart *Cartridge) Write(address uint16, value byte) error {
+	return fmt.Errorf("Writing to cartridge address %X not implemented!", address)
 }

gb/cartridge_test.go

@@ -0,0 +1,31 @@
+package gb
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestInsert(t *testing.T) {
+	cartridge, err := InsertCartridge("../roms/dmg-acid2.gb")
+
+	assert := assert.New(t)
+
+	assert.Nil(err)
+	assert.Equal(cartridge.Filename, "../roms/dmg-acid2.gb")
+	assert.Equal(cartridge.Title, "DMG-ACID2")
+	assert.Equal(cartridge.Mapper, "ROM ONLY")
+	assert.Equal(cartridge.Licensee, "None")
+	assert.False(cartridge.SGBSupport, "SGB support should be false")
+	assert.Equal(cartridge.ROMSize, 32)
+	assert.Equal(cartridge.RAMSize, "0 - No RAM")
+	assert.Equal(cartridge.Destination, "Japan (and possibly overseas)")
+	assert.Equal(cartridge.Version, 0)
+	assert.Equal(cartridge.Checksum, byte(0x9F))
+}
+
+func TestFailedChecksum(t *testing.T) {
+	_, err := InsertCartridge("../roms/failed-checksum.gb")
+
+	assert.EqualError(t, err, "ROM checksum failed: 9F does not equal 41")
+}

gb/console.go

@@ -0,0 +1,72 @@
+package gb
+
+import (
+	"fmt"
+	"image"
+	"image/color"
+)
+
+const (
+	ConsoleWidth  = 160
+	ConsoleHeight = 144
+)
+
+type Console struct {
+	Bus   *Bus
+	CPU   *CPU
+	front *image.RGBA
+	Ticks uint64
+}
+
+func NewConsole(path string) (*Console, error) {
+	cart, err := InsertCartridge(path)
+	if err != nil {
+		return &Console{}, err
+	}
+
+	fmt.Println("Cartridge loaded:")
+	fmt.Printf("\t Title    : %s\n", cart.Title)
+	fmt.Printf("\t Type     : %02X (%s)\n", cart.Header.CartridgeType, cart.Mapper)
+	fmt.Printf("\t ROM Size : %d KB\n", cart.ROMSize)
+	fmt.Printf("\t RAM Size : %02X (%s)\n", cart.Header.RAMSize, cart.RAMSize)
+	fmt.Printf("\t LIC Code : %02X (%s)\n", cart.Header.OldLicenseeCode, cart.Licensee)
+	fmt.Printf("\t ROM Vers : %02X\n", cart.Header.MaskROMVersionNumber)
+	fmt.Printf("\t Checksum : %02X ", cart.Checksum)
+	if cart.Checksum == cart.Header.Checksum {
+		fmt.Printf("(PASSED)\n")
+	} else {
+		fmt.Printf("(FAILED)\n")
+	}
+
+	buffer := image.NewRGBA(image.Rect(0, 0, ConsoleWidth, ConsoleHeight))
+
+	bus := NewBus(cart)
+	console := Console{Bus: bus, CPU: NewCPU(bus), front: buffer}
+
+	return &console, nil
+}
+
+func (console *Console) StepMilliSeconds(ms uint64) {
+	speed := int(ms / 3)
+	for y := range ConsoleHeight {
+		for x := range ConsoleWidth {
+			console.front.Set(x, y, color.RGBA{0, uint8(y + speed), uint8(x + speed), 255})
+		}
+	}
+}
+
+func (console *Console) Buffer() *image.RGBA {
+
+	return console.front
+}
+
+func (console *Console) Cycle(cycles int) {
+	for range cycles {
+		// Cycles are given in M-cycles (machine cycles) instead of T-states (system clock ticks)
+		// One machine cycle takes 4 system clock ticks to complete
+		for range 4 {
+			console.Ticks++
+			timer.Tick()
+		}
+	}
+}

gb/cpu.go

@@ -0,0 +1,382 @@
+package gb
+
+import (
+	"fmt"
+	"os"
+)
+
+const CPUFrequency = 4194304
+
+type CPUFlags byte
+
+const (
+	C CPUFlags = 1 << 4 // Carry Flag
+	H CPUFlags = 1 << 5 // Half Carry Flag
+	N CPUFlags = 1 << 6 // Subtract Flag
+	Z CPUFlags = 1 << 7 // Zero Flag
+)
+
+type Registers struct {
+	A  byte
+	F  CPUFlags
+	B  byte
+	C  byte
+	D  byte
+	E  byte
+	H  byte
+	L  byte
+	PC uint16
+	SP uint16
+}
+
+type CPU struct {
+	Bus                   *Bus
+	Regs                  Registers
+	Halted                bool
+	Stepping              bool
+	InterruptMasterEnable bool
+	InterruptFlags        byte
+}
+
+func NewCPU(bus *Bus) *CPU {
+	cpu := CPU{}
+	cpu.Bus = bus
+	// NOTE(m): PC is usually set to 0x100 by the boot rom
+	// TODO(m): SP is usually set programmatically by the cartridge code.
+	// Remove this hardcoded value later!
+	cpu.Regs = Registers{SP: 0xDFFF}
+	cpu.Stepping = true
+
+	return &cpu
+}
+
+func (cpu *CPU) Step() {
+	if !cpu.Halted {
+		opcode := cpu.Bus.Read(cpu.Regs.PC)
+
+		fmt.Printf("%04X: (%02X %02X %02X) A: %02X B: %02X C: %02X D: %02X E: %02X H: %02X L: %02X\n", cpu.Regs.PC,
+			opcode, cpu.Bus.Read(cpu.Regs.PC+1), cpu.Bus.Read(cpu.Regs.PC+2), cpu.Regs.A, cpu.Regs.B, cpu.Regs.C,
+			cpu.Regs.D, cpu.Regs.E, cpu.Regs.H, cpu.Regs.L)
+
+		cpu.Regs.PC++
+
+		switch opcode {
+
+		case 0x00:
+			// NOP
+
+		case 0x0D:
+			// DEC C
+			cpu.Regs.C--
+
+			// Set appropriate flags
+			if cpu.Regs.C == 0 {
+				cpu.SetFlag(Z)
+			} else {
+				cpu.ClearFlag(Z)
+			}
+
+			cpu.SetFlag(N)
+
+			if (cpu.Regs.C & 0x0F) == 0x0F {
+				cpu.SetFlag(H)
+			} else {
+				cpu.ClearFlag(H)
+			}
+
+		case 0x0E:
+			// LD C, n8
+			val := cpu.Bus.Read(cpu.Regs.PC)
+			//     emu_cycles(1);
+			cpu.Regs.C = val
+			cpu.Regs.PC++
+
+		case 0x10:
+			// STOP n8
+			cpu.Halted = true
+
+		case 0x11:
+			// LD DE, n16
+			cpu.Regs.E = cpu.Bus.Read(cpu.Regs.PC)
+			//     emu_cycles(1);
+			cpu.Regs.D = cpu.Bus.Read(cpu.Regs.PC + 1)
+			// emu_cycles(1);
+			cpu.Regs.PC += 2
+
+		case 0x12:
+			// LD [DE], A
+			// Get 16-bit address from DE
+			address := uint16(cpu.Regs.D)<<8 | uint16(cpu.Regs.E)
+			cpu.Bus.Write(address, cpu.Regs.A)
+
+		case 0x14:
+			// INC D
+			cpu.Regs.D++
+
+			// Set appropriate flags
+			if cpu.Regs.D == 0 {
+				cpu.SetFlag(Z)
+			} else {
+				cpu.ClearFlag(Z)
+			}
+
+			cpu.ClearFlag(N)
+
+			if (cpu.Regs.D & 0x0F) == 0 {
+				cpu.SetFlag(H)
+			} else {
+				cpu.ClearFlag(H)
+			}
+
+		case 0x18:
+			// JR e8
+			// Jump relative to 8-bit signed offset
+			// emu_cycles(3);
+			offset := int8(cpu.Bus.Read(cpu.Regs.PC))
+			cpu.Regs.PC++
+			cpu.Regs.PC = uint16(int(cpu.Regs.PC) + int(offset))
+
+		case 0x1C:
+			// INC E
+			cpu.Regs.E++
+
+			// Set appropriate flags
+			if cpu.Regs.E == 0 {
+				cpu.SetFlag(Z)
+			} else {
+				cpu.ClearFlag(Z)
+			}
+
+			cpu.ClearFlag(N)
+
+			if (cpu.Regs.E & 0x0F) == 0 {
+				cpu.SetFlag(H)
+			} else {
+				cpu.ClearFlag(H)
+			}
+
+		case 0x20:
+			// JR NZ, e8
+			if cpu.IsFlagSet(Z) {
+				// Z is set, don't execute
+				// emu_cycles(2);
+				cpu.Regs.PC++
+			} else {
+				// Z is not set, execute
+				// Jump relative to 8-bit signed offset
+				// emu_cycles(3);
+				offset := int8(cpu.Bus.Read(cpu.Regs.PC))
+				cpu.Regs.PC++
+				cpu.Regs.PC = uint16(int(cpu.Regs.PC) + int(offset))
+			}
+
+		case 0x21:
+			// LD HL, n16
+			cpu.Regs.L = cpu.Bus.Read(cpu.Regs.PC)
+			//     emu_cycles(1);
+			cpu.Regs.H = cpu.Bus.Read(cpu.Regs.PC + 1)
+			// emu_cycles(1);
+			cpu.Regs.PC += 2
+
+		case 0x2A:
+			// LD A, [HL+] or LD A, [HLI]
+			// Get 16-bit address from HL
+			address := uint16(cpu.Regs.H)<<8 | uint16(cpu.Regs.L)
+			// Read byte at address and assign value to A register
+			cpu.Regs.A = cpu.Bus.Read(address)
+			// emu_cycles(1);
+			// Increment HL
+			address++
+			cpu.Regs.H = byte(address >> 8)
+			cpu.Regs.L = byte(address)
+			// emu_cycles(1);
+
+		case 0x31:
+			// LD SP, n16
+			lo := cpu.Bus.Read(cpu.Regs.PC)
+			//     emu_cycles(1);
+			hi := cpu.Bus.Read(cpu.Regs.PC + 1)
+			// emu_cycles(1);
+			cpu.Regs.SP = uint16(lo) | uint16(hi)<<8
+			cpu.Regs.PC += 2
+
+		case 0x3C:
+			// INC A
+			cpu.Regs.A++
+
+			// Set appropriate flags
+			if cpu.Regs.A == 0 {
+				cpu.SetFlag(Z)
+			} else {
+				cpu.ClearFlag(Z)
+			}
+
+			cpu.ClearFlag(N)
+
+			if (cpu.Regs.A & 0x0F) == 0 {
+				cpu.SetFlag(H)
+			} else {
+				cpu.ClearFlag(H)
+			}
+
+		case 0x3E:
+			// LD A, n8
+			val := cpu.Bus.Read(cpu.Regs.PC)
+			//     emu_cycles(1);
+			cpu.Regs.A = val
+			cpu.Regs.PC++
+
+		case 0x47:
+			// LD B, A
+			cpu.Regs.B = cpu.Regs.A
+
+		case 0x78:
+			// LD A, B
+			cpu.Regs.A = cpu.Regs.B
+
+		case 0x7C:
+			// LD A, H
+			cpu.Regs.A = cpu.Regs.H
+
+		case 0x7D:
+			// LD A, L
+			cpu.Regs.A = cpu.Regs.L
+
+		case 0xCB:
+			// Prefix byte instructions
+			cbOpcode := cpu.Bus.Read(cpu.Regs.PC)
+
+			fmt.Printf("%04X: (%02X %02X %02X) A: %02X B: %02X C: %02X\n", cpu.Regs.PC,
+				cbOpcode, cpu.Bus.Read(cpu.Regs.PC+1), cpu.Bus.Read(cpu.Regs.PC+2), cpu.Regs.A, cpu.Regs.B, cpu.Regs.C)
+
+			cpu.Regs.PC++
+
+			switch cbOpcode {
+			// case 0x7E:
+			// 	// BIT 7, [HL]
+			// 	// Read byte pointed to by address HL
+			// 	address := uint16(cpu.Regs.H)<<8 | uint16(cpu.Regs.L)
+			// 	val := cpu.Bus.Read(address)
+
+			// 	// Check if bit 7 is set
+			// 	if (val & 0x80) == 0 {
+			// 		// Set zero flag if bit is not set
+			// 		cpu.SetFlag(Z)
+			// 	}
+			// 	cpu.ClearFlag(N)
+			// 	cpu.SetFlag(H)
+
+			default:
+				fmt.Printf("\nINVALID INSTRUCTION! Unknown CB opcode: %02X\n", cbOpcode)
+				os.Exit(1)
+			}
+
+		case 0xC3:
+			// JP a16
+			lo := cpu.Bus.Read(cpu.Regs.PC)
+			//     emu_cycles(1);
+			hi := cpu.Bus.Read(cpu.Regs.PC + 1)
+			// emu_cycles(1);
+			cpu.Regs.PC = uint16(lo) | uint16(hi)<<8
+
+		case 0xC9:
+			// RET
+			// emu_cycles(4);
+			cpu.Regs.PC = cpu.StackPop16()
+
+		case 0xCD:
+			// CALL a16
+			cpu.StackPush16(cpu.Regs.PC + 2)
+
+			lo := cpu.Bus.Read(cpu.Regs.PC)
+			//     emu_cycles(1);
+			hi := cpu.Bus.Read(cpu.Regs.PC + 1)
+			// emu_cycles(1);
+			cpu.Regs.PC = uint16(lo) | uint16(hi)<<8
+
+		case 0xE0:
+			// LDH [a8], A
+			offset := cpu.Bus.Read(cpu.Regs.PC)
+			address := 0xFF00 | uint16(offset)
+			cpu.Bus.Write(address, cpu.Regs.A)
+			cpu.Regs.PC++
+
+		case 0xE5:
+			// PUSH HL
+			// emu_cycles(4);
+			cpu.StackPush(cpu.Regs.H)
+			cpu.StackPush(cpu.Regs.L)
+
+		case 0xE9:
+			// JP HL
+			val := uint16(cpu.Regs.H)<<8 | uint16(cpu.Regs.L)
+			cpu.Regs.PC = val
+
+		case 0xEA:
+			// LD [a16], A
+			lo := cpu.Bus.Read(cpu.Regs.PC)
+			cpu.Regs.PC++
+			hi := cpu.Bus.Read(cpu.Regs.PC)
+			cpu.Regs.PC++
+
+			address := uint16(lo) | uint16(hi)<<8
+			cpu.Bus.Write(address, cpu.Regs.A)
+
+		case 0xF3:
+			// DI
+			cpu.InterruptMasterEnable = false
+
+		default:
+			fmt.Printf("\nINVALID INSTRUCTION! Unknown opcode: %02X\n", opcode)
+			os.Exit(1)
+		}
+	}
+}
+
+func (cpu *CPU) SetFlag(flag CPUFlags) {
+	cpu.Regs.F |= flag
+}
+
+func (cpu *CPU) ClearFlag(flag CPUFlags) {
+	cpu.Regs.F &^= flag
+}
+
+func (cpu *CPU) ToggleFlag(flag CPUFlags) {
+	cpu.Regs.F ^= flag
+}
+
+func (cpu *CPU) IsFlagSet(flag CPUFlags) bool {
+	return cpu.Regs.F&flag != 0
+}
+
+func (cpu *CPU) StackPush(data byte) {
+	cpu.Regs.SP--
+	cpu.Bus.Write(cpu.Regs.SP, data)
+}
+
+func (cpu *CPU) StackPush16(data uint16) {
+	cpu.StackPush(byte((data >> 8) & 0xFF))
+	cpu.StackPush(byte(data & 0xFF))
+}
+
+func (cpu *CPU) StackPop() byte {
+	val := cpu.Bus.Read(cpu.Regs.SP)
+	cpu.Regs.SP++
+
+	return val
+}
+
+func (cpu *CPU) StackPop16() uint16 {
+	lo := cpu.StackPop()
+	hi := cpu.StackPop()
+
+	return uint16(hi)<<8 | uint16(lo)
+}
+
+func (cpu *CPU) GetInterruptFlags() byte {
+	return cpu.InterruptFlags
+}
+
+func (cpu *CPU) SetInterruptFlags(value byte) {
+	cpu.InterruptFlags = value
+}

gb/cpu_test.go

@@ -0,0 +1,520 @@
+package gb
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func createCPU(data []byte) *CPU {
+	cart := Cartridge{Filename: "test"}
+	cart.Data = data
+	cpu := NewCPU(NewBus(&cart))
+	cpu.Regs.PC = 0
+
+	return cpu
+}
+
+func TestSetFlag(t *testing.T) {
+	cartridge, _ := InsertCartridge("../roms/dmg-acid2.gb")
+	bus := NewBus(cartridge)
+	cpu := NewCPU(bus)
+
+	cpu.SetFlag(C)
+
+	assert.True(t, cpu.IsFlagSet(C))
+}
+
+func TestClearFlag(t *testing.T) {
+	cartridge, _ := InsertCartridge("../roms/dmg-acid2.gb")
+	bus := NewBus(cartridge)
+	cpu := NewCPU(bus)
+
+	cpu.SetFlag(C)
+	assert.True(t, cpu.IsFlagSet(C))
+
+	cpu.ClearFlag(C)
+	assert.False(t, cpu.IsFlagSet(C))
+}
+
+func TestToggleFlag(t *testing.T) {
+	cartridge, _ := InsertCartridge("../roms/dmg-acid2.gb")
+	bus := NewBus(cartridge)
+	cpu := NewCPU(bus)
+
+	cpu.ToggleFlag(C)
+	assert.True(t, cpu.IsFlagSet(C))
+
+	cpu.ToggleFlag(C)
+	assert.False(t, cpu.IsFlagSet(C))
+}
+
+func TestInstruction00(t *testing.T) {
+	cpu := createCPU([]byte{0x00, 0x00, 0x00})
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0x01), cpu.Regs.PC)
+}
+
+func TestInstruction3C(t *testing.T) {
+	// Should increment A register
+	cpu := createCPU([]byte{0x3C, 0x00, 0x00})
+
+	cpu.Step()
+	assert.Equal(t, byte(0x01), cpu.Regs.A)
+
+	// Should clear Zero Flag
+	cpu = createCPU([]byte{0x3C, 0x00, 0x00})
+
+	cpu.SetFlag(Z)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(Z))
+
+	// Should set Zero Flag
+	cpu = createCPU([]byte{0x3C, 0x00, 0x00})
+	cpu.Regs.A = 0xFF
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(Z))
+
+	// Should clear Subtract Flag
+	cpu = createCPU([]byte{0x3C, 0x00, 0x00})
+
+	cpu.SetFlag(N)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(N))
+
+	// Should set Half Carry Flag if we overflow from bit 3
+	cpu = createCPU([]byte{0x3C, 0x00, 0x00})
+	cpu.Regs.A = 0x0F
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(H))
+
+	// Should clear Half Carry Flag if we don't overflow from bit 3
+	cpu = createCPU([]byte{0x3C, 0x00, 0x00})
+
+	cpu.SetFlag(H)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(H))
+}
+
+func TestInstructionC3(t *testing.T) {
+	cpu := createCPU([]byte{0xC3, 0x50, 0x01})
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0x150), cpu.Regs.PC)
+}
+
+func TestInstructionE9(t *testing.T) {
+	cpu := createCPU([]byte{0xE9, 0x00, 0x00})
+	cpu.Regs.H = 0x12
+	cpu.Regs.L = 0x34
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0x1234), cpu.Regs.PC)
+}
+
+func TestInstructionF3(t *testing.T) {
+	cpu := createCPU([]byte{0xF3, 0x00, 0x00})
+
+	cpu.InterruptMasterEnable = true
+	cpu.Step()
+
+	assert.False(t, cpu.InterruptMasterEnable)
+}
+
+func TestInstruction31(t *testing.T) {
+	cpu := createCPU([]byte{0x31, 0xFF, 0xCF})
+
+	cpu.Step()
+
+	// Should load SP with n16 value
+	assert.Equal(t, uint16(0xCFFF), cpu.Regs.SP)
+
+	// Should step over the 16 bit value onto the next instruction, i.e. increase the program counter with 3.
+	assert.Equal(t, uint16(0x0003), cpu.Regs.PC)
+}
+
+func TestInstructionCD(t *testing.T) {
+	cpu := createCPU([]byte{0xCD, 0x4C, 0x48, 0x41})
+
+	cpu.Step()
+
+	// Should push the address of the next instruction onto the stack
+	// In this case 0x41 which is at address 0x03 (i.e. the 4th instruction in the row above creating the CPU instance)
+	assert.Equal(t, uint16(0x03), cpu.Bus.Read16(cpu.Regs.SP))
+
+	// Should jump to n16 value
+	assert.Equal(t, uint16(0x484C), cpu.Regs.PC)
+}
+
+func TestInstruction21(t *testing.T) {
+	cpu := createCPU([]byte{0x21, 0x34, 0x12})
+
+	cpu.Step()
+
+	// Should load the 16-bit immediate value into the combined HL register
+	assert.Equal(t, byte(0x12), cpu.Regs.H)
+	assert.Equal(t, byte(0x34), cpu.Regs.L)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x3), cpu.Regs.PC)
+}
+
+// func TestInstructionCB7E(t *testing.T) {
+// 	cpu := createCPU([]byte{0xCB, 0x7E, 0x00, 0x00})
+
+// 	cpu.Regs.H = 0xFF
+// 	cpu.Regs.L = 0x40
+// 	err := cpu.Bus.Write(0xFF40, 0xFF)
+// 	assert.Equal(t, err, nil)
+
+// 	// FIXME(m): This needs bus access to IO, in particular the LCD
+// 	// at 0xFF40.
+
+// 	// assert.Equal(t, 0xFF, cpu.Bus.Read(0xFF40))
+
+// 	// cpu.Step()
+
+// 	// // Should set the zero flag
+// 	// assert.True(t, cpu.IsFlagSet(Z))
+// }
+
+func TestInstruction47(t *testing.T) {
+	cpu := createCPU([]byte{0x47, 0x00, 0x00})
+
+	cpu.Regs.A = 0xDE
+
+	cpu.Step()
+
+	// Should load value in register A into register B
+	assert.Equal(t, byte(0xDE), cpu.Regs.B)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x1), cpu.Regs.PC)
+}
+
+func TestInstruction11(t *testing.T) {
+	cpu := createCPU([]byte{0x11, 0x34, 0x12})
+
+	cpu.Step()
+
+	// Should load the 16-bit immediate value into the combined DE register
+	assert.Equal(t, byte(0x12), cpu.Regs.D)
+	assert.Equal(t, byte(0x34), cpu.Regs.E)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x3), cpu.Regs.PC)
+}
+
+func TestInstruction0E(t *testing.T) {
+	cpu := createCPU([]byte{0x0E, 0xDE, 0x00})
+
+	cpu.Step()
+
+	// Should load the 8-bit immediate value into register C
+	assert.Equal(t, byte(0xDE), cpu.Regs.C)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x2), cpu.Regs.PC)
+}
+
+func TestInstruction2A(t *testing.T) {
+	cpu := createCPU([]byte{0x2A, 0x00, 0x00})
+	cpu.Regs.H = 0xD1
+	cpu.Regs.L = 0x23
+	cpu.Bus.Write(0xD123, 0xDE)
+
+	cpu.Step()
+
+	// Should load the byte pointed to by HL into register A
+	assert.Equal(t, byte(0xDE), cpu.Regs.A)
+
+	// Should increment HL
+	hl := uint16(cpu.Regs.H)<<8 | uint16(cpu.Regs.L)
+	assert.Equal(t, uint16(0xD124), hl)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x1), cpu.Regs.PC)
+}
+
+func TestInstruction12(t *testing.T) {
+	cpu := createCPU([]byte{0x12, 0x00, 0x00})
+	cpu.Regs.D = 0xD1
+	cpu.Regs.E = 0x23
+	cpu.Regs.A = 0xDE
+
+	cpu.Step()
+
+	// Should copy the value in register A into the byte pointed to by DE
+	address := uint16(cpu.Regs.D)<<8 | uint16(cpu.Regs.E)
+	assert.Equal(t, byte(0xDE), cpu.Bus.Read(address))
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x1), cpu.Regs.PC)
+}
+
+func TestInstruction1C(t *testing.T) {
+	// Should increment E register
+	cpu := createCPU([]byte{0x1C, 0x00, 0x00})
+
+	cpu.Step()
+	assert.Equal(t, byte(0x01), cpu.Regs.E)
+
+	// Should clear Zero Flag
+	cpu = createCPU([]byte{0x1C, 0x00, 0x00})
+
+	cpu.SetFlag(Z)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(Z))
+
+	// Should set Zero Flag
+	cpu = createCPU([]byte{0x1C, 0x00, 0x00})
+	cpu.Regs.E = 0xFF
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(Z))
+
+	// Should clear Subtract Flag
+	cpu = createCPU([]byte{0x1C, 0x00, 0x00})
+
+	cpu.SetFlag(N)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(N))
+
+	// Should set Half Carry Flag if we overflow from bit 3
+	cpu = createCPU([]byte{0x1C, 0x00, 0x00})
+	cpu.Regs.E = 0x0F
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(H))
+
+	// Should clear Half Carry Flag if we don't overflow from bit 3
+	cpu = createCPU([]byte{0x1C, 0x00, 0x00})
+
+	cpu.SetFlag(H)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(H))
+}
+
+func TestInstruction20(t *testing.T) {
+	// Should not jump if Z is set
+	cpu := createCPU([]byte{0x20, 0xFB, 0x00})
+	cpu.SetFlag(Z)
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0x02), cpu.Regs.PC)
+
+	// Should jump to positive offset if Z is not set
+	cpu = createCPU([]byte{0x20, 0x0A, 0x00})
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0x0C), cpu.Regs.PC)
+
+	// Should jump to negative offset if Z is not set
+	cpu = createCPU([]byte{0x20, 0xFB, 0x00})
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0xFFFD), cpu.Regs.PC)
+}
+
+func TestInstruction10(t *testing.T) {
+	cpu := createCPU([]byte{0x10, 0x2A, 0x12})
+
+	cpu.Step()
+
+	assert.True(t, cpu.Halted)
+}
+
+func TestInstruction14(t *testing.T) {
+	// Should increment D register
+	cpu := createCPU([]byte{0x14, 0x00, 0x00})
+
+	cpu.Step()
+	assert.Equal(t, byte(0x01), cpu.Regs.D)
+
+	// Should clear Zero Flag
+	cpu = createCPU([]byte{0x14, 0x00, 0x00})
+
+	cpu.SetFlag(Z)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(Z))
+
+	// Should set Zero Flag
+	cpu = createCPU([]byte{0x14, 0x00, 0x00})
+	cpu.Regs.D = 0xFF
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(Z))
+
+	// Should clear Subtract Flag
+	cpu = createCPU([]byte{0x14, 0x00, 0x00})
+
+	cpu.SetFlag(N)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(N))
+
+	// Should set Half Carry Flag if we overflow from bit 3
+	cpu = createCPU([]byte{0x14, 0x00, 0x00})
+	cpu.Regs.D = 0x0F
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(H))
+
+	// Should clear Half Carry Flag if we don't overflow from bit 3
+	cpu = createCPU([]byte{0x14, 0x00, 0x00})
+
+	cpu.SetFlag(H)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(H))
+}
+
+func TestInstruction0D(t *testing.T) {
+	// Should decrement C register
+	cpu := createCPU([]byte{0x0D, 0x00, 0x00})
+	cpu.Regs.C = 0x01
+
+	cpu.Step()
+	assert.Equal(t, byte(0x00), cpu.Regs.C)
+
+	// Should clear Zero Flag
+	cpu = createCPU([]byte{0x0D, 0x00, 0x00})
+
+	cpu.SetFlag(Z)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(Z))
+
+	// Should set Zero Flag
+	cpu = createCPU([]byte{0x0D, 0x00, 0x00})
+	cpu.Regs.C = 0x01
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(Z))
+
+	// Should set Subtract Flag
+	cpu = createCPU([]byte{0x0D, 0x00, 0x00})
+
+	cpu.SetFlag(N)
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(N))
+
+	// Should set Half Carry Flag if we overflow from bit 3
+	cpu = createCPU([]byte{0x0D, 0x00, 0x00})
+	cpu.Regs.C = 0x10
+
+	cpu.Step()
+	assert.True(t, cpu.IsFlagSet(H))
+
+	// Should clear Half Carry Flag if we don't overflow from bit 3
+	cpu = createCPU([]byte{0x0D, 0x00, 0x00})
+	cpu.Regs.C = 0x01
+
+	cpu.SetFlag(H)
+	cpu.Step()
+	assert.False(t, cpu.IsFlagSet(H))
+}
+
+func TestInstruction78(t *testing.T) {
+	cpu := createCPU([]byte{0x78, 0x00, 0x00})
+
+	cpu.Regs.B = 0xDE
+
+	cpu.Step()
+
+	// Should load value in register B into register A
+	assert.Equal(t, byte(0xDE), cpu.Regs.A)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x1), cpu.Regs.PC)
+}
+
+func TestInstructionEA(t *testing.T) {
+	cpu := createCPU([]byte{0xEA, 0x23, 0xD1})
+	cpu.Regs.A = 0x42
+
+	cpu.Step()
+
+	// Should load byte in register A into the memory location pointed to by the 16-bit immediate value
+	val := cpu.Bus.Read(0xD123)
+	assert.Equal(t, byte(0x42), val)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x3), cpu.Regs.PC)
+}
+
+func TestInstruction3E(t *testing.T) {
+	cpu := createCPU([]byte{0x3E, 0xDE, 0x00})
+
+	cpu.Step()
+
+	// Should load the 8-bit immediate value into register A
+	assert.Equal(t, byte(0xDE), cpu.Regs.A)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x2), cpu.Regs.PC)
+}
+
+func TestInstructionE0(t *testing.T) {
+	cpu := createCPU([]byte{0xE0, 0x07, 0x00})
+	cpu.Regs.A = 0x42
+
+	cpu.Step()
+
+	// Should copy the value in register A into the byte at address 0xFF00 + 0x07
+	val := cpu.Bus.Read(0xFF07)
+	assert.Equal(t, byte(0x42), val)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x2), cpu.Regs.PC)
+}
+
+func TestInstruction7D(t *testing.T) {
+	cpu := createCPU([]byte{0x7D, 0x00, 0x00})
+
+	cpu.Regs.L = 0xDE
+
+	cpu.Step()
+
+	// Should load into register A the value in register L
+	assert.Equal(t, byte(0xDE), cpu.Regs.A)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x1), cpu.Regs.PC)
+}
+
+func TestInstruction7C(t *testing.T) {
+	cpu := createCPU([]byte{0x7C, 0x00, 0x00})
+
+	cpu.Regs.H = 0xDE
+
+	cpu.Step()
+
+	// Should load into register A the value in register H
+	assert.Equal(t, byte(0xDE), cpu.Regs.A)
+
+	// Should increase the stack pointer
+	assert.Equal(t, uint16(0x1), cpu.Regs.PC)
+}
+
+func TestInstruction18(t *testing.T) {
+	// Should jump to positive offset
+	cpu := createCPU([]byte{0x18, 0x0A, 0x00})
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0x0C), cpu.Regs.PC)
+
+	// Should jump to negative offset
+	cpu = createCPU([]byte{0x18, 0xFB, 0x00})
+
+	cpu.Step()
+
+	assert.Equal(t, uint16(0xFFFD), cpu.Regs.PC)
+}

gb/io.go

@@ -0,0 +1,45 @@
+package gb
+
+import (
+	"fmt"
+	"os"
+)
+
+var SerialData [2]byte
+var InterruptFlags byte
+
+func IORead(address uint16) byte {
+	if address == 0xFF01 {
+		return SerialData[0]
+	} else if address == 0xFF02 {
+		return SerialData[1]
+	} else if (address >= 0xFF04) && (address <= 0xFF07) {
+		return timer.Read(address)
+	} else if address == 0xFF0F {
+		return InterruptFlags
+	} else if (address >= 0xFF10) && (address <= 0xFF3F) {
+		// Ignore sound
+		return 0
+	} else {
+		fmt.Printf("Reading from IO: invalid address %X\n", address)
+		os.Exit(1)
+	}
+	return 0
+}
+
+func IOWrite(address uint16, value byte) {
+	if address == 0xFF01 {
+		SerialData[0] = value
+	} else if address == 0xFF02 {
+		SerialData[1] = value
+	} else if (address >= 0xFF04) && (address <= 0xFF07) {
+		timer.Write(address, value)
+	} else if address == 0xFF0F {
+		InterruptFlags = value
+	} else if (address >= 0xFF10) && (address <= 0xFF3F) {
+		// Ignore sound
+	} else {
+		fmt.Printf("Writing to IO: invalid address %X\n", address)
+		os.Exit(1)
+	}
+}

gb/ram.go

@@ -0,0 +1,55 @@
+package gb
+
+import (
+	"fmt"
+	"os"
+)
+
+type RAM struct {
+	WRAM [0x2000]byte
+	HRAM [0x80]byte
+}
+
+func NewRAM() *RAM {
+	ram := RAM{}
+
+	return &ram
+}
+
+func (ram *RAM) WRAMRead(address uint16) byte {
+	// TODO(m): Understand this line
+	address -= 0xC000
+
+	if address >= 0x2000 {
+		fmt.Printf("Reading from WRAM: invalid address %X\n", address+0xC000)
+		os.Exit(1)
+	}
+
+	return ram.WRAM[address]
+}
+
+func (ram *RAM) WRAMWrite(address uint16, value byte) {
+	// TODO(m): Understand this line
+	address -= 0xC000
+
+	if address >= 0x2000 {
+		fmt.Printf("Writing to WRAM: invalid address %X\n", address)
+		os.Exit(1)
+	}
+
+	ram.WRAM[address] = value
+}
+
+func (ram *RAM) HRAMRead(address uint16) byte {
+	// TODO(m): Understand this line
+	address -= 0xFF80
+
+	return ram.HRAM[address]
+}
+
+func (ram *RAM) HRAMWrite(address uint16, value byte) {
+	// TODO(m): Understand this line
+	address -= 0xFF80
+
+	ram.HRAM[address] = value
+}

gb/stack_test.go

@@ -0,0 +1,59 @@
+package gb
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestStackPush(t *testing.T) {
+	cpu := createCPU([]byte{0x00, 0x00, 0x00})
+
+	cpu.StackPush(0xDE)
+
+	// Should decrement the stack pointer
+	assert.Equal(t, cpu.Regs.SP, uint16(0xDFFE))
+
+	// Should write the value to the stack
+	assert.Equal(t, cpu.Bus.Read(cpu.Regs.SP), byte(0xDE))
+}
+
+func TestStackPush16(t *testing.T) {
+	cpu := createCPU([]byte{0x00, 0x00, 0x00})
+
+	cpu.StackPush16(0xDEAD)
+
+	// Should decrement the stack pointer twice
+	assert.Equal(t, cpu.Regs.SP, uint16(0xDFFD))
+
+	// Should write the value to the stack
+	assert.Equal(t, cpu.Bus.Read16(cpu.Regs.SP), uint16(0xDEAD))
+}
+
+func TestStackPop(t *testing.T) {
+	cpu := createCPU([]byte{0x00, 0x00, 0x00})
+
+	cpu.StackPush(0xDE)
+
+	val := cpu.StackPop()
+
+	// Should increment the stack pointer
+	assert.Equal(t, cpu.Regs.SP, uint16(0xDFFF))
+
+	// Should return the byte value
+	assert.Equal(t, val, byte(0xDE))
+}
+
+func TestStackPop16(t *testing.T) {
+	cpu := createCPU([]byte{0x00, 0x00, 0x00})
+
+	cpu.StackPush16(0xBEEF)
+
+	val := cpu.StackPop16()
+
+	// Should increment the stack pointer
+	assert.Equal(t, cpu.Regs.SP, uint16(0xDFFF))
+
+	// Should return the 16 bit value
+	assert.Equal(t, val, uint16(0xBEEF))
+}

gb/timer.go

@@ -0,0 +1,125 @@
+package gb
+
+import (
+	"fmt"
+	"os"
+)
+
+var timer = Timer{DIV: 0xAC00}
+
+type Timer struct {
+	DIV  uint16
+	TIMA byte
+	TMA  byte
+	TAC  byte
+}
+
+func (timer *Timer) Tick() {
+	previousDIV := timer.DIV
+	timer.DIV++
+
+	timerNeedsUpdate := false
+
+	// Determine clock mode
+	// TAC (Timer control register)
+	// Bits 0-1 determines clock frequency
+	// 00: 4096 Hz
+	// 01: 262144 Hz
+	// 10: 65536 Hz
+	// 11: 16384 Hz
+	// Bit 2 determines whether timer is enabled or not
+
+	clockMode := timer.TAC & (0b11)
+	switch clockMode {
+	case 0b00:
+		// 4096 Hz
+		// Detect a falling edge by comparing bit 9 in the previous DIV value
+		// with bit 9 in the current DIV value
+		previouslyEnabled := previousDIV&(1<<9) != 0
+		currentlyDisabled := timer.DIV&(1<<9) == 0
+		timerNeedsUpdate = previouslyEnabled && currentlyDisabled
+
+	case 0b01:
+		// 262144 Hz
+		// Detect a falling edge by comparing bit 3 in the previous DIV value
+		// with bit 3 in the current DIV value
+		previouslyEnabled := previousDIV&(1<<3) != 0
+		currentlyDisabled := timer.DIV&(1<<3) == 0
+		timerNeedsUpdate = previouslyEnabled && currentlyDisabled
+
+	case 0b10:
+		// 65536 Hz
+		// Detect a falling edge by comparing bit 5 in the previous DIV value
+		// with bit 5 in the current DIV value
+		previouslyEnabled := previousDIV&(1<<5) != 0
+		currentlyDisabled := timer.DIV&(1<<5) == 0
+		timerNeedsUpdate = previouslyEnabled && currentlyDisabled
+
+	case 0b11:
+		// 16384 Hz
+		// Detect a falling edge by comparing bit 7 in the previous DIV value
+		// with bit 7 in the current DIV value
+		previouslyEnabled := previousDIV&(1<<7) != 0
+		currentlyDisabled := timer.DIV&(1<<7) == 0
+		timerNeedsUpdate = previouslyEnabled && currentlyDisabled
+	}
+
+	timerIsEnabled := timer.TAC&(1<<2) != 0
+	// If the timer needs to be updated based on the determined clock mode and the timer is enabled, increment the timer
+	if timerNeedsUpdate && timerIsEnabled {
+		timer.TIMA++
+
+		// Check if TIMA is going to wrap and trigger an interrupt if necessary
+		if timer.TIMA == 0xFF {
+			timer.TIMA = timer.TMA
+
+			fmt.Println("TODO: cpu_request_interrupt(IT_TIMER")
+		}
+	}
+
+}
+
+func (timer *Timer) Read(address uint16) byte {
+	switch address {
+	case 0xFF04:
+		return byte(timer.DIV >> 8)
+
+	case 0xFF05:
+		return timer.TIMA
+
+	case 0xFF06:
+		return timer.TMA
+
+	case 0xFF07:
+		return timer.TAC
+
+	default:
+		fmt.Printf("Reading from Timer: invalid address %X\n", address)
+		os.Exit(1)
+	}
+	return 0
+}
+
+func (timer *Timer) Write(address uint16, value byte) {
+	switch address {
+	case 0xFF04:
+		//DIV
+		timer.DIV = 0
+
+	case 0xFF05:
+		//TIMA
+		timer.TIMA = value
+
+	case 0xFF06:
+		//TMA
+		timer.TMA = value
+
+	case 0xFF07:
+		//TAC
+		timer.TAC = value
+
+	default:
+		fmt.Printf("Writing to Timer: invalid address %X\n", address)
+		os.Exit(1)
+	}
+}

go.mod

@@ -1,3 +1,12 @@
 module gb-player
 
 go 1.24.5
+
+require github.com/stretchr/testify v1.10.0
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/veandco/go-sdl2 v0.4.40
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,12 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/veandco/go-sdl2 v0.4.40 h1:fZv6wC3zz1Xt167P09gazawnpa0KY5LM7JAvKpX9d/U=
+github.com/veandco/go-sdl2 v0.4.40/go.mod h1:OROqMhHD43nT4/i9crJukyVecjPNYYuCofep6SNiAjY=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

main.go

@@ -2,17 +2,29 @@ package main
 
 import (
 	"fmt"
+	"log"
+	"os"
+
+	// "gb-player/ui"
 	"gb-player/gb"
 )
 
 func main() {
-	cartridge := gb.Insert("rom.gb")
-	fmt.Println("Title:", cartridge.Title)
-	fmt.Println("Mapper:", cartridge.Mapper)
-	fmt.Println("Licensee:", cartridge.Licensee)
-	fmt.Println("Super Game Boy support?", cartridge.SGBSupport)
-	fmt.Println("ROM size:", cartridge.ROMSize, "bytes")
-	fmt.Println("RAM size:", cartridge.RAMSize)
-	fmt.Println("Publication destination:", cartridge.Destination)
-	fmt.Println("ROM version:", cartridge.Version)
+	if len(os.Args) != 2 {
+		log.Fatalln("No rom file specified")
+	}
+	romPath := os.Args[1]
+
+	// ui.Run(romPath)
+
+	console, err := gb.NewConsole(romPath)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println("Executing instructions")
+
+	for !console.CPU.Halted {
+		console.CPU.Step()
+	}
 }

ui/controller.go

@@ -0,0 +1,111 @@
+package ui
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/veandco/go-sdl2/sdl"
+	"github.com/veandco/go-sdl2/ttf"
+
+	"gb-player/gb"
+)
+
+type Controller struct {
+	window    *sdl.Window
+	renderer  *sdl.Renderer
+	font      *ttf.Font
+	view      *View
+	timestamp uint64
+}
+
+func NewController(window *sdl.Window, renderer *sdl.Renderer, font *ttf.Font) *Controller {
+	controller := Controller{}
+	controller.window = window
+	controller.renderer = renderer
+	controller.font = font
+	return &controller
+}
+
+func (c *Controller) Start(path string) {
+	console, err := gb.NewConsole(path)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	c.view = NewView(c, console)
+	c.Run()
+}
+
+func (c *Controller) Step() {
+	timestamp := sdl.GetTicks64()
+	dt := timestamp - c.timestamp
+	c.timestamp = timestamp
+	c.view.Update(dt)
+}
+
+func (c *Controller) Run() {
+	var fps float64
+	var frameCount uint32
+	var frameStart = sdl.GetTicks64()
+
+	running := true
+	for running {
+		for event := sdl.PollEvent(); event != nil; event = sdl.PollEvent() {
+			switch e := event.(type) {
+			case *sdl.QuitEvent:
+				running = false
+			case *sdl.KeyboardEvent:
+				if e.Type == sdl.KEYDOWN {
+					if e.Keysym.Sym == sdl.K_ESCAPE {
+						running = false
+					}
+				}
+			}
+		}
+
+		// Clear screen
+		c.renderer.SetDrawColor(0x63, 0x94, 0xED, 0xff)
+		c.renderer.Clear()
+
+		// Update state
+		c.Step()
+		c.drawDebugWindow(fps)
+
+		// Present to screen
+		c.renderer.Present()
+
+		// Calculate framerate
+		frameCount++
+		frameEnd := sdl.GetTicks64()
+		elapsed := frameEnd - frameStart
+
+		if elapsed >= 1000 {
+			fps = float64(frameCount) / (float64(elapsed) / 1000.0)
+
+			// Reset framerate counters
+			frameCount = 0
+			frameStart = frameEnd
+		}
+	}
+}
+
+func (c *Controller) drawDebugWindow(fps float64) {
+	renderer := c.renderer
+	font := c.font
+
+	// FPS
+	textSurface, err := font.RenderUTF8Blended(fmt.Sprintf("FPS: %.2f", fps), sdl.Color{R: 0, G: 0, B: 0, A: 255})
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer textSurface.Free()
+
+	textTexture, err := renderer.CreateTextureFromSurface(textSurface)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer textTexture.Destroy()
+
+	textRect := sdl.Rect{X: 0, Y: 0, W: textSurface.W, H: textSurface.H}
+	renderer.Copy(textTexture, nil, &textRect)
+}

ui/run.go

@@ -0,0 +1,58 @@
+package ui
+
+import (
+	"log"
+	"runtime"
+
+	"github.com/veandco/go-sdl2/sdl"
+	"github.com/veandco/go-sdl2/ttf"
+)
+
+const (
+	windowWidth  = 800
+	windowHeight = 600
+)
+
+func init() {
+	runtime.LockOSThread()
+}
+
+func Run(romPath string) {
+	if err := sdl.Init(sdl.INIT_EVERYTHING); err != nil {
+		log.Fatal(err)
+	}
+	defer sdl.Quit()
+
+	if err := ttf.Init(); err != nil {
+		log.Fatal((err))
+	}
+	defer ttf.Quit()
+
+	window, err := sdl.CreateWindow(
+		"GB Player",
+		sdl.WINDOWPOS_UNDEFINED,
+		sdl.WINDOWPOS_UNDEFINED,
+		windowWidth, windowHeight,
+		sdl.WINDOW_SHOWN)
+	if err != nil {
+		panic(err)
+	}
+	defer window.Destroy()
+
+	renderer, err := sdl.CreateRenderer(window, -1, 0)
+	if err != nil {
+		panic(err)
+	}
+	defer renderer.Destroy()
+	renderer.RenderSetVSync(true)
+
+	font, err := ttf.OpenFont("SourceCodePro.ttf", 18)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer font.Close()
+	font.SetStyle(ttf.STYLE_BOLD)
+
+	controller := NewController(window, renderer, font)
+	controller.Start(romPath)
+}

ui/view.go

@@ -0,0 +1,60 @@
+package ui
+
+import (
+	"image"
+	"log"
+
+	"github.com/veandco/go-sdl2/sdl"
+
+	"gb-player/gb"
+)
+
+type View struct {
+	controller *Controller
+	console    *gb.Console
+}
+
+func NewView(controller *Controller, console *gb.Console) *View {
+	return &View{controller, console}
+}
+
+func (view *View) Update(dt uint64) {
+	console := view.console
+	renderer := view.controller.renderer
+
+	console.StepMilliSeconds(dt)
+
+	buffer := console.Buffer()
+
+	drawBuffer(renderer, buffer)
+}
+
+func drawBuffer(renderer *sdl.Renderer, buffer *image.RGBA) {
+	width, height := gb.ConsoleWidth, gb.ConsoleHeight
+
+	imageTexture, err := renderer.CreateTexture(
+		uint32(sdl.PIXELFORMAT_RGBA32),
+		sdl.TEXTUREACCESS_STREAMING,
+		int32(width), int32(height))
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer imageTexture.Destroy()
+
+	pixels, pitch, err := imageTexture.Lock(nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+	for y := range height {
+		start := y * buffer.Stride
+		end := start + width*4
+		copy(pixels[y*pitch:y*pitch+width*4], buffer.Pix[start:end])
+	}
+	imageTexture.Unlock()
+
+	x := (windowWidth / 2) - width
+	y := (windowHeight / 2) - height
+	imageRect := sdl.Rect{X: int32(x), Y: int32(y), W: 2 * int32(width), H: 2 * int32(height)}
+
+	renderer.Copy(imageTexture, nil, &imageRect)
+}