SCRYMAMEReferenceBreakpointsregpoint_addAlso in DOSBox-X

MAMEBreakpoints

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

On Gridlee, a free ROM from mamedev.org, stopped at take_credit, the routine that takes a credit when START is pressed.
Ask

Stop as soon as register A holds 0x99.

Call
regpoint_add(condition="a==99")
Reply 6 of 12 fields
{
  "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:

Call
run_for(frames=1, seconds=300)
Reply 5 of 22 fields
{
  "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:

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

JSON
{
  "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
armed once the debugger lists it enabled. The top of the page lists the rest.
ref
The condition as typed. declaration_clear takes 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
true when 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

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 rpset names no cpu. At start it is set again only if its cpu is then the visible one.
  • At start each saved condition is evaluated again: unresolved when the debugger answers unknown symbol, otherwise unarmable. 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 through debug does not mark it either, but an action after the condition counts as a write.
  • by is always expr, and while_running says the machine was running when the call came.
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`.

`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.
Tools