SCRYMAMEReferenceReadregistersAlso in DOSBox-X

MAMERead

registers

Read the cpu's registers, now or as they were at the last stop.

registers(from_last_stop=false, cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped by a watch right after the game wrote its third credit.
Ask

Show me the cpu's registers at this stop.

Call
registers()
Reply 2 of 5 fields
{
  "summary": "registers: 10 registers",
  "cpu": ":maincpu"
}

Gridlee's cpu has ten registers. The whole reply, folded below, lists each under regs, and its width in bits under register_bits.

The whole reply
JSON
{
  "summary": "registers: 10 registers",
  "status": "ok",
  "regs": {
    "A": "0x03",
    "B": "0xcf",
    "D": "0x03cf",
    "X": "0xe199",
    "Y": "0xf2e6",
    "U": "0x7acf",
    "PC": "0xb58f",
    "S": "0x07fc",
    "CC": "0x80",
    "DP": "0x00"
  },
  "register_bits": {"A": 8, "B": 8, "D": 16, "X": 16, "Y": 16, "U": 16, "PC": 16, "S": 16, "CC": 8, "DP": 8},
  "cpu": ":maincpu"
}

Arguments

from_last_stop boolean, default false
true returns the registers the last stop recorded, and answers while the program runs. Left out, the registers are read now.
cpu string, default ""
The cpu whose registers are read. Left empty, the one the debugger is showing.

What comes back

regs
Each register by name, as a hex string of its own width.
register_bits
Each register's own width in bits.
superseded
true with from_last_stop: the values are the last stop's, which last_stop identifies, not the current ones.
cpu
The cpu the registers belong to.
All 4 reply fields
  • cpu (string)
  • register_bits (object)
  • regs (object)
  • superseded (boolean)

What it refuses

Why it works this way

Each value is printed at its register's own width, and register_bits states it, because a fixed eight digits would make a 16-bit register look 32-bit. A V30's 16-bit register is named EAX and says 16.

The names are the ones MAME's gdbstub gives the cpu. A 68000 has D0 to D7, A0 to A5, FP, SP, PS and PC; an x86 or a V30 has EAX to GS with EIP. set_register also takes the 68000 aliases A6, A7, SR and USP, which are not listed here.

More on why

The byte order is MAME's: the endianness of the cpu's program space, as start read it. It is not established when that read failed, or when it disagrees with the order measured for that architecture, and the cpu is then no_channel.

At a stop, the regs of such a cpu say available: false with a why, never another cpu's registers under its name.

The contract your client receives
Text
Every register of `cpu` (`subcpu`; the visible one when empty), by the gdbstub's name.
`from_last_stop=True` returns the registers as of the last stop, answers on a running
machine, and is refused before any stop and beside `cpu`.

Reply: `regs` (name to hex string), `register_bits` (name to declared width), `cpu`,
`superseded` (with `from_last_stop`). A cpu with no register map or an unknown byte order is
`no_channel`.

Reference: REFERENCE.md, Reading and writing.
Tools