SCRYMAMEReferenceReadmemdumpAlso in DOSBox-X

MAMERead

memdump

Write a range of memory to a file, for ranges too large to read into the conversation.

memdump(ref, length, dest, cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped at any moment: the range is ROM, which never changes.
Ask

Save the first 4096 bytes of the ROM at 0xa000 to a file.

Call
memdump(ref="0xa000", length=4096, dest="./tmp/demos/tour/rom.bin")
Reply 5 of 8 fields
{
  "summary": "memdump 0xa000: 4096 bytes to ./tmp/demos/tour/rom.bin",
  "addr": "0x0000a000",
  "length": 4096,
  "path": "./tmp/demos/tour/rom.bin",
  "bytes": 4096
}

The file holds 4096 bytes, as asked: bytes equals length. path is where it was written.

The whole reply
JSON
{
  "summary": "memdump 0xa000: 4096 bytes to ./tmp/demos/tour/rom.bin",
  "status": "ok",
  "ref": "0xa000",
  "addr": "0x0000a000",
  "length": 4096,
  "path": "./tmp/demos/tour/rom.bin",
  "bytes": 4096,
  "cpu": ":maincpu"
}

Arguments

ref string, required
Where the range begins: a symbol or a 0x address.
length integer, required
How many bytes to write.
dest string, required
The file to create, required: an absolute or ~-led path, in a folder that exists, not there yet. The path holds no space, comma, semicolon, quote or bracket.
cpu string, default ""
The cpu whose program memory is written out. Left empty, the one the debugger is showing.

What comes back

path
The file as written; a note says so when its name is not the one dest gave.
bytes
The file's size, which equals length.
addr
The address ref resolved to.
All 6 reply fields
  • addr (string)
  • bytes (integer)
  • cpu (string or object)
  • length (integer)
  • path (string)
  • ref (string)

What it refuses

Why it works this way

MAME's own save command writes the file, so the bytes never pass through the debugger connection. The server then reads the first bytes of the range directly and compares them with the file, which is what shows the file holds the memory asked for.

A range that runs past the cpu's program memory would hang save, so it is refused before anything is written and leaves no file.

The contract your client receives
Text
Write `length` bytes from `ref` of `cpu` (`subcpu`) to the new file `dest` (absolute or `~`-led, in a directory that exists, with no comma, semicolon, quote, whitespace, bracket or control character).

Reply: `ref`, `addr`, `length`, `path`, `bytes`, `cpu`. A file not `length` bytes, or whose
first bytes differ from a protocol read, is `status: INVALID`; a refused control read is
`readback_refused`, a broken channel `session_broken`. A range past the program space is
`bad_argument`.

Reference: REFERENCE.md, Reading and writing.
Tools