SCRYDOSBox-XReferenceWriteset_registerAlso in MAME

DOSBox-XWrite

set_register

Force a register to a value you choose, and see what the cpu holds afterwards.

set_register(name, value)

Try it

On Bricks, the game this repository builds, stopped at brick_hit as the ball knocks out its first brick. AL holds the brick's row there.
Ask

Set AX to 0, so the game takes this brick for one of the top row.

Call
set_register(name="ax", value=0)
Reply 5 of 7 fields
{
  "summary": "set_register ax = 0, verified True",
  "register": "ax",
  "value": "0x0000",
  "readback": "0x0000",
  "verified": true
}

AX now holds 0. readback is what the register held after the write, four digits for a 16-bit name, and verified says it equals what was asked.

The whole reply
JSON
{
  "summary": "set_register ax = 0, verified True",
  "status": "ok",
  "value": "0x0000",
  "register": "ax",
  "regs": {
    "EAX": "0x00000000",
    "EBX": "0x00000707",
    "ECX": "0x005b0020",
    "EDX": "0x00000000",
    "ESI": "0x00000039",
    "EDI": "0x000064e4",
    "EBP": "0x0000091c",
    "ESP": "0x0000fffa",
    "EIP": "0x000002c8",
    "CS": "0x08df",
    "DS": "0x08df",
    "ES": "0xa000",
    "FS": "0x0000",
    "GS": "0x0000",
    "SS": "0x08df"
  },
  "readback": "0x0000",
  "verified": true
}

Arguments

name string, required
The register, as the debugger's SR command takes it: a 32-bit one (eax), a segment (ds), or a 16-bit low half (ax, ip).
value integer or string, required
The value to set: an integer or a 0x string, not negative and no wider than the register.

What comes back

register
The register written, in lower case.
value
What was asked, as 0x text at the register's width.
readback
What the register holds after the write, in the same spelling. A 16-bit name is read as the low half of its 32-bit register, so four digits.
verified
true when readback equals value.
regs
Every register as it reads after the write.
All 5 reply fields
  • readback (string)
  • register (string)
  • regs (object)
  • value (string)
  • verified (boolean)

What it refuses

Why it works this way

The value is read back because a register can refuse part of it. verified: false is not always a failure: a register that masks the value is doing its job.

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 one register and read it back; marks the session `altered`. Needs the machine
stopped.

`name` is a register the debugger's `SR` takes (`eax`, `ax`, `ip`); a negative or too wide
`value` is refused unsent.

Reply: `register`, `regs`, `value`, `readback` (both `0x` at the register's width),
`verified`. INVALID when the registers did not come back.
Tools