Difference between revisions of "Introduction to the MAME debugger"

Revision as of 00:49, 23 December 2015

introduction to the MAME debugger

The MAME debugger is handy when you aren't sure what's going on with your program, and need to dig deeper. This entry introduces you to the basics of the debugger.

To launch MAME with the debugger enabled, type in the following, substituting your own ROM file for the one provided:

mame64 a7800 -cart digdug.a78 -debug

Mame will launch in a window, and a separate debugger window will also appear. The debugger is active initially, program paused and ready for your input.

If you want your debugger commands to be active prior to the 7800 bios running, go ahead and enter them now. Otherwise, hit F5 to allow the bios to run, and when you see your game screen appear, hit F11 (step into) to get the debugger to hold up the program again.

Your bread-and-butter commands in the debugger are setting break points, and setting watch points. More detail on those and other useful commands in the following sections.

break points

Break points tell the MAME debugger to stop execution of your program when a certain address is reached. This is useful if you know the exact ROM address the routine you wish to inspect is located at. You can confirm that for your own programs by locating the routine in your DASM listing.

To set a break point at $8000, enter:

bpset 0x8000

Hit F5 to resume execution. When $8000 is reached, the game will stop and the debugger window will pop-up. (if it's been hidden or minimized)

At this point you can examine the register values, or step through the code using the Step selections in the Debug menu.

bpset has a lot more complexity available - you can get it to print information into the debug window, conditionally apply the break points, and more. Type "help bpset" for more info.

You can set multiple break points, list, clear, enable or disable break points. Check out the help for bpset, bpclear, bplist, bpdisable, and bpenable.

watch points

Watch points tell the MAME debugger to stop execution when some bit of memory is accessed. This is useful for tracking down the routines that use certain registers, or to determine how a variable is being updated in your program.

To set a watch point to see when the game reads console switchings, enter:

wpset 0x282,1,r

And hit F5 to resume execution. When the register $282 is read, the game will stop and the debugger window will pop-up. (if it's been hidden or minimized)

wpset has a lot more complexity available than the above example - you can watch a range of addresses, trigger only on certain conditions, print out useful information, and more. Type "help wpset" for more info.

You can set multiple watch points, list, clear, enable or disable watch points. Check of the help for wpset, wpclear, wplist, wpdisable, and wpenable.

other handy commands

dasm - create a dissassembly file from certain memory range

e.g. dasm disassembly.txt,0x8000,0x1000

dump - create a memory dump file from a certain memory range

e.g. dump dump.txt,0x8000,0x1000

statesave - save the current state to a file

e.g. statesave precrash.state

stateload - load a saved state from a file

e.g. stateload precrash.state

help - used without arguments, displays help overview. Used with an argument, it provides help on a section or command.

quality check your beta games with the debugger

Its a good idea to check that your game doesn't try to write to ROM, or write to read-only registers. A number of commercial and homebrew games have been observed to do this seemingly weird behavior, and it's typically the result of off-by-1 errors in code that uses 6502 indirect memory access.

This sort of error may not be immediately obvious or fatal, but can result in unexpected behavior on some consoles and/or bank switching cartridges.

debugger quirks

You need to keep in mind that the debugger operates in the live 6502 address space. If your game is bank switched, you need to keep in mind that commands that inspect memory only apply to the currently active bank. The debugger is like the 6502 - it doesn't know or care what cartridge magic is going on.

It should also be noted a watch point that looks for reads of a memory location will also be triggered by writes to that same location. I believe on some internal level the 6502 does a read during a write, and the MAME devs have decided to act on this. Not the most intuitive, so you may need to check the command that triggered the break point, and confirm it was indeed a read.