SCRYMAMEReferenceWritewriteAlso in DOSBox-X

MAMEWrite

write

Write bytes into memory at an address or a symbol, and see what the memory holds afterwards.

write(ref, data_hex, cpu="", region=false)

Try it

On Gridlee, a free ROM from mamedev.org, at any stop, with the example session's symbols loaded: credits names the first of the two bytes the game keeps its credits in.
Ask

Give me nine credits: write 9 into both bytes the game keeps its credits in.

Call
write(ref="credits", data_hex="0909")
Reply 5 of 8 fields
{
  "summary": "write credits: 2 bytes, verified True",
  "addr": "0x0000042b",
  "bytes_written": 2,
  "readback": "0909",
  "verified": true
}

Both bytes from 0x42b now hold 9. readback is what the memory holds after the write, and verified says it is what was sent.

The whole reply
JSON
{
  "summary": "write credits: 2 bytes, verified True",
  "status": "ok",
  "ref": "credits",
  "addr": "0x0000042b",
  "bytes_written": 2,
  "readback": "0909",
  "verified": true,
  "cpu": ":maincpu"
}

Arguments

ref string, required
Where the bytes go: a 0x address or a symbol.
data_hex string, required
The bytes to write, as hex digits, two per byte: 1 to 1024 bytes.
cpu string, default ""
The cpu whose memory is written. Left empty, the one the debugger is showing.
region boolean, default false
true patches ROM, in the memory region that holds the address. Left out, a write to ROM changes nothing and the reply says why.

What comes back

readback
The bytes at the address after the write, as hex, read through the same cpu.
verified
true when readback is what was sent.
bytes_written
How many bytes were sent, whether or not they landed.
target
rom, when a write without region did not land because the address is ROM. note then says where its bytes live.
region
The memory region that holds the address, with region_offset the offset in it: where a region write went, or where a ROM address keeps its bytes.
captures_reading_it
With region: each capture watch that reads the block the write changed, by ref, cpu and, for a port, space.
All 10 reply fields
  • addr (string)
  • bytes_written (integer)
  • captures_reading_it (array)
  • cpu (string or object)
  • readback (string)
  • ref (string)
  • region (string)
  • region_offset (string)
  • target (string)
  • verified (boolean)

What it refuses

Why it works this way

The reply says what the memory holds after the write, never what was sent. A write to ROM is taken and changes nothing, and readback is where that shows. verified: false on RAM means the write went nowhere; on a hardware register it can be the register answering something else, which is its job.

ROM is patched only with region, so it never happens by accident. As the cpu sees it ROM has no write side: its bytes live in a memory region, and region=true changes them there without running an instruction.

The write marks the session: the session block of every later reply carries altered, which says this session has written to the machine.

More on why

A capture watch, watch_add(mode="capture"), records a block of memory each time its trigger address is accessed. A region write changes that block with no write on the bus, so the watch would show the change with nothing saying why; the reply names each watch it reaches.

With region, data_hex is still in the order the cpu reads the bytes, whatever order the region keeps them in. The write lands whole or not at all: when the console cannot copy the whole span out and back, it is refused and nothing is loaded.

The contract your client receives
Text
Write bytes to memory at `ref` of `cpu` and read them back through it; needs the machine
stopped.

`data_hex` is 1..1024 bytes. `region=True` patches ROM in the memory region backing
the address (refused where none does, or past its end); without it a ROM write goes
nowhere and says why. A range past the program space is `bad_argument`.

Reply: `ref`, `addr`, `bytes_written`, `readback`, `verified`, `cpu`; with `region` also
`region`, `region_offset`, `captures_reading_it`; on ROM `target`, `note`. A failed
re-read is `readback_refused` or `session_broken`.

Reference: REFERENCE.md, Reading and writing.
Tools