SCRYMAMEReferenceSessioncpu_focus

MAMESession

cpu_focus

Choose which cpu MAME's debugger shows, the one every call that names no cpu acts on.

cpu_focus(cpu)

Try it

This needs a board with more than one cpu, which neither free ROM has. The reply shown comes from a test program that is not distributed.
Ask

Show me the main cpu in the debugger.

Call
cpu_focus(cpu="maincpu")
Reply 8 of 8 fields
{
  "summary": "cpu_focus: :maincpu visible, was :maincpu, nothing ran (stub)",
  "status": "ok",
  "cpu": ":maincpu",
  "was": ":maincpu",
  "via": "stub",
  "machine_ran": false,
  "frame": 0,
  "unchanged": [":maincpu", ":subcpu"]
}

The main cpu was already the visible one. via stub and machine_ran false say nothing ran, and unchanged lists both cpus: their registers read the same before and after.

The whole reply
JSON
{
  "summary": "cpu_focus: :maincpu visible, was :maincpu, nothing ran (stub)",
  "status": "ok",
  "cpu": ":maincpu",
  "was": ":maincpu",
  "via": "stub",
  "machine_ran": false,
  "frame": 0,
  "unchanged": [":maincpu", ":subcpu"]
}

Arguments

cpu string, required
The cpu to show, by its tag in either spelling: subcpu or :subcpu. machine_map lists the tags.

What comes back

cpu
The cpu the debugger shows after the call, read back from its cpulist.
was
The cpu it showed before.
via
stub when the gdbstub switched it, which runs nothing; console when the debugger's focus command did.
machine_ran
true when the machine ran to make the switch. The reply then also describes the stop it reached.
unchanged
With stub: the cpus whose registers read the same before and after, which is the evidence that nothing ran.
ignored
With console: the cpus the debugger now ignores.
All 17 reply fields
  • cpu (string)
  • following (array of string)
  • instruction (StopInstruction)
  • errorlog (object)
  • frame (integer or object)
  • ignored (array)
  • machine_ran (boolean)
  • pc (string)
  • regpoint_hit (object)
  • regs (object)
  • stop_seq (integer)
  • unchanged (array)
  • unread (array)
  • via (string)
  • was (string or object)
  • watch_hit (object)
  • watches (array)

What it refuses

Why it works this way

MAME's debugger acts on one cpu at a time, the visible one, and every stop makes the cpu that stopped visible. A call that names a cpu acts on that cpu and leaves the visible one alone, so cpu_focus is the call that moves it. REFERENCE.md, The session has the whole rule.

On a MAME built with the gdbstub thread patch, which gives each cpu its own debugger thread, nothing runs. The reply shows it: machine_ran: false, the frame, and unchanged. Without the patch the debugger's focus command ignores every other cpu, and the machine may run until the chosen cpu executes.

More on why

unread names a cpu whose registers the gdbstub would not give, so it is never counted as unchanged.

The contract your client receives
Text
Make `cpu` (`subcpu` or `:subcpu`) the debugger's visible cpu, read back off the console's
`cpulist`. Needs the machine STOPPED (else `not_stopped`).

With the stub's thread patch nothing runs. Without it the console's `focus` ignores every
other cpu and may run until `cpu` executes.

Refused: a cpu the machine lacks (`unknown_ref`); on the patched stub, a cpu the debugger
ignores (`bad_argument`). A visible cpu read back other than `cpu`: `readback_refused`; a
console run reaching no stop: `not_settled`.

Reply: `cpu`, `was`, `via` (`stub` or `console`), `machine_ran`; `frame`, `unchanged`,
`unread` (stub); `ignored` and, on a run, its survey (console).

Reference: REFERENCE.md, The session.
Tools