SCRYMAMEReferenceBreakpointswatch_addAlso in DOSBox-X

MAMEBreakpoints

watch_add

Keep a variable in view at every stop, stop the machine when it is written, or count every write to it, by name.

watch_add(ref, mode, length=0, fmt="auto", by="auto", cpu="", condition="", trigger="", space="program", trigger_type="w")

Try it

On Gridlee, a free ROM from mamedev.org, stopped in its coin routine right after a coin was counted, with the example session's symbol file loaded.
Ask

Stop the game when the BCD copy of the credits is written, and tell me which instruction did it.

Call
watch_add(ref="credits_bcd", mode="change")
Reply 6 of 19 fields
{
  "summary": "watch_add credits_bcd: change watch armed at 0x0000042c, 1 byte",
  "status": "ok",
  "reading": {"available": true, "value": 2, "raw_hex": "02"},
  "state": "armed",
  "entry": "1 @ 042C-042C write",
  "values_from": "memory"
}

Then run for one frame at most:

Call
run_for(frames=1, seconds=300)
Reply 5 of 22 fields
{
  "summary": "run_for 1 frame: OTHER_STOP, frame 552 to 552",
  "verdict": "OTHER_STOP",
  "cause": "watch credits_bcd: 0x0000042c written by pc 0x0000b58c",
  "pc": "0x0000b58f",
  "frame": 552
}

OTHER_STOP is a stop the run did not ask for: here, the watch. The writer is at 0xb58c; pc is the instruction after it, since the write has landed.

The two replies, whole

The first call's:

JSON
{
  "summary": "watch_add credits_bcd: change watch armed at 0x0000042c, 1 byte",
  "status": "ok",
  "ref": "credits_bcd",
  "by": "symbol",
  "mode": "change",
  "length": 1,
  "fmt": "u8",
  "cpu": ":maincpu",
  "while_running": false,
  "addr": "0x0000042c",
  "reading": {"available": true, "value": 2, "raw_hex": "02"},
  "stored": true,
  "armed": true,
  "state": "armed",
  "index": 1,
  "entry": "1 @ 042C-042C write",
  "write_maps_to": "memory@0",
  "read_maps_to": "memory@0",
  "values_from": "memory"
}

The second call's:

JSON
{
  "summary": "run_for 1 frame: OTHER_STOP, frame 552 to 552",
  "status": "ok",
  "verdict": "OTHER_STOP",
  "frame_before": 552,
  "frame_after": 552,
  "emulated_before_s": 9.32817,
  "emulated_after_s": 9.32817,
  "cycles": 0,
  "polls": 1,
  "cause": "watch credits_bcd: 0x0000042c written by pc 0x0000b58c",
  "stop_seq": 20,
  "pc": "0x0000b58f",
  "cpu": ":maincpu",
  "frame": 552,
  "regs": {
    "A": "0x03",
    "B": "0xcf",
    "D": "0x03cf",
    "X": "0xe199",
    "Y": "0xf2e6",
    "U": "0x7acf",
    "PC": "0xb58f",
    "S": "0x07fc",
    "CC": "0x80",
    "DP": "0x00"
  },
  "instruction": {"address": "B58F", "bytes": "39", "text": "RTS", "symbol": "count_coin", "delta": 12},
  "following": ["B590: 96 F4    LDA    <$F4", "B592: 27 21    BEQ    $B5B5", "B594: 96 B3    LDA    <$B3", "B596: 84 07    ANDA   #$07", "B598: 26 1A    BNE    $B5B4", "B59A: 8E F6 59 LDX    #$F659", "... 7 more"],
  "errorlog": "<volatile>",
  "watches": [
    {
      "ref": "credits_bcd",
      "cpu": ":maincpu",
      "state": "armed",
      "reading": {"available": true, "value": 3, "raw_hex": "03"}
    }
  ],
  "omitted": ["addr", "by", "entry", "fmt", "length", "mode"],
  "how": "`declaration_list(kind=\"watch\")` answers each watch whole: its declaration, the debugger's row for it, and a count's or a capture's tables",
  "watch_hit": {
    "ref": "credits_bcd",
    "addr": "0x0000042c",
    "cpu": ":maincpu",
    "index": 1,
    "writes_total": 1,
    "truncated": false,
    "writer_pc": "0x0000b58c",
    "writes": [
      {"wrote": "0x03", "to": "0x0000042c", "pc": "0x0000b58c"}
    ],
    "values_from": "memory",
    "before": 2,
    "after": 3,
    "lines": ["Stopped at watchpoint 1 writing 03 to 042C (PC=B58C)"]
  }
}

The five modes

mode what it does stops?
show Reads the value at every stop. no
change Stops when the bytes are written. yes
expr Evaluates one debugger expression at every stop. no
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

Arguments

ref string, required
What to watch: a symbol, a 0x address, or an address reached through a pointer ([base]+0x28, base->field). For expr, the expression itself.
mode one of "show", "change", "expr", "count", "capture", required
show, change, expr, count or capture, 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, 1024 for the others.
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.
cpu string, default ""
The cpu whose memory is watched. Left empty, the one the debugger is showing.
condition string, default ""
For change only: a debugger expression that must hold for the stop, where wpdata is the value written: wpdata==0x7f.
trigger string, default ""
For capture only: the address whose every write takes a row holding the block at ref.
space one of "program", "io", default "program"
io watches a port instead of memory: count or capture only, and for this session only.
trigger_type one of "w", "r", "rw", default "w"
w takes writes. On a capture, r takes reads of ref itself, with no trigger, length or fmt; on a count, r or rw counts reads too.

What comes back

state
armed for a change watch set in the debugger, evaluated for show and expr, pending for count and capture. The top of the page lists the rest.
reading
What this call read at ref, on a stopped machine: value and raw_hex, or available: false with the reason, never a zero.
entry
The debugger's own row for the watch, once armed.
stored
The server saved the watch, and sets it again at start. false for a port watch.
installed
false for a count or capture just sent: MAME installs it when its console next reads a line, and pending stays true until then.
values_from
bus when the address does not read back what is written to it, as a write-only register: the values are then the writes logged, never a memory read.
All 35 reply fields
  • addr (string)
  • already_stored (boolean)
  • armed (boolean)
  • by (string)
  • call (string)
  • condition (string)
  • condition_typed (string)
  • cpu (string)
  • cpus_with_io (array)
  • entry (string)
  • fmt (string)
  • index (integer)
  • installed (boolean)
  • length (integer)
  • lines_ahead (integer)
  • mine (boolean)
  • mode (string)
  • pending (boolean)
  • pointer (object)
  • read_maps_to (string)
  • reading (object)
  • ref (string)
  • source (object)
  • space (string)
  • state (string)
  • stored (boolean)
  • tally_id (string)
  • trigger (string)
  • trigger_addr (string)
  • trigger_maps_to (string)
  • trigger_type (string)
  • values_from (string)
  • visible_cpu (string)
  • while_running (boolean)
  • write_maps_to (string)

What it refuses

Why it works this way

A change watch answers "who wrote this byte". The write has landed when the machine stops, so the stop's pc is the instruction after the writer. The stop's watch_hit names the writer and each write since the previous stop.

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.

state says where the watch stands and reading what this call read, since a change watch is armed and read at the same stop. One ref carries one watch per cpu: another mode, size, format, condition or trigger under it is refused until cleared.

More on why

On every watch:

  • An address matches in any spelling; a symbol and its address are two refs.
  • 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.
  • Arming writes nothing to the machine, so the session is not altered.
  • A watch set while the machine runs is armed at once and fires. Only a ref through a pointer needs a stop.
  • reading holds available, then value and raw_hex (value and hex for an expr), or why when nothing could be read.

On show and expr:

  • A watch on another cpu is read only on a MAME whose gdbstub reads every cpu. Otherwise its reading is available: false, and a watch through a pointer there is refused.
  • Every expr is read in one print at each stop, so one more costs a stop nothing.
  • An expr has no cpu, and takes no ,, ;, assignment, length or fmt.

On change:

  • The writer comes from the debugger's own log line for the stop. A 68000 writes a long as two words, so one write lists as two.
  • The debugger accepts a watchpoint on the ROM copy of a variable whose live copy is in RAM, and it never fires. So the memory map is asked first.
  • Two watchpoints on one byte would make "who wrote it" ambiguous, so an overlap is refused. A count or a capture never stops, so only an identical one is refused.
  • The debugger's list is read back after every arm, and a watch is saved only once it is armed.
  • For a write-only register a stop's reading is bus with last_wrote, the last value written.
  • write_maps_to and read_maps_to say what the memory map has at the address for each direction.
  • The writer's pc is a 0x address, so it goes straight into disassemble or breakpoint_at as a ref. MAME names it only for a write by the watch's own cpu.

On a condition:

  • It answers "who writes bits 0-1 of this byte" without a stop at every write of the register.
  • wpdata is the value as it reached the bus, shifted down to the bytes written.
  • It takes breakpoint_at's grammar on the watch's cpu and is evaluated once before arming: MAME sets a watchpoint whose condition it cannot evaluate, and that one never fires.
  • A watch through a pointer that is still null has its condition checked right away: the stop that finds the pointer set has no call left to refuse it.
  • A row the debugger lists without the condition sent is readback_refused. A row already at that range under another condition is ambiguous_ref.

On count:

  • It sees the writes of its own cpu only, never those a DMA or a blitter makes on its own bus.
  • It counts writes to its own range only. To count one register's values by the value of another, use a capture: two counts cannot be joined afterwards.
  • A write lands in one bus word, so a word covered in part would give fragments with no value. That is why such a range is refused.
  • It sees every write the cpu makes, handled or not, so it arms where nothing handles the write: write_maps_to is then unmapped, with a note.
  • tally_id names it: its range, plus the cpu when that is not the first one.
  • A count that never started must not read as zero. An install the console echoed and never ran is sent once more (install_resent); lost twice, the state is install_lost.
  • lines_ahead is how many console lines wait before the install, and call the line that marks it done.
  • Declaring the range again installs over the old count and keeps its counts. After a clear that ran, it counts from zero.
  • A count or capture whose periodic write keeps failing leaves its last finished dump on disk. Its reading is superseded, its why the error error.log logs as MCP_DUMP_FAILED.

On capture:

  • The row is taken before the write lands. When trigger lies inside the block, the block holds the value from before the write.
  • The block must be plain memory. Reading through a handler would run it at every trigger, and reading around it gives zeros that look like data.
  • source says where the block is read: kind, then addr in the cpu's memory, or the tag and offset of a memory share or region.
  • time_s is the accessing cpu's own clock at full precision, so two accesses one cycle apart never share it.
  • Captures on two cpus share one clock: order their rows by time_s, not by position. line is the screen line being drawn.
  • A capture of reads keeps the access and no block. It sees no instruction fetch and no ROM read, so on code or ROM it keeps no row.
  • It runs at every read, so on an address the program polls it costs a Lua call per poll.
  • A read capture's ref is its trigger, so a write capture of the same address under that ref is refused.
  • gfx_blits, gfx_blit_source, gfx_draft and a region write read write captures only.
  • trigger_addr is where trigger resolves, and trigger_maps_to what the memory map has there.

On a port (space="io"):

  • A board that drives its palette or sound through out writes nothing to program memory, so only a port watch sees it.
  • It lasts the session only. The saved breakpoints file knows no ports, and would set it again as the memory address of the same number.
  • It is cleared with its ref and space="io". Its tally_id carries the space (6_2@io): port 6 and address 6 are two watches.
  • cpus_with_io lists the cpus that have ports, when the one named has none.

Through a pointer:

  • It reaches a field a C program keeps in a heap struct behind a global pointer.
  • The pointer is read at the width its type gives (ptr16{...}, ptr32{...}), else at the stack pointer's width.
  • On a board whose symbol file sets bases, a pointer read through a symbol of a relocated class is an offset in that class's segment.
  • A type can name the class (ptr16@CODE), which a routine's address kept in DATA needs.
  • It is followed again at every stop. A change watch moves with it (moved), and a null pointer is null_pointer, never a watch at address zero.
  • pointer holds where the pointer was read (at, length), its value, the offset and field added, and relocated (class, base, class_from).
The contract your client receives
Text
Declare a watch at `ref`. Stored, re-armed at `start`.

`mode`: `show` (read at each stop), `change` (a write stops the machine), `count` (tallies
writes by value and by writer pc; with `trigger_type` `r` or `rw` the reads are one count,
`reads`, apart), `capture` (rows at
`trigger`), `expr` (one debugger expression). `ref`: a symbol,
`0x` address or pointer place (`base->field`; stopped machine only). `fmt`: a scalar (`u8`
.. `f64`), an array (`u16[8]`), a string (`char[16]`) or a struct (`{x:i16,y:i16}`).
`length`: total bytes, needed unless `fmt` is sized or the symbol typed; at most
128 for show or capture, 1024 otherwise. `condition`: change only, a
debugger expression over `wpdata`, the value written (`wpdata==0x7f`).
`trigger`: capture only; `trigger_type` `w` or `r` there; a capture of reads (`r`) takes no
`length` or `fmt`. `space="io"`: a port tap, `count` or `capture` only, for this session only
(never
stored).

Refused: a change watch on an unmapped write; a count range splitting a bus word; a ref
declared another way; an unknown pointer base or `cpu`.

Reply: `ref`, `mode`, `stored`, `already_stored`, `armed`, `state`, `reading` (on a stopped
machine), and each mode's own fields.

Reference: REFERENCE.md, Breakpoints and watches.
Tools