SCRYMAMEReferenceBreakpointsbreakpoint_atAlso in DOSBox-X
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
take_credit.Stop the game where it takes a credit to start a game.
breakpoint_at(ref="take_credit"){
"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:
input(port=":IN1", field="1 Player Start", frames=4, seconds=300){
"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:
{
"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:
{
"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
0xaddress in the code. Never an expression. - by one of
"auto","symbol","address", default"auto" - How
refis read:symboloraddressforces one. Left atauto, a0xref is an address and anything else a symbol. - role one of
"stop","control", default"stop" stophalts the machine there.controlnever halts: it counts each time the code runs, forrun_toto read.- condition string, default
"" - For a
stoponly: a debugger expression that must hold for the stop, such asd0==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
armedonce the debugger lists it enabled,unresolvedwhilerefnames 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
refresolves to, once it does. - stored
truewhen the server saved the breakpoint. It is set again at the nextstart.- already_stored
truewhen the same breakpoint was saved already, so the call changed nothing.- temp
- For a
control, the debugger variable that counts its hits,temp0totemp9.
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
- A
refwith a segment (seg:off): an address here is one0xnumber (bad_argument). - A
conditionthe debugger cannot evaluate, or one that holds,,;, braces or an assignment (bad_argument). - A
conditiontoo long for one console command:command_charsandlimit_charssay by how much (bad_argument). - A
conditionon acontrol, which counts every hit (bad_argument). - A cpu the machine does not have (
unknown_ref). - An address another saved breakpoint already holds, or the same
refunder the other role or another condition (ambiguous_ref). - An eleventh
control: the debugger has ten variables to count with (bad_argument). - A breakpoint the debugger took and does not list back: nothing is armed, and it stays saved as
gone(readback_refused).
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_runningsays the machine was running when the call came. run_tosaves its owncontrolas 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
controlthere 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.
conditionis the condition as the debugger reads it, your symbols replaced by addresses.condition_typedis 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_cpunames the cpu left visible (unexpected_answer). - At
start, a saved condition the debugger cannot evaluate is reportedunresolvedwhen it names a symbol this build lacks andunarmableotherwise. It stays saved either way. cpuis the cpu the breakpoint is on.notewarns when the debugger is set to ignore that cpu: the breakpoint has no effect untildebug("observe <cpu>").- Each row is armed naming its cpu,
bp <addr>:<cpu>, which never changes the visible cpu, atstart'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
bplistshows without the condition sent is not armed: the call is refused, andstart's re-arm lists itunarmable. Watches follow the same rule.
Related tools
The contract your client receives
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.