SCRYMAMEReferenceReadread_memoryAlso in DOSBox-X

MAMERead

read_memory

Read a few bytes of memory at an address, as hex text.

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

Try it

On Gridlee, a free ROM from mamedev.org, stopped at reset, right after start.
Ask

Read the two bytes of the IRQ vector, at 0xfff8.

Call
read_memory(ref="0xfff8", length=2)
Reply 4 of 7 fields
{
  "summary": "read_memory 0xfff8: 2 bytes at 0x0000fff8: fd80",
  "addr": "0x0000fff8",
  "length": 2,
  "hex": "fd80"
}

The two bytes at 0xfff8 are fd80. They are the cpu's IRQ vector, so the interrupt routine starts at 0xfd80.

The whole reply
JSON
{
  "summary": "read_memory 0xfff8: 2 bytes at 0x0000fff8: fd80",
  "status": "ok",
  "ref": "0xfff8",
  "addr": "0x0000fff8",
  "length": 2,
  "hex": "fd80",
  "cpu": ":maincpu"
}

Arguments

ref string, required
The address to read: a symbol or a 0x address.
length integer (>= 1, <= 1024), default 16
How many bytes: 1 to 1024. Left out, 16.
cpu string, default ""
The cpu whose program memory is read. Left empty, the one the debugger is showing.

What comes back

hex
The bytes, two hex characters each, lowest address first.
addr
The address ref resolved to.
cpu
The cpu that was read.
All 5 reply fields
  • addr (string)
  • cpu (string or object)
  • hex (string)
  • length (integer)
  • ref (string)

What it refuses

Why it works this way

The reply is hex text in the conversation, so it is kept short: a screen's worth of video memory would bury everything else. For more, memdump writes the bytes to a file.

Memory the board can only write to reads back as zeros, with no error, because its values sit behind the write handler. symbols_find marks such an address latch, and read_block reads it.

The contract your client receives
Text
Read `length` bytes (1..1024) at `ref` (a symbol or `0x` address) of `cpu` (`subcpu`;
the visible one when empty). A range past the cpu's program space is `bad_argument`.

Reply: `ref`, `addr`, `length`, `hex`, `cpu`. Above the ceiling use `memdump`. A write-only
range (`latch`) answers zeros with no error: use `read_block`.

Reference: REFERENCE.md, Reading and writing.
Tools