SCRYDOSBox-XReferenceBreakpointsregpoint_addAlso in MAME

DOSBox-XBreakpoints

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

On Bricks, the game this repository builds, stopped inside brick_hit with bricks.sym loaded.
Ask

Stop as soon as DX holds 3DAh, the VGA status port.

Call
regpoint_add(condition="DX==3DA")
Reply 5 of 10 fields
{
  "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:

Call
resume(seconds=60)
Reply 4 of 16 fields
{
  "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:

JSON
{
  "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:

JSON
{
  "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
armed when set, pending while the program runs. The top of the page lists the rest.
ref
The condition as the debugger prints it back. declaration_clear takes it.
entry
The debugger's own row for the registerpoint, once armed.
already_stored
true when the same registerpoint was saved already, so the call changed nothing.
while_running
true when 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

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 carry 0x.
  • by is always expr, and condition repeats ref. armed is true once the debugger holds the row.
The contract your client receives
Text
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.
Tools