SCRYMAMEReferenceRuntraceAlso in DOSBox-X

MAMERun

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

On Gridlee, a free ROM from mamedev.org, started with the names in gridlee-symbols.yaml and stopped about a second into a new game.
Ask

Trace the next two frames and tell me which routines the game runs.

Call
trace(frames=2, dest="./tmp/demos/tour/trace.txt", seconds=300)
Reply 5 of 19 fields
{
  "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
JSON
{
  "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
true logs 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: path to MAME's log, set_path to the list of addresses, instructions, addresses, unplaced (addresses no symbol covers) and symbols.
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 and cycles as run_for returns 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

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.

The contract your client receives
Text
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.
Tools