ASMSchool - Lesson 15

How to use the BGB Emulator/Debugger

This is a VERY important lesson, for it teaches you to use the best emulator/debugger available for the GameBoy system, BGB! This awesome tool will help you alot in learning assembly code, and help alot when you've got a bug in your code and can't find it. BGB is FREE and you can download it from http://bgb.bircd.org/.

Interface

Obviously, it's pretty smart to get to know the interface first. In the image below you can see the 5 major sections of the interface. Section A is the Code Window. This is where you can view the disassembled program code, and even poke in quick, temporary changes if you want to. Panel B is an extension of the Code Window but instead doesn't show opcodes, but straight hex values anywhere in the GB's address space. Panel C is the LCD display output window, whatever would appear on the GameBoy screen appears in this window. Panel D shows the CPU's Registers and Flags, you can even alter the Flags, as they are simple check boxes, which is pretty handy for checking out "what if" conditions at run-time. Panel E shows 16-bit wide values in the address space, and I'm pretty sure follows the Stack Pointer. Ok! Now that you know what the program looks like, you can begin using it! Press F12 to get open a ROM Image (preferrably a LEGAL one), pick one, and it will load up and run. Simple eh? Ok, the default configuration for key input is the arrow keys, TAB and SPACE for A & B, and CTRL and ENTER for SELECT & START. Pressing ESC while emulation is in progress will pause it and bring you back to the debugger, where the current line of code executing will be highlighted.


Tools

VRAM Viewer (F5)

The figure below show a picture of the VRAM Viewer window in No$gmb. You can open it from the "Window" menu or by pressing F5 when a program is NOT running (pressing F5 while a program is running will bring up the SNAPSHOT dialog). This window shows various data in the video RAM of the GameBoy. This is a VERY handy little tool, so I advise you start using it.



In the picture above, the PALETTES tab is selected, showing you the current contents of all the GBC palettes. There are a few other tabs, one which shows the output screen, one shows the BG Map contents, one shows the Tile RAM contents, and another shows the OAM (sprite) data.
NOTE: you CAN have the VRAM Viewer window open (and in the background) while running a program, and it will show the contents of VRAM "on-the-fly", but be warned, it sucks alot more CPU time. (on my K6-2 500, the emu can run about 8X faster than normal)


Emulator Setup (F11)

Pressing F11 gets you the Setup window where you can set and change various emulator options, including type of GameBoy emulated and debugging exceptions, sound, controls, etc.



Play with all the options to get a feel for what you have available, as there is really too many options for me to detail. Take note that the "Xcept" tab holds options for how the emulator acts during emulation. It can tell you if your code is doing something illegal but hard to notice, like turning off the LCD outside of V-Blank, or accessing the Echo RAM and a few other things, including software breakpoints.

Hardware Info (F10)

Pressing F10 brings up the Hardware Info window. In this window you can view all of the hardware registers in the GameBoy and their current contents. UNLIKE the VRAM Viewer, you can't see the contents of this window "on-the-fly", but rather, when you pause emulation by hitting ESC.



Utilities Menu

This menu is FULL of great little goodies to help in your debugging. You can start No$GMB's built-in text editor to edit source code, and then tell no$gmb to assemble it. There is an option to write the currently loaded ROM image to a GBXchanger flash cart (highly reccommended). You can disassemble the currently loaded ROM image to a text file, or dump hex data to a file. Pressing the PrntScr button on your keyboard will take a screenshot of the current running screen. You can also edit the color scheme that no$gmb displays DMG games in and even open a window to enter GameShark and GameGenie cheat codes.

Other Menus

The other menus contain options and commands that control the emulator, allowing you to reset the emulation, step though emulation one instruction at a time, trace, and many other things including search functions and assembling an opcode directly into memory.

That's all for now, play with the emulator and get to know all of it's features, you'll find it to be VERY helpful with developing and debugging your own GameBoy programs/games. You should check out the Help file included as it's very helpful and contains EVERYTHING you'd want to know about the emulator.

Also, I REALLY recommend that you register the emulator, as GameBoy standard emulation is freeware, but GameBoy Color emulation is shareware and lasts for only 5 minutes each time you start the emu. To register is really easy and inexpensive, and is well worth it for everything that the emulator does. Check out http://www.work.de/nocash for details. A special thanks to Martin Korth for writing the emulator in the first place.