SCRYDOSBox-XReferenceBreakpointsdeclaration_listAlso in MAME

DOSBox-XBreakpoints

declaration_list

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

declaration_list(kind="")

Try it

On Bricks, the game this repository builds, stopped after a recording, with three watches saved: one shown at every stop, one counting writes, one capturing reads.
Ask

Which breakpoints and watches are set right now?

Call
declaration_list()
Reply 5 of 6 fields
{
  "summary": "declaration_list: 0 breakpoints declared, 0 regpoints declared, 3 watches declared",
  "status": "ok",
  "breakpoints": [],
  "regpoints": [],
  "debugger_read": true
}

Three watches are saved, and no breakpoint or registerpoint. debugger_read is true: the states come from the debugger's own list, read at this stop.

The whole reply
JSON
{
  "summary": "declaration_list: 0 breakpoints declared, 0 regpoints declared, 3 watches declared",
  "status": "ok",
  "breakpoints": [],
  "regpoints": [],
  "watches": [
    {
      "ref": "ball_x",
      "by": "symbol",
      "cpu": {"available": false, "why": "a DOS machine has one cpu, and every row acts on it"},
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "mode": "show",
      "length": 8,
      "fmt": "{x:i16,y:i16,dx:i16,dy:i16}",
      "state": "evaluated"
    },
    {
      "ref": "score",
      "by": "symbol",
      "cpu": {"available": false, "why": "a DOS machine has one cpu, and every row acts on it"},
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "mode": "count",
      "length": 2,
      "fmt": "u16",
      "tally_id": "1",
      "addr": "08DF:00000615",
      "installed": true,
      "state": "tallied",
      "total": 1,
      "overflow_values": 0,
      "overflow_pcs": 0,
      "values": [
        {"at": "08DF:00000615", "raw_hex": "4600", "count": 1, "value": 70}
      ],
      "values_total": 1,
      "writers": [
        {"pc": "08DF:000002E7", "count": 1, "symbol": "brick_hit+0x1f"}
      ],
      "writers_total": 1
    },
    {
      "ref": "paddle_x",
      "by": "symbol",
      "cpu": {"available": false, "why": "a DOS machine has one cpu, and every row acts on it"},
      "created_at": "<volatile>",
      "origin": "<volatile>",
      "inherited": false,
      "age_s": "<volatile>",
      "mode": "capture",
      "length": 1,
      "fmt": "u8",
      "tally_id": "2",
      "addr": "08DF:0000061F",
      "trigger_type": "r",
      "installed": true,
      "state": "captured",
      "total": 110,
      "rows_path": "<volatile>",
      "rows_kept": 110,
      "overflow_rows": 0,
      "rows_max": 100000,
      "first_rows": [
        {
          "n": 1,
          "frame": 37,
          "line": 417,
          "time_s": 0.532617,
          "pc": "08DF:000003E4",
          "data": "0xd4000000",
          "mask": "0xff000000",
          "symbol": "draw_paddle+0xe"
        },
        {
          "n": 2,
          "frame": 38,
          "line": 417,
          "time_s": 0.5468845999999999,
          "pc": "08DF:000003E4",
          "data": "0xd6000000",
          "mask": "0xff000000",
          "symbol": "draw_paddle+0xe"
        },
        {
          "n": 3,
          "frame": 39,
          "line": 417,
          "time_s": 0.5611531,
          "pc": "08DF:000003E4",
          "data": "0xd8000000",
          "mask": "0xff000000",
          "symbol": "draw_paddle+0xe"
        },
        {
          "n": 4,
          "frame": 40,
          "line": 417,
          "time_s": 0.5754217,
          "pc": "08DF:000003E4",
          "data": "0xda000000",
          "mask": "0xff000000",
          "symbol": "draw_paddle+0xe"
        },
        {
          "n": 5,
          "frame": 41,
          "line": 417,
          "time_s": 0.589689,
          "pc": "08DF:000003E4",
          "data": "0xdc000000",
          "mask": "0xff000000",
          "symbol": "draw_paddle+0xe"
        },
        {
          "n": 6,
          "frame": 42,
          "line": 417,
          "time_s": 0.6039579,
          "pc": "08DF:000003E4",
          "data": "0xde000000",
          "mask": "0xff000000",
          "symbol": "draw_paddle+0xe"
        },
        "... 18 more"
      ]
    }
  ],
  "debugger_read": true
}

Arguments

kind one of "", "breakpoint", "regpoint", "watch", default ""
breakpoint, regpoint or watch. Left empty, every kind.

What comes back

breakpoints
The saved breakpoints, interrupt breakpoints included. Each row has ref, role, state and, once armed, the debugger's entry.
regpoints
The saved registerpoints, each with its condition, state and entry.
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.
debugger_read
false while the program runs: the states are then the last stop's, which last_stop dates.
All 5 reply fields
  • breakpoints (array)
  • debugger_read (boolean)
  • foreign (object)
  • regpoints (array)
  • watches (array)

Why it works this way

At a stop each state is the debugger's own answer: the call reads its list back. While the program runs the debugger cannot be asked, so the rows carry the last stop's states.

inherited is true on a row an earlier session saved, since no reply names this session to compare with. Nothing expires: a row another session left stays until it is cleared by its ref.

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.
  • cpu is always an object with available set to false and a why: a DOS machine has one cpu.
  • A breakpoint adds role, entry and marked. A row with no session recorded adds orphan: true.
  • A registerpoint adds condition and entry.
  • A watch adds mode, length, fmt, pointer for a ref through one, and a change watch's entry.
  • A count or a capture adds tally_id, addr, trigger, trigger_addr, trigger_type, installed and total.
  • 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 and overflow_pcs.
  • A capture adds 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 freeze adds addr, entries, frozen_hex and bytes, what the memory holds now.

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

state what it means
tallied, captured Installed and recording.
displaced The memory page's handler was replaced since, so it sees nothing more. Declare it again.
unlisted The debugger's list did not show it or could not be read, as while the program runs.
unarmed This session has not set it.
holding, not_held A freeze whose bytes still are, or no longer are, the frozen ones.
unreadable A freeze whose bytes could not be read. why says the reason.

What the tables say:

  • A value's value is given when one access covered the range whole; otherwise the row is partial.
  • data and mask are the 32-bit word that holds the trigger and which of its bytes the access touched. A word written over the trigger and its neighbour shows both.
  • pc is the instruction that made the access, with symbol when a symbol table names it.
  • time_s is the emulated clock, line the screen line being drawn and frame the display's frame count.
  • line is unavailable before the display has timed its first frame, and frame on a DOSBox-X whose TAP writes only a row's time and line.
  • Rows past the limit are counted in overflow_rows, values and writers past theirs in overflow_values and overflow_pcs, so a table that was cut says so.
  • 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, cross-referenced
with the debugger's own list. On a running guest the states are the last stop's survey
(`debugger_read` false).

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 entries no declaration resolves to), `debugger_read`.

Reference: REFERENCE.md, Breakpoints and watches.
Tools