SCRYMAMEReferenceBreakpointswatch_addAlso in DOSBox-X
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
Stop the game when the BCD copy of the credits is written, and tell me which instruction did it.
watch_add(ref="credits_bcd", mode="change"){
"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:
run_for(frames=1, seconds=300){
"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:
{
"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:
{
"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
0xaddress, or an address reached through a pointer ([base]+0x28,base->field). Forexpr, the expression itself. - mode one of
"show","change","expr","count","capture", required show,change,expr,countorcapture, as above.- length integer, default
0 - Total bytes; not needed when
fmthas a size or the symbol has a type. At most 128 forshowandcapture, 1024 for the others. - 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. - cpu string, default
"" - The cpu whose memory is watched. Left empty, the one the debugger is showing.
- condition string, default
"" - For
changeonly: a debugger expression that must hold for the stop, wherewpdatais the value written:wpdata==0x7f. - trigger string, default
"" - For
captureonly: the address whose every write takes a row holding the block atref. - space one of
"program","io", default"program" iowatches a port instead of memory:countorcaptureonly, and for this session only.- trigger_type one of
"w","r","rw", default"w" wtakes writes. On acapture,rtakes reads ofrefitself, with notrigger,lengthorfmt; on acount,rorrwcounts reads too.
What comes back
- state
armedfor achangewatch set in the debugger,evaluatedforshowandexpr,pendingforcountandcapture. The top of the page lists the rest.- reading
- What this call read at
ref, on a stopped machine:valueandraw_hex, oravailable: falsewith 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.falsefor a port watch. - installed
falsefor acountorcapturejust sent: MAME installs it when its console next reads a line, andpendingstaystrueuntil then.- values_from
buswhen 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
- A
changewatch where nothing handles the write, such as the ROM copy of a variable (bad_argument). - A
countrange that covers part of a bus word, such as a word at an odd address on a 16-bit bus (bad_argument). - One
refunder two modes, sizes, formats, conditions or triggers: clear the first (ambiguous_ref). - A
changewatch that shares a byte with another armed one on the same cpu, or acounton a range already counted (ambiguous_ref). - A pointer base or a
triggerthat names no symbol, or a cpu the machine does not have (unknown_ref). - A watch through a pointer while the machine runs (
not_stopped). - A
countorcapturethrough a pointer, or acaptureblock with a handler inside it (bad_argument). - A
lengthover the mode's maximum, or none where neitherfmtnor the symbol gives a size (bad_argument). conditionon any mode butchange,triggeron any mode butcapture, and a write capture without one (bad_argument).- On a port:
show,change,expror a count of reads, or a cpu with no io space (bad_argument). - A
changewatch the debugger took and does not list back: nothing is saved (readback_refused).
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
fmtleft atauto, a typed symbol reads as its type, else as the widest unsigned scalar that divideslength. - 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.
readingholdsavailable, thenvalueandraw_hex(valueandhexfor anexpr), orwhywhen 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
readingisavailable: false, and a watch through a pointer there is refused. - Every
expris read in oneprintat each stop, so one more costs a stop nothing. - An
exprhas no cpu, and takes no,,;, assignment,lengthorfmt.
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
countor acapturenever 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
buswithlast_wrote, the last value written. write_maps_toandread_maps_tosay what the memory map has at the address for each direction.- The writer's
pcis a0xaddress, so it goes straight intodisassembleorbreakpoint_atas aref. 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.
wpdatais 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 isambiguous_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_tois thenunmapped, with anote. tally_idnames 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 isinstall_lost. lines_aheadis how many console lines wait before the install, andcallthe 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, itswhythe errorerror.loglogs asMCP_DUMP_FAILED.
On capture:
- The row is taken before the write lands. When
triggerlies 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.
sourcesays where the block is read:kind, thenaddrin the cpu's memory, or thetagandoffsetof a memory share or region.time_sis 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.lineis 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
refis its trigger, so a write capture of the same address under that ref is refused. gfx_blits,gfx_blit_source,gfx_draftand a region write read write captures only.trigger_addris wheretriggerresolves, andtrigger_maps_towhat the memory map has there.
On a port (space="io"):
- A board that drives its palette or sound through
outwrites 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
refandspace="io". Itstally_idcarries the space (6_2@io): port 6 and address 6 are two watches. cpus_with_iolists 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
changewatch moves with it (moved), and a null pointer isnull_pointer, never a watch at address zero. pointerholds where the pointer was read (at,length), itsvalue, theoffsetandfieldadded, andrelocated(class,base,class_from).
Related tools
The contract your client receives
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.