SCRYDOSBox-XReferenceBreakpointsregpoint_addAlso in MAME
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)
Try it
brick_hit with bricks.sym loaded.Stop as soon as DX holds 3DAh, the VGA status port.
regpoint_add(condition="DX==3DA"){
"summary": "regpoint_add DX==3DA: armed",
"status": "ok",
"ref": "DX==3DA",
"state": "armed",
"entry": "BPIF DX==3DA"
}Then let the game run, for a minute at most:
resume(seconds=60){
"summary": "resume: OTHER_STOP, stopped at 08DF:00000583",
"verdict": "OTHER_STOP",
"cause": "registerpoint DX==3DA, whose condition came true at 08DF:00000583",
"pc": "08DF:00000583"
}The registerpoint is armed as the debugger's BPIF DX==3DA. The game then stops where DX takes that value: cause names the registerpoint and the address.
The two replies, whole
The first call's:
{
"summary": "regpoint_add DX==3DA: armed",
"status": "ok",
"ref": "DX==3DA",
"by": "expr",
"condition": "DX==3DA",
"stored": true,
"while_running": false,
"armed": true,
"state": "armed",
"entry": "BPIF DX==3DA"
}The second call's:
{
"summary": "resume: OTHER_STOP, stopped at 08DF:00000583",
"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:00000583",
"cpu_mode": "real",
"frame": 36,
"regs": {
"EAX": "0x0000000f",
"EBX": "0x0000000f",
"ECX": "0x005b0004",
"EDX": "0x000003da",
"ESI": "0x00000615",
"EDI": "0x00006266",
"EBP": "0x0000091c",
"ESP": "0x0000fffc",
"EIP": "0x00000583",
"CS": "0x08df",
"DS": "0x08df",
"ES": "0xa000",
"FS": "0x0000",
"GS": "0x0000",
"SS": "0x08df"
},
"watches": [
{
"ref": "ball_x",
"by": "symbol",
"mode": "show",
"length": 8,
"fmt": "{x:i16,y:i16,dx:i16,dy:i16}",
"state": "evaluated",
"value": {"x": 230, "y": 78, "dx": 2, "dy": 2},
"bytes": "e6004e0002000200"
}
],
"cause": "registerpoint DX==3DA, whose condition came true at 08DF:00000583",
"regpoint_hit": {
"ref": "DX==3DA",
"condition": "DX==3DA",
"pc": "08DF:00000583",
"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"
},
"e9": {"lines_total": 1, "truncated": false, "lines": ["Bochs port E9h: HIT 0 7"], "mark": "<volatile>"},
"stop_seq": 7,
"instruction": {
"address": "08DF:00000583",
"bytes": "EC",
"text": "in al, dx",
"flow": "sequential",
"code_bits": 16,
"bytes_from": "memory",
"symbol": "retrace",
"delta": 3
}
}Arguments
- condition string, required
- Up to four terms joined by
&&. Each is a register (AX,EAX,AL,CS,FLAGS), a comparison and a hex value:AX==3B.
What comes back
- state
armedwhen set,pendingwhile the program runs. The top of the page lists the rest.- ref
- The condition as the debugger prints it back.
declaration_cleartakes it. - entry
- The debugger's own row for the registerpoint, once armed.
- already_stored
truewhen the same registerpoint was saved already, so the call changed nothing.- while_running
truewhen the program was running as the call arrived.
All 9 reply fields
already_stored(boolean)armed(boolean)by(string)condition(string)entry(string)ref(string)state(string)stored(boolean)while_running(boolean)
What it refuses
- A term that is not a register, a comparison and a hex value (
bad_argument). - A DOSBox-X whose debugger has no
BPIFcommand (no_channel).
Why it works this way
The debugger compiles the terms once and checks them before every instruction. It fires as the condition comes true: one set while it already holds waits until it no longer does, and a resumed machine does not stop again at once.
When the debugger's RUNSTATE command names the row that fired, the stop is credited to that registerpoint. Otherwise the stop's attribution.regpoints_holding lists the registerpoints whose condition holds, as the likely cause.
A registerpoint has no address, so it is never stale and has no role. It compares and never assigns.
More on why
- The comparisons are
==,!=,<,<=,>and>=, and the value may carry0x. byis alwaysexpr, andconditionrepeatsref.armedistrueonce the debugger holds the row.
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`; pending while
the guest runs. Needs the debugger's `BPIF`.
`condition`: up to four terms joined by `&&`, each a register (`AX`, `EAX`, `AL`, `CS`, ...,
`FLAGS`), a comparison (`==`, `!=`, `<`, `<=`, `>`, `>=`) and a hex value (`AX==3B`,
`0x` allowed); compares, never assigns.
Refused: a term not in that shape (`bad_argument`); a build without `BPIF` (`no_channel`).
Reply: `ref` (the condition as the debugger prints it back, what `declaration_clear` takes),
`stored`, `already_stored`, `armed`, `state`, `while_running`, `entry` (once armed),
`note`.
Reference: REFERENCE.md, Breakpoints and watches.