SCRYDOSBox-XReferenceBreakpointsbreakpoint_atAlso in MAME

DOSBox-XBreakpoints

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")

Try it

On Bricks, the game this repository builds, stopped in play with bricks.sym loaded.
Ask

Stop the game the next time a brick is hit.

Call
breakpoint_at(ref="brick_hit")
Reply 5 of 9 fields
{
  "summary": "breakpoint_at brick_hit: armed",
  "status": "ok",
  "role": "stop",
  "state": "armed",
  "entry": "BP 08DF:02C8"
}

Then let the game run, for a minute at most:

Call
resume(seconds=60)
Reply 4 of 15 fields
{
  "summary": "resume: OTHER_STOP, stopped at 08DF:000002C8",
  "verdict": "OTHER_STOP",
  "cause": "breakpoint brick_hit (by symbol) at 08DF:000002C8",
  "pc": "08DF:000002C8"
}

The breakpoint is armed at 08DF:02C8. OTHER_STOP means something other than the call's own target stopped the machine: here, cause names the breakpoint on brick_hit.

The two replies, whole

The first call's:

JSON
{
  "summary": "breakpoint_at brick_hit: armed",
  "status": "ok",
  "ref": "brick_hit",
  "by": "symbol",
  "role": "stop",
  "stored": true,
  "armed": true,
  "state": "armed",
  "entry": "BP 08DF:02C8"
}

The second call's:

JSON
{
  "summary": "resume: OTHER_STOP, stopped at 08DF:000002C8",
  "status": "ok",
  "verdict": "OTHER_STOP",
  "omitted": ["output", "output_chars", "clipped"],
  "how": "detail=True adds what the debugger printed for this command",
  "waited_s": "<volatile>",
  "pc": "08DF:000002C8",
  "cpu_mode": "real",
  "frame": 244,
  "regs": {
    "EAX": "0x00000005",
    "EBX": "0x00000000",
    "ECX": "0x005b0020",
    "EDX": "0x00000000",
    "ESI": "0x00000032",
    "EDI": "0x00006410",
    "EBP": "0x0000091c",
    "ESP": "0x0000fffa",
    "EIP": "0x000002c8",
    "CS": "0x08df",
    "DS": "0x08df",
    "ES": "0xa000",
    "FS": "0x0000",
    "GS": "0x0000",
    "SS": "0x08df"
  },
  "watches": [],
  "cause": "breakpoint brick_hit (by symbol) at 08DF:000002C8",
  "e9": {"lines_total": 0, "truncated": false, "lines": [], "mark": "<volatile>"},
  "stop_seq": 10,
  "instruction": {
    "address": "08DF:000002C8",
    "bytes": "88DF",
    "text": "mov bh, bl",
    "flow": "sequential",
    "code_bits": 16,
    "bytes_from": "memory",
    "comment": "AL = row, BL = column of the brick that falls",
    "symbol": "brick_hit",
    "delta": 0
  }
}

Arguments

ref string, required
Where to break: a symbol or a SEG:OFF address in the code.
by one of "auto", "symbol", "address", default "auto"
How ref is read: symbol or address forces one. Left at auto, a ref with a colon is an address and anything else a symbol.
role one of "stop", "control", default "stop"
stop halts the machine there. control never halts a run: every run_to counts how often the code runs.

What comes back

state
armed when set, counted for a control, pending while the program runs. The top of the page lists the rest.
entry
The debugger's own row for the breakpoint, once armed.
stored
true when the server saved the breakpoint. It is set again at start and after symbols_load.
already_stored
true when the same breakpoint was saved already, so the call changed nothing.
why
The reason, when state is unarmable.
marked
true when the symbol carries the linker's mark. Whether a breakpoint there fires is an open question, and note says so.
All 10 reply fields
  • already_stored (boolean)
  • armed (boolean)
  • by (string)
  • entry (string)
  • marked (boolean)
  • ref (string)
  • role (string)
  • state (string)
  • stored (boolean)
  • why (string)

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.

A DOSBox-X breakpoint always halts, so the debugger holds a control only while a run_to counts it: each hit stops the machine, is counted and let go. Between runs nothing is set, so resume, run_for and a wait never stop there.

A symbol missing from the loaded symbol table is saved unresolved, not refused: the compiler may have inlined it this time. A raw SEG:OFF belongs to the build it was declared over and goes stale over another.

More on why
  • A breakpoint at a ROM address is accepted and never fires, while the same command at a RAM address does. Nothing detects it in advance.
  • When a run_to does not reach such a target, its note names this cause.
  • On a dynamic cpu core, or core=auto once protected-mode code runs, execution can pass over a breakpoint inside a compiled block. note says so.
  • A raw SEG:OFF declared before any symbol table was loaded is set again at start. One declared over a map is set again after a symbols_load of the same map.
  • run_to's own control counts for that run alone: saved as one, it would stop the machine once per hit on every later run.
  • An on_breakpoint wait on a control is refused.
  • Setting needs the machine stopped, and the row is read back from the debugger's list.
  • A pending one is set by the first call that meets the next stop, a reader such as registers included. That call's reply lists it in applied_on_stop.
  • by says how the ref was read and role which role it has. armed is true once the debugger holds the row.
The contract your client receives
Text
Declare a code breakpoint at a symbol or `SEG:OFF`, as a `stop` (armed if it can be) or a
`control` (never halts; armed only while a `run_to` counts its hits). Stored, and re-armed on
`symbols_load`; a raw `SEG:OFF` goes `stale` over another build. `by`: `auto` (this server's
choice), `symbol` or `address`, which is how the ref is read.

Refused: a name matching several symbols; an address another declaration holds, naming it; one
ref under the other role. On a dynamic cpu core, or `auto` (protected-mode code runs dynamic),
which can pass over it inside a compiled block, `note` says so. A symbol absent from this
build is stored `unresolved`.

Reply: `ref`, `role`, `stored`, `already_stored`, `armed`, `entry` (once armed), `state`
(`armed`, `counted` for a control, `unresolved`, `unarmable`, `pending` while the guest runs),
`why`, `marked` and `note` for a linker-marked symbol.

Reference: REFERENCE.md, Breakpoints and watches.
Tools