SCRYMAMEReferenceRuntraceAlso in DOSBox-X
trace
Run for a number of frames or milliseconds and get every address one cpu executed, grouped by symbol.
trace(milliseconds=0, frames=0, dest="", seconds=60.0, cpu="", noloop=false)
Try it
Trace the next two frames and tell me which routines the game runs.
trace(frames=2, dest="./tmp/demos/tour/trace.txt", seconds=300){
"summary": "trace :maincpu 2 frames: 192 addresses in 4 symbols, 19627 bytes",
"verdict": "ELAPSED",
"frame_before": 628,
"frame_after": 630,
"cycles": 42239
}In two frames, 628 to 630, the main cpu ran through 192 distinct addresses under 4 symbols, and the log is 19627 bytes. trace, in the whole reply, lists each symbol.
The whole reply
{
"summary": "trace :maincpu 2 frames: 192 addresses in 4 symbols, 19627 bytes",
"status": "ok",
"verdict": "ELAPSED",
"frame_before": 628,
"frame_after": 630,
"emulated_before_s": 10.627602,
"emulated_after_s": 10.661393,
"cycles": 42239,
"polls": 2,
"cause": "the `gvblank` stop of the last frame asked",
"stop_seq": 59,
"pc": "0x0000fd80",
"cpu": ":maincpu",
"frame": 630,
"regs": {
"A": "0x00",
"B": "0xd8",
"D": "0x00d8",
"X": "0x0014",
"Y": "0xf2e6",
"U": "0x4071",
"PC": "0xfd80",
"S": "0x07f4",
"CC": "0xd4",
"DP": "0x00"
},
"instruction": {"address": "FD80", "bytes": "0CB2", "text": "INC <$B2", "symbol": "irq", "delta": 0},
"following": ["FD82: 96 B2 LDA <$B2", "FD84: 84 03 ANDA #$03", "FD86: 26 04 BNE $FD8C", "FD88: 0C B3 INC <$B3", "FD8A: 0C B4 INC <$B4", "FD8C: B6 03 BE LDA $03BE", "... 9 more"],
"errorlog": "<volatile>",
"trace": {
"cpu": ":maincpu",
"path": "./tmp/demos/tour/trace.txt",
"bytes": 19627,
"set_path": "./tmp/demos/tour/trace-txt-set.jsonl",
"instructions": 9398,
"addresses": 192,
"unplaced": 0,
"symbols": [
{
"symbol": "wait_frame",
"addr": "0x0000a631",
"addresses": 26,
"first": "0x0000a631",
"last": "0x0000a79b"
},
{
"symbol": "write_sprites",
"addr": "0x0000a7f6",
"addresses": 25,
"first": "0x0000b52b",
"last": "0x0000b561"
},
{
"symbol": "count_coin",
"addr": "0x0000b583",
"addresses": 36,
"first": "0x0000b58f",
"last": "0x0000cc5b"
},
{
"symbol": "irq",
"addr": "0x0000fd80",
"addresses": 105,
"first": "0x0000fd80",
"last": "0x0000ffa0"
}
],
"symbols_total": 4,
"truncated": false,
"noloop": false,
"note": "the pc :maincpu was parked on, 0x0000fd80, is counted: the window executed it first and the tracer, armed there, does not log it"
}
}Arguments
- milliseconds integer, default
0 - The window to trace, in milliseconds of emulated time. Give this or
frames, never both. - frames integer, default
0 - The window to trace, in frames. Give this or
milliseconds, never both. - dest string, default
"" - Where MAME writes the trace: an absolute path to a new file. Left empty, a file in the session's temporary folder.
- seconds number (> 0, <= 600.0), default
60.0 - How long to wait for the run to end, in real seconds. Left out, 60.
- cpu string, default
"" - The cpu to trace. Left empty, the visible one.
- noloop boolean, default
false truelogs every instruction, so the counts are exact and the largest window is shorter. Left out, MAME condenses loops and only the list of addresses is exact.
What comes back
- trace
- The result:
pathto MAME's log,set_pathto the list of addresses,instructions,addresses,unplaced(addresses no symbol covers) andsymbols. - verdict
- How the run ended, as in
run_for:ELAPSED, the window ran out as asked;TIMEOUT, the wait gave up;OTHER_STOP, a breakpoint or a watch stopped it first. - frame_after
- The frame counter after the run, with
frame_before, the clock andcyclesasrun_forreturns them.
All 18 reply fields
emulated_after_s(number or object)emulated_before_s(number or object)cpu(string or object)cycles(integer)following(array of string)instruction(StopInstruction)errorlog(object)frame(integer)frame_after(integer)frame_before(integer)path(string)pc(string or object)polls(integer)regs(object)stop_seq(integer)trace(object)verdict(string)watches(array)
What it refuses
- A
destthat exists already, or whose list file<name>-<extension>-set.jsonldoes (bad_argument). - A cpu with no disassembler, since the tracer disassembles every line it writes (
no_channel). - A trace with no instruction line: the cpu executed nothing or the tracer recorded nothing, and the two look alike (
readback_refused). - A tracer that could not be shown closed, with
trace.closed: false(readback_refused). - A file MAME could not open (
host_failed).
Why it works this way
The tracer is armed and closed inside one call, because one left armed keeps writing on the next run of a client that forgot it. Arming replaces a trace typed through debug on that cpu. The limits on the window keep one call's output small; a longer window is consecutive calls.
MAME's tracer logs an address when the cpu reaches it, before executing it. So the address a stopped cpu is waiting at is missing from a trace armed there, and the address the run ends at is logged although never executed. Both are corrected, and note says which applied.
By default the tracer condenses loops: it keeps the last addresses and skips one it has seen twice among them. The list of addresses survives that, because an address is logged before it is skipped. The counts do not, so instructions is exact only under noloop.
More on why
in trace |
what it holds |
|---|---|
path, bytes |
MAME's own log and its size |
set_path |
a file with one JSON line per executed address, ascending: addr, symbol when one covers it, count under noloop |
instructions, addresses, unplaced |
instructions logged, distinct addresses, addresses no symbol covers |
symbols |
the first rows, by address: symbol, addr, addresses, first, last, and instructions under noloop |
symbols_total, truncated |
how many symbols ran, and whether symbols leaves some out |
cpu, noloop, note |
the cpu traced, whether loops were kept whole, and the corrections applied |
closed |
on a refusal: whether the tracer was closed |
The tracer cannot see a cpu the debugger ignores, a cpu waiting on its own, or a stretch that runs with a save or a load pending. MAME calls no instruction hook for them. A cpu that pauses in the middle of an instruction, as MAME's 68000 does, finishes it after the window, unlogged.
When the tracer cannot be shown closed, the way out is stop, then debug("trace off,<cpu>"). If stop fails, close then start, since closing MAME closes the file. A run that ends INVALID carries trace with path, bytes and closed, and no list file.
One address can go missing from a condensed trace: address 0, when it runs among the first instructions, because the tracer's history starts as zeros.
The server never watches a run with no end: trace covers one bounded window. A count across an open-ended run is a job for a tracer you write in Lua and run with lua.
Related tools
The contract your client receives
Run as `run_for` does with MAME's tracer on one cpu, then return the addresses it executed,
joined to symbols. Window: `milliseconds` or `frames` (at most 5026 frames or
98143 ms; `noloop`, 1648 and 32920). `dest`: an absolute
new path. `noloop=True`: exact `count`s, not which addresses ran. Needs a stopped machine.
Reply: `run_for`'s, plus `trace` (`path`, `set_path`, `instructions`, `addresses`,
`unplaced`, `symbols` (first 64)). Refused: `dest` existing,
`no_channel`, `readback_refused`.
Reference: REFERENCE.md, Running and stopping.