ASMSchool - Lesson 7

What the hell is RGBDS and WLA?

This lesson will introduce you to the assemblers of choice among GB asm coders. Both RGBDS and WLA are great packages for turning your code into a ROM image. Both include an assembler, linker, etc. All the tools you'll need. I WILL NOT put one head and shoulders above the other, since both have their own plusses and minuses. Currently I use RGBDS, but I have used WLA and I like that one just as much.

Ok, if you haven't already, go download RGBDS and WLA. You're definately going to need them. And you might want to get CGBIDE also, just so I know what kind of editor you're using ;-).

First we'll work with RGBDS. You should have these files, either in the same directory as your source, or pointed to in your DOS PATH:

 Volume in drive C has no label
 Volume Serial Number is XXXX-XXXX
 Directory of C:\Program Files\GAMEBOY\RGBDS

.              <DIR>        04-08-01 10:18a .
..             <DIR>        04-08-01 10:18a ..
DOCS           <DIR>        04-08-01 10:18a docs
RGBASM   EXE       114,688  02-19-00  4:42p RGBASM.EXE
RGBFIX   EXE        45,056  02-19-00  4:43p RGBFIX.EXE
XLIB     EXE        43,520  02-19-00  4:42p XLIB.EXE
XLINK    EXE        53,248  02-19-00  4:42p XLINK.EXE
CGBIDE   EXE       466,944  03-11-00 11:09p CGBIDE.EXE
DOCS     ZIP        44,684  02-19-00  4:43p
CGBIDE   ZIP       196,714  04-09-01  6:43p
         7 file(s)        964,854 bytes
         3 dir(s)     516,530,176 bytes free

If you don't know what a DOS PATH is, just stick the files in the same directory as your source code. These files don't have to be that specific size, there is a plain DOS version, and a version compiled for Win9X console (DOS box in Windows) so the file sizes may not match. No worries, mon!

Ok, you'll see that we have 4 EXE's. RGBASM is the assembler, it takes your code and converts it to the correct data objects that XLINK turns into a final ROM image. RGBFIX is a cleanup tool. What it does is takes a ROM image and corrects internal header information (checksum, name, filesize, etc) and can pad or truncate the rom image to an appropriate size (32, 64, 128, 256, 512K, etc). I haven't really used XLIB.EXE, though I'm sure it has something to do with managing libraries of code. =P

Ok, lets jump right in and take a look at the batch file that I use in one of my projects.

Contents of file MAKE.BAT:

rgbasm -obank1.obj bank1.asm
rgbasm -obank2.obj bank2.asm
rgbasm -obank3.obj bank3.asm
rgbasm -odecomp.obj decomp.asm
rgbasm -ouservars.obj uservars.asm
rgbasm -ostartup.obj startup.asm
rgbasm -olib.obj lib.asm

xlink -ntest.sym link1

rgbfix -v -o test.gbc

ren testmap.txt

I REALLY hope you know how to use batch files and the DOS Prompt. If not, STOP READING NOW and go get "DOS For Dummies", a great book for all of you kids who were raised in a GUI world...

The first 7 lines are just running the assembler on several source files for my project. My project is split up into multiple files for clarity and simplicity, plus if I only make one small change in one of the source files, I only have to recomile that specific source file. The syntax for RGBASM is pretty simple, and I've used the simplest form here, just an input and output file. Obviously the "-o<filename>" tells the assembler what file to write the output to, and the second operand is just the source file.

The next line "xlink -ntest.sym link1" invokes the linker to put together all of the objects that RGBASM created from the source files. The "" option tells the linker to output a map file named "", which is basically a little text detailing everything in the ROM, and the "-ntest.sym" option tells the linker to output a no$gmb compatible SYMbol file called test.sym, so that when I load the ROM in the no$gmb debugger, it will show the labels from my source code so it's easier to debug. The symbol file must have the same name as the ROM image, or else no$gmb wont know where to load the symbol file from. More information on the format of the sym file and other no$gmb options can be found in it's help file (open the emu and press F1). And the option on the very end is the link script. The link script tells the linker all of the object files to put together into a ROM and what name to give the output.

Contents of file LINK1:



Now we have a ROM image, but we aren't quite done yet. In the next line of the batch file I use RGBFIX to check the ROM image header and correct any information that needs to be done, such as checksums, the Nintendo logo data, etc. And then the last line of the batch file just renames the map file to a TXT file so I can open it easily in Notepad and take a look.

<IMPORTANT NOTE> The logo data in the header is a VERY touchy subject. Nintendo has staunchly defended the idea that this logo data is their property, since it draws out the Nintendo logo when the GB powers up. Nintendo claims that using this piece of data without their prior authorization is a violation of copyright laws. Unfortunately, the ROM image MUST contain a correct header to run the game. There has been legal precedent that it is not illegal to include such a "signature" on the basis that it is an anti-competetive practice. Sega and Accolade were involved in a lawsuit over the same issue. Accolade produced a game for the Genesis game console without the prior consent of Sega, and distributed the game. The game included a signature that the Genesis checks to make sure it's an authorized game, even though the game had NOT been approved by Sega. The judge ruled in favor of Accolade stating that Sega was being anti-competetive. Of course, the game package didn't have Sega's "Seal Of Approval" on the front of it, but the game ran nonetheless. You'll find that in many game consoles, there is a note in the instruction manual saying something to the effect that using any game not approved for use on the console isn't authorized, etc... It's pretty much bullshit strongarm tactics to get the consumer to think of non-approved games as possible damaging to your game system. So, you REALLY have to watch yourself in homebrew game development to make sure you stay clear of copyright issues. </IMPORTANT NOTE>

Ok, now we've made it through our first make file. Now lets run it and see what happens! Just type MAKE if you're at a DOS prompt, or double-click the batch file if you're using Windows Explorer.


C:\GAME>rgbasm -obank1.obj bank1.asm
Output filename bank1.obj
Assembling bank1.asm
Pass 1...
Pass 2...
Success! 1212 lines in 0.17 seconds (427764 lines/minute)

...(clipped out other assembling for space concerns)...

C:\GAME>xlink -ntest.sym link1

C:\GAME>rgbfix -v -o test.gbc
Setting Colour GameBoy only mode
        Colour GameBoy only mode set
Validating header:
        Nintendo Character Area is OK
		ROM size byte is OK
		Cartridge type byte is OK
		Checksum changed from 0x000 to 0xF44C
		CompChecksum changed from 0x00 to 0x4C
C:\GAME>ren testmap.txt

WOW! if you see the word SUCCESS in your assembling, that's a GOOD THING. =) It means that the assembler didn't have any MAJOR issues with your sourcecode, such as syntax errors. Ok, now that you've watched me compile one of my projects, you sorta know how things will go when you start assembling your own projects.

Well, now I've run into a problem. I've spent this whole afternoon writing this tutorial, now I'm tired as hell and I haven't even touched on the WLA assembler yet... (sorry Ville!) Well, in actuality WLA is very similar to RGBDS, it's just a little different. Plus, WLA will assemble for a few different CPU's, not just the GameBoy.

That's the end of this lesson. The next lesson will be along shortly... =)