Execution Debugger Commands¶

step: single step for <count> instructions (F11)
over: single step over <count> instructions (F10)
out: single step until the current subroutine/exception handler returns (Shift-F11)
go: resume execution (F5)
gbt: resume execution until next true branch is executed
gbf: resume execution until next false branch is executed
gex: resume execution until exception is raised
gint: resume execution until interrupt is taken (F7)
gni: resume execution until next further instruction
gtime: resume execution until the given delay has elapsed
gvblank: resume execution until next vertical blanking interval (F8)
next: resume execution until the next CPU switch (F6)
focus: focus debugger only on <CPU>
ignore: stop debugging on <CPU>
observe: resume debugging on <CPU>
trace: trace the specified CPU to a file
traceover: trace the specified CPU to a file skipping subroutines
traceflush: flush all open trace files.

step¶

s[tep] [<count>]

Single steps one or more instructions on the currently executing CPU. Executes one instruction if <count> is omitted, or steps <count> instructions if it is supplied.

Examples:

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

Back to Execution Debugger Commands

over¶

o[ver] [<count>]

The over command single steps “over” one or more instructions on 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 returns.

Steps over one instruction if <count> is omitted, or steps over <count> instructions if it is supplied.

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

Examples:

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

Back to Execution Debugger Commands

out¶

out

Single steps until a return from subroutine or return from exception instruction is encountered. Note that because it detects return from exception conditions, if you attempt to step out of a subroutine and an interrupt/exception occurs before the subroutine completes, execution may stop prematurely at the end of the exception handler.

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

Example:

out: Steps until a subroutine or exception handler returns.

Back to Execution Debugger Commands

go¶

g[o] [<address>]

Resumes execution. Control will not be returned to the debugger until a breakpoint or watchpoint is triggered, or a debugger break is manually requested. If the optional <address> is supplied, a temporary unconditional breakpoint will be set for the visible CPU at the specified address. It will be cleared automatically when triggered.

Examples:

g: Resume execution until a breakpoint/watchpoint is triggered, or a break is manually requested.
g 1234: Resume execution, stopping at address 1234, unless another condition causes execution to stop before then.

Back to Execution Debugger Commands

gbf¶

gbf [<condition>]

Resumes execution. Control will not be returned to the debugger until a breakpoint or watchpoint is triggered, or until a conditional branch or skip instruction is not taken, following any delay slots.

The optional <condition> parameter lets you specify an expression that will be evaluated each time a conditional branch is encountered. If the result of the expression is true (non-zero), execution will be halted after the branch if it is not taken; otherwise, execution will continue with no notification.

Examples:

gbf: Resume execution until a breakpoint/watchpoint is triggered, or until the next false branch.
gbf {pc != 1234}: Resume execution until the next false branch, disregarding the instruction at address 1234.

Back to Execution Debugger Commands

gbt¶

gbt [<condition>]

Resumes execution. Control will not be returned to the debugger until a breakpoint or watchpoint is triggered, or until a conditional branch or skip instruction is taken, following any delay slots.

The optional <condition> parameter lets you specify an expression that will be evaluated each time a conditional branch is encountered. If the result of the expression is true (non-zero), execution will be halted after the branch if it is taken; otherwise, execution will continue with no notification.

Examples:

gbt: Resume execution until a breakpoint/watchpoint is triggered, or until the next true branch.
gbt {pc != 1234}: Resume execution until the next true branch, disregarding the instruction at address 1234.

Back to Execution Debugger Commands

gex¶

ge[x] [<exception>,[<condition>]]

Resumes execution. Control will not be returned to the debugger until a breakpoint or watchpoint is triggered, or until an exception condition is raised on the current CPU. Use the optional <exception> parameter to stop execution only for a specific exception condition. If <exception> is omitted, execution will stop for any exception condition.

The optional <condition> parameter lets you specify an expression that will be evaluated each time the specified exception condition is raised. If the result of the expression is true (non-zero), the exception will halt execution; otherwise, execution will continue with no notification.

Examples:

gex: Resume execution until a breakpoint/watchpoint is triggered, or until any exception condition is raised on the current CPU.
ge 2: Resume execution until a breakpoint/watchpoint is triggered, or until exception condition 2 is raised on the current CPU.

Back to Execution Debugger Commands

gint¶

gi[nt] [<irqline>]

Resumes execution. Control will not be returned to the debugger until a breakpoint or watchpoint is triggered, or until an interrupt is asserted and acknowledged on the current CPU. Use the optional <irqline> parameter to stop execution only for a specific interrupt line being asserted and acknowledged. If <irqline> is omitted, execution will stop when any interrupt is acknowledged.

Examples:

gi: Resume execution until a breakpoint/watchpoint is triggered, or any interrupt is asserted and acknowledged on the current CPU.
gint 4: Resume execution until a breakpoint/watchpoint is triggered, or interrupt request line 4 is asserted and acknowledged on the current CPU.

Back to Execution Debugger Commands

gni¶

gni [<count>]

Resumes execution. Control will not be returned to the debugger until a breakpoint or watchpoint is triggered. A temporary unconditional breakpoint is set at the program address <count> instructions sequentially past the current one. When this breakpoint is hit, it is automatically removed.

The <count> parameter is optional and defaults to 1 if omitted. If <count> is specified as zero, the command does nothing. <count> is not permitted to exceed 512 decimal.

Examples:

gni: Resume execution until a breakpoint/watchpoint is triggered, including the temporary breakpoint set at the address of the following instruction.
gni 2: Resume execution until a breakpoint/watchpoint is triggered. A temporary breakpoint is set two instructions past the current one.

Back to Execution Debugger Commands

gtime¶

gt[ime] <milliseconds>

Resumes execution. Control will not be returned to the debugger until a specified interval of emulated time has elapsed. The interval is specified in milliseconds.

Example:

gtime #10000: Resume execution for ten seconds of emulated time.

Back to Execution Debugger Commands

gvblank¶

gv[blank]

Resumes execution. Control will not be returned to the debugger until a breakpoint or watchpoint is triggered, or until the beginning of the vertical blanking interval for an emulated screen.

Example:

gv: Resume execution until a breakpoint/watchpoint is triggered, or a vertical blanking interval starts.

Back to Execution Debugger Commands

next¶

n[ext]

Resumes execution until a different CPU is scheduled. Execution will not stop when a CPU is scheduled if it is ignored due to the use of ignore or focus.

Example:

n: Resume execution, stopping when a different CPU that is not ignored is scheduled.

Back to Execution Debugger Commands

focus¶

focus <CPU>

Focus exclusively on to the specified <CPU>, ignoring all other CPUs. The <CPU> argument can be a device tag or debugger CPU number (see Specifying devices and address spaces for details). This is equivalent to using the ignore command to ignore all CPUs besides the specified CPU.

Examples:

focus 1: Focus exclusively on the second CPU in the system (zero-based index), ignoring all other CPUs.
focus audiopcb:melodycpu: Focus exclusively on the CPU with the absolute tag path :audiopcb:melodycpu.

Back to Execution Debugger Commands

ignore¶

ignore [<CPU>[,<CPU>[,…]]]

Ignores the specified CPUs in the debugger. CPUs can be specified by tag or debugger CPU number (see Specifying devices and address spaces for details). The debugger never shows execution for ignored CPUs, and breakpoints or watchpoints on ignored CPUs have no effect. If no CPUs are specified, currently ignored CPUs will be listed. Use the observe command to stop ignoring a CPU.

Note that you cannot ignore all CPUs; at least CPU must be observed at all times.

Examples:

ignore audiocpu: Ignore the CPU with the absolute tag path :audiocpu when using the debugger.
ignore 2,3,4: Ignore the third, fourth and fifth CPUs in the system (zero-based indices) when using the debugger.
ignore: List the CPUs that are currently being ignored by the debugger.

Back to Execution Debugger Commands

observe¶

observe [<CPU>[,<CPU>[,…]]]

Allow interaction with the specified CPUs in the debugger. CPUs can be specified by tag or debugger CPU number (see Specifying devices and address spaces for details). This command reverses the effects of the ignore command. If no CPUs are specified, currently observed CPUs will be listed.

Examples:

observe audiocpu: Stop ignoring the CPU with the absolute tag path :audiocpu when using the debugger.
observe 2,3,4: Stop ignoring the third, fourth and fifth CPUs in the system (zero-based indices) when using the debugger.
observe: List the CPUs that are currently being observed by the debugger.

Back to Execution Debugger Commands

trace¶

trace {<filename>|off}[,<CPU>[,[noloop|logerror][,<action>]]]

Starts or stops tracing for execution of the specified <CPU>, or the currently visible CPU if no CPU is specified. To enable tracing, specify the trace log file name in the <filename> parameter. To disable tracing, use the keyword off for the <filename> parameter. If the <filename> argument begins with two right angle brackets (>>), it is treated as a directive to open the file for appending rather than overwriting.

The optional third parameter is a flags field. The supported flags are noloop and logerror. Multiple flags must be separated by | (pipe) characters. By default, loops are detected and condensed to a single line. If the noloop flag is specified, loops will not be detected and every instruction will be logged as executed. If the logerror flag is specified, error log output will be included in the trace log.

The optional <action> parameter is a debugger command to execute before each trace message is logged. Generally, this will include a tracelog or tracesym command to include additional information in the trace log. Note that you may need to surround the action within braces { } to ensure commas and semicolons within the command are not interpreted in the context of the trace command itself.

Examples:

trace joust.tr: Begin tracing the execution of the currently visible CPU, logging output to the file joust.tr.
trace dribling.tr,maincpu: Begin tracing the execution of the CPU with the absolute tag path :maincpu:, logging output to the file dribling.tr.
trace starswep.tr,,noloop: Begin tracing the execution of the currently visible CPU, logging output to the file starswep.tr, with loop detection disabled.
trace starswep.tr,1,logerror: Begin tracing the execution of the second CPU in the system (zero-based index), logging output along with error log output to the file starswep.tr.
trace starswep.tr,0,logerror|noloop: Begin tracing the execution of the first CPU in the system (zero-based index), logging output along with error log output to the file starswep.tr, with loop detection disabled.
trace >>pigskin.tr: Begin tracing execution of the currently visible CPU, appending log output to the file pigskin.tr.
trace off,0: Turn off tracing for the first CPU in the system (zero-based index).
trace asteroid.tr,,,{tracelog "A=%02X ",a}: Begin tracing the execution of the currently visible CPU, logging output to the file asteroid.tr. Before each line, output A=<aval> to the trace log.

Back to Execution Debugger Commands

traceover¶

traceover {<filename>|off}[,<CPU>[,[noloop|logerror][,<action>]]]

Starts or stops tracing for execution of the specified <CPU>, or the currently visible CPU if no CPU is specified. When a subroutine call is encountered, tracing will skip over the subroutine. The same algorithm is used as is used in the step over command. It will not work properly with recursive functions, or if the return address does not immediately follow the call instruction.

This command accepts the same parameters as the trace command. Please refer to the corresponding section for a detailed description of options and more examples.

Examples:

traceover joust.tr: Begin tracing the execution of the currently visible CPU, logging output to the file joust.tr.
traceover dribling.tr,maincpu: Begin tracing the execution of the CPU with the absolute tag path :maincpu:, logging output to the file dribling.tr.
traceover starswep.tr,,noloop: Begin tracing the execution of the currently visible CPU, logging output to the file starswep.tr, with loop detection disabled.
traceover off,0: Turn off tracing for the first CPU in the system (zero-based index).
traceover asteroid.tr,,,{tracelog "A=%02X ",a}: Begin tracing the execution of the currently visible CPU, logging output to the file asteroid.tr. Before each line, output A=<aval> to the trace log.

Back to Execution Debugger Commands

traceflush¶

traceflush

Flushes all open trace log files to disk.

Example:

traceflush: Flush trace log files.

Back to Execution Debugger Commands