SCRYMAMEReferenceWritedebugAlso in DOSBox-X

MAMEWrite

debug

Send one line to MAME's debugger console and read what it printed, for what no other tool does.

debug(command)

Try it

On Gridlee, a free ROM from mamedev.org, at any stop.
Ask

Ask MAME's debugger what handles address 0x9380.

Call
debug(command="map 9380")
Reply 4 of 6 fields
{
  "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
JSON
{
  "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: clipped is true and output_path names a file with all output_chars of it.
mutates
true when 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. ignored lists the ones it skips.
refused
On a refusal: each command the console refused, with its index in the line, the command and the console's error. not_run lists 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

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:

  • suspend and resume count when they name a cpu, and so does source, which runs a file of console commands.
  • A bare suspend, resume, ignore or observe only lists.
  • An action given to bp, ep, rp, wp, trace or traceover counts: it is a command list run at every hit.
  • // and /* are the console's comadd and commit. A comment's text is never evaluated, and a comadd typed 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=1 is: 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.

The contract your client receives
Text
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.
Tools