SCRYDOSBox-XReferenceWritewriteAlso in MAME

DOSBox-XWrite

write

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

write(ref, data_hex)

Try it

On Bricks, the game this repository builds, at any stop, with its symbols loaded: quit is the flag the game checks to leave.
Ask

Set the game's quit flag, so it exits by itself.

Call
write(ref="quit", data_hex="01")
Reply 5 of 7 fields
{
  "summary": "write quit: 1 byte, verified True",
  "seg_off": "08DF:00000619",
  "bytes_written": 1,
  "readback": "01",
  "verified": true
}

The byte at 08DF:00000619 now holds 1. readback is what the memory holds after the write, and verified says it is what was sent.

The whole reply
JSON
{
  "summary": "write quit: 1 byte, verified True",
  "status": "ok",
  "ref": "quit",
  "seg_off": "08DF:00000619",
  "bytes_written": 1,
  "readback": "01",
  "verified": true
}

Arguments

ref string, required
Where the bytes go: a SEG:OFF address or a symbol.
data_hex string, required
The bytes to write, as hex digits, two per byte: 1 to 128 bytes, what one read takes back for the readback.

What comes back

readback
The bytes at the address after the write, as hex.
verified
true when readback is what was sent.
bytes_written
How many bytes were sent, whether or not they landed.
seg_off
The address ref resolved to, as segment and offset.
All 5 reply fields
  • bytes_written (integer)
  • readback (string)
  • ref (string)
  • seg_off (string)
  • verified (boolean)

What it refuses

Why it works this way

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 refused because SM, the debugger's memory-write command, ends the emulator there instead of writing.

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

The contract your client receives
Text
Write bytes at a symbol or `SEG:OFF` and read them back. Modifies the machine; needs it
stopped.

`data_hex` is whole hex bytes, up to 128. An absent or ambiguous symbol, and a
real-mode ROM address, are refused unsent.

Reply: `ref`, `seg_off`, `bytes_written`, `readback`, `verified`.
Tools