SCRYMAMEReferenceWritewriteAlso in DOSBox-X
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
credits names the first of the two bytes the game keeps its credits in.Give me nine credits: write 9 into both bytes the game keeps its credits in.
write(ref="credits", data_hex="0909"){
"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
{
"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
0xaddress 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 truepatches 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
truewhenreadbackis what was sent.- bytes_written
- How many bytes were sent, whether or not they landed.
- target
rom, when a write withoutregiondid not land because the address is ROM.notethen says where its bytes live.- region
- The memory region that holds the address, with
region_offsetthe offset in it: where aregionwrite went, or where a ROM address keeps its bytes. - captures_reading_it
- With
region: each capture watch that reads the block the write changed, byref,cpuand, 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
- A machine that is running (
not_stopped). data_hexthat is not whole hex bytes, is empty, or holds more than 1024 (bad_argument).- A range that runs past the cpu's program memory (
bad_argument). region=truewhere no memory region holds the address, or where the bytes run past its end (bad_argument).- A
cpuother than the first, on a MAME build whose debugger connection serves one cpu only (bad_argument). - A failed read after the write, with the session still usable (
readback_refused) or not (session_broken).
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.
Related tools
The contract your client receives
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.