SCRYMAMEReferenceBreakpointsdeclaration_clearAlso in DOSBox-X

MAMEBreakpoints

declaration_clear

Remove saved breakpoints, registerpoints or watches: one by its ref, or every one of a kind.

declaration_clear(kind, ref="", cpu="", all=false, space="program")

Try it

On Gridlee, a free ROM from mamedev.org, with two breakpoints saved: one on take_credit, and the control an earlier run_to left on wait_frame.
Ask

Remove every breakpoint.

Call
declaration_clear(kind="breakpoint", all=true)
Reply 5 of 5 fields
{
  "summary": "declaration_clear breakpoint all: 2 cleared, 2 disarmed",
  "status": "ok",
  "declarations_cleared": 2,
  "disarmed": ["1 @ A631 if (++temp0)==0", "3 @ D676"],
  "while_running": false
}

Both saved breakpoints are gone, and disarmed shows the two debugger rows removed. The first was the control: its condition counts in temp0 and never comes true.

The whole reply
JSON
{
  "summary": "declaration_clear breakpoint all: 2 cleared, 2 disarmed",
  "status": "ok",
  "declarations_cleared": 2,
  "disarmed": ["1 @ A631 if (++temp0)==0", "3 @ D676"],
  "while_running": false
}

Arguments

kind one of "breakpoint", "regpoint", "watch", required
breakpoint, regpoint or watch: what to clear.
ref string, default ""
The one to clear, as the reply that saved it gave its ref. Left empty with all=True.
cpu string, default ""
Clear on this cpu only. Left empty, on every cpu.
all boolean, default false
true clears every one of kind, and takes no ref.
space one of "program", "io", default "program"
io when ref is a port watch. Only watch takes it.

What comes back

declarations_cleared
How many were removed from the saved breakpoints file.
disarmed
The debugger rows removed, as the debugger listed them, checked by reading its list back.
tallies_removed
The count and capture watches whose removal was sent to MAME, each with tally_id, removal, lines_ahead and call.
while_running
true when the machine was running as the call arrived. The clear works either way.
All 4 reply fields
  • declarations_cleared (integer)
  • disarmed (array)
  • tallies_removed (array)
  • while_running (boolean)

What it refuses

Why it works this way

It removes only what this server set: a foreign row, one typed through debug, is never deleted.

A ref is read once, so a clear reaches only its own kind, and a name is never taken for the address its letters spell. An address matches in any spelling; a symbol must be the one saved.

With no cpu it reaches that ref on every cpu. In a file several sessions use, all=True also clears rows another session saved, which read inherited: true: clear by ref when they are not yours.

More on why
  • Removing a count or a capture is sent to MAME's console and applied when it next reads a line.
  • It is never sent twice: the id is the range, and a second send could remove a watch declared since.
  • A removal MAME did not carry out shows on every reply under session.tallies_not_removed.
  • If the debugger still lists a row after its removal, note says so and names the debug command that removes it.
  • all=True on watch removes the port watches too.
  • A registerpoint's condition or an expr watch matches as typed but for its numbers, read as the console reads them: 7fff, 0x7fff, $7fff and #32767 are one.
  • There a run of letters such as ab stays a name and keeps its case. A saved address written in bare hex is that address.
  • With a state_dir, all=True reaches only the rows saved in that folder. Without one, it reaches every session's rows of the same system and symbol file.
  • Declaring the range again installs over a count not removed, keeping its totals, and a clear then removes it. Its tallies_not_removed row stays: this session counted past a removal.
The contract your client receives
Text
Clear the declarations of `kind` that `ref` names (as its declaring reply gave it), or
every one with `all=True` and no `ref`, on `cpu` or every cpu. Disarms what this server
armed; a foreign row is never deleted. `space="io"` clears a watch's io tap. Works on a
running machine.

Refused: an empty `ref` without `all`; a `ref` matching none (`unknown_ref`, naming the
refs held); `space` for a kind other than `watch`.

Reply: `declarations_cleared`, `disarmed`, `while_running`, `tallies_removed` (removing an io
tap), `note`.

Reference: REFERENCE.md, Breakpoints and watches.
Tools