SCRYDOSBox-XReferenceBreakpointswatch_addAlso in MAME
watch_add
Keep a variable in view at every stop, stop the machine when it changes, or count every write to it, by name.
watch_add(ref, mode, length=0, fmt="auto", by="auto", trigger="", trigger_type="w")
Try it
brick_hit as the first brick falls, with bricks.sym loaded.Stop the game when the score changes, and show me where it stopped.
watch_add(ref="score", mode="change", fmt="u16"){
"summary": "watch_add score: armed",
"status": "ok",
"state": "armed",
"entry": "BPMEM 08DF:0615",
"entries": ["BPMEM 08DF:0615", "BPMEM 08DF:0616"]
}Then let the game run, for a minute at most:
resume(seconds=60){
"summary": "resume: OTHER_STOP, stopped at 08DF:000002EB",
"verdict": "OTHER_STOP",
"pc": "08DF:000002EB",
"cpu_mode": "real",
"frame": 36
}OTHER_STOP is a stop the call did not target, and its cause cannot name a watch. pc is just past the instruction that wrote the score, and watches in the whole reply holds the new value.
The two replies, whole
The first call's:
{
"summary": "watch_add score: armed",
"status": "ok",
"ref": "score",
"by": "symbol",
"mode": "change",
"fmt": "u16",
"length": 2,
"stored": true,
"armed": true,
"state": "armed",
"entry": "BPMEM 08DF:0615",
"entries": ["BPMEM 08DF:0615", "BPMEM 08DF:0616"],
"command": "BPM 08DF:0615"
}The second call's:
{
"summary": "resume: OTHER_STOP, stopped at 08DF:000002EB",
"status": "ok",
"verdict": "OTHER_STOP",
"omitted": ["output", "output_chars", "clipped"],
"how": "detail=True adds what the debugger printed for this command",
"waited_s": "<volatile>",
"pc": "08DF:000002EB",
"cpu_mode": "real",
"frame": 36,
"regs": {
"EAX": "0x0000003c",
"EBX": "0x00000700",
"ECX": "0x005b001e",
"EDX": "0x00000000",
"ESI": "0x00000007",
"EDI": "0x00001ee1",
"EBP": "0x0000091c",
"ESP": "0x0000fffa",
"EIP": "0x000002eb",
"CS": "0x08df",
"DS": "0x08df",
"ES": "0xa000",
"FS": "0x0000",
"GS": "0x0000",
"SS": "0x08df"
},
"watches": [
{
"ref": "ball_x",
"by": "symbol",
"mode": "show",
"length": 8,
"fmt": "{x:i16,y:i16,dx:i16,dy:i16}",
"state": "evaluated",
"value": {"x": 230, "y": 78, "dx": 2, "dy": -2},
"bytes": "e6004e000200feff"
},
{
"ref": "score",
"by": "symbol",
"mode": "change",
"length": 2,
"fmt": "u16",
"state": "armed",
"value": 60,
"bytes": "3c00"
}
],
"cause": "no declared code breakpoint at 08DF:000002EB, and the debugger does not say which row stopped the machine, so what made this stop cannot be told",
"e9": {"lines_total": 0, "truncated": false, "lines": [], "mark": "<volatile>"},
"stop_seq": 6,
"instruction": {
"address": "08DF:000002EB",
"bytes": "F71E2706",
"text": "neg word ptr [0x627]",
"flow": "sequential",
"code_bits": 16,
"bytes_from": "memory",
"symbol": "brick_hit",
"delta": 35
}
}The five modes
| mode | what it does | stops? |
|---|---|---|
show |
Reads the value at every stop. | no |
change |
Stops when the bytes change. | yes |
count |
Counts every write and which instruction made it. | no |
capture |
Logs a row per access, with the screen line being drawn and the time. | no |
freeze |
Holds the bytes at their value: whatever the program writes is undone. | no |
Arguments
- ref string, required
- What to watch: a symbol, a
SEG:OFFaddress, or an address reached through a pointer ([base]+0x28,base->field). - mode one of
"show","change","count","capture","freeze", required show,change,count,captureorfreeze, as above.- length integer, default
0 - Total bytes; not needed when
fmthas a size or the symbol has a type. At most 128 forshowandcapture, 16 forchangeandfreeze, 1024 forcount. - fmt string, default
"auto" - How the bytes read: a scalar (
u8tof64), an array (u16[8]), a string (char[16]) or a struct ({x:i16,y:i16}). - by one of
"auto","symbol","address","pointer", default"auto" - How
refis read:symbol,addressorpointerforces one;autolets the server choose. - trigger string, default
"" - For
captureonly: the address whose every write takes a row holding the block atref. - trigger_type one of
"w","r", default"w" wtakes writes. On acapture,rtakes reads ofrefitself, with notrigger,lengthorfmt.
What comes back
- state
armedwhen set in the debugger and able to fire,evaluatedfor ashowwatch,pendingwhile the program runs. The top of the page lists the rest.- entry
- The debugger's own row for the watch, once armed.
- stored
- The server saved the watch, and sets it again after
symbols_load. - caveat
- A warning: in protected mode a
changewatch can fire when nothing changed. - entries
- Every debugger row the watch uses, one per byte, for
changeandfreeze. - frozen_hex
- For
freeze: the bytes being held, in hex.
All 21 reply fields
addr(string)already_stored(boolean)armed(boolean)by(string)caveat(string)command(string)entries(array)entry(string)fmt(string)frozen_hex(string)length(integer)mode(string)pointer(object)ref(string)state(string)stored(boolean)tally_id(string)trigger(string)trigger_addr(string)trigger_type(string)why(string)
What it refuses
- One
refdeclared two ways (bad_argument). - A
lengthover the mode's maximum (bad_argument). - A
count,captureorfreezewhile the program runs (not_stopped), or through a pointer. - A
countorcaptureon a DOSBox-X without theTAPdebugger command, or afreezeon one built without heavy debugging (no_channel). - A
freezeon an offset already frozen (ambiguous_ref). triggeron any mode butcapture, and a write capture without one (bad_argument).- A pointer base the symbol table lacks, most likely a stack local (
unknown_ref). - A name that matches several symbols, or a
changewatch on a byte another watch already holds (ambiguous_ref).
Why it works this way
A change watch breaks when memory changes, which is the thing most likely to be misread: a read never fires it, nor does a write storing the value already there. The debugger compares one byte, so a watch arms a row per byte, and that is why its length is capped.
count and capture exist for what a stop cannot give: every value a variable takes over a stretch, and who wrote each, while the program keeps running.
A freeze is the debugger putting each byte back after every instruction, so it holds against the program's own writes. It holds the values of the stop it is declared at, so a saved freeze is never set again by start or symbols_load.
More on why
On every watch:
- A
showwatch sets nothing: it is a plain read at every stop. Achangewatch is read at every stop too. - A
changewatch declared while the program runs ispending. The first call that meets the next stop sets it, a reader included, and lists it inapplied_on_stop. - A watch saved with no record of its session, marked
orphan: true, is still read at every stop. - A NaN or infinite
f32orf64reads as the textnan,infor-inf, which JSON has no number for. - A region is
memdump's job, which is why lengths are limited. - With
fmtleft atauto, a typed symbol reads as its type, else as the widest unsigned scalar that divideslength. Otherwiselengthis a whole number offmtvalues. whygives the reason for a state that sets nothing, andaddris where acount,captureorfreezesits.
On change:
- Arming reads the CPU mode off the machine: the same
SEG:OFFis a different byte in each mode, and the mode changes as the program boots. - The debugger's
BPLM, a watch on a linear address, is not offered. - A DPMI program, a DOS program in protected mode, runs paged, so a memory frame belongs to whoever holds it at that instant.
- For the same reason a protected-mode
changewatch fires on the paging host, not on the program. It is armed, andcaveatsays not to trust its firing. - In real mode a
changewatch is trusted. - A watch at a raw
SEG:OFFkeeps the CPU mode of the stop that set it. At a stop of the other mode it readsunarmablewith no value. - A watch by symbol or through a pointer is resolved at each stop and keeps no mode.
commandis the debugger command sent, andentrythe row as the debugger lists it:BPM 0040:006Clists asBPMEM 0040:006C.- A protected-mode row,
BPPM, lists its offset in eight digits.
Through a pointer:
- The pointer is read as a near pointer in the base's own segment, at the width its type gives (
ptr16{...},ptr32{...}in thetypesfile). - With no such type it is four bytes in protected mode and two in real mode. A class after the width (
ptr16@CODE) is accepted and changes nothing. - A
changewatch moves with its pointer (moved, withfromandto) and with the CPU mode: a row armed in the other mode is armed again in this one. - A null pointer is
null_pointer, never a watch at address zero. pointerholds where the pointer was read (at,length), itsvalue, and theoffsetandfieldadded.
On count and capture:
- The debugger's
TAPrecords every access the program makes to that memory, a write storing the value already there included. The debugger's own reads and writes are not recorded. - A
countadds up each 32-bit word an access touches, by value and by writer, sototalcounts a write that straddles two words twice. - A capture of writes keeps the block at
refas it stood before the write landed; the write's own value is the row'sdata. - A capture of reads keeps one row per read of
refand no block. On code it also sees the instruction fetches of that byte. - It goes in at a stop, because it replaces the handler of a memory page, which the debugger does between instructions.
- It is set again at
startand aftersymbols_load, where itsrefresolves. - Something that replaces the page's handler later, such as a video mode change, displaces it: it lists
displacedand sees nothing more until declared again. - It needs a cpu core that reads memory through the page handlers, so the dynamic core is refused. Under
core=autoa protected-mode program is already on that core when stopped. - One set from real mode cannot cover extended memory. For a DPMI or DJGPP program's variables, start on the normal core:
flags=["-set","cpu core=normal"]. - The high memory area is refused because its alias follows the A20 line. So is a range that paging splits across pages that are not adjacent.
- Each stop with one saved costs one
TAPLIST, which writes its rows and tables to disk. tally_idis the debugger's number for it, andtrigger_addrwheretriggerresolves.
On freeze:
- It does not hold against what is not an instruction the debugger steps: a dynamic core, a DMA transfer. Each stop reads the bytes back and says
holdingornot_held. - The debugger lists a freeze by its offset alone, so a second one at the same offset is refused: the two rows could not be told apart.
entriesare those rows, offset and value with no segment.addris where the freeze is.- A freeze writes to the machine, so the session reads
altered, which means written to.
Related tools
The contract your client receives
Declare a watch by symbol, `SEG:OFF` or through a pointer, read as `fmt`. Persists and
re-resolves on `symbols_load`.
`mode`: `show` (read at each stop), `change` (stops when the bytes change), `count` (tallies
every write and its writer), `capture` (a row per access of `trigger`, with the beam line
and the time), `freeze` (pins the bytes at their value: the guest's writes are undone, and
the session is `altered`);
count, capture and freeze never stop the machine. `ref`: a symbol, `SEG:OFF`, or
`[base]+0x28`, `base->field`. `fmt`: a scalar (`u8` .. `f64`), an array (`u16[8]`), a string
(`char[16]`) or a struct (`{x:i16,y:i16}`). `length`: total bytes; at most 128 for
show, 16 for change and 16 for freeze (a debugger row per byte,
`entries`), 1024 for count, 128 for capture. `trigger`,
`trigger_type`: capture only; a capture of reads (`r`) is of `ref` itself, with no
`trigger`, `length` or `fmt`. A count or capture is declared at a stop, by symbol or
`SEG:OFF`, on a build whose debugger has `TAP`; from then on it records while the guest
runs. A freeze likewise, on a heavy-debug build, pinning the values of that stop; each stop
reads its bytes back (`holding`, or `not_held` when something ran past it), and a stored
freeze is not armed again at `start` or `symbols_load`, where its bytes hold other values.
Refused: one ref declared two ways; a length over the ceiling; a pointer base the table
lacks; a count, capture or freeze through a pointer or on a running machine (`not_stopped`);
a count or capture with no `TAP`, a freeze with no heavy debugger (`no_channel`); a freeze
on an offset already frozen (`ambiguous_ref`); a write capture with no `trigger`; `trigger`
or `trigger_type` on another mode.
Reply: `ref`, `by`, `mode`, `fmt`, `length`, `stored`, `already_stored`, `state` (`evaluated`,
`unresolved`, `unarmable`, `null_pointer`, `pending`, `armed`), `armed`, `pointer` (a pointer
`ref`), `entry` (once armed), `caveat` (protected mode); a count or capture's `tally_id`,
`addr`, `trigger`, `trigger_addr`, `trigger_type`; a freeze's `addr`, `entries`, `frozen_hex`;
its account is `declaration_list`'s.
Reference: REFERENCE.md, Breakpoints and watches.