SCRYDOSBox-XReferenceBreakpointsbreakpoint_atAlso in MAME
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
bricks.sym loaded.Stop the game the next time a brick is hit.
breakpoint_at(ref="brick_hit"){
"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:
resume(seconds=60){
"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:
{
"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:
{
"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:OFFaddress in the code. - by one of
"auto","symbol","address", default"auto" - How
refis read:symboloraddressforces one. Left atauto, a ref with a colon is an address and anything else a symbol. - role one of
"stop","control", default"stop" stophalts the machine there.controlnever halts a run: everyrun_tocounts how often the code runs.
What comes back
- state
armedwhen set,countedfor acontrol,pendingwhile the program runs. The top of the page lists the rest.- entry
- The debugger's own row for the breakpoint, once armed.
- stored
truewhen the server saved the breakpoint. It is set again atstartand aftersymbols_load.- already_stored
truewhen the same breakpoint was saved already, so the call changed nothing.- why
- The reason, when
stateisunarmable. - marked
truewhen the symbol carries the linker's mark. Whether a breakpoint there fires is an open question, andnotesays 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
- A name that matches several symbols (
ambiguous_ref). - An address another saved breakpoint already holds; the message names it (
ambiguous_ref). - The same
refunder the other role: clear it first (bad_argument). - A
SEG:OFFthat is not hex on both sides of the colon (bad_argument).
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_todoes not reach such a target, its note names this cause. - On a dynamic cpu core, or
core=autoonce protected-mode code runs, execution can pass over a breakpoint inside a compiled block.notesays so. - A raw
SEG:OFFdeclared before any symbol table was loaded is set again atstart. One declared over a map is set again after asymbols_loadof the same map. run_to's owncontrolcounts for that run alone: saved as one, it would stop the machine once per hit on every later run.- An
on_breakpointwait on a control is refused. - Setting needs the machine stopped, and the row is read back from the debugger's list.
- A
pendingone is set by the first call that meets the next stop, a reader such asregistersincluded. That call's reply lists it inapplied_on_stop. bysays how the ref was read androlewhich role it has.armedistrueonce the debugger holds the row.
Related tools
The contract your client receives
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.