Getting Started

RealBoy is a technical and documentational effort to help people get started with the beautiful art of computer emulation. It’s not written (neither documentation nor code) by an expert or authority in the field; RealBoy is the result of spare time and an authentic passion for programming and computers in general. The documentation is organized as a series of posts, intended to be read in chronological order, (although the reader should feel free to explore as he wishes). For example, the first three posts are:

1. The Nintendo Game Boy, Part 1: The Intel 8080 and the Zilog Z80

2. The Nintendo Game Boy, Part 2: The Game Boy’s CPU

3. The Nintendo Game Boy, Part 3: The Rest of the Hardware

These are intended to give a complete overview of the Game Boy’s hardware architecture; if you are already familiar with this, you can obviously skip any or all of these posts. In general, in every post we assume that you have read all previous posts, so really if you are unsure just follow the chronological order.

RealBoy is not intended for absolute beginners; it has a set of prerequisites and assumptions that, although potentially reducing the quantity of the audience, hopefully will enable to aim for quality of writings. Indeed, because we will work with a real emulator, with a real implementation and not just with abstract problems, it would be hard to write for the absolute beginner; writing an emulator already implies a set of preconditions in form of knowledge and experience.

With this in mind, this page is intended as a quick review of this set of prerequisites, just enough to get started with our learning process.


The most important assumption we make is a basic knowledge of computer architecture. Familiarity with key terminology such as Program Counter, Endianness, Stack Pointer, Register, Jump/Branch, Instruction Set, Memory Pointer, Most/Least Significant Bit/Byte, Operation Code, Fetch-And-Execute Cycle, Instruction Cycle, Machine Cycle, Clock Cycle, Address/Data Bus, Address Space, Load/StoreMemory Addressing, Accumulator, Carry Flag, Zero Flag, Byte/Word, among other jargon is, therefore, assumed.

Ability to work with hexadecimal and binary notations is very important; this is, in fact, essential for studying the programs throughout our ‘course’.

It would be ideal to have a strong knowledge of The C Programming Language and the nature of the Assembly Language. We say ‘the nature of…’ because there are tons of Assembly languages; if you really understand the basics of computer architecture, learning an Assembly Language for a particular machine would actually be the easy part of whatever you are doing. This effectively translates to: Computer architecture knowledge implies Assembly Language knowledge. Computer Architecture knowledge will also allow you a deeper knowledge of The C Programming Language.


RealBoy is written in a mixture of The C Programming Language and x86-64 Assembly Language. Actually, the part written in Assembly Language (which is really the core of the emulator) has been recently rewritten in C, so RealBoy would work on 32-bit x86 machines, and could be easily ported to other architectures. However, we are convinced that exposing the Assembly Language version to the reader gives us a unique opportunity in this learning experience. First of all, emulation is all about the machine; if you are interested in emulation, chances are you want to understand how computers actually work. Implementing RealBoy in a mixture of C and Assembly Language will enable us to get a better understanding of what is really going on.

For this reason, familiarity with the x86-64 architecture is highly desirable. (It is, nevertheless, absolutely feasible to learn all this on the way; we will try to be careful to highlight and explain the really key aspects of whatever we are looking at).

Let’s take a look at the following example of a fragment of RealBoy’s code written in x86-64 Assembly Language:

FILE: gboy_cpu.S

 movq $addr_sp, %r13 # set PC to 0x0000
 addq %rdi, %r13 # 0x0000 or 0x0100
 movq $z80_ldex, %r15 # %r15 holds pointer to opcode records
 movq (%r13), %r12 # %r12 holds the instruction's opcode
 call exec_next # GO GO GO!

For every piece of code we study, we will give information about the file’s name and the line number where the code we are studying begins.

Let’s quickly review this small example: rom_exec is a label, a name that represents a value in memory. A label can be used to represent variables or functions; it is then possible to access these variables or to call these functions using the label.  In this case rom_exec is a function that gets called right before executing the first emulated instruction.  Note that the syntax of the code follows Unix’s rather than Intel’s.  This is, the instruction’s operands are ordered starting from the source operand. For example, movq $addr_sp, %r13 means copy $addr_sp to %r13, not copy %r13 to $addr_sp.

On the other hand, we will also show portions of the code being debugged in the GNU Debugger (gdb). For example:


right before RealBoy begins emulation

This will enable us to study in detail the way RealBoy solves problems in the ‘real world’, that is, we will show the outputs of RealBoy while it is being executed. Hopefully this will give us a better understanding of the issues that arise when implementing an emulation system, and various important decisions in order to overcome them.

Let’s overview our working environment for programming.

FreeBSD, Linux, GNU…

Since Ken Thompson and Dennis Ritchie came up with the Unix Operating System back at the end of the 60’s, there have been lots of Unix-like operating systems and programming environments. It’s a matter of personal taste, actually, and much of the development of RealBoy was done under the FreeBSD operating system, a Unix-like descendant of Berkeley Unix, the same that created the internet sockets and that implemented the first TCP/IP network protocol stack, used by DARPA in ARPANET. However, access to a Linux box is more common, and both being Unix-like, there are no practical differences between both and what we’ll do.

Systems software like GNU C compiler (GCC), GNU Assembler (GAS), GNU Linker (ld) and GNU Debugger (gdb) were naturally indispensable for this work, so much credit goes to GNU. One essential tool for the development of RealBoy was Vim. It is a classical text editor with lots of unique features that make programming even more pleasent.


We hope that this page makes it clear what to expect from the project. You can start the documentation with our first post: The Nintendo Game Boy, Part 1: The Intel 8080 and the Zilog Z80. You can find all the posts over here.

Remember: hard work is the only truly indispensable aptitude for success.

Happy Hacking!


4 thoughts on “Getting Started

    • Ideally it would be desirable to “feel comfortable” talking about endianness, instruction set, CPU registers, status flags, and the like; the issues that are explicitly exposed to the programmer.

      I’d recommend “Structured Computer Organization” from Andrew Tanenbaum, specifically the following chapters:

      Chapters 1 and 2 (Introduction and Computer Systems Organization): This should give you a fresh start.
      Chapter 5 (The Instruction Set Architecture Level): This chapter gives you way more than you need to follow the posts.

      Good luck.

    • Sure, it’s quite easy: You just need to modify the file gboy_joy.c. In it, the joy_event() function takes care of key presses and depresses. Say you want to remap the ‘a’ button, which currently maps to the ‘d’ key on the keyboard. Just change where it says ‘SDLK_d’ at lines 38 and 123 to something like ‘SDLK_p’ to map to key ‘p’. The different SDLK_* are just macros from the SDL library that represents the different keystrokes. Take a better look at: where they are described.
      Hope this helps.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s