SCRYMAMEReferenceBreakpointsbreakpoint_atAlso in DOSBox-X

MAMEBreakpoints

breakpoint_at

Set a breakpoint at a symbol or an address, to stop there or to count how often the code runs.

breakpoint_at(ref, by="auto", role="stop", condition="", cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped with a credit in and the example session's symbol file loaded, which names the routine take_credit.
Ask

Stop the game where it takes a credit to start a game.

Call
breakpoint_at(ref="take_credit")
Reply 6 of 12 fields
{
  "summary": "breakpoint_at take_credit: armed at 0x0000d676",
  "status": "ok",
  "role": "stop",
  "addr": "0x0000d676",
  "state": "armed",
  "entry": "3 @ D676"
}

Then press START, held for four frames:

Call
input(port=":IN1", field="1 Player Start", frames=4, seconds=300)
Reply 5 of 40 fields
{
  "summary": "input :IN1 '1 Player Start': still HELD from frame 552, releases at 556",
  "verdict": "OTHER_STOP",
  "cause": "breakpoint take_credit at 0xd676",
  "pc": "0x0000d676",
  "frame": 553
}

The breakpoint is armed at 0xd676. Pressing START ends in OTHER_STOP, a stop the call did not ask for: cause names the breakpoint on take_credit.

The two replies, whole

The first call's:

JSON
{
  "summary": "breakpoint_at take_credit: armed at 0x0000d676",
  "status": "ok",
  "ref": "take_credit",
  "by": "symbol",
  "role": "stop",
  "cpu": ":maincpu",
  "stored": true,
  "while_running": false,
  "addr": "0x0000d676",
  "armed": true,
  "state": "armed",
  "entry": "3 @ D676"
}

The second call's:

JSON
{
  "summary": "input :IN1 '1 Player Start': still HELD from frame 552, releases at 556",
  "status": "ok",
  "verdict": "OTHER_STOP",
  "frame_before": 552,
  "frame_after": 553,
  "emulated_before_s": 9.343506,
  "emulated_after_s": 9.347718,
  "cycles": 5265,
  "polls": 2,
  "lines_ahead": 0,
  "thread_errors": 0,
  "console_reruns": 0,
  "route": "ioport",
  "port": ":IN1",
  "field": "1 Player Start",
  "value": "0x00000001",
  "frames": 4,
  "name": "1 Player Start",
  "player": 0,
  "mask": "0x00000004",
  "defvalue": "0x00000004",
  "port_before": "0x000000cf",
  "frame_set": 552,
  "released": false,
  "active": {
    "available": false,
    "why": "the field is still HELD: the port is read at its release, which the run has not reached"
  },
  "port_held": {
    "available": false,
    "why": "the field is still HELD: the port is read at its release, which the run has not reached"
  },
  "frame_release_planned": 556,
  "note": "the field is still HELD: the run stopped before the release frame, and the script releases it when the machine reaches it",
  "cause": "breakpoint take_credit at 0xd676",
  "stop_seq": 21,
  "pc": "0x0000d676",
  "cpu": ":maincpu",
  "frame": 553,
  "regs": {
    "A": "0xcb",
    "B": "0xff",
    "D": "0xcbff",
    "X": "0x0431",
    "Y": "0x00f1",
    "U": "0xc66d",
    "PC": "0xd676",
    "S": "0x07fc",
    "CC": "0xa8",
    "DP": "0x00"
  },
  "instruction": {"address": "D676", "bytes": "7A042B", "text": "DEC    $042B", "symbol": "take_credit", "delta": 0},
  "following": ["D679: 86 99    LDA    #$99", "D67B: BB 04 2C ADDA   $042C", "D67E: 19       DAA", "D67F: B7 04 2C STA    $042C", "D682: 39       RTS", "D683: 8E 04 31 LDX    #$0431", "... 10 more"],
  "errorlog": "<volatile>",
  "watches": [
    {
      "ref": "credits_bcd",
      "cpu": ":maincpu",
      "state": "armed",
      "reading": {"available": true, "value": 3, "raw_hex": "03"}
    }
  ],
  "omitted": ["addr", "by", "entry", "fmt", "length", "mode"],
  "how": "`declaration_list(kind=\"watch\")` answers each watch whole: its declaration, the debugger's row for it, and a count's or a capture's tables"
}

Arguments

ref string, required
Where to break: a symbol or a 0x address in the code. Never an expression.
by one of "auto", "symbol", "address", default "auto"
How ref is read: symbol or address forces one. Left at auto, a 0x ref is an address and anything else a symbol.
role one of "stop", "control", default "stop"
stop halts the machine there. control never halts: it counts each time the code runs, for run_to to read.
condition string, default ""
For a stop only: a debugger expression that must hold for the stop, such as d0==1. Bare numbers are hex.
cpu string, default ""
The cpu whose code holds the breakpoint. Left empty, the one the debugger is showing.

What comes back

state
armed once the debugger lists it enabled, unresolved while ref names no symbol of this build. The top of the page lists the rest.
entry
The debugger's own row for the breakpoint, once armed.
addr
The address ref resolves to, once it does.
stored
true when the server saved the breakpoint. It is set again at the next start.
already_stored
true when the same breakpoint was saved already, so the call changed nothing.
temp
For a control, the debugger variable that counts its hits, temp0 to temp9.
All 17 reply fields
  • addr (string)
  • already_stored (boolean)
  • armed (boolean)
  • by (string)
  • command_chars (integer)
  • condition (string)
  • condition_typed (string)
  • cpu (string)
  • entry (string)
  • limit_chars (integer)
  • ref (string)
  • role (string)
  • state (string)
  • stored (boolean)
  • temp (string)
  • visible_cpu (string)
  • while_running (boolean)

What it refuses

Why it works this way

A control is for an address you know runs. run_to counts it beside its target, so a target never reached can be told from code that never ran. MAME counts the hits inside the debugger without halting, so a control costs a run nothing.

A condition makes one run out of many: "stop at the vblank handler once this variable reads X" is a single resume. It is saved as typed, like ref, so after a rebuild a symbol in it is compared where it now lives.

The condition is evaluated once before the breakpoint is set, because the debugger accepts a condition it cannot evaluate and that breakpoint never fires. A name that is both a symbol and a register of that cpu is refused as ambiguous.

More on why
  • A breakpoint set while the machine runs fires at once. while_running says the machine was running when the call came.
  • run_to saves its own control as one, so every later run counts it too.
  • A stop no instruction caused (the end of a frame, a time, a step) lands on an instruction whose breakpoints some MAME builds skip. A control there misses that hit.
  • A run by frames lands on one such instruction every frame, often the first of the vblank handler. Put a control somewhere else.
  • condition is the condition as the debugger reads it, your symbols replaced by addresses. condition_typed is what you typed, when the two differ.
  • The condition is evaluated on the breakpoint's own cpu: the server makes it the visible one for that and puts the visible one back, which runs nothing.
  • If the visible cpu cannot be put back, the call is refused before anything is saved and visible_cpu names the cpu left visible (unexpected_answer).
  • At start, a saved condition the debugger cannot evaluate is reported unresolved when it names a symbol this build lacks and unarmable otherwise. It stays saved either way.
  • cpu is the cpu the breakpoint is on. note warns when the debugger is set to ignore that cpu: the breakpoint has no effect until debug("observe <cpu>").
  • Each row is armed naming its cpu, bp <addr>:<cpu>, which never changes the visible cpu, at start's re-arm too. A saved row with no cpu is the first cpu's.
  • A row the debugger already lists there on that cpu, under the same condition and held by no other declaration, is taken over, not doubled, here and at start's re-arm.
  • A row bplist shows without the condition sent is not armed: the call is refused, and start's re-arm lists it unarmable. Watches follow the same rule.
The contract your client receives
Text
Declare an execution breakpoint at `ref`, a place in the code, as a `stop` or a `control`
(never halts; hits counted in a `temp`, 10 at most, read by `run_to`). Stored,
re-armed at `start`.

`ref`: a symbol or linear `0x` address, never an expression. `condition` (a `stop` only):
console grammar, bare numbers hex, no `,`, `;`, braces or assignment. `cpu`: else the
visible one.

Refused: a `seg:off`; a `condition` the console refuses or too long (`command_chars`); an
unknown cpu (`unknown_ref`); an address another declaration holds; one ref under the other
role; a control past the 10 temps.

Reply: `ref`, `stored`, `already_stored`, `armed`, `state`, `temp` (a control), `addr` (once
`ref` resolves), `entry` (once armed).

Reference: REFERENCE.md, Breakpoints and watches.
Tools