Difference between revisions of "Introduction to the MAME debugger"

Revision as of 14:27, 25 February 2020

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

Or if you want to enable extra hardware, like the XM, use something like the following:

mame64 a7800 -cart1 xm -cart2 digdug.a78 -debug

Mame will launch in a window, and a separate debugger window will also appear. The debugger is active initially, with the 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. (or their keyboard equivalents)

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)

If you want to watch memory access, without having to restart with F5 every time, modify the read or write examples below for your address:

wp 0x282,1,r,1,{printf "Read %04X (%02D)",wpaddr,pb@wpaddr; g}

wp 0xcc,1,w,1,{printf "Write %04X=%02X",wpaddr,wpdata; g}

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.

viewing memory

If you select the Debug menu in the MAME debugger window, a window will pop-up that displays the entire memory range of the first CPU. You can watch memory values change live as the program runs, or also use this window to view memory contents as you single-step through instructions in the debugger.

You can also see the memory contents of other devices in the driver, but there's a lot of information, especially a lot of driver specific internal information. Usually it's more fruitful to just stick to the main CPU memory, and if you need extra debug diagnostic information, you can write to some free area of memory in your game, and watch it's values change in this window.

other handy commands and tips

[ENTER] - hitting ENTER in the debugger window without any other text will pause the emulation and start single-stepping through instructions.

[UP ARROW] - recall previous items you typed into the debugger.

dasm - create a dissassembly file from certain memory range

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

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

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

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

e.g. save dump.bin,0x4000,0x2000

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

trace - log all executed instructions to a file

e.g. trace tracefile.txt           (trace instructions to file)
e.g. trace tracefile.txt,0,noloop  (trace instructions to file, and show instructions within loops)
e.g. trace off                     (turn off tracing)

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

e.g. help
e.g. help memory
e.g. help bplist

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.

wpset 0x8001,0x7fff,w        (can be used with supergame bankswitch games, if you stick to using 0x8000 as the hot spot)

An off-by-1 error that causes bad indirect memory access 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.

Authorship

Introduction to the MAME debugger was written by Mike Saarna (aka RevEng) as original content for 7800.8bitdev.org.