SCRYMAMEReferenceBreakpointsdeclaration_listAlso in DOSBox-X

MAMEBreakpoints

declaration_list

List the saved breakpoints, registerpoints and watches, each with its state checked against the debugger's own list.

declaration_list(kind="", cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, after the breakpoint, the registerpoint and the watch of the other entries were set, and a run_to left its control.
Ask

Which breakpoints and watches are set right now?

Call
declaration_list()
Reply 3 of 6 fields
{
  "summary": "declaration_list: 2 breakpoints (2 armed), 1 regpoint (1 armed), 1 watch (1 armed)",
  "status": "ok",
  "cpu": {"available": false, "why": "no cpu was named, so the rows are every cpu's"}
}

Two breakpoints, one registerpoint and one watch are saved, and the debugger lists each as armed. No cpu was named, so the rows are every cpu's.

The whole reply
JSON
{
  "summary": "declaration_list: 2 breakpoints (2 armed), 1 regpoint (1 armed), 1 watch (1 armed)",
  "status": "ok",
  "breakpoints": [
    {
      "ref": "wait_frame",
      "by": "symbol",
      "cpu": ":maincpu",
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "role": "control",
      "addr": "0x0000a631",
      "state": "armed",
      "entry": "1 @ A631 if (++temp0)==0",
      "hits_since_armed": 3
    },
    {
      "ref": "take_credit",
      "by": "symbol",
      "cpu": ":maincpu",
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "role": "stop",
      "addr": "0x0000d676",
      "state": "armed",
      "entry": "3 @ D676"
    }
  ],
  "regpoints": [
    {
      "ref": "a==99",
      "by": "expr",
      "cpu": ":maincpu",
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "condition": "a==99",
      "state": "armed",
      "entry": "1 if a==99",
      "index": 1
    }
  ],
  "watches": [
    {
      "ref": "credits_bcd",
      "by": "symbol",
      "cpu": ":maincpu",
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "mode": "change",
      "length": 1,
      "fmt": "u8",
      "addr": "0x0000042c",
      "state": "armed",
      "entry": "1 @ 042C-042C write",
      "values_from": "memory"
    }
  ],
  "cpu": {"available": false, "why": "no cpu was named, so the rows are every cpu's"}
}

Arguments

kind one of "", "breakpoint", "regpoint", "watch", default ""
breakpoint, regpoint or watch. Left empty, every kind.
cpu string, default ""
Narrows the rows to one cpu. Left empty, every cpu's.

What comes back

breakpoints
The saved breakpoints. Each row has ref, role, addr, state and, once armed, the debugger's entry.
regpoints
The saved registerpoints, each with its condition, state, entry and the debugger's index.
watches
The saved watches, each with mode, length, fmt and state. A count or a capture adds its tables.
foreign
Debugger rows the server did not set, by kind, as the debugger lists them. They are listed and never deleted.
cpu
The cpu the rows were narrowed to, or available: false when none was named.
All 5 reply fields
  • breakpoints (array)
  • cpu (string or object)
  • foreign (object)
  • regpoints (array)
  • watches (array)

What it refuses

Why it works this way

It answers while the machine runs, and each state is the machine's own answer: every call reads the debugger's breakpoint, watchpoint and registerpoint lists back.

inherited is true on a row an earlier session saved, since no reply names this session to compare with. age_s counts the seconds since created_at; a date ahead of this computer's clock gives a negative age, never a zero that would read as "now".

More on why

What a row carries:

  • Every row: ref, by (how the ref is read), cpu, created_at, origin (the session that saved it), inherited, age_s, state, and why where the state needs a reason.
  • A breakpoint adds role, addr, entry, its condition (with condition_typed when the debugger reads it differently) and a control's hits_since_armed.
  • A registerpoint adds condition, entry and index.
  • A watch adds mode, length, fmt, addr, reading on a stopped machine, pointer for a ref through one, and a change watch's entry and values_from.
  • A count or a capture adds tally_id, installed, pending, install_resent, call, total, frame_as_of and superseded.
  • A count adds values (each at, raw_hex, count, and value or partial), values_total and overflow_values.
  • It also adds writers (each pc, count, symbol), writers_total, overflow_pcs, and reads when it counts them.
  • A capture adds trigger, trigger_addr, trigger_type, source, rows_path, rows_kept, rows_max, overflow_rows and first_rows.
  • Each of first_rows has n, frame, line, time_s, pc, symbol, data, mask, and a write capture's raw_hex and block.
  • A port watch adds space and stored: false.
  • A reset or a state load under a count adds across (event, frame_from): its totals then span two runs.
  • A callback that raised adds callback_errors (count, first). While the machine runs the reply adds last_stop.

The states of a count or a capture, beside those at the top of the page:

state what it means
tallied, captured Installed, and its tables were read.
no_dump_yet Nothing is on disk yet: MAME writes the tables at a stop.
not_installed This session holds none for it: start did not send it, or it was cleared.
install_failed MAME ran the install and it failed. why has the error.
install_lost MAME's console never ran the install, twice. It recorded nothing: clear it and declare it again.

What the tables say:

  • values and writers add up from the install on. A write that found its table full is counted in overflow_values or overflow_pcs and not named.
  • A capture's total counts every access to its trigger: rows_kept of them have a row, and overflow_rows came after the limit rows_max.
  • The listing shows a capture's first rows only, since each holds a whole block. rows_path is the file with every row.
  • superseded is true when the tables on disk are older than the frame the machine stands at. frame_as_of is the frame they were written at.
  • A stop's reply adds since_last_stop, and reset when the total fell, and never the rows or tables. A listing between two stops uses up nothing.
The contract your client receives
Text
List the declarations of `kind` (empty: every kind) with their state, against the
debugger's own list read back. `cpu` narrows the rows to it. Answers on a running machine.

Reply: `breakpoints`, `regpoints`, `watches` (each kind asked; each row `ref`, `by`,
`cpu`, `created_at`, `origin`, `inherited`, `age_s`, `state`, plus its kind's fields),
`foreign` (debugger rows no declaration placed), `cpu`.

Reference: REFERENCE.md, Breakpoints and watches.
Tools