Introduction to the MAME debugger - Revision history

MSaarna at 01:31, 1 May 2025

2025-05-01T01:31:18Z

MSaarna at 01:25, 1 May 2025

2025-05-01T01:25:44Z

MSaarna at 13:53, 27 April 2025

2025-04-27T13:53:10Z

MSaarna at 01:55, 27 April 2025

2025-04-27T01:55:16Z

MSaarna at 01:51, 27 April 2025

2025-04-27T01:51:47Z

MSaarna at 01:50, 27 April 2025

2025-04-27T01:50:15Z

MSaarna at 18:57, 26 April 2025

2025-04-26T18:57:55Z

MSaarna at 15:41, 26 April 2025

2025-04-26T15:41:36Z

MSaarna at 15:40, 26 April 2025

2025-04-26T15:40:35Z

MSaarna: /* advanced debugger tricks */

2025-04-26T15:39:46Z

‎advanced debugger tricks

@@ Line 17: / Line 17: @@
 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.
-One last important note before we move on. Any unprefixed numbers you enter into the debugger are interpreted as hexadecimal. (as are numbers you prefix with "0x" or "$") To input decimal numbers you can prefix the value with "#". e.g. "#10" is 10 decimal, and "10" is 10 hexadecimal/16 decimal.
+One last important note before we move on. Any unprefixed values you enter into the debugger are interpreted as hexadecimal. To input decimal values you need to prefix the value with "#".
@@ Line 25: / Line 25: @@
 To set a break point at $8000, enter:
-  bpset 0x8000
+  bpset 8000
 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)
@@ Line 41: / Line 41: @@
 To set a watch point to see when the game reads console switches enter:
-  wpset 0x282,1,r
+  wpset 282,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)
@@ Line 47: / Line 47: @@
 Similarly, if you want to stop execution when a certain bit of memory is written to, you can do that too:
-  wpset 0x2020,1,w
+  wpset 2020,1,w
 As you might have guessed, the second parameter is the number of consecutive bytes to watch, so to watch sixteen bytes you might enter:
-  wpset 0x2010,0x10,w
+  wpset 2010,10,w
 If you want to only stop only when a particular data value is used to access your memory location, you can specify that condition:
-  wpset 0x2020,1,w,wpdata==13
+  wpset 2020,1,w,wpdata==13
 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}
+  wpset 282,1,r,1,{printf "Read %04X (%02D)",wpaddr,pb@wpaddr; g}
-  wp 0xcc,1,w,1,{printf "Write %04X=%02X",wpaddr,wpdata; g}
+  wpset cc,1,w,1,{printf "Write %04X=%02X",wpaddr,wpdata; g}
@@ Line 86: / Line 86: @@
 dasm - create a dissassembly file from certain memory range
-  e.g. dasm disassembly.txt,0x8000,0x1000
+  e.g. dasm disassembly.txt,8000,1000
 dump - create a text memory dump file from a certain memory range
-  e.g. dump dump.txt,0x8000,0x1000
+  e.g. dump dump.txt,8000,1000
 save - create a binary memory dump file from a certain memory range
-  e.g. save dump.bin,0x4000,0x2000
+  e.g. save dump.bin,4000,2000
@@ Line 121: / Line 121: @@
 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)
+  wpset 8001,7fff,w        (can be used with supergame bankswitch games, if you stick to using $8000 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.

@@ Line 16: / Line 16: @@
 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.
@@ Line 144: / Line 146: @@
 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. 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.

@@ Line 129: / Line 129: @@
-When a watchpoint is triggered you can write to memory or registers. Here we set the background color register to a specific value. (without pausing execution)
+When a watchpoint is triggered you can tell it to write to memory or registers. Here we set the background color register (0x20) to a specific value. (without pausing execution)
   wpset 294,4,w,1,{b@20=42;g}
 You can use watchpoints to duplicate writes from one region of memory to another. Here we're directing writes from a pokey@450 to a pokey@800. ( without pausing execution)
   wpset 450,10,w,1,{b@(wpaddr-450+800)=wpdata;g}
 If you have an ongoing trace log, you can output to it from watchpoints. Here's an example that watches all of the address space, and outputs a running log of register values in the trace.

@@ Line 69: / Line 69: @@
 ==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.
+If you select the "Debug->New Memory Window" 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.

@@ Line 135: / Line 135: @@
   wpset 450,10,w,1,{b@(wpaddr-450+800)=wpdata;g}
-If you have an ongoing trace log, you can output to it from watchpoints. Here's an example that watches all of the address space, so we get a running log of register values.
+If you have an ongoing trace log, you can output to it from watchpoints. Here's an example that watches all of the address space, and outputs a running log of register values in the trace.
   wpset 0,ffff,rw,1,{tracelog "[A:%x X:%x Y:%x PC:%x]\n",a,x,y,pc;g}

@@ Line 130: / Line 130: @@
 When a watchpoint is triggered you can write to memory or registers. Here we set the background color register to a specific value. (without pausing execution)
-  wpset 294,4,w,1==1,{b@20=42;g}
+  wpset 294,4,w,1,{b@20=42;g}
 You can use watchpoints to duplicate writes from one region of memory to another. Here we're directing writes to a pokey@450 to a pokey@800. ( without pausing execution)

@@ Line 16: / Line 16: @@
 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==
@@ Line 112: / Line 113: @@
   e.g. help memory
   e.g. help bplist
 ==quality check your beta games with the debugger==

@@ Line 123: / Line 123: @@
 ==advanced debugger tricks==
 The debugger also allows you to interact with the emulated console more than you might expect. Here are a few examples.
@@ Line 136: / Line 135: @@
 If you have an ongoing trace log, you can output to it from watchpoints. Here's an example that watches all of the address space, so we get a running log of register values.
   wpset 0,ffff,rw,1,{tracelog "[A:%x X:%x Y:%x PC:%x]\n",a,x,y,pc;g}
 ==debugger quirks==