SCRYDOSBox-XReferenceBreakpointsdeclaration_listAlso in MAME
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
Which breakpoints and watches are set right now?
declaration_list(){
"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
{
"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,regpointorwatch. Left empty, every kind.
What comes back
- breakpoints
- The saved breakpoints, interrupt breakpoints included. Each row has
ref,role,stateand, once armed, the debugger'sentry. - regpoints
- The saved registerpoints, each with its
condition,stateandentry. - watches
- The saved watches, each with
mode,length,fmtandstate. Acountor acaptureadds 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
falsewhile the program runs: the states are then the last stop's, whichlast_stopdates.
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, andwhywhere the state needs a reason. cpuis always an object withavailableset tofalseand awhy: a DOS machine has one cpu.- A breakpoint adds
role,entryandmarked. A row with no session recorded addsorphan: true. - A registerpoint adds
conditionandentry. - A watch adds
mode,length,fmt,pointerfor a ref through one, and achangewatch'sentry. - A
countor acaptureaddstally_id,addr,trigger,trigger_addr,trigger_type,installedandtotal. - A
countaddsvalues(eachat,raw_hex,count, andvalueorpartial),values_totalandoverflow_values. - It also adds
writers(eachpc,count,symbol),writers_totalandoverflow_pcs. - A
captureaddsrows_path,rows_kept,rows_max,overflow_rowsandfirst_rows. - Each of
first_rowshasn,frame,line,time_s,pc,symbol,data,mask, and a write capture'sraw_hexandblock. - A
freezeaddsaddr,entries,frozen_hexandbytes, 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
valueis given when one access covered the range whole; otherwise the row ispartial. dataandmaskare 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.pcis the instruction that made the access, withsymbolwhen a symbol table names it.time_sis the emulated clock,linethe screen line being drawn andframethe display's frame count.lineis unavailable before the display has timed its first frame, andframeon a DOSBox-X whoseTAPwrites only a row's time and line.- Rows past the limit are counted in
overflow_rows, values and writers past theirs inoverflow_valuesandoverflow_pcs, so a table that was cut says so. - A stop's reply adds
since_last_stop, andresetwhen the total fell, and never the rows or tables. A listing between two stops uses up nothing.
Related tools
The contract your client receives
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.