SCRYDOSBox-XReferenceBreakpointswatch_addAlso in MAME

DOSBox-XBreakpoints

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

On Bricks, the game this repository builds, stopped inside brick_hit as the first brick falls, with bricks.sym loaded.
Ask

Stop the game when the score changes, and show me where it stopped.

Call
watch_add(ref="score", mode="change", fmt="u16")
Reply 5 of 13 fields
{
  "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:

Call
resume(seconds=60)
Reply 5 of 15 fields
{
  "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:

JSON
{
  "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:

JSON
{
  "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:OFF address, or an address reached through a pointer ([base]+0x28, base->field).
mode one of "show", "change", "count", "capture", "freeze", required
show, change, count, capture or freeze, as above.
length integer, default 0
Total bytes; not needed when fmt has a size or the symbol has a type. At most 128 for show and capture, 16 for change and freeze, 1024 for count.
fmt string, default "auto"
How the bytes read: a scalar (u8 to f64), 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 ref is read: symbol, address or pointer forces one; auto lets the server choose.
trigger string, default ""
For capture only: the address whose every write takes a row holding the block at ref.
trigger_type one of "w", "r", default "w"
w takes writes. On a capture, r takes reads of ref itself, with no trigger, length or fmt.

What comes back

state
armed when set in the debugger and able to fire, evaluated for a show watch, pending while 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 change watch can fire when nothing changed.
entries
Every debugger row the watch uses, one per byte, for change and freeze.
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

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 show watch sets nothing: it is a plain read at every stop. A change watch is read at every stop too.
  • A change watch declared while the program runs is pending. The first call that meets the next stop sets it, a reader included, and lists it in applied_on_stop.
  • A watch saved with no record of its session, marked orphan: true, is still read at every stop.
  • A NaN or infinite f32 or f64 reads as the text nan, inf or -inf, which JSON has no number for.
  • A region is memdump's job, which is why lengths are limited.
  • With fmt left at auto, a typed symbol reads as its type, else as the widest unsigned scalar that divides length. Otherwise length is a whole number of fmt values.
  • why gives the reason for a state that sets nothing, and addr is where a count, capture or freeze sits.

On change:

  • Arming reads the CPU mode off the machine: the same SEG:OFF is 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 change watch fires on the paging host, not on the program. It is armed, and caveat says not to trust its firing.
  • In real mode a change watch is trusted.
  • A watch at a raw SEG:OFF keeps the CPU mode of the stop that set it. At a stop of the other mode it reads unarmable with no value.
  • A watch by symbol or through a pointer is resolved at each stop and keeps no mode.
  • command is the debugger command sent, and entry the row as the debugger lists it: BPM 0040:006C lists as BPMEM 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 the types file).
  • 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 change watch moves with its pointer (moved, with from and to) 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.
  • pointer holds where the pointer was read (at, length), its value, and the offset and field added.

On count and capture:

  • The debugger's TAP records 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 count adds up each 32-bit word an access touches, by value and by writer, so total counts a write that straddles two words twice.
  • A capture of writes keeps the block at ref as it stood before the write landed; the write's own value is the row's data.
  • A capture of reads keeps one row per read of ref and 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 start and after symbols_load, where its ref resolves.
  • Something that replaces the page's handler later, such as a video mode change, displaces it: it lists displaced and 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=auto a 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_id is the debugger's number for it, and trigger_addr where trigger resolves.

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 holding or not_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.
  • entries are those rows, offset and value with no segment. addr is where the freeze is.
  • A freeze writes to the machine, so the session reads altered, which means written to.
The contract your client receives
Text
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.
Tools