ASMSchool - Lesson 1
Welcome to ASMSchool, my own little attempt at helping people to learn how to code in assembly
language on the GameBoy using RGBDS. These tutorials will hopefully be of use to quite a few people, both total newbies
and more experienced coders. I am NOT going to just post some source code, give comments and have you cutting and
pasting, that won't teach you very much of anything. Instead, I will be going to the lowest levels and explain
everything in as much detail as I can so that you can understand "why does this do this" or "why can't
I do that?". You will learn how the processor works and how to control it before I ever start writing lessons on
how to display graphics or how to make sound. Lesson 1 will teach the student about the layout, structure, and general
philosophy behind the GameBoy CPU, as well as basic data manipulation. This CPU is a derivative of the very popular
8-bit Zilog Z-80 CPU, and has many identical features, although the GameBoy's CPU includes memory handlers, I/O control,
and other things not found in the Z80 on-chip. There are also a few things that the Z80 has that were taken out of the
GameBoy, as they were deemed by Nintendo R&D as unnesecary. (either that or SHARP's custom chip didn't have those
options available. who knows.)
Lesson 1: Description and Processor Theory
Ok, so you're probably thinking, "where do I start?" or "how do I make a
game?". Well, we are a LONG way from making a game. You have to learn the hardware and how to manipulate
it way before you can even make anything worthwhile. I'm going to start here with the basic structure of the GameBoy's
CPU, and then explain how you can make it do your evil bidding! MWA HA HA HA HA HA HA!!!.... uh hrm.. oh sorry. ;-)
Well to do ANYTHING with a CPU, you have to MOVE and OPERATE on DATA! And how on earth are we going to do that? Well,
with registers that's how. Registers in the CPU are where all data is handled and processed.
Working with and manipulating data with this processor is accomplished through the use of 8
registers inside the CPU. Each of these registers can hold 8-bits or 1 byte of data. The registers can also be paired
up to form 16-bit registers for tasks such as addressing data. The names of these registers are A, F, B, C, D, E,
H, and L. They can be grouped to form the 16-bit registers AF, BC, DE, and HL. There are also
the 16-bit registers SP and PC. Each of these registers has it's own little part to play inside the CPU.
The A register is where almost all data being processed passes through. It is also
known as the Accumulator (No, not because it's accumulating dust either!). This register, as well as B,
C, D, E, H, L can have data loaded into it directly.(I purposely left out register F) By this I mean you
can just say "I want the A register to contain 25!". You don't specifically have to load a value from memory
somewhere. It is the only 8-bit register that can be shifted with a one-byte instruction (you'll find out about
SHIFT instructions later). It is the only register that can be complemented, decimal adjusted, or negated with a
single byte instruction. It is the source AND destination for all 8-bit arithmetic and logical instructions except
for INC and DEC, which increment or decrement a register by 1. This means that when you want to
perform a certian operation like ADDing two 8-bit registers together, the two numbers you'd want to add
would be in A and some other 8-bit register, then the answer would be left in A after the operation was completed.
The F register (F for Flags) is a processor status register that can only be read from
and not written to, with one exception. Four of the bits in this register indicate the outcome of generally the last
operation performed. One bit indicates whether the last operation produced a zero or not, another bit indicates whether
or not the last instruction generated a carry, yet another indicates whether or not the last instruction performed a
subtract, and a half-carry flag in case a carry is generated between nybbles in a byte.
The B and C registers are generally used as counters during repetitive blocks of
code such as moving data from one location to another.
Registers D and E are generally used together as a 16-bit register for holding a
destination address in moving data from one address to another. They can be used for other operations though, as much
as the instructions will permit.
The H and L registers are special due to the fact that they are extensively used
for indirect addressing as register pair HL. Indirect Addressing is when instead of specifying an specific
address for an operation, you could just use the 16-bit value in HL as an address. It's pretty handy for things
like address calculations when you need to access an array of value for example. This is the ONLY register pair that can
be used indirectly in the instructions ADC, ADD, AND, CP, DEC, INC, OR, SUB, and XOR.
The SP register is the Stack Pointer, where values from PUSH, POP, CALL,
and RET instructions are placed or taken. These values are return addresses for subroutines and such. When the
GameBoy is initlaized, this register contains the value $FFFE. On the GameBoy CPU, the Stack grows from TOP DOWN. The
means that when you PUSH a 16-bit value to the stack, it hangs down the address space from the top like a
stalactite (or is it stalagmite? I can never remember).
The PC is the Program Counter. This register tells the CPU the address that
the next instruction is to be fetched from in memory. When the GameBoy starts up, this register contains the value
Well, those are the GameBoy's CPU registers. So now that you think you know those, we'll
jump right on into the instructiuons that get to play with those registers. Can you hear it? Can you? Can you? I
hear the sound of data screaming! We're coming to get you data! Cower in fear little data for a new ASM coder
is born!!! MWA HA HA!!!
The instructions in the instruction set for the GameBoy CPU are also known as opcodes. These
opcodes are grouped into 8 general categories.
- 8 and 16-bit Loads
- 8-bit Arithmetic and Logical Instructions
- 16-bit Arithmetic Instructions
- General Purpose Arithmetic and CPU Control Instructions
- Rotate and Shift Instructions
- Bit Manipulation Instructions
- Jump Instructions
- Call and Return Instructions
Lesson 1 will cover the 8 and 16-bit load instructions and some general ideas. Lesson 2 will
consist of 8 and 16-bit Arithmetic instructions and Logical instructions. Lesson 3 will cover General Purpose arithmetic
and CPU control instructions as well as rotates, shifts, and bit manipulation. Lesson 4 will be Jump Instructions and
Calls and Returns for program flow control, including all the CONDITIONAL Jumps and Calls.
8 and 16-bit Loads
Well, when programming, your ultimate goal is to manipluate data, as simple as that might
sound. Simple yes. Easy, not nessecarily. These instructions are what move data to and from registers, memory, and
oblivion (in the case of directly loading a fixed value into a register).
Register to Register Transfers
The LD (load) instruction can transfer any 8-bit general-purpose register (A, B,
C, D, E, H, or L) to any other 8-bit general purpose register. The F register can only be transferred
to or from the stack, along with the accumulator as register pair AF (PUSH AF and POP AF).
The common transfer instructions are:
- LD A, reg - Transfers the contents of reg into the accumulator
- LD reg, A - Transfers the contents of the accumulator into reg
- LD reg, (HL) - Load reg with the value at the address in HL
- LD (HL), reg - stores reg at the address in HL
Note the the destination of the data comes first in the operand field of the LD
instruction. The LD instruction changes ONLY the destination, the source stays intact. Rather than being a
MOVE style of instruction, it is rather a COPY of the source contents to the destination contents.
Now you try...
- LD A, B
- LD C, A
- LD A, (HL)
- LD (HL), A
See? Was that really difficult? The first instruction loaded the contents of register B
into register A. The next instruction loaded the contents of register A into register C. The third
instruction load the memory contents located at the address contained in HL into register A. That might
seem a bit wordy, but its just a way to use HL as an address place holder. The last instruction does just the
Direct Loading of Registers
The accumulator, register pairs BC, DE, or HL, and the Stack Pointer
can be loaded from memory using Direct Addressing. Some examples of this are:
1. LD A, ($3FFF)
This instruction loads the accumulator (register A) from memory location $3FFF.
2. LD HL, ($A000)
This instruction loads register L from memory location $A000, and register H from memory location $A001.
Note the practice of storing the Least Significant byte at the lower address. Oops! No wait! This instruction isn't
viable on the GameBoy CPU! (just checking the experienced coders) You can't just load H and L from two memory
locations with one instruction, you must load each one independently when load from memory. When loading a direct data
value you CAN do that though.
3. LD SP, ($4050)
This instruction loads the Stack Pointer from memory locations $4050 (least significant byte) and $4051
(most significant byte). All subsequent stack operations such as PUSH or POP will be located at that
new address loaded from that loacation, EG.. if at $4050 the data was $00 and at $4051 was $C4, then the Stack
Pointer will contain $C400 and all stack operations will happen there. Notice how the less significant byte of a
16-bit address is stored at the LOWER address.
Immediate Loading of Registers
Immediate addressing can be used to load any specific register or register pair with a specific
fixed value. This also includes the Stack Pointer and the Program Counter, though you shouldn't directly
load the Program Counter unless you really know what you're doing, since that is where the CPU get the address
for the next instruction to execute. Some more examples follow.
1. LD C, 3
This instruction loads register C with the value 3. The 3 is an 8-bit data item, NOT a 16-bit address. Also, do
not confuse the plain decimal 3 with $0003, even though they are relatively equal.
2. LD DE, $FF80
This instruction loads register pair DE with the value $FF80. This would be the same as loading register
D with $FF and loading register E with $80.
Indirect Loading of Registers
The instruction LD reg, (HL) can load any 8-bit register from the address in register
pair HL. The instruction LD A, (rp) can load the accumulator from the address in register pairs BC,
DE, or HL. A is the only register that can use BC and DE with indirect addressing. Note that
there is no instruction to load a register pair indirectly, so you CANNOT say something like LD DE,(HL) or
LD HL,(A000h). Examples:
1. LD D, (HL)
This instruction loads D with the byte located at the address in register pair HL.
2. LD A, (BC)
This instruction loads the accumulator from the memory address in register pair BC. Note that you cannot load any
register besides A using BC or DE indirectly.
Stack Loading of Registers
The instruction POP rp (rp is a register pair) loads a register pair from the top
of the stack. Remember, that the stack in the GameBoy grows from top-down, so the top of the stack is the lowest address
occupied by the stack, which is indexed by the Stack Pointer. Of course, POPping from the stack INCREMENTS
the stack pointer by 2, to point to the new top-of-stack address. PUSH is how you store a register pair to the
stack. These two instructions are great for temporarily saving registers if you need to use them for something else
(since there's only a few registers).
Storing Registers in Memory
Well, we talked about loading registers from memory, I guess we should now talk about storing them
TO memory. The concept is really easy now that you know how to LD a register. To store registers, you just turn the
operands around in the previous examples I gave you. Remember in Z80 and GameBoy assembly code, the structure of an
instruction is the OPERATION first, then the DESTINATION, then the SOURCE. Like this:
LD dest, source
All you gotta do to store a register is change the destination to a memory location instead of a
register and make the source a register. Here's an example:
This just loads the contents of A into the memory location $C000. Note that there are brackets around the memory
destination. This is to distinguish the address $C000 from the actual plain 16-bit data value of $C000. You can also do
This just moves the contents of C to the address contained in HL. Is that pretty simple or what? =)
Ok, well say you want to store a specific value in memory, like maybe.... $6F. Well how would we
do that? You could do it a few ways. Let's start out by loading HL with the destination memory address. Then we have to
use that address in HL as a destination in memory to load a register to:
LD HL, address (eg: $8000)
LD (HL), A <-loads contents of register A into memory location at HL
LD HL, address
LD (HL), $6F <-loads value $6F into memory location at HL
Now those weren't too hard right?
For all the specific limitations and abilities when using the LD opcode, see the instruction set reference guide also on my webpage.