SCRYMAMEReferenceWriteset_registerAlso in DOSBox-X
set_register
Force a register to a value you choose, and see what the cpu holds afterwards.
set_register(name, value, cpu="")
Try it
Ask
Force register A to 0x42.
Call
set_register(name="A", value="0x42")Reply 6 of 7 fields
{
"summary": "set_register A = 0x42, verified True",
"register": "A",
"value": "0x42",
"readback": "0x42",
"verified": true,
"cpu": ":maincpu"
}Register A of :maincpu now holds 0x42. readback is what the register held after the write, and verified says it equals what was asked.
The whole reply
JSON
{
"summary": "set_register A = 0x42, verified True",
"status": "ok",
"register": "A",
"value": "0x42",
"readback": "0x42",
"verified": true,
"cpu": ":maincpu"
}Arguments
- name string, required
- The register, by a name
registerslists (D0,PC). A 16-bit register served under anEname takes its short one:AXforEAXon a V30. - value integer or string, required
- The value to set: an integer or a
0xstring, not negative and no wider than the register. - cpu string, default
"" - The cpu whose register is set. Left empty, the one the debugger is showing.
What comes back
- register
- The register as the debugger names it, which can differ from the name given (
EAXforAX). - value
- What was asked, as
0xtext at the register's width. - readback
- What the register holds after the write, in the same spelling.
- verified
truewhenreadbackequalsvalue.
All 5 reply fields
cpu(string)readback(string)register(string)value(string)verified(boolean)
What it refuses
- A machine that is running (
not_stopped). - A name the cpu does not have; the message lists the ones it has (
bad_argument). - A negative value, or one wider than the register (
bad_argument). - A bool, or a value of either spelling wider than 64 bits, the widest number MAME's debugger holds (
bad_argument). - A
cpuother than the first, on a MAME build whose debugger connection serves one cpu only (bad_argument). - A cpu whose registers the debugger connection does not describe (
no_channel).
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, or answers something else, 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.
Related tools
The contract your client receives
Text
Force register `name` of `cpu` to `value` and read it back. Modifies the machine; needs it
stopped.
Refuses an unknown name (listing the cpu's) and a value wider than the register.
Reply: `register`, `value`, `readback`, `verified`, `cpu`. A cpu the stub does not
describe is `no_channel`.
Reference: REFERENCE.md, Reading and writing.