SCRYMAMEReferenceSessioncpu_focus
cpu_focus
Choose which cpu MAME's debugger shows, the one every call that names no cpu acts on.
cpu_focus(cpu)
Try it
Show me the main cpu in the debugger.
cpu_focus(cpu="maincpu"){
"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
{
"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:
subcpuor:subcpu.machine_maplists 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
stubwhen the gdbstub switched it, which runs nothing;consolewhen the debugger'sfocuscommand did.- machine_ran
truewhen 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
- The machine is running (
not_stopped). - A cpu the machine does not have (
unknown_ref). - With the gdbstub thread patch, a cpu the debugger ignores (
bad_argument). - The cpu read back afterwards is not the one asked for (
readback_refused). - Without the patch, the run the console started reached no stop that was read (
not_settled).
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.
Related tools
The contract your client receives
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.