SCRYMAMEReferenceWritedebugAlso in DOSBox-X
debug
Send one line to MAME's debugger console and read what it printed, for what no other tool does.
debug(command)
Try it
Ask MAME's debugger what handles address 0x9380.
debug(command="map 9380"){
"summary": "debug 'map 9380'",
"command": "map 9380",
"mutates": false,
"output": " Read: 9380 logical program == 9380 physical program -> un ... (224 characters)"
}output holds what the console's map command printed, shown here cut short: the whole reply below has it all. mutates is false: the line changed nothing.
The whole reply
{
"summary": "debug 'map 9380'",
"status": "ok",
"command": "map 9380",
"mutates": false,
"output": " Read: 9380 logical program == 9380 physical program -> unmapped\n Write: 9380 logical program == 9380 physical program -> watchdog_timer_device::reset_w\n Fetch: 9380 logical program == 9380 physical program -> unmapped\n\n",
"clipped": false
}Arguments
- command string, required
- One line for the debugger console, as you would type it there. Several commands go on one line, with
;between them.
What comes back
- output
- What the console printed. Past 4000 characters it is cut:
clippedistrueandoutput_pathnames a file with alloutput_charsof it. - mutates
truewhen the line can change the machine: it then counts as a write.- note
- What the line did beyond printing: it let the machine run, completed a held save or load, or moved a counter.
- visible_cpu
- After a line that changes which cpus the debugger shows or skips: the cpu it shows now.
ignoredlists the ones it skips. - refused
- On a refusal: each command the console refused, with its
indexin the line, thecommandand the console'serror.not_runlists the commands that never ran.
All 13 reply fields
clipped(boolean)command(string)command_chars(integer)ignored(array or object)limit_chars(integer)mutates(boolean)not_run(array)output(string)output_chars(integer)output_path(string)refused(array)refused_total(integer)visible_cpu(string or object)
What it refuses
- A machine that is running (
not_stopped). - A line holding
hardreset, before anything is sent:closethenstartis that reset (bad_argument). - A line the console answers with an error of its own, such as an unknown command or a bad expression (
bad_argument). - A line too long for one packet of the debugger connection, before it is sent;
command_charsandlimit_charssay by how much (bad_argument). - A
statesaveorstateloadMAME still holds after one instruction (not_settled).
Why it works this way
A line that can change the machine counts as a write, whether it fills memory, loads a file, resets, runs or assigns a value. It marks the session: the session block of every later reply carries altered, which says this session has written to the machine.
A line that lets the machine run (g and its family, step N, over, next) leaves the session running until stop, and tools that read the machine refuse until then.
The console has no exit code, so its error answers are read. Otherwise a refused line would come back ok, and a perform, which runs several calls as one, would go on to its next step.
More on why
Each command is classified from MAME's own command table, on the cautious side. The cases that are not obvious:
suspendandresumecount when they name a cpu, and so doessource, which runs a file of console commands.- A bare
suspend,resume,ignoreorobserveonly lists. - An action given to
bp,ep,rp,wp,traceortraceovercounts: it is a command list run at every hit. //and/*are the console'scomaddandcommit. A comment's text is never evaluated, and acomaddtyped here is not saved or listed by the comment tools.- A comparison is never an assignment:
print {d1==7fff}is a read. An assignment is looked for outside quoted strings only. - An assignment to a debugger temporary variable is not a write, but
temp0=w@100=1is: the chain reaches memory. - A line of several commands is split at each
;outside brackets and quotes, and each command is classified alone.
A line that assigns the temporary variable of a control, an address counted beside a run's target, names that control in note. The write moves the hits_since_armed that declaration_list(kind="breakpoint") reports, not a run's control_hits. Writing -1 makes the control stop the machine at its next hit.
MAME drops a packet longer than its debugger connection takes, without answering, and the wait that followed would blame the wrong thing. The same limit covers every tool that sends a console command: a long condition, a find pattern, a memdump path.
A parse error, such as unknown command or unbalanced quotes, stops the line there: the commands after it never ran, and a g behind it leaves the machine stopped. An error printed while a command ran, such as Error in expression or Error opening file, leaves the rest running.
A command refused while it ran still counts as a write, because the console evaluates parameters in order: print d0=5,zzz writes D0 before it refuses zzz. An error the answer cannot pin on one command names the whole line. Only the error shapes the console is known to print are matched, each at the start of a line.
A bare comparison typed as a command, print d1==1234, is an assignment expression to the console's parser and is refused; in braces it answers.
A statesave or stateload typed here is completed as state_write completes its own when MAME holds it, and note says so. MAME keeps one held save or load at a time, so a line that held several completes only the last.
Related tools
The contract your client receives
Run any MAME debugger command, `command`. Prefer the typed readers: a wide `find` takes
MAME down. Needs the machine stopped.
A line that changes the machine (`fill`, `load`, `stateload`, a reset, a run or step, an
assignment) is a write. `hardreset` is refused unsent. The `g` family, `step N`, `over`
and `next` mark the session RUNNING until `stop`. A too long packet, or the console's own
error answer, is `bad_argument`.
Reply: `command`, `mutates`, `output`, `clipped`, `note`; past 4000 characters the
text goes to a file (`output_chars`, `output_path`); `visible_cpu`, `ignored` (a line that
sets cpus); on refusal `command_chars`, `limit_chars`, `refused`, `refused_total`, `not_run`.
Reference: REFERENCE.md, The console.