14 ms·

GameBoy CPU Manual (2013) [pdf]

261 points by pplonski86 8y ago

Waterluvian 8y ago
If you're a web developer or someone working pretty high level and have this desire to explore the depths, here's a project idea for you. First write a CHIP8 emulator in your most comfortable language, then write a Gameboy emulator in something like Rust or C++.
- vSanjo 8y ago
  I would love to, but have - genuinely - no idea where to begin beyond tearing down someone else's work on Github. Can you recommend any starting paths for someone like you mentioned?
  - Scaevolus 8y ago
    CHIP8 is a game-oriented bytecode from the 1970s, with just a few instructions: http://mattmik.com/files/chip8/mastering/chip8.html http://mattmik.com/files/chip8/mastering/chip8.html There's a good IDE for it with a bunch more resources: https://github.com/JohnEarnest/Octo https://github.com/JohnEarnest/Octo
  - zeta0134 8y ago
    For the CHIP-8 emulator in particular, this is a good starting point: http://www.multigesture.net/articles/how-to-write-an-emulator-chip-8-interpreter/ http://www.multigesture.net/articles/how-to-write-an-emulato... Or you could just read the documentation directly here: http://devernay.free.fr/hacks/chip8/C8TECH10.HTM http://devernay.free.fr/hacks/chip8/C8TECH10.HTM CHIP8 was itself an interpreted bit of hardware, so it's reeeeally loose with things like timing requirements. Just run a couple dozen instructions per "frame" in your game loop, then draw the screen somewhere, and you'll come close to playability for most of the sample games if your interpreter is bug free. It's the kind of project that with enough motivation you could complete in a week or so, which is why it's usually recommended for a first emulator project. Once you have CHIP8 working somewhat, think about how you had to structure your code to make that work. Wouldn't the z80 CPU in a gameboy, or the 6502 CPU in an NES, also have opcodes just like the CHIP8 interpreter did? Surely you wrote a function for each CHIP8 opcode, so why not write a function for each z80 opcode, figure out how to read the gameboy's cartridge header, and see if your new CPU can run some instructions from Tetris? Once you get the code writing to VRAM, can you draw the tiles? What about the background? Build the emulator up piece by piece, and suddenly your game library is just chok full of little puzzle boxes, waiting to be tackled one by one. It's very difficult to do all of this accurately, but don't focus on that right away. Just get it working, and learn about the system as you go.
    - djmips 8y ago
      It's really pervasive that the CPU in the Gameboy is a Z80. It's not. It's got a few instructions from the Z80 but it's closer to the 8080 overall.
  - ehaskins 8y ago
    I've been working on a GB emulator for awhile. Step one is to understand the architecture of the system. What are the different hardware components? How do they interact? A simple emulator boils down to: While(true) Emulate_one_cpu_cycle() For each cycle you have to produce any side effects from the various peripherals (serial comms, update the display, generate audio, etc.), process any external changes (button presses, serial data), and emulate the next CPU instruction (basically a big switch). I recommend "The Ultimate Gameboy Talk (33c3)" [0], for an overview of the Gameboy and it's internal peripherals. There are various test ROMs available that you can use to verify the basic functionality. [1][2] 0. https://m.youtube.com/watch?v=HyzD8pNlpwI https://m.youtube.com/watch?v=HyzD8pNlpwI 1. http://gbdev.gg8.se/wiki/articles/Test_ROMs http://gbdev.gg8.se/wiki/articles/Test_ROMs 2. https://github.com/Gekkio/mooneye-gb https://github.com/Gekkio/mooneye-gb
mastrsushi 8y ago
I was gonna say this depth of exposure would have a major impact in performance for all the GB emulators our there. Then I realized they probably don't need any more performance impact because they're GB emulators.
- simias 8y ago
  This doc isn't new, but beyond that getting more details about the original hardware tends to make emulators slower, not faster, since they end up having to emulate more subtle details and quirks of the original. Making an emulator run fast generally involves finding an efficient software architecture to emulate a piece of hardware (a non-trivial task since hardware is massively parallel and synchronous) and if you still can't get it to run fast enough you start cutting corners on accuracy until you do.
- bredren 8y ago
  Is this document brand new?
  - Eiriksmal 8y ago
    It's been circulating in various forms since the late 90s, IIRC. Commonly referred to as the "Pan Docs." http://gbdev.gg8.se/wiki/articles/Pan_Docs http://gbdev.gg8.se/wiki/articles/Pan_Docs
Eiriksmal 8y ago
Every time someone resurfaces the Pan Docs in a new form, I'm reminded of how I haven't touched my Gameboy dev efforts[0] in months. As fun as it is to conquer the Z80, it's difficult to get motivated working in an ecosystem that is still almost utterly without development tools. Kirby's Dreamland was programmed with a track ball running on a hacked up Famicom. [1] We haven't come too far since then. [0] https://github.com/Eiriksmal/gameboy https://github.com/Eiriksmal/gameboy [1] https://arstechnica.com/gaming/2017/04/the-first-kirby-game-was-programmed-without-a-keyboard/ https://arstechnica.com/gaming/2017/04/the-first-kirby-game-...
- BonsaiDen 8y ago
  I actually wrote a Asteroids "Clone" that uses Vector Graphics last year :) [0] But I agree, tooling is complicated. I'm currently adding the finishing touches to the rewrite of my own Assembler / Compiler pipeline [1] and started work on a more "traditional" Metroid-like shooter, the sprite and map editor are both custom programs written in rust using imgui bindings and take care of the grunt work for generating all the data structures used in the game currently the dev efforts are 50/50 tooling/game though :D [0] https://gitlab.com/BonsaiDen/vectroid.gb https://gitlab.com/BonsaiDen/vectroid.gb [1] https://gitlab.com/BonsaiDen/gbasm-rs https://gitlab.com/BonsaiDen/gbasm-rs
- zeta0134 8y ago
  There a few good homebrew tools and libraries available. We did a gameboy game for a Ludum dare a short while back, and while it's certainly not pretty z80, the tooling got the job done. (Be gentle, it was my first time trying to do anything serious directly in assembly and we had a 72-hour time limit.) https://github.com/zeta0134/ludum-dare-42 https://github.com/zeta0134/ludum-dare-42 We used the RGBDS assembler and its built in tools to make the thing, mostly because that runs on Linux and that's what we both wanted to develop on. My partner did the graphics and I got a decent flow going from LibreSprite using RGBGFX for the conversions. https://github.com/rednex/rgbds https://github.com/rednex/rgbds I'll admit that I did have a major advantage going in, having written a mostly functional gameboy emulator already, but emulating a system is very, very different from programming against its constraints. There are decent software libraries floating around, but since there's no real standard way to leverage the hardware once you get past the basics (even commercial games had wildly varying strategies from company to company) the best tool in the belt is probably your documentation. Pan docs and the various wikis were instrumental in understanding how to leverage the hardware to do what we wanted.
aappleby 8y ago
Beware, contains errors. (been writing a gameboy simulator for a few months now...)
- softblush 8y ago
  Maybe consider pointing out those errors
kbumsik 8y ago
Is it a fan-made document or extracted from the vendor (Nintendo)? If it's the former, it is surprising to see how they ended up with writing a chip reference manual-grade document.
- userbinator 8y ago
  Definitely fan-made. The formatting feels off, probably because it was originally a text file that was converted into a PDF. Thus you see section headings with proportional font, but body text in monospace with ASCII art diagrams and tables.
_srbu 8y ago
I have recently finished a GameBoy DMG/CGB emulator with friends from school https://github.com/nbouchin/gbmu https://github.com/nbouchin/gbmu It was a lot of fun!
- Yajirobe 8y ago
  How do you use it
jchw 8y ago
I really like the Gameboy hardware; it's limited, but the design feels very elegant in it's simplicity. I've written a couple of toy Gameboy emulators at this point. It's a bit challenging to get anything working, and honestly I have no idea how to approach audio at all. Nevertheless, it's still quite fun. The LCD timings are a point of curiosity for me. It seems there's still a slight bit of mystery around it, still today. I was inspired to play with emulating Gameboy specifically after an excellent 33c3 talk, The Ultimate Game Boy Talk, which I highly recommend. https://youtu.be/HyzD8pNlpwI https://youtu.be/HyzD8pNlpwI (Some day I would like to approach emulation for more platforms, both newer and older, but I feel I still have so much time learn about designing emulators that I haven't bothered with that yet. It's so open ended, and handling things like cycle counting has a lot of different approaches of varying desirability.)
- anyfoo 8y ago
  You might really enjoy this talk as well, then: https://youtu.be/GBYwjch6oEE https://youtu.be/GBYwjch6oEE
  - jchw 8y ago
    Oh thank you, I've never seen this talk nor heard of this conference but on it's face it sounds like it's right up my alley.
deleted 8y ago
[deleted]
cryptokernel 8y ago
finally! Earn crypto here: https://coincircle.com/l/50VVxbObg3 https://coincircle.com/l/50VVxbObg3
simias 8y ago
If you're interested in making a GB emulator here are a few resources that helped me when I did just that a few years ago: - An intro to making a GB emulator in JS (it doesn't matter if you don't plan on using JS, it still explains the basic concepts pretty well): http://imrannazar.com/GameBoy-Emulation-in-JavaScript:-The-CPU http://imrannazar.com/GameBoy-Emulation-in-JavaScript:-The-C... - Opcode map (note that the GB CPU is not a stock Z80, it has different timings, different registers, different flags and different opcodes, do not use stock Z80 docs as a reference lest you end up with broken CPU emulation): http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html - The GameBoy programming manual: http://www.romhacking.net/documents/544/ http://www.romhacking.net/documents/544/ - Accuracy test ROMs, very useful to make sure your timings are ok and you emulate various quirks of the hardware: http://tasvideos.org/EmulatorResources/GBAccuracyTests.html http://tasvideos.org/EmulatorResources/GBAccuracyTests.html Also note that even if you focus on making an original (DMG) GameBoy emulator you should be able to add GameBoy Color support later without too much difficulty, it's a fairly straightforward evolution of the original hardware.
- b_tterc_p 8y ago
  Dumb question: is there a reason to make a gameboy emulator besides interest? Is it not a completely solved problem space, with all games playable with optimal performance?
  - Sodaware 8y ago
    It's fun, if you're into that kind of thing. It's more like building a car in the garage. There's no real need to do, but some people enjoy the process of figuring out how everything fits together.
  - bitexploder 8y ago
    The microcorruption challenge is one of the best ways to learn about exploitation because it uses a simple CPU and easy to understand memory model. Implementing a z80-alike is like hello world if you are interested in learning lower level programming. Both of these examples share this: the obscuring parts of modern architecture are gone. And, personally, it is very rewarding to write your own emulator. It really sharpens skills for systems stuff.
ArtWomb 8y ago
GB never dies ;) And Nintendo hardware remains a great way to explore computation internals: CPSC 305: Computer Systems and Architecture http://ianfinlayson.net/class/cpsc305/ http://ianfinlayson.net/class/cpsc305/ Using The Game Boy Advance To Teach Computer Systems And Architecture https://www.researchgate.net/publication/323199083_Using_The_Game_Boy_Advance_To_Teach_Computer_Systems_And_Architecture https://www.researchgate.net/publication/323199083_Using_The...
- cmpgamer 8y ago
  This was my professor! It was honestly a cool class. Half of it was learning CPU design from the bottom up, and the other half was programming for the GBA.
n-gauge 8y ago
One thing I would like to see in a gameboy emulator is the option to record / input from file keypresses so that you can test speedruns or find exploits. I was thinking this would be trivial for something like a js emulator where you usually have a key array defined for storing keypresses. If anyone knows of a GB emulator that already allows this please link to my comment.
deleted 8y ago
[deleted]

261 points by pplonski86 8y ago

If you're a web developer or someone working pretty high level and have this desire to explore the depths, here's a project idea for you. First write a CHIP8 emulator in your most comfortable language, then write a Gameboy emulator in something like Rust or C++.

vSanjo 8y ago
I would love to, but have - genuinely - no idea where to begin beyond tearing down someone else's work on Github. Can you recommend any starting paths for someone like you mentioned?
- Scaevolus 8y ago
  CHIP8 is a game-oriented bytecode from the 1970s, with just a few instructions: http://mattmik.com/files/chip8/mastering/chip8.html http://mattmik.com/files/chip8/mastering/chip8.html There's a good IDE for it with a bunch more resources: https://github.com/JohnEarnest/Octo https://github.com/JohnEarnest/Octo
- zeta0134 8y ago
  For the CHIP-8 emulator in particular, this is a good starting point: http://www.multigesture.net/articles/how-to-write-an-emulator-chip-8-interpreter/ http://www.multigesture.net/articles/how-to-write-an-emulato... Or you could just read the documentation directly here: http://devernay.free.fr/hacks/chip8/C8TECH10.HTM http://devernay.free.fr/hacks/chip8/C8TECH10.HTM CHIP8 was itself an interpreted bit of hardware, so it's reeeeally loose with things like timing requirements. Just run a couple dozen instructions per "frame" in your game loop, then draw the screen somewhere, and you'll come close to playability for most of the sample games if your interpreter is bug free. It's the kind of project that with enough motivation you could complete in a week or so, which is why it's usually recommended for a first emulator project. Once you have CHIP8 working somewhat, think about how you had to structure your code to make that work. Wouldn't the z80 CPU in a gameboy, or the 6502 CPU in an NES, also have opcodes just like the CHIP8 interpreter did? Surely you wrote a function for each CHIP8 opcode, so why not write a function for each z80 opcode, figure out how to read the gameboy's cartridge header, and see if your new CPU can run some instructions from Tetris? Once you get the code writing to VRAM, can you draw the tiles? What about the background? Build the emulator up piece by piece, and suddenly your game library is just chok full of little puzzle boxes, waiting to be tackled one by one. It's very difficult to do all of this accurately, but don't focus on that right away. Just get it working, and learn about the system as you go.
  - djmips 8y ago
    It's really pervasive that the CPU in the Gameboy is a Z80. It's not. It's got a few instructions from the Z80 but it's closer to the 8080 overall.
- ehaskins 8y ago
  I've been working on a GB emulator for awhile. Step one is to understand the architecture of the system. What are the different hardware components? How do they interact? A simple emulator boils down to: While(true) Emulate_one_cpu_cycle() For each cycle you have to produce any side effects from the various peripherals (serial comms, update the display, generate audio, etc.), process any external changes (button presses, serial data), and emulate the next CPU instruction (basically a big switch). I recommend "The Ultimate Gameboy Talk (33c3)" [0], for an overview of the Gameboy and it's internal peripherals. There are various test ROMs available that you can use to verify the basic functionality. [1][2] 0. https://m.youtube.com/watch?v=HyzD8pNlpwI https://m.youtube.com/watch?v=HyzD8pNlpwI 1. http://gbdev.gg8.se/wiki/articles/Test_ROMs http://gbdev.gg8.se/wiki/articles/Test_ROMs 2. https://github.com/Gekkio/mooneye-gb https://github.com/Gekkio/mooneye-gb

mastrsushi 8y ago

I was gonna say this depth of exposure would have a major impact in performance for all the GB emulators our there. Then I realized they probably don't need any more performance impact because they're GB emulators.

simias 8y ago
This doc isn't new, but beyond that getting more details about the original hardware tends to make emulators slower, not faster, since they end up having to emulate more subtle details and quirks of the original. Making an emulator run fast generally involves finding an efficient software architecture to emulate a piece of hardware (a non-trivial task since hardware is massively parallel and synchronous) and if you still can't get it to run fast enough you start cutting corners on accuracy until you do.
bredren 8y ago
Is this document brand new?
- Eiriksmal 8y ago
  It's been circulating in various forms since the late 90s, IIRC. Commonly referred to as the "Pan Docs." http://gbdev.gg8.se/wiki/articles/Pan_Docs http://gbdev.gg8.se/wiki/articles/Pan_Docs

Eiriksmal 8y ago

Every time someone resurfaces the Pan Docs in a new form, I'm reminded of how I haven't touched my Gameboy dev efforts[0] in months. As fun as it is to conquer the Z80, it's difficult to get motivated working in an ecosystem that is still almost utterly without development tools. Kirby's Dreamland was programmed with a track ball running on a hacked up Famicom. [1] We haven't come too far since then. [0] https://github.com/Eiriksmal/gameboy https://github.com/Eiriksmal/gameboy [1] https://arstechnica.com/gaming/2017/04/the-first-kirby-game-was-programmed-without-a-keyboard/ https://arstechnica.com/gaming/2017/04/the-first-kirby-game-...

BonsaiDen 8y ago
I actually wrote a Asteroids "Clone" that uses Vector Graphics last year :) [0] But I agree, tooling is complicated. I'm currently adding the finishing touches to the rewrite of my own Assembler / Compiler pipeline [1] and started work on a more "traditional" Metroid-like shooter, the sprite and map editor are both custom programs written in rust using imgui bindings and take care of the grunt work for generating all the data structures used in the game currently the dev efforts are 50/50 tooling/game though :D [0] https://gitlab.com/BonsaiDen/vectroid.gb https://gitlab.com/BonsaiDen/vectroid.gb [1] https://gitlab.com/BonsaiDen/gbasm-rs https://gitlab.com/BonsaiDen/gbasm-rs
zeta0134 8y ago
There a few good homebrew tools and libraries available. We did a gameboy game for a Ludum dare a short while back, and while it's certainly not pretty z80, the tooling got the job done. (Be gentle, it was my first time trying to do anything serious directly in assembly and we had a 72-hour time limit.) https://github.com/zeta0134/ludum-dare-42 https://github.com/zeta0134/ludum-dare-42 We used the RGBDS assembler and its built in tools to make the thing, mostly because that runs on Linux and that's what we both wanted to develop on. My partner did the graphics and I got a decent flow going from LibreSprite using RGBGFX for the conversions. https://github.com/rednex/rgbds https://github.com/rednex/rgbds I'll admit that I did have a major advantage going in, having written a mostly functional gameboy emulator already, but emulating a system is very, very different from programming against its constraints. There are decent software libraries floating around, but since there's no real standard way to leverage the hardware once you get past the basics (even commercial games had wildly varying strategies from company to company) the best tool in the belt is probably your documentation. Pan docs and the various wikis were instrumental in understanding how to leverage the hardware to do what we wanted.

aappleby 8y ago

Beware, contains errors. (been writing a gameboy simulator for a few months now...)

softblush 8y ago
Maybe consider pointing out those errors

kbumsik 8y ago

Is it a fan-made document or extracted from the vendor (Nintendo)? If it's the former, it is surprising to see how they ended up with writing a chip reference manual-grade document.

userbinator 8y ago
Definitely fan-made. The formatting feels off, probably because it was originally a text file that was converted into a PDF. Thus you see section headings with proportional font, but body text in monospace with ASCII art diagrams and tables.

_srbu 8y ago

I have recently finished a GameBoy DMG/CGB emulator with friends from school https://github.com/nbouchin/gbmu https://github.com/nbouchin/gbmu It was a lot of fun!

Yajirobe 8y ago
How do you use it

jchw 8y ago

I really like the Gameboy hardware; it's limited, but the design feels very elegant in it's simplicity. I've written a couple of toy Gameboy emulators at this point. It's a bit challenging to get anything working, and honestly I have no idea how to approach audio at all. Nevertheless, it's still quite fun. The LCD timings are a point of curiosity for me. It seems there's still a slight bit of mystery around it, still today. I was inspired to play with emulating Gameboy specifically after an excellent 33c3 talk, The Ultimate Game Boy Talk, which I highly recommend. https://youtu.be/HyzD8pNlpwI https://youtu.be/HyzD8pNlpwI (Some day I would like to approach emulation for more platforms, both newer and older, but I feel I still have so much time learn about designing emulators that I haven't bothered with that yet. It's so open ended, and handling things like cycle counting has a lot of different approaches of varying desirability.)

anyfoo 8y ago
You might really enjoy this talk as well, then: https://youtu.be/GBYwjch6oEE https://youtu.be/GBYwjch6oEE
- jchw 8y ago
  Oh thank you, I've never seen this talk nor heard of this conference but on it's face it sounds like it's right up my alley.

deleted 8y ago

[deleted]

cryptokernel 8y ago

finally! Earn crypto here: https://coincircle.com/l/50VVxbObg3 https://coincircle.com/l/50VVxbObg3

simias 8y ago

If you're interested in making a GB emulator here are a few resources that helped me when I did just that a few years ago: - An intro to making a GB emulator in JS (it doesn't matter if you don't plan on using JS, it still explains the basic concepts pretty well): http://imrannazar.com/GameBoy-Emulation-in-JavaScript:-The-CPU http://imrannazar.com/GameBoy-Emulation-in-JavaScript:-The-C... - Opcode map (note that the GB CPU is not a stock Z80, it has different timings, different registers, different flags and different opcodes, do not use stock Z80 docs as a reference lest you end up with broken CPU emulation): http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html - The GameBoy programming manual: http://www.romhacking.net/documents/544/ http://www.romhacking.net/documents/544/ - Accuracy test ROMs, very useful to make sure your timings are ok and you emulate various quirks of the hardware: http://tasvideos.org/EmulatorResources/GBAccuracyTests.html http://tasvideos.org/EmulatorResources/GBAccuracyTests.html Also note that even if you focus on making an original (DMG) GameBoy emulator you should be able to add GameBoy Color support later without too much difficulty, it's a fairly straightforward evolution of the original hardware.

b_tterc_p 8y ago
Dumb question: is there a reason to make a gameboy emulator besides interest? Is it not a completely solved problem space, with all games playable with optimal performance?
- Sodaware 8y ago
  It's fun, if you're into that kind of thing. It's more like building a car in the garage. There's no real need to do, but some people enjoy the process of figuring out how everything fits together.
- bitexploder 8y ago
  The microcorruption challenge is one of the best ways to learn about exploitation because it uses a simple CPU and easy to understand memory model. Implementing a z80-alike is like hello world if you are interested in learning lower level programming. Both of these examples share this: the obscuring parts of modern architecture are gone. And, personally, it is very rewarding to write your own emulator. It really sharpens skills for systems stuff.

ArtWomb 8y ago

GB never dies ;) And Nintendo hardware remains a great way to explore computation internals: CPSC 305: Computer Systems and Architecture http://ianfinlayson.net/class/cpsc305/ http://ianfinlayson.net/class/cpsc305/ Using The Game Boy Advance To Teach Computer Systems And Architecture https://www.researchgate.net/publication/323199083_Using_The_Game_Boy_Advance_To_Teach_Computer_Systems_And_Architecture https://www.researchgate.net/publication/323199083_Using_The...

cmpgamer 8y ago
This was my professor! It was honestly a cool class. Half of it was learning CPU design from the bottom up, and the other half was programming for the GBA.

n-gauge 8y ago

One thing I would like to see in a gameboy emulator is the option to record / input from file keypresses so that you can test speedruns or find exploits. I was thinking this would be trivial for something like a js emulator where you usually have a key array defined for storing keypresses. If anyone knows of a GB emulator that already allows this please link to my comment.

deleted 8y ago

[deleted]