summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/debugger/execution.rst
blob: fd2cc597f260f9e56e3ac179f29fa37ee9e17d9a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
.. _debugger-execution-list:

Execution Debugger Commands
===========================


You can also type **help <command>** for further details on each command in the MAME Debugger interface.

| :ref:`debugger-command-step` -- single steps for <count> instructions (F11)
| :ref:`debugger-command-over` -- single steps over <count> instructions (F10)
| :ref:`debugger-command-out` -- single steps until the current subroutine/exception handler is exited (Shift-F11)
| :ref:`debugger-command-go` -- resumes execution, sets temp breakpoint at <address> (F5)
| :ref:`debugger-command-gint` -- resumes execution, setting temp breakpoint if <irqline> is taken (F7)
| :ref:`debugger-command-gtime` -- resumes execution until the given delay has elapsed
| :ref:`debugger-command-gvblank` -- resumes execution, setting temp breakpoint on the next VBLANK (F8)
| :ref:`debugger-command-next` -- executes until the next CPU switch (F6)
| :ref:`debugger-command-focus` -- focuses debugger only on <cpu>
| :ref:`debugger-command-ignore` -- stops debugging on <cpu>
| :ref:`debugger-command-observe` -- resumes debugging on <cpu>
| :ref:`debugger-command-trace` -- trace the given CPU to a file (defaults to active CPU)
| :ref:`debugger-command-traceover` -- trace the given CPU to a file, but skip subroutines (defaults to active CPU)
| :ref:`debugger-command-traceflush` -- flushes all open trace files.


 .. _debugger-command-step:

step
----

|  **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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-over:

over
----

|  **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.
|
| Note that the step over functionality may not be implemented on 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 :ref:`debugger-execution-list`


 .. _debugger-command-out:

out
---

|  **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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-go:

go
--

|  **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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-gvblank:

gvblank
-------

|  **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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-gint:

gint
----

|  **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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-gtime:

gtime
-----

|  **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.
|
| Example:
|
|  gtime #10000
|
| Resume execution for ten seconds
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-next:

next
----

|  **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-'ignore'd CPU is scheduled.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-focus:

focus
-----

|  **focus <cpu>**
|
| Sets the debugger focus exclusively to the given <cpu>. This is equivalent to specifying 'ignore' on all other CPUs.
|
| Example:
|
|  focus 1
|
| Focus exclusively CPU #1 while ignoring all other CPUs when using the debugger.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-ignore:

ignore
------

|  **ignore [<cpu>[,<cpu>[,...]]]**
|
| Ignores the specified <cpu> 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 <cpu>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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-observe:

observe
-------

|  **observe [<cpu>[,<cpu>[,...]]]**
|
| Re-enables interaction with the specified <cpu> in the debugger. This command undoes the effects of the 'ignore' command. You can specify multiple <cpu>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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-trace:

trace
-----

|  **trace {<filename>|OFF}[,<cpu>[,[noloop|logerror][,<action>]]]**
|
| Starts or stops tracing of the execution of the specified <cpu>. If <cpu> 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>.
|
| <detectloops> should be either true or false.
|
| If 'noloop' is omitted, the trace will have loops detected and condensed to a single line. If 'noloop' is specified, the trace will contain every opcode as it is executed.
|
| If 'logerror' is specified, logerror output will augment the trace. 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 joust.tr
|
| Begin tracing the currently active CPU, logging output to joust.tr.
|
|  trace dribling.tr,0
|
| Begin tracing the execution of CPU #0, logging output to dribling.tr.
|
|  trace starswep.tr,0,noloop
|
| Begin tracing the execution of CPU #0, logging output to starswep.tr, with loop detection disabled.
|
|  trace starswep.tr,0,logerror
|
| Begin tracing the execution of CPU #0, logging output (along with logerror output) to starswep.tr.
|
|  trace starswep.tr,0,logerror|noloop
|
| Begin tracing the execution of CPU #0, logging output (along with logerror output) to starswep.tr, with loop detection disabled.
|
|  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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-traceover:

traceover
---------

|  **traceover {<filename>|OFF}[,<cpu>[,<detectloops>[,<action>]]]**
|
| Starts or stops tracing of the execution of the specified <cpu>.
|
| 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.
|
| <detectloops> should be either true or false. If <detectloops> is *true or omitted*, the trace will have loops detected and condensed to a single line. If it is false, the trace will contain every opcode as it is executed.
| If <cpu> 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 joust.tr
|
| Begin tracing the currently active CPU, logging output to joust.tr.
|
|  traceover dribling.tr,0
|
| Begin tracing the execution of CPU #0, logging output to dribling.tr.
|
|  traceover starswep.tr,0,false
|
| Begin tracing the execution of CPU #0, logging output to starswep.tr, with loop detection disabled.
|
|  traceover off,0
|
| Turn off tracing on CPU #0.
|
|  traceover asteroid.tr,0,true,{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.
|
| Back to :ref:`debugger-execution-list`


 .. _debugger-command-traceflush:

traceflush
----------

|  **traceflush**
|
| Flushes all open trace files.
|
| Back to :ref:`debugger-execution-list`