SCRYMAMEReferenceBreakpointsregpoint_addAlso in DOSBox-X
regpoint_add
Stop the machine when a condition on the registers comes true, wherever the program is, to find who puts a value in a register.
regpoint_add(condition, cpu="")
Try it
take_credit, the routine that takes a credit when START is pressed.Stop as soon as register A holds 0x99.
regpoint_add(condition="a==99"){
"summary": "regpoint_add a==99: armed, index 1",
"status": "ok",
"ref": "a==99",
"state": "armed",
"entry": "1 if a==99",
"index": 1
}Then run for one frame at most:
run_for(frames=1, seconds=300){
"summary": "run_for 1 frame: OTHER_STOP, frame 553 to 553",
"verdict": "OTHER_STOP",
"cause": "registerpoint 'a==99'",
"pc": "0x0000d67b",
"frame": 553
}A bare number in a condition is hex, so a==99 compares with 0x99. The run ends in OTHER_STOP, a stop it did not ask for, with pc at 0xd67b.
The two replies, whole
The first call's:
{
"summary": "regpoint_add a==99: armed, index 1",
"status": "ok",
"ref": "a==99",
"cpu": ":maincpu",
"by": "expr",
"condition": "a==99",
"stored": true,
"while_running": false,
"armed": true,
"state": "armed",
"entry": "1 if a==99",
"index": 1
}The second call's:
{
"summary": "run_for 1 frame: OTHER_STOP, frame 553 to 553",
"status": "ok",
"verdict": "OTHER_STOP",
"frame_before": 553,
"frame_after": 553,
"emulated_before_s": 9.347726,
"emulated_after_s": 9.347726,
"cycles": 0,
"polls": 1,
"cause": "registerpoint 'a==99'",
"stop_seq": 22,
"pc": "0x0000d67b",
"cpu": ":maincpu",
"frame": 553,
"regs": {
"A": "0x99",
"B": "0xff",
"D": "0x99ff",
"X": "0x0431",
"Y": "0x00f1",
"U": "0xc66d",
"PC": "0xd67b",
"S": "0x07fc",
"CC": "0xa8",
"DP": "0x00"
},
"instruction": {"address": "D67B", "bytes": "BB042C", "text": "ADDA $042C", "symbol": "take_credit", "delta": 5},
"following": ["D67E: 19 DAA", "D67F: B7 04 2C STA $042C", "D682: 39 RTS", "D683: 8E 04 31 LDX #$0431", "D686: C6 5F LDB #$5F", "D688: 6F 85 CLR B,X", "... 10 more"],
"errorlog": "<volatile>",
"regpoint_hit": {
"ref": "a==99",
"condition": "a==99",
"pc": "0x0000d67b",
"note": "still armed: a registerpoint stops at every instruction where its condition holds, so the next advance stops again; `declaration_clear(kind=\"regpoint\")` removes it",
"cpu": ":maincpu",
"index": 1
},
"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
- condition string, required
- The condition, in the debugger's own expression grammar, where a bare number is hex:
d1==0x7fff. It compares and never assigns. - cpu string, default
"" - Only the cpu the debugger is showing, which is also what leaving it empty means. Another cpu is refused, naming
cpu_focus.
What comes back
- state
armedonce the debugger lists it enabled. The top of the page lists the rest.- ref
- The condition as typed.
declaration_cleartakes it. - condition
- The condition as the debugger read it, your symbols replaced by their addresses.
- entry
- The debugger's own row for the registerpoint.
- index
- The debugger's row number for it.
- already_stored
truewhen the same registerpoint was saved already, so the call changed nothing.
All 13 reply fields
already_stored(boolean)armed(boolean)by(string)command_chars(integer)condition(string)cpu(string or object)entry(string)index(integer)limit_chars(integer)ref(string)state(string)stored(boolean)while_running(boolean)
What it refuses
- A condition the debugger cannot evaluate, or one that assigns or holds
,,;or braces (bad_argument). - A condition too long for one console command:
command_charsandlimit_charssay by how much (bad_argument). - A
cputhat is not the one the debugger is showing:cpu_focusfirst (needs_call). - A condition that reads the same as another saved registerpoint's once symbols are replaced (
ambiguous_ref). - A MAME whose debugger has no
rpsetcommand (no_channel). - A registerpoint the debugger took and does not list back: it stays saved as
gone(readback_refused).
Why it works this way
A registerpoint has no address, so it is never stale or aliased and has no role. run_to and run_for answer OTHER_STOP, a stop the run did not ask for, because a registerpoint is never a run's target.
It is evaluated after every instruction, so while the condition stays true it fires again one instruction later. The stop's cause reads registerpoint '<ref>', and regpoint_hit holds the details.
The condition is evaluated once before it is saved, because the debugger accepts a registerpoint it cannot evaluate and that one never fires.
More on why
- It belongs to the cpu the debugger is showing, because MAME's
rpsetnames no cpu. Atstartit is set again only if its cpu is then the visible one. - At
starteach saved condition is evaluated again:unresolvedwhen the debugger answersunknown symbol, otherwiseunarmable. One that fails does not stop the others. - Saving the same condition again takes over the debugger's existing row only on the visible cpu. The same text under another cpu compares other registers and is left
foreign. - It works while the machine runs and does not mark the session
altered, which means written to. rpset {<condition>}typed throughdebugdoes not mark it either, but an action after the condition counts as a write.byis alwaysexpr, andwhile_runningsays the machine was running when the call came.
Related tools
The contract your client receives
Declare a registerpoint: the machine stops when `condition` comes true, wherever in the
program ("who puts this value in this register"). Stored, re-armed at `start`.
`condition`: console grammar, bare numbers hex (`d1==0x7fff`); compares, never assigns.
`cpu`: only the visible one; another is refused naming `cpu_focus`.
Refused: a condition the console refuses (`bad_argument`) or too long (`command_chars`,
`limit_chars`); one equal to another registerpoint's (`ambiguous_ref`); a debugger with no
registerpoints (`no_channel`).
Reply: `ref` (the condition as typed), `stored`, `already_stored`, `armed`, `state`,
`while_running`, `entry`, `cpu`, `note`.
Reference: REFERENCE.md, Breakpoints and watches.