SCRYMAMEReferenceReadmemdumpAlso in DOSBox-X
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
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
0xaddress. - 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
notesays so when its name is not the onedestgave. - bytes
- The file's size, which equals
length. - addr
- The address
refresolved to.
All 6 reply fields
addr(string)bytes(integer)cpu(string or object)length(integer)path(string)ref(string)
What it refuses
- A
destthat is relative, already there, or in a folder that does not exist (bad_argument). - A range that runs past the cpu's program memory (
bad_argument). - A file that is not
lengthbytes, or whose first bytes differ from a direct read of the same memory (readback_refused). - A debugger connection that breaks during that direct read (
session_broken).
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.
Related tools
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.