SCRYDOSBox-XReferenceRuntraceAlso in MAME

DOSBox-XRun

trace

Run a number of instructions with the debugger's CPU log on and get every address executed, grouped by symbol.

trace(instructions, shape="normal", dest="", seconds=60.0)

Try it

On Bricks, the game this repository builds, stopped inside brick_hit. It needs a DOSBox-X built with heavy debugging, started on the normal cpu core.
Ask

Trace the next 40 instructions and tell me which routines they run through.

Call
trace(instructions=40)
Reply 4 of 13 fields
{
  "summary": "trace 40 normal: ELAPSED, 40 executed at 34 addresses, at 08 ... (121 characters)",
  "verdict": "ELAPSED",
  "pc": "08DF:00000221",
  "frame": 36
}

All 40 instructions ran, which is what ELAPSED says, at 34 distinct addresses. trace, in the whole reply, lists the routines they ran through.

The whole reply
JSON
{
  "summary": "trace 40 normal: ELAPSED, 40 executed at 34 addresses, at 08DF:00000221, to ./tmp/demos/tour/files/captures/trace-1.trace",
  "status": "ok",
  "pc": "08DF:00000221",
  "cpu_mode": "real",
  "frame": 36,
  "regs": {
    "EAX": "0x00000000",
    "EBX": "0x00000700",
    "ECX": "0x005b0002",
    "EDX": "0x00000008",
    "ESI": "0x00000007",
    "EDI": "0x00001efd",
    "EBP": "0x0000091c",
    "ESP": "0x0000fff0",
    "EIP": "0x00000221",
    "CS": "0x08df",
    "DS": "0x08df",
    "ES": "0xa000",
    "FS": "0x0000",
    "GS": "0x0000",
    "SS": "0x08df"
  },
  "watches": [
    {
      "ref": "ball_x",
      "by": "symbol",
      "mode": "show",
      "length": 8,
      "fmt": "{x:i16,y:i16,dx:i16,dy:i16}",
      "state": "evaluated",
      "value": {"x": 230, "y": 78, "dx": 2, "dy": -2},
      "bytes": "e6004e000200feff"
    }
  ],
  "cause": "the end of the trace's count, at 08DF:00000221",
  "e9": {"lines_total": 0, "truncated": false, "lines": [], "mark": "<volatile>"},
  "stop_seq": 5,
  "instruction": {
    "address": "08DF:00000221",
    "bytes": "F3AA",
    "text": "rep stosb byte ptr es:[di], al",
    "flow": "sequential",
    "code_bits": 16,
    "bytes_from": "memory",
    "symbol": "fill_rect",
    "delta": 3
  },
  "verdict": "ELAPSED",
  "trace": {
    "path": "./tmp/demos/tour/files/captures/trace-1.trace",
    "bytes": 10209,
    "shape": "normal",
    "instructions": 40,
    "addresses": 34,
    "unplaced": 0,
    "set_path": "./tmp/demos/tour/files/captures/trace-1-trace-set.jsonl",
    "symbols": [
      {
        "symbol": "brick_index",
        "addr": "0x00008fde",
        "addresses": 6,
        "instructions": 6,
        "first": "0x00008fde",
        "last": "0x00008fe8"
      },
      {
        "symbol": "brick_rect",
        "addr": "0x00008fe9",
        "addresses": 18,
        "instructions": 18,
        "first": "0x00008fe9",
        "last": "0x0000900c"
      },
      {
        "symbol": "fill_rect",
        "addr": "0x0000900e",
        "addresses": 4,
        "instructions": 10,
        "first": "0x0000900e",
        "last": "0x00009011"
      },
      {
        "symbol": "brick_hit",
        "addr": "0x000090b8",
        "addresses": 6,
        "instructions": 6,
        "first": "0x000090bc",
        "last": "0x000090cb"
      }
    ],
    "symbols_total": 4,
    "truncated": false
  }
}

The four shapes

shape the debugger command it uses
normal LOG
short LOGS
long LOGL, whose lines say their own cpu mode.
cs_ip LOGC

Arguments

instructions integer (>= 1, <= 3000000), required
How many instructions to run and log.
shape one of "normal", "short", "long", "cs_ip", default "normal"
Which of the debugger's log formats to write, as above. Left out, normal.
dest string, default ""
Where the log ends up: an absolute or ~ path to a new file in a folder that exists. Left empty, the next trace-<n>.trace among the captures.
seconds number (> 0, <= 600.0), default 60.0
How long to wait for the log to finish, in real seconds. Left out, 60.

What comes back

verdict
ELAPSED, every instruction ran; OTHER_STOP, a breakpoint or a pending retrace stopped it first; TIMEOUT, the wait gave up and the run was interrupted where it stood.
trace
The result: path to the log, set_path to the list of addresses, instructions executed, distinct addresses, unplaced (addresses no symbol covers) and symbols.
All 12 reply fields
  • cause (string)
  • regpoint_hit (object)
  • cpu_mode (string or object)
  • e9 (object)
  • frame (integer or object)
  • instruction (DosboxInstruction)
  • pc (string)
  • regs (object)
  • stop_seq (integer)
  • trace (object)
  • verdict (string)
  • watches (array)

What it refuses

Why it works this way

The debugger's log ends with the instruction it stops at, logged and not executed, so a complete file holds one line more than instructions. A trace runs forward only. The debugger writes its history of what ran before a stop only when the emulator exits, so that question is a trace from an earlier stop.

A trace checks its own count. A line is one executed instruction only on the normal cpu core, so the cycle count RUNSTATE gives must have moved by the lines the file holds. That is why any other core is refused.

The debugger writes its log only in the emulator's working directory, so the file passes through there on its way to dest.

More on why
in trace what it holds
path, bytes, shape the log, its size and its format
set_path a file with one JSON line per executed address: seg_off, addr and symbol with delta where they can be worked out, count. Unavailable when it could not be written, which note says
instructions, addresses, unplaced instructions executed, distinct addresses, addresses no symbol covers
symbols the first rows, by address: symbol, addr, addresses, instructions, first, last
symbols_total, truncated how many symbols ran, and whether symbols leaves some out
closed on a refusal: whether the log was closed

An interrupt breakpoint stops inside its INT, after the counter took it and before it ran, so a run it stops may count one more than it executed. The log writes each line before breakpoints are checked, so a trace started on a breakpoint's address stops there again with nothing executed.

The machine can close the log itself: the BIOS's power-on self test does, so a trace started right after a reset meets it. How each address gets its symbol is in REFERENCE.md.

How a logged address becomes a linear one, and so gets its symbol:

  • In real or virtual-8086 mode it is CS times 16 plus EIP. Otherwise it is the base of the selector in CS plus EIP.
  • That selector counts only as a present code descriptor whose privilege is the one it requests, read from one GDT and LDT listing at the stop.
  • A trace that starts and stops in real mode is read the real-mode way, even where it passed through protected mode.
  • An address with no linear form gets no symbol, and counts in unplaced.
The contract your client receives
Text
Run `instructions` (1 to 3000000) with the debugger's CPU log on and come back
STOPPED with the log in a file, joined to symbols.

`shape`: `normal` (`LOG`), `short` (`LOGS`), `long` (`LOGL`) or `cs_ip` (`LOGC`). `dest`:
absolute or `~`-led, its directory there, the file not; empty is the next `trace-<n>.trace` in
captures. `seconds` bounds the wait for the log. Needs a stopped machine, a writable working
directory and `build_check`'s
`heavy_debug`; a dynamic core needs `start(flags=["-set", "cpu core=normal"])`.

Reply: `verdict`, the stop reply of `run_to`, `trace` (`path`, `instructions`, `addresses`,
`unplaced`, `set_path`, `symbols` (first 64)). Refused: `no_channel`,
`readback_refused`, `host_failed`.

Reference: REFERENCE.md, Running and stopping.
Tools