Anonymous user
GB Programming: Difference between revisions
→Credits & Resources
>ISSOtm (Created this huge page, though it's a WIP. Hope it will help. Also, should link here from the ACE page. I'm unsure where to put the link, though.) |
|||
| (21 intermediate revisions by 9 users not shown) | |||
Line 1:
Welcome to this tutorial
Our goal will first be to create [[
Let's get started!
==A new world==
In this part is a collection of different terms, concepts and notations that are '''vital''' for the rest of this tutorial. Do NOT skip anything here unless the text specifies you can. I mean it.
If you don't understand something later on, read
===Numeric systems===
Line 28 ⟶ 27:
However, decimal is the base humans like to count in. But computers don't. Instead, they prefer '''binary'''. Binary is '''base 2''', that is, instead of working with powers of 10, we work with powers of 2. Also, only 2 symbols are allowed, 0 and 1. Each of them is called a '''bit'''.
This paragraph is some trivia about why computers use binary instead of decimal. You can skip it if you
To differentiate decimal numbers from binary numbers, binary numbers will be prepended with a % symbol. So, 10 is decimal, and %10 is binary. Got it
Here is an example :
Line 49 ⟶ 48:
* A group of 32 bits is called a '''double word''' or '''dword'''.
* A group of 64 bits is called a '''quadruple word''' or '''qword'''.
We will mostly be working with bytes, sometimes with words and rarely with nibbles. It is
Now, let's talk about '''hexadecimal'''. It is '''base 16''', so we will be working with 16 symbols : 0 1 2 3 4 5 6 7 8 9 A B C D E F. Again, we will prepend hex numbers with a $ to differentiate them.
Line 61 ⟶ 59:
</pre>
Why using hexadecimal
<pre>
$9 = %1001
Line 70 ⟶ 68:
This way, we have a more readable way of writing numbers that can be converted to binary in a snap.
For the rest of this tutorial, we will mostly be using hexadecimal, but always remember the binary lying down below
==A dip into
===Registers===
Registers are sections of RAM within the CPU itself. That is what you will be working with, alongside memory. But we'll see memory later.
There are 8 different registers, which can be actually paired up. These are A, B, C, D, E, F, H and L. These are NOT hex digits, so beware
Any of these registers can hold an '''unsigned 8-bit value'''. That means :
Line 95 ⟶ 91:
* A is the '''Accumulator'''. It is the register you have to use to make arithmetic operations, and most of the time, memory access.
* B is usually a 8-bit counter.
* C is also used as a 8-bit counter, but also for port access. We'll see that
* D, E, H and L have no special attribute as 8-bit. However, when paired, they do.
* F holds the CPU's '''Flags'''. It is very special, as you cannot use it as a general-purpose register. You can't even directly access it
* HL is quite the equivalent of A, but is 16-bit. Its name is because it stores the '''High''' and '''Low''' bytes of a memory address.
* BC is mostly used as a '''Byte Counter'''. It can also be used together with A to access memory.
Line 108 ⟶ 104:
|Store the value of ''source'' into ''destination''.
|}
Did I mention that nothing is case-sensitive
However, you can't do LD as you wish, there are restrictions :
Line 127 ⟶ 123:
|DE
|HL
|
|
|
|
|-
|A
Line 292 ⟶ 288:
|Yes
|-
|
|Yes
|No
Line 308 ⟶ 304:
|No
|-
|
|Yes
|No
Line 324 ⟶ 320:
|No
|-
|
|Yes
|Yes
Line 340 ⟶ 336:
|No
|-
|
|Yes
|No
Line 400 ⟶ 396:
|Store value of register B into register D.
|-
|''ld
|Store the value of register A into memory address $8325.
|}
Line 408 ⟶ 404:
Trying to do something like ''ld a, $100'' isn't possible. Like, physically impossible. You'll see why much, much later.
Note that ''ld a, -1'' is valid, but actually, the "-1" wraps. Storing -1 will truly store 255 in a 8-bit register, and 65535 in a 16-bit register. Why
Notice that F and AF aren't usable anywhere. Actually, only a few instructions use them.
===Negative numbers===
Time to confess
I've told you, "individual registers can hold unsigned 8-bit values, and pairs unsigned 16-bit values". However, these aren't true
What we will be doing is cutting our number range in half, and telling one half is composed of negative numbers. But how to distinguish positive and negative numbers
How to multiply by -1
* Calculate zero minus your number (just like in real life). However, you should consider 0 the same as 256 (in 8-bit mode) or 65536 (in 16-bit mode).
* Flip the state of every bit, then add one.
Line 429 ⟶ 424:
Add 1 %10000000
</pre>
So, uh, -(-128) = -128
Now, let's see how the CPU handles the difference between unsigned and signed values. Surprise, it doesn't
<pre>
unsigned signed
Line 438 ⟶ 433:
%1 00000000 = 256 = 0 (Disqualify ninth bit)
</pre>
And, you just saw why I told you to consider 0 the same as 256 : they are similar
===Memory===
Finally
Ever wondered why you could open a JPEG in Word
How is every byte differentiated from its neighbors
So, how does running a program works
So now, how to access memory
To access the memory location pointed to by HL, just do...
So, to retrieve the value at memory address $
And to store the value of register C into the memory pointed to by HL : ''ld
Remember to refer to the chart above for the legal LD combinations.
Obviously, ''ld
For those wondering, ''ld a, [$6511]'' leaves [$6511] untouched.
==Flags==
Remember that "special" F register
Here are the 8 flags :
Line 472 ⟶ 465:
|7||6||5||4||3||2||1||0
|-
|}
===Z : Zero===
Line 484 ⟶ 474:
===H : Half-Carry===
Works like the Carry flag, but referring to the least-significant ''nibble''. It is only used with the DAA instruction, so... forget it until then.
===N : Add/Subtract===
Line 501 ⟶ 484:
* SCF sets it, and
* CCF inverts it.
==Manipulating data==
===Instructions get
Let's get these :
{| class="wikitable"
!Syntax
!Effect
!Z
!C
|-
|INC <nowiki>{reg8 | reg16 |
|Adds one to the operand ("increments" it)
|Affected, except for reg16
|Not affected
|-
|DEC <nowiki>{reg8 | reg16 |
|Subtracts one to the operand ("decrements" it)
|Affected, except for reg16
|Not affected
|-
|ADD A, <nowiki>{reg8 |
|Adds the operand to the accumulator
|Affected
|Not affected
|-
Line 539 ⟶ 512:
|Adds the operand to HL
|Affected
|Not affected
|-
|SUB
|Subtracts the operand from the accumulator. The syntax SUB A, <nowiki>{...}</nowiki> is also valid but less common.
|Affected
|Not affected
|}
If you want to get information about any instruction, go [http://tutorials.eeems.ca/ASMin28Days/ref/z80is.html there].
Q : Hey, but where's MULT
A : Nowhere :D To multiply, you must write your own routines
For the rest of the tutorial, you'll see some text prefixed by a ";". These are comments, and are NOT part of the code. This line : "ld
Also, the Game Boy's CPU as four very specific instructions :
{| class="wikitable"
|ld
|Equivalent to ''ld
|-
|ld
|Equivalent to ''ld
|-
|ld a,
|Equivalent to ''ld a,
|-
|ld a,
|Equivalent to ''ld a,
|}
These are often used to operate on
===Overflow===
Line 588 ⟶ 549:
add a, 119
</pre>
What value will hold A
Thus, the result is A equals 66 = %01000010, and the C flag is set.
===Register pairs and RAM===
Let's say you run a ld hl, $D361. $D361 is put into HL, but since it is registers H and L paired up, what happen to them
Because two hex digits mean one byte, $D3, as well as $61, is a byte. Since $D3 and H are leftmost in both cases, ld hl, $D361 is actually a shorter form of ld h, $D3 then ld l, $61.
Let's say the following instruction is ld
Stop here, and remember this until it becomes natural to you. Because this "little-endian"ness is very tricky for beginners. It is ''very'' important when working with memory.
Here is an exercise : what values will
Initial values :
{| class="wikitable"
|$C000||$C001||$C002||$C003||$
|-
|$00||$03||$4F||$C0||$DE||$57||$2A||$00||$FF||$01||$23||$34||$56||$78||$9A||$BC
Line 613 ⟶ 573:
<pre>
ld hl, $C303
ld a,
ld b, 3
add a, b
ld c, 0
sbc hl, bc
ld
inc hl
ld b,
sub a, b
inc
inc hl
ld
ld bc, 9
add hl, bc
ld
ld
</pre>
==Stacks==
===A stack
No
In our case, we will do it by saving the top of the stack as a memory address. This value is called the ''stack pointer''. Here is an example, with the stack growing to the right :
Line 668 ⟶ 627:
|$00||$03||$4F||$C0||$7C||$2A||??||??||??||??||??||??||??||??||??||??
|}
===Coding a stack===
Let's say we have our stack pointer saved at memory address $C000 (because it is a 16-bit value, it also uses memory address $C001
To push register DE :
<pre>
ld hl,
ld
inc hl ; Move stack pointer
ld
inc hl
ld
</pre>
To pop into register DE :
<pre>
ld hl,
dec hl ; Move stack pointer
ld d,
dec hl ; Repeat
ld e,
ld
</pre>
===Good news===
Okay, coding a stack is cool, but... isn't there a faster way of doing it
{| class="wikitable"
|PUSH reg16
Line 716 ⟶ 673:
where reg16 is any 16-bit register pair. AF can be used here.
Also meet SP, which makes all of this possible. SP is the '''hardware Stack Pointer'''. You can INC and DEC it, and you can't use it as a source in LD. Here are equivalents of ''push hl'' and ''pop hl'' (assuming we could use
{| class="wikitable"
|PUSH HL
|<pre>
dec sp
ld
dec sp
ld
</pre>
|-
|POP HL
|<pre>
ld l,
inc sp
ld h,
inc sp
</pre>
Line 736 ⟶ 693:
Note that the stack grows '''downwards''' (ie, PUSH reduces the value from SP, and POP augments it). Also, POP doesn't alter memory.
You cannot PUSH / POP with 8-bit registers. Instead, to save register B, you '''must''' ''push bc''. You don't have to push and pop to the same register
<pre>
push af
ld a,
pop de
</pre>
is completely valid. (Note that E's value after the POP is equal to F's when PUSHing, so this is the only way to directly access the F register)
Beware with the stack, even more when you're not coding your own game : everyone uses the stack ; even the CPU
==Control structures==
===Rollin' around===
...at the speed of sound
Up until now, we've seen only programs that begin somewhere and that are ran top to bottom, in that order. However, this never happens in a more complex context. So, let's see how to manipulate code flow
We have two instructions that allow execution to jump somewhere else in memory :
Line 761 ⟶ 717:
|Has execution jumping over offset8 bytes
|}
What's the difference
First, JP can go '''anywhere'''. JP tells the CPU "jump to this memory address". JR is much more limited, as it can only reach a signed 8-bit range (128 bytes backwards, or 127 bytes forwards).
Line 769 ⟶ 725:
Third, JR takes 7 or 12 CPU cycles to run, whereas JP always takes 10.
Labels are actually memory addresses, they mark the target of the jumps. Here is an example of label usage :
<pre>
loop: ; This is a label ! This defines label "loop".
sub a, $0A
jr c, finished
; Do stuff with a...
jr loop ; This jumps to the "sub a, $0A" right after the "loop:" line.
finished:
inc a
; Do some more stuff, we don't care anymore.
</pre>
You may wonder what this "jr c, finished" is. And this brings us to the next part!
===Conditionals===
JP and JR can be executed in unconditional ways, meaning the jump will always occur. This can be useful, but sometimes we don't want that. And that's where flags come in handy
{| class="wikitable"
|JP condition, label
Line 794 ⟶ 761:
Four instructions can use conditionals : CALL, RET (these are coming in soon), JP and JR. JR has a handicap, though : it can only use the Z, NZ, C and NC conditions.
So, there you see how you can create conditionals in z80 assembly : by shifting the flow of code.
I want you to understand the following : even though you have more contol over the flow of code, try to be organized ; intricate jumps can be excessively tough to understand. Also, jumps consume space and time ; try to jump the least you can.
Last thing, though it's more on the optimization side, but remember : if you're going for space - and that's often the case with ACE - you should use jr. But if speed is a must (that is, you absolutely need to shave 5 CPU cycles per jump, which is *RARE*), use jp. Use jp also when jr cannot reach the target - never use a chain of jr spaced by $7F bytes. It's '''pointless'''.
===A special jp===
There is one special case of jp, though !
{| class="wikitable"
|JP HL
|Has execution jumping to the address pointed to by hl.<br/>Does not accept any conditionals.
|}
Example :
<pre>
ld hl, $2457
jp hl
</pre>
will jump to $2457. Some might argue that "jp $2457" is better, as it'd save 1 byte and preserve the hl register.
However, "jp hl" is used to do dynamic jumps: "jp hl" may jump to a different location every time it is ran. When doing "static" (ie. always the same) jumps, it '''is''' better to use jp $xxyy. "jp hl" mostly used with function pointer tables - we'll see that later.
===Comparing stuff===
Here is an instruction that is heavily used with conditional jumps :
{| class="wikitable"
|CP <nowiki>{reg8 | imm8}</nowiki>
|Does the same as SUB <nowiki>{...}</nowiki>, but leaves a untouched.
|}
cp is heavily used with conditionals, since it compares the accumulator's value with another. Here is a nifty table :
{| class="wikitable"
|Comparison
|Unsigned equivalent
|Signed equivalent
|-
|A == ''number''
!colspan="2"|Z is set (A - ''number'' == 0)
|-
|A != ''number''
!colspan="2"|Z is not set (A - ''number'' != 0)
|-
|A < ''number''
|C is set (A - ''number'' generated a borrow)
|S and P/V are different (P/V means overflow)
|-
|A >= ''number''
|C is reset (A - ''number'' generated no borrow)
|S and P/V are the same
|}
Example :
<pre>
ld a, [hl]
cp $63
jr z, placeItems
inc hl
inc hl
jr someplace
placeItems:
ld b, [hl]
</pre>
If [hl] equals $63, execution jumps to placeItems.
Otherwise, executions continues through, increments hl twice, then jumps to "someplace"
===Chaining conditionals===
!!WARNING!! The code I'll be writing in assembly can be written in other ways. If you think you'd have done it in another way, try it. Count the instructions in your code, and if it is less than I did, then you did well !
Don't assume my way is the only. It is a good idea to try to find other ways to do the stuff I propose ! It's a good exercise !
Okay, so let's try the following C code, assuming a is the a register :
<pre>
if(a == $2A) {
// Success stuff
} else {
// Failure stuff
}
// Rest of the code
</pre>
In assembly, that's easy !
<pre>
cp $2A
jr nz, failure
; Success stuff
jr afterConditional
failure:
; Failure stuff
afterConditional:
; Rest of the code
</pre>
Think of another way... like, having the failure stuff first.
<pre>
cp $2A
jr z, success
; Failure stuff
jr afterConditional
sucess:
; Success stuff
afterConditional:
; Rest of the code
</pre>
Got it ? Good !
Okay. Let's get it one level higher.
<pre>
if(b == $C0 && c == $DE) { // && means AND. But it's a logical AND - we'll see another AND later.
// Success stuff
} else {
// Failure stuff
}
</pre>
Um... let's try doing multiple jumps.
<pre>
ld a, $C0
cp b
jr nz, failure
ld a, c
cp $DE
jr nz, failure
; Success stuff
jr afterCond
failure:
; Failure stuff
afterCond:
</pre>
Phew ! Not exactly the same, but it's still going fine.
To do a AND, simply treat stuff as a failure if any of the conditions fail.
Okay. Let's get it a lil' bit different.
<pre>
if(b == $C0 || c == $DE) { // || means OR. But it's a logical OR- we'll see another OR later.
// Success stuff
} else {
// Failure stuff
}
</pre>
Um... let's try doing multiple jumps.
<pre>
ld a, $C0
cp b
jr z, success
ld a, c
cp $DE
jr z, success
; Failure stuff
jr afterCond
success:
; Success stuff
afterCond:
</pre>
Okay ! Now, to do OR, we simply run each comparison. If any succeeds, we jump straight to SUCCESS. Othewise, we FAIL.
I'll leave the following code as an exercise :
<pre>
if((h == $C0 && l == $DE) || a == $2A) {
// Success stuff
} else {
// Failure stuff
}
</pre>
===On to loopings===
Some of you might have thought "Hey, ISSOtm. Up until now, you've been going forwards all the time. Even your jumps were skipping over instructions - but forever forwards. What if we went '''backwards''' ?"
Well, kudos to you ! This is the basis of looping structures.
Here is the most simple loop in assembly :
<pre>
loop:
; Do stuff
jr cond, loop
</pre>
Ta-daah ! Here is a more explicit (less generic) loop:
<pre>
ld b, $06
countingLoop:
; Do stuff (admit it preserves b)
dec b ; Sets Z if b == 0 after the DEC.
jr nz, countingLoop ; go back if b is non-zero
; Do some MOAR stuff
</pre>
This should run the "Do stuff" part six times exactly. If said part modifies b... it will work in other ways.
I'll leave to you as an exercise what would happen if the "ld b, $06" was replaced by a "ld b, $00"...
Now you got how to create loops. Neato. Let's see how to create... routines. Or procedures. Or functions. Whatever you call them.
===Routines / Functions / Procedures / Whatever===
I've told you about CALL and RET in the "Conditionals" section. Now let's see what they do.
They are a more avanced way to do jumps. Basically, you "call" a piece of code, that does its stuff, then "returns" to your code control of the CPU. Bam, CALL and RET explained.
{| class="wikitable"
|CALL label16
|Calls code starting at label16
|-
|CALL cond, label16
|Same, but with the same conditionals as JP (not JR)
|-
|RET
|Returns to the previous "caller".
|-
|RET cond
|Do I need to explain ?
|}
But wait, there is more ! And it is '''VITAL'''. The way call works is very simple :
# Get the address of the instruction right after the call.
# Push it onto the stack.
# Jump to the address specified by the call adress.
And ret works in a way that is compatible with call :
# Pop a number from the stack.
# Jump to that address.
Now, you need to be super-duper careful with the stack, since it is used by the call-ret system. Basically, make sure that between label16 and the next ret, you have done the same amount of PUSHes and POPs :
<pre>
call routine
; Ton of code
routine:
push hl
push bc
; Code
pop bc
; Codez
pop hl
; Codeeeee
ret
</pre>
is fine
<pre>
call baaad
; Ton of code
baaad:
push hl
push bc
; Code
pop bc
; Codeeeey
ret
</pre>
is bad.
Unless you'e ABSOLUTELY CERTAIN about what you're doing, upon leaving your routine's code, leave the stack the SAME is was. It is absolutely necessary to avoid screwing up everything.
<hr>
==Solutions to the exercises==
===Instructions get
B can be swapped with any other register (except A)
{| class="wikitable"
Line 838 ⟶ 1,048:
</pre>
|}
===Register pair and RAM===
Line 845 ⟶ 1,054:
ld hl, $C303 ; Now H = $C3 and L = $03
ld a,
ld b, 3 ; B = $03
Line 855 ⟶ 1,064:
sbc hl, bc ; HL = HL - (BC + C flag) = $C303 - ($0300 + $00) = $C003
ld
inc hl ; HL = $C004
ld b,
sub a, b ; A = A - B = $06 - $DE = $06 + (-$DE) = $06 + ($21 + $01) = $28, C flag = 0
<br/>
Notice here that doing ''sub a, b'' actually increased A's value
inc
inc hl ; HL = $C005
ld
ld bc, 9 ; B = $00, C = $09
Line 875 ⟶ 1,084:
add hl, bc ; HL = HL + BC = $C005 + $0009 = $C00E
ld
ld
Initial values :
Line 892 ⟶ 1,101:
|}
===Chaining conditionals===
You think you gotcha ? I'll be explaining the code, don't'cha worry :)
<pre>
cp $2A ; it's better to do the a comparison first, since we'll use it for later comparisons.
jr z, success ; if we don't jump, we will do the ANDed comparison.
ld a, b
cp $C0
jr nz, failure ; first AND operand...
ld a, c
cp $DE
jr nz, failure ; ...then the second. The order doesn't matter here.
success:
; Success stuff
jr afterConditional
failure:
; Failure stuff
afterConditional:
</pre>
Didja get it ? If not, try to understand which part of the code matches which part of the C code. If you get it, you'll understand the assembly code. I admit it's tough at the first glance. I've been through this, don't'cha worry.
===On to loopings===
What would happen ? Well, imagine you ran the "Do stuff" part once. B is zero - we didn't touch it - and we reached a "dec b". Now, remember what the instruction does :
# We decrement B (B = 0 - 1 = 255, remember overflow ?)
# If B is zero, we set the Z flag. Otherwise we reset it. (Z is reset, since B != 0)
... so the loops starts again with B = 255.
tl;dr : the loop is ran 256 times !
"Hey ISSOtm, what if I wanted my loop to run zero times instead of 256 in that case ?" Simple !
<pre>
ld a, b ; this does NOT modifiy Z !!
cp $0 ; there is a more efficient way of doing this, but you don't know it yet.
jr z, afterLoop ; if b - 0 == 0, we skip the loop completely.
countingLoop:
; Do stuff (admit it preserves b)
dec b ; Sets Z if b == 0 after the DEC.
jr nz, countingLoop ; go back if b is non-zero
afterLoop:
; Do some MOAR stuff
</pre>
==Credits & Resources==
Tutorial written (mostly) by ISSOtm for Glitch City Laboratories.
Thanks to Torchickens and RaltsEye for correcting typos, formatting 'n stuff.
Includes bits of [http://tutorials.eeems.ca/ASMin28Days/welcome.html this tutorial] for the ASM part.
Heavily using [http://gbdev.gg8.se/wiki/articles/Pan_Docs the Pan Docs] for GameBoy-specific stuff.
The [http://marc.rawer.de/Gameboy/Docs/GBCPU_Instr.html GCISheet] is useful for understanding CPU instructions and can be combined with [https://iimarckus.org/etc/asmopcodes.txt IIMarckus's opcode to instruction page] or the copy on [[The Big HEX List]].
[https://tcrf.net/Help:Contents/Finding_Content/Debugger_guide/BGB Torchickens has started a tutorial for BGB emulator's debugger at The Cutting Room Floor]
[[Category:Arbitrary code execution]]
[[Category:Reference documents]]
| |||