SCRYMAMEReferenceReaddisassembleAlso in DOSBox-X

MAMERead

disassemble

Disassemble the code at an address, one instruction a line, each marked as a call, a branch, a return or none of those.

disassemble(ref, length=16, cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped at reset with the example session's symbol file loaded, which names count_coin.
Ask

Show me the first instructions of the routine that counts a coin.

Call
disassemble(ref="count_coin", length=12)
Reply 4 of 10 fields
{
  "summary": "disassemble count_coin: 5 lines at 0x0000b583",
  "lines": [
    "B583: 7C 04 2B INC    $042B",
    "B586: 86 01    LDA    #$01",
    "B588: BB 04 2C ADDA   $042C",
    "B58B: 19       DAA",
    "B58C: B7 04 2C STA    $042C"
  ],
  "flow_source": "none",
  "note": "no mnemonic table for cpu type 'm6809' (tables: m68000, v30), so no line is classified"
}

Five instructions from 0xb583: the routine adds one to $042B, then to the decimal copy at $042C. Gridlee's cpu is a 6809, one with no mnemonic table, so no line is classified and note says why.

The whole reply
JSON
{
  "summary": "disassemble count_coin: 5 lines at 0x0000b583",
  "status": "ok",
  "ref": "count_coin",
  "addr": "0x0000b583",
  "length": 12,
  "lines": ["B583: 7C 04 2B INC    $042B", "B586: 86 01    LDA    #$01", "B588: BB 04 2C ADDA   $042C", "B58B: 19       DAA", "B58C: B7 04 2C STA    $042C"],
  "cpu": ":maincpu",
  "flow": ["unknown", "unknown", "unknown", "unknown", "unknown"],
  "flow_source": "none",
  "note": "no mnemonic table for cpu type 'm6809' (tables: m68000, v30), so no line is classified"
}

Arguments

ref string, required
Where to start: a symbol or a 0x address.
length integer (>= 1, <= 1024), default 16
How many bytes to decode, 1 to 1024; left out, 16. The last instruction is completed even when it runs past them.
cpu string, default ""
The cpu whose code is read. Left empty, the one the debugger is showing.

What comes back

lines
One instruction a line, as MAME's dasm prints it: address, bytes, text. A line with a comment ends // <text>.
flow
One word per line: call, branch, return, sequential or unknown.
flow_source
What classified the lines: mnemonic_table:<cpu type>, or none with a note saying why no line was classified.
resolved
Only when start was given bases: each direct memory operand as the address the board uses. Rows carry line, operand, offset, class, linear, symbol and delta.
addr
The address ref resolved to.
All 8 reply fields
  • addr (string)
  • cpu (string or object)
  • flow (array)
  • flow_source (string)
  • length (integer)
  • lines (array)
  • ref (string)
  • resolved (array)

What it refuses

Why it works this way

flow is read off each mnemonic with a table per cpu type, because MAME's console does not say which instructions call or return.

On a segmented board MAME prints an operand as an offset inside its segment. resolved gives the address the board uses as linear, which read_memory and watch_add take, once per symbol class that has a base. An operand relative to a register is not resolved: its address is the register's value at run time.

A word MAME cannot decode is marked by MAME itself: dc.w ...; ILLEGAL.

The contract your client receives
Text
Disassemble `length` bytes (1..1024) from `ref` of `cpu` (`subcpu`; the visible one
when empty), as MAME's `dasm`; the last instruction is completed.

Reply: `ref`, `addr`, `length`, `cpu`, `lines`, `flow` (per line: `call`, `branch`, `return`,
`sequential`, `unknown`), `flow_source`, `note`, and on a relocated board `resolved` (per
direct memory operand: `line`, `operand`, `offset`, `linear`, `symbol`, `delta`). The
printed operand is the map's offset: `read_memory` and `watch_add` take `linear`.
Register-relative operands are not resolved.

Reference: REFERENCE.md, Reading and writing.
Tools