SCRYMAMEReferenceSessionstatusAlso in DOSBox-X

MAMESession

status

Ask whether a session is open and what the machine is doing, without moving it.

status()

Try it

On Gridlee, right after that start: the machine is stopped and nothing has run.
Ask

Is the emulator still up, and where is it stopped?

Call
status()
Reply 6 of 22 fields
{
  "summary": "status: gridlee alive at pc 0x0000f000",
  "status": "ok",
  "system": "gridlee",
  "pc": "0x0000f000",
  "in_debugger": {"breakpoints": [], "watches": [], "regpoints": []},
  "cpu_tags": [":maincpu"]
}

Gridlee is up and stopped at 0x0000f000. in_debugger is empty because no breakpoint or watch is set yet, and cpu_tags names the board's one cpu.

The whole reply
JSON
{
  "summary": "status: gridlee alive at pc 0x0000f000",
  "status": "ok",
  "system": "gridlee",
  "pid": "<volatile>",
  "stub_port": "<volatile>",
  "scratch_dir": "<volatile>",
  "state_dir": "./tmp/demos/tour/gridlee-states",
  "cfg": {"available": false, "why": "no cfg was given, so MAME runs on its defaults"},
  "debugger": {
    "attached": "gdbstub",
    "note": "MAME runs with -debug under this stub. A capture taken at one of this session's stops can land a frame away from an autoboot golden taken by a frame notifier at the same count, in a scene that changes every frame: compare a live capture wit ... (255 characters)"
  },
  "presence": true,
  "fingerprint": "9ddedcc4d2bcbc14",
  "fingerprints": {":maincpu": "9ddedcc4d2bcbc14"},
  "errorlog_path": "<volatile>",
  "stdout_path": "<volatile>",
  "pc": "0x0000f000",
  "last_stop": {
    "stop_seq": 1,
    "pc": "0x0000f000",
    "cpu": ":maincpu",
    "frame": 0,
    "cause": "start",
    "since_s": "<volatile>",
    "wall_at": "<volatile>"
  },
  "in_debugger": {"breakpoints": [], "watches": [], "regpoints": []},
  "threads": {"1": ":maincpu"},
  "cpu_tags": [":maincpu"],
  "console_pending": 0,
  "tallies_pending_removal": [],
  "frame_symbol": "frame"
}

Arguments

Takes no argument.

What comes back

last_stop
Where the machine last stopped: its pc, cpu and cause, and since_s, how long ago. Unavailable, with why, when there is no stop to report.
pc
Where the machine stands now. Unavailable while it runs or once the session is broken; last_stop.pc is then the answer.
stopped_on_its_own
Present when the machine had stopped and no call had reported it yet. status records that stop as the last one.
broken
Present when the session can no longer be trusted, with the reason. The way out is close, then start.
in_debugger
What MAME's debugger holds now: breakpoints, watches and regpoints (registerpoints, stops on a register condition), each by its ref, a symbol or an address, and its cpu.
fingerprint
A hash of the system, the reference image and the symbol file. A breakpoint or watch saved under another one is not trusted; fingerprints has one per cpu.
All 19 reply fields
  • cfg (object)
  • console_pending (integer)
  • debugger (object)
  • errorlog_path (string)
  • fingerprint (string)
  • fingerprints (object)
  • frame_symbol (string or object)
  • in_debugger (object)
  • pc (string or object)
  • pid (integer)
  • presence (boolean)
  • scratch_dir (string)
  • state_dir (string)
  • stdout_path (string)
  • stub_port (integer)
  • system (string)
  • tallies_pending_removal (array)
  • threads (object)
  • throttles_pending (array)

Why it works this way

status answers in every state: with no session, while the machine runs and once the session is broken. It is where you learn why another tool does not answer.

More on why
  • With no session the reply is last_stop and, when there is one to give, a note. After MAME exited under the session it is exit_code and a note.
  • debugger.note says a capture at a stop can land one frame from an autoboot reference capture; start says why.
  • threads is empty on a MAME without the gdbstub thread patch, which gives each cpu a debugger thread. cpu_tags only names the cpus; what each is doing is cpu_info's.
  • console_pending counts Lua lines sent and not yet run. throttles_pending lists speed switches asked and not yet applied (tag, on).
  • tallies_pending_removal lists write counts waiting to be removed (tally_id, call); a row that leaves is a removal done.
  • presence is true when the border is drawn, false when it was asked off, or the reason it is not drawn.
  • last_stop also carries stop_seq, frame and wall_at. frame_symbol is the frame counter's name, as start found it.
  • cfg, stdout_path, errorlog_path, scratch_dir and state_dir are the session's files, as start named them.
The contract your client receives
Text
Whether a machine is alive, and which one. Safe on a running machine; a stop it finds the
machine reached on its own is recorded and reported in `stopped_on_its_own`.

Reply: `last_stop` (`stop_seq`, `pc`, `cpu`, `cause`, `since_s`, `wall_at`) with or without a
session, unavailable once a session has ended; with no session also a
`note` when there is one to give, or, for a process that exited under it, `exit_code` and a
`note`; with a session `system`, `pid`, `stub_port`, `scratch_dir`, `state_dir`, `presence`,
`debugger`, `fingerprint` (`fingerprints` per cpu), `errorlog_path`, `pc`, `in_debugger`
(`breakpoints`, `watches`, `regpoints`: each `ref`, `cpu`), `console_pending`,
`throttles_pending`, `tallies_pending_removal`, and `broken` when the session can no longer
be trusted: `close`, then `start`.

Reference: REFERENCE.md, The session.
Tools