GameBoy Emulator in Zig ehhhh?

Why the hell not? Why do I want to keep making projects, and yet another one in a language I don't know? What could possibly go wrong??

Why

To really struggle and understand something deeply. In other words, no cheating with AI/LLM generative content. None of the source code will be written by an LLM nor will I consult any large language models. This includes, AI responses from search engines, LLM web interfaces, etc. It's entirely possible that I may stumble upon a blog post, a forum answer that's been generated by an LLM, but the main idea is that I have to search, read it, and determine the validity of the answer with my own critical thinking.

Also because System of Levers told me I should make a GameBoy emulator.

Resources

See RESOURCES.md for resources I'm using to fill gaps in my knowledge. Mainly around zig, GameBoy Emulation, and emulators, and a bit of systems programming.

To Do

CPU Instructions

Miscellaneous instructions

• 0x00 - NOP
• 0x10 - STOP
• 0x27 - DAA
• 0x2F - CPL
• 0x37 - SCF
• 0x3F - CCF
• 0x76 - HALT
• 0xF3 = DI
• 0xFB - EI

8-bit load instructions

• 0x02 - LD (BC), A
• 0x06 - LD B, d8
• 0x0A - LD A, (BC)
• 0x0E - LD C, d8
• 0x12 - LD (DE), A
• 0x16 - LD D, d8
• 0x1A - LD A, (DE)
• 0x1E - LD E, d8
• 0x22 - LD (HL+), A
• 0x26 - LD H, d8
• 0x2A - LD A, (HL+)
• 0x2E - LD L, d8
• 0x32 - LD (HL-), A
• 0x36 - LD (HL), d8
• 0x3A - LD A, (HL-)
• 0x3E - LD A, d8
• 0x40 - LD B, B
• 0x41 - LD B, C
• 0x42 - LD B, D
• 0x43 - LD B, E
• 0x44 - LD B, H
• 0x45 - LD B, L
• 0x46 - LD B, (HL)
• 0x47 - LD B, A
• 0x48 - LD C, B
• 0x49 - LD C, C
• 0x4A - LD C, D
• 0x4B - LD C, E
• 0x4C - LD C, H
• 0x4D - LD C, L
• 0x4E - LD C, (HL)
• 0x4F - LD C, A
• 0x50 - LD D, B
• 0x51 - LD D, C
• 0x52 - LD D, D
• 0x53 - LD D, E
• 0x54 - LD D, H
• 0x55 - LD D, L
• 0x56 - LD D, (HL)
• 0x57 - LD D, A
• 0x58 - LD E, B
• 0x59 - LD E, C
• 0x5A - LD E, D
• 0x5B - LD E, E
• 0x5C - LD E, H
• 0x5D - LD E, L
• 0x5E - LD E, (HL)
• 0x5F - LD E, A
• 0x60 - LD H, B
• 0x61 - LD H, C
• 0x62 - LD H, D
• 0x63 - LD H, E
• 0x64 - LD H, H
• 0x65 - LD H, L
• 0x66 - LD H, (HL)
• 0x67 - LD H, A
• 0x68 - LD L, B
• 0x69 - LD L, C
• 0x6A - LD L, D
• 0x6B - LD L, E
• 0x6C - LD L, H
• 0x6D - LD L, L
• 0x6E - LD L, (HL)
• 0x6F - LD L, A
• 0x70 - LD (HL), B
• 0x71 - LD (HL), C
• 0x72 - LD (HL), D
• 0x73 - LD (HL), E
• 0x74 - LD (HL), H
• 0x75 - LD (HL), L
• 0x77 - LD (HL), A
• 0x78 - LD A, B
• 0x79 - LD A, C
• 0x7A - LD A, D
• 0x7B - LD A, E
• 0x7C - LD A, H
• 0x7D - LD A, L
• 0x7E - LD A, (HL)
• 0x7F - LD A, A
• 0xE0 - LD (a8), A
• 0xE2 - LD (C), A
• 0xEA - LD (a16), A
• 0xF0 - LD A, (a8)
• 0xF2 - LD A, (C)
• 0xFA - LD A, (a16)

16-bit load instructions

• 0x01 - LD BC, d16
• 0x08 - LD (a16), SP
• 0x12 - LD DE, d16
• 0x21 - LD HL, d16
• 0x31 - LD SP, d16
• 0xC1 - POP BC
• 0xC5 - PUSH BC
• 0xD1 - POP DE
• 0xD5 - PUSH DE
• 0xE1 - POP HL
• 0xE5 - PUSH HL
• 0xF1 - POP AF
• 0xF5 - PUSH AF
• 0xF8 - LD HL, SP+s8
• 0xF9 - LD SP, HL

Control Flow Instructions

• 0x18 - JR s8
• 0x20 - JR NZ, s8
• 0x28 - JR Z, s8
• 0x30 - JR NC, s8
• 0x38 - JR C, s8
• 0xC0 - RET NZ
• 0xC2 - JP NZ, a16
• 0xC3 - JP a16
• 0xC4 - CALL NZ, a16
• 0xC7 - RST 0
• 0xC8 - RET Z
• 0xC9 - RET
• 0xCA - JP Z, a16
• 0xCC - CALL Z, a16
• 0xCD - CALL a16
• 0xCF - RST 1
• 0xD0 - RET NC
• 0xD2 - JP NC, a16
• 0xD4 - CALL NC, a16
• 0xD7 - RST 2
• 0xD8 - RET C
• 0xD9 - RETI
• 0xDA - JP C, a16
• 0xDC - CALL C, a16
• 0xDF - RST 3
• 0xE7 - RST 4
• 0xE9 - JP HL
• 0xEF - RST 5
• 0xF7 - RST 6
• 0xFF - RST 7

8-bit Arithmetic Instructions

• 0x04 - INC B
• 0x05 - DEC B
• 0x0C - INC C
• 0x0D - DEC C
• 0x14 - INC D
• 0x15 - DEC D
• 0x1C - INC E
• 0x1D - DEC E
• 0x24 - INC H
• 0x25 - DEC H
• 0x2C - INC L
• 0x2D - DEC L
• 0x34 - INC (HL)
• 0x35 - DEC (HL)
• 0x3C - INC A
• 0x3D - DEC A
• 0x80 - ADD A, B
• 0x81 - ADD A, C
• 0x82 - ADD A, D
• 0x83 - ADD A, E
• 0x84 - ADD A, H
• 0x85 - ADD A, L
• 0x86 - ADD A, (HL)
• 0x87 - ADD A, A
• 0x88 - ADC A, B
• 0x89 - ADC A, C
• 0x8A - ADC A, D
• 0x8B - ADC A, E
• 0x8C - ADC A, H
• 0x8D - ADC A, L
• 0x8E - ADC A, (HL)
• 0x8F - ADC A, A
• 0x90 - SUB B
• 0x91 - SUB C
• 0x92 - SUB D
• 0x93 - SUB E
• 0x94 - SUB H
• 0x95 - SUB L
• 0x96 - SUB (HL)
• 0x97 - SUB A
• 0x98 - SBC A, B
• 0x99 - SBC A, C
• 0x9A - SBC A, D
• 0x9B - SBC A, E
• 0x9C - SBC A, H
• 0x9D - SBC A, L
• 0x9E - SBC A, (HL)
• 0x9F - SBC A, A
• 0xA0 - AND B
• 0xA1 - AND C
• 0xA2 - AND D
• 0xA3 - AND E
• 0xA4 - AND H
• 0xA5 - AND L
• 0xA6 - AND (HL)
• 0xA7 - AND A
• 0xA8 - XOR B
• 0xA9 - XOR C
• 0xAA - XOR D
• 0xAB - XOR E
• 0xAC - XOR H
• 0xAD - XOR L
• 0xAE - XOR (HL)
• 0xAF - XOR A
• 0xB0 - OR B
• 0xB1 - OR C
• 0xB2 - OR D
• 0xB3 - OR E
• 0xB4 - OR H
• 0xB5 - OR L
• 0xB6 - OR (HL)
• 0xB7 - OR A
• 0xB8 - CP B
• 0xB9 - CP C
• 0xBA - CP D
• 0xBB - CP E
• 0xBC - CP H
• 0xBD - CP L
• 0xBE - CP (HL)
• 0xBF - CP A
• 0xC6 - ADD A, d8
• 0xCE - ADC A, d8
• 0xD6 - SUB d8
• 0xDE - SBC A, d8
• 0xE6 - AND d8
• 0xEE - XOR d8
• 0xF6 - OR d8
• 0xFE - CP d8

16-bit Arithmetic Instructions

• 0x03 - INC BC
• 0x09 - ADD HL, BC
• 0x0B - DEC BC
• 0x13 - INC DE
• 0x19 - ADD HL, DE
• 0x1B - DEC DE
• 0x23 - INC HL
• 0x29 - ADD HL, HL
• 0x2B - DEC HL
• 0x33 - INC SP
• 0x39 - ADD HL, SP
• 0x3B - DEC SP
• 0xE8 - ADD SP, s8

Rotate, shift, and bit operations

• 0x07 - RLCA
• 0x0F - RRCA
• 0x17 - RLA
• 0x1F - RRA
• 0xCB00 - RLC B
• 0xCB01 - RLC C
• 0xCB02 - RLC D
• 0xCB03 - RLC E
• 0xCB04 - RLC H
• 0xCB05 - RLC L
• 0xCB06 - RLC (HL)
• 0xCB07 - RLC A
• 0xCB08 - RRC B
• 0xCB09 - RRC C
• 0xCB0A - RRC D
• 0xCB0B - RRC E
• 0xCB0C - RRC H
• 0xCB0D - RRC L
• 0xCB0E - RRC (HL)
• 0xCB0F - RRC A
• 0xCB10 - RL B
• 0xCB11 - RL C
• 0xCB12 - RL D
• 0xCB13 - RL E
• 0xCB14 - RL H
• 0xCB15 - RL L
• 0xCB16 - RL (HL)
• 0xCB17 - RL A
• 0xCB18 - RR B
• 0xCB19 - RR C
• 0xCB1A - RR D
• 0xCB1B - RR E
• 0xCB1C - RR H
• 0xCB1D - RR L
• 0xCB1E - RR (HL)
• 0xCB1F - RR A
• 0xCB20 - SLA B
• 0xCB21 - SLA C
• 0xCB22 - SLA D
• 0xCB23 - SLA E
• 0xCB24 - SLA H
• 0xCB25 - SLA L
• 0xCB26 - SLA (HL)
• 0xCB27 - SLA A
• 0xCB28 - SRA B
• 0xCB29 - SRA C
• 0xCB2A - SRA D
• 0xCB2B - SRA E
• 0xCB2C - SRA H
• 0xCB2D - SRA L
• 0xCB2E - SRA (HL)
• 0xCB2F - SRA A
• 0xCB30 - SWAP B
• 0xCB31 - SWAP C
• 0xCB32 - SWAP D
• 0xCB33 - SWAP E
• 0xCB34 - SWAP H
• 0xCB35 - SWAP L
• 0xCB36 - SWAP (HL)
• 0xCB37 - SWAP A
• 0xCB38 - SRL B
• 0xCB39 - SRL C
• 0xCB3A - SRL D
• 0xCB3B - SRL E
• 0xCB3C - SRL H
• 0xCB3D - SRL L
• 0xCB3E - SRL (HL)
• 0xCB3F - SRL A
• 0xCB40 - BIT 0, B
• 0xCB41 - BIT 0, C
• 0xCB42 - BIT 0, D
• 0xCB43 - BIT 0, E
• 0xCB44 - BIT 0, H
• 0xCB45 - BIT 0, L
• 0xCB46 - BIT 0, (HL)
• 0xCB47 - BIT 0, A
• 0xCB48 - BIT 1, B
• 0xCB49 - BIT 1, C
• 0xCB4A - BIT 1, D
• 0xCB4B - BIT 1, E
• 0xCB4C - BIT 1, H
• 0xCB4D - BIT 1, L
• 0xCB4E - BIT 1, (HL)
• 0xCB4F - BIT 1, A
• 0xCB50 - BIT 2, B
• 0xCB51 - BIT 2, C
• 0xCB52 - BIT 2, D
• 0xCB53 - BIT 2, E
• 0xCB54 - BIT 2, H
• 0xCB55 - BIT 2, L
• 0xCB56 - BIT 2, (HL)
• 0xCB57 - BIT 2, A
• 0xCB58 - BIT 3, B
• 0xCB59 - BIT 3, C
• 0xCB5A - BIT 3, D
• 0xCB5B - BIT 3, E
• 0xCB5C - BIT 3, H
• 0xCB5D - BIT 3, L
• 0xCB5E - BIT 3, (HL)
• 0xCB5F - BIT 3, A
• 0xCB60 - BIT 4, B
• 0xCB61 - BIT 4, C
• 0xCB62 - BIT 4, D
• 0xCB63 - BIT 4, E
• 0xCB64 - BIT 4, H
• 0xCB65 - BIT 4, L
• 0xCB66 - BIT 4, (HL)
• 0xCB67 - BIT 4, A
• 0xCB68 - BIT 5, B
• 0xCB69 - BIT 5, C
• 0xCB6A - BIT 5, D
• 0xCB6B - BIT 5, E
• 0xCB6C - BIT 5, H
• 0xCB6D - BIT 5, L
• 0xCB6E - BIT 5, (HL)
• 0xCB6F - BIT 5, A
• 0xCB70 - BIT 6, B
• 0xCB71 - BIT 6, C
• 0xCB72 - BIT 6, D
• 0xCB73 - BIT 6, E
• 0xCB74 - BIT 6, H
• 0xCB75 - BIT 6, L
• 0xCB76 - BIT 6, (HL)
• 0xCB77 - BIT 6, A
• 0xCB78 - BIT 7, B
• 0xCB79 - BIT 7, C
• 0xCB7A - BIT 7, D
• 0xCB7B - BIT 7, E
• 0xCB7C - BIT 7, H
• 0xCB7D - BIT 7, L
• 0xCB7E - BIT 7, (HL)
• 0xCB7F - BIT 7, A
• 0xCB80 - RES 0, B
• 0xCB81 - RES 0, C
• 0xCB82 - RES 0, D
• 0xCB83 - RES 0, E
• 0xCB84 - RES 0, H
• 0xCB85 - RES 0, L
• 0xCB86 - RES 0, (HL)
• 0xCB87 - RES 0, A
• 0xCB88 - RES 1, B
• 0xCB89 - RES 1, C
• 0xCB8A - RES 1, D
• 0xCB8B - RES 1, E
• 0xCB8C - RES 1, H
• 0xCB8D - RES 1, L
• 0xCB8E - RES 1, (HL)
• 0xCB8F - RES 1, A
• 0xCB90 - RES 2, B
• 0xCB91 - RES 2, C
• 0xCB92 - RES 2, D
• 0xCB93 - RES 2, E
• 0xCB94 - RES 2, H
• 0xCB95 - RES 2, L
• 0xCB96 - RES 2, (HL)
• 0xCB97 - RES 2, A
• 0xCB98 - RES 3, B
• 0xCB99 - RES 3, C
• 0xCB9A - RES 3, D
• 0xCB9B - RES 3, E
• 0xCB9C - RES 3, H
• 0xCB9D - RES 3, L
• 0xCB9E - RES 3, (HL)
• 0xCB9F - RES 3, A
• 0xCBA0 - RES 4, B
• 0xCBA1 - RES 4, C
• 0xCBA2 - RES 4, D
• 0xCBA3 - RES 4, E
• 0xCBA4 - RES 4, H
• 0xCBA5 - RES 4, L
• 0xCBA6 - RES 4, (HL)
• 0xCBA7 - RES 4, A
• 0xCBA8 - RES 5, B
• 0xCBA9 - RES 5, C
• 0xCBAA - RES 5, D
• 0xCBAB - RES 5, E
• 0xCBAC - RES 5, H
• 0xCBAD - RES 5, L
• 0xCBAE - RES 5, (HL)
• 0xCBAF - RES 5, A
• 0xCBB0 - RES 6, B
• 0xCBB1 - RES 6, C
• 0xCBB2 - RES 6, D
• 0xCBB3 - RES 6, E
• 0xCBB4 - RES 6, H
• 0xCBB5 - RES 6, L
• 0xCBB6 - RES 6, (HL)
• 0xCBB7 - RES 6, A
• 0xCBB8 - RES 7, B
• 0xCBB9 - RES 7, C
• 0xCBBA - RES 7, D
• 0xCBBB - RES 7, E
• 0xCBBC - RES 7, H
• 0xCBBD - RES 7, L
• 0xCBBE - RES 7, (HL)
• 0xCBBF - RES 7, A
• 0xCBC0 - SET 0, B
• 0xCBC1 - SET 0, C
• 0xCBC2 - SET 0, D
• 0xCBC3 - SET 0, E
• 0xCBC4 - SET 0, H
• 0xCBC5 - SET 0, L
• 0xCBC6 - SET 0, (HL)
• 0xCBC7 - SET 0, A
• 0xCBC8 - SET 1, B
• 0xCBC9 - SET 1, C
• 0xCBCA - SET 1, D
• 0xCBCB - SET 1, E
• 0xCBCC - SET 1, H
• 0xCBCD - SET 1, L
• 0xCBCE - SET 1, (HL)
• 0xCBCF - SET 1, A
• 0xCBD0 - SET 2, B
• 0xCBD1 - SET 2, C
• 0xCBD2 - SET 2, D
• 0xCBD3 - SET 2, E
• 0xCBD4 - SET 2, H
• 0xCBD5 - SET 2, L
• 0xCBD6 - SET 2, (HL)
• 0xCBD7 - SET 2, A
• 0xCBD8 - SET 3, B
• 0xCBD9 - SET 3, C
• 0xCBDA - SET 3, D
• 0xCBDB - SET 3, E
• 0xCBDC - SET 3, H
• 0xCBDD - SET 3, L
• 0xCBDE - SET 3, (HL)
• 0xCBDF - SET 3, A
• 0xCBE0 - SET 4, B
• 0xCBE1 - SET 4, C
• 0xCBE2 - SET 4, D
• 0xCBE3 - SET 4, E
• 0xCBE4 - SET 4, H
• 0xCBE5 - SET 4, L
• 0xCBE6 - SET 4, (HL)
• 0xCBE7 - SET 4, A
• 0xCBE8 - SET 5, B
• 0xCBE9 - SET 5, C
• 0xCBEA - SET 5, D
• 0xCBEB - SET 5, E
• 0xCBEC - SET 5, H
• 0xCBED - SET 5, L
• 0xCBEE - SET 5, (HL)
• 0xCBEF - SET 5, A
• 0xCBF0 - SET 6, B
• 0xCBF1 - SET 6, C
• 0xCBF2 - SET 6, D
• 0xCBF3 - SET 6, E
• 0xCBF4 - SET 6, H
• 0xCBF5 - SET 6, L
• 0xCBF6 - SET 6, (HL)
• 0xCBF7 - SET 6, A
• 0xCBF8 - SET 7, B
• 0xCBF9 - SET 7, C
• 0xCBFA - SET 7, D
• 0xCBFB - SET 7, E
• 0xCBFC - SET 7, H
• 0xCBFD - SET 7, L
• 0xCBFE - SET 7, (HL)
• 0xCBFF - SET 7, A

Timeline

Day 20 - Completed All 8-bit and 16-bit load instructions with tests (to the best of my knowledge)

Day 31 - Completed All control flow instructions

Day 35 - Completed All 8-bit Arithmetic instructions

Day 39 - Completed All 16-bit Arithmetic instructions

Day 44 - Completed All rotate, shift, and bit operations

Day 68 - Read Cartridge Header