MAME Debugger Execution Commands

Syntax: s[tep] [<count>=1]

The step command single steps one or more instructions in the currently executing CPU. By default, step executes one instruction each time it is issued. You can also tell step to step multiple instructions by including the optional <count> parameter.

Examples:

• s – Steps forward one instruction on the current CPU.
• step 4 – Steps forward four instructions on the current CPU.

Syntax: o[ver] [<count>=1]

The over command single steps “over” one or more instructions in the currently executing CPU, stepping over subroutine calls and exception handler traps and counting them as a single instruction. Note that when stepping over a subroutine call, code may execute on other CPUs before the subroutine call completes. By default, over executes one instruction each time it is issued. You can also tell step to step multiple instructions by including the optional <count> parameter.

Examples:

• o – Steps forward over one instruction on the current CPU.
• over 4 – Steps forward over four instructions on the current CPU.

Syntax: out

The out command single steps until it encounters a return from subroutine or return from exception instruction. Note that because it detects return from exception conditions, if you attempt to step out of a subroutine and an interrupt/exception occurs before you hit the end, then you may stop prematurely at the end of the exception handler.

Note that the step out functionality may not be implemented on all CPU types. If it is not implemented, then out will behave exactly like step.

Examples:

• out – Steps until the current subroutine or exception handler returns.

Syntax: g[o] [<address>]

The go command resumes execution of the current code. Control will not be returned to the debugger until a breakpoint or watchpoint is hit, or until you manually break in using the assigned key. The go command takes an optional <address> parameter which is a temporary unconditional breakpoint that is set before executing, and automatically removed when hit.

Examples:

• g – Resume execution until the next break/watchpoint or until a manual break.
• g 1234 – Resume execution, stopping at address 1234 unless something else stops us first.

Syntax: gv[blank]

The gvblank command resumes execution of the current code. Control will not be returned to the debugger until a breakpoint or watchpoint is hit, or until the next VBLANK occurs in the emulator.

Examples:

• gv – Resume execution until the next break/watchpoint or until the next VBLANK.

Syntax: gi[nt] [<irqline>]

The gint command resumes execution of the current code. Control will not be returned to the debugger until a breakpoint or watchpoint is hit, or until an IRQ is asserted and acknowledged on the current CPU. You can specify <irqline> if you wish to stop execution only on a particular IRQ line being asserted and acknowledged. If <irqline> is omitted, then any IRQ line will stop execution.

Examples:

• gi – Resume execution until the next break/watchpoint or until any IRQ is asserted and acknowledged on the current CPU.
• gint 4 – Resume execution until the next break/watchpoint or until IRQ line 4 is asserted and acknowledged on the current CPU.

Syntax: gt[ime] <milliseconds>

The gtime command resumes execution of the current code. Control will not be returned to the debugger until a specified delay has elapsed. The delay is in milliseconds.

Examples:

• gtime #10000 – Resume execution for ten seconds.

Syntax: n[ext]

The next command resumes execution and continues executing until the next time a different CPU is scheduled. Note that if you have used ignore to ignore certain CPUs, you will not stop until a non-ignored CPU is scheduled.

Syntax: focus <cpunum>

Sets the debugger focus exclusively to the given <cpunum>. This is equivalent to specifying ignore on all other CPUs.

Examples:

• focus 1 – Focus exclusively CPU #1 while ignoring all other CPUs when using the debugger.

Syntax: ignore [<cpunum>[,<cpunum>[,…]]]

Ignores the specified <cpunum> in the debugger. This means that you won't ever see execution on that CPU, nor will you be able to set breakpoints on that CPU. To undo this change use the observe command. You can specify multiple <cpunum>s in a single command. Note also that you are not permitted to ignore all CPUs; at least one must be active at all times.

Examples:

• ignore 1 – Ignore CPU #1 when using the debugger.
• ignore 2,3,4 – Ignore CPU #2, #3 and #4 when using the debugger.
• ignore – List the CPUs that are currently ignored.

Syntax: observe [<cpunum>[,<cpunum>[,…]]]

Re-enables interaction with the specified <cpunum> in the debugger. This command undoes the effects of the ignore command. You can specify multiple <cpunum>s in a single command.

Examples:

• observe 1 – Stop ignoring CPU #1 when using the debugger.
• observe 2,3,4 – Stop ignoring CPU #2, #3 and #4 when using the debugger.
• observe – List the CPUs that are currently observed.

Syntax: trace {<filename>|OFF}[,<cpunum>[,<action>]]

Starts or stops tracing of the execution of the specified <cpunum>. If <cpunum> is omitted, the currently active CPU is specified. When enabling tracing, specify the filename in the <filename> parameter. To disable tracing, substitute the keyword off for <filename>. If you wish to log additional information on each trace, you can append an <action> parameter which is a command that is executed before each trace is logged. Generally, this is used to include a tracelog command. Note that you may need to embed the action within braces { } in order to prevent commas and semicolons from being interpreted as applying to the trace command itself.

Examples:

• trace dribling.tr,0 – Begin tracing the execution of CPU #0, logging output to dribling.tr.
• trace joust.tr – Begin tracing the currently active CPU, logging output to joust.tr.
• trace >>pigskin.tr – Begin tracing the currently active CPU, appending log output to pigskin.tr.
• trace off,0 – Turn off tracing on CPU #0.
• trace asteroid.tr,0,{tracelog "A=%02X ",a} – Begin tracing the execution of CPU #0, logging output to asteroid.tr. Before each line, output A=<aval> to the tracelog.

Syntax: traceover {<filename>|OFF}[,<cpunum>[,<action>]]

Starts or stops tracing of the execution of the specified <cpunum>. When tracing reaches a subroutine or call, tracing will skip over the subroutine. The same algorithm is used as is used in the step over command. This means that traceover will not work properly when calls are recursive or the return address is not immediately following the call instruction. If <cpunum> is omitted, the currently active CPU is specified. When enabling tracing, specify the filename in the <filename> parameter. To disable tracing, substitute the keyword off for <filename>. If you wish to log additional information on each trace, you can append an <action> parameter which is a command that is executed before each trace is logged. Generally, this is used to include a tracelog command. Note that you may need to embed the action within braces { } in order to prevent commas and semicolons from being interpreted as applying to the trace command itself.

Examples:

• traceover dribling.tr,0 – Begin tracing the execution of CPU #0, logging output to dribling.tr.
• traceover joust.tr – Begin tracing the currently active CPU, logging output to joust.tr.
• traceover off,0 – Turn off tracing on CPU #0.
• traceover asteroid.tr,0,{tracelog "A=%02X ",a} – Begin tracing the execution of CPU #0, logging output to asteroid.tr. Before each line, output A=<aval> to the tracelog.

Syntax: traceflush

Flushes all open trace files.