SCRYDOSBox-XReferenceRunstopAlso in MAME

DOSBox-XRun

stop

Stop a running machine where it is and read where it stopped.

stop(until="")

Try it

On Bricks, the game this repository builds, running after a resume.
Ask

Stop the game where it is.

Call
stop()
Reply 3 of 13 fields
{
  "interrupted": true,
  "via": "break",
  "cpu_mode": "real"
}

interrupted: true means this call stopped the machine, through the debugger's own interrupt, which is via: break. It landed in real mode; where exactly differs from run to run.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "interrupted": true,
  "via": "break",
  "pc": "<volatile>",
  "cpu_mode": "real",
  "frame": "<volatile>",
  "regs": "<volatile>",
  "watches": "<volatile>",
  "cause": "<volatile>",
  "e9": "<volatile>",
  "stop_seq": "<volatile>",
  "instruction": "<volatile>"
}

Arguments

until one of "", "protected", default ""
protected goes on resuming and interrupting, in short runs, until the machine stops in protected mode. Left empty, it stops where it is.

What comes back

interrupted
true when this call stopped the machine, with the stop's readings. false when it was already stopped, with a note.
via
break when the stop came from this call's own interrupt.
runs_to_protected
With until: how many short runs it took. A note says so when none ended in protected mode.
cpu_mode
The cpu mode the machine stopped in: real, protected, paged or VM86.
All 13 reply fields
  • cause (string)
  • regpoint_hit (object)
  • cpu_mode (string or object)
  • e9 (object)
  • frame (integer or object)
  • instruction (DosboxInstruction)
  • interrupted (boolean)
  • pc (string)
  • regs (object)
  • runs_to_protected (integer)
  • stop_seq (integer)
  • via (string)
  • watches (array)

What it refuses

Why it works this way

The interrupt goes through the emulator's own debugger connection, the conf's [dosbox] mcp_server setting. It needs no window and no menu, and takes nothing from your screen and keyboard.

The machine stops wherever it is, often outside your program. A DJGPP program spends part of every frame in real-mode BIOS handlers, at F000:xxxx, where no symbol of a protected-mode table can be given an address. A breakpoint in your code, set at a stop inside it before resuming, brings the machine back into it, and so does until="protected".

More on why

At a stop outside the program, a breakpoint on a symbol reads unarmable when the symbol is in the table and its address cannot be worked out at this instant. It reads unresolved when the table does not hold the name. That is a fact about the table, since symbols_load adds each table to the ones before.

A stop on a machine already stopped answers with that stop as last_stop. If stop fails as well, close then start.

The contract your client receives
Text
Bring a running guest back to the debugger and survey the stop, headless or windowed.

`until="protected"` is for a stop that landed in real mode (a DPMI client's interrupt, in
the BIOS), this call's own or one already held: the guest is let run again in short runs, a
`BREAK` ending each, until one stops in protected mode, 256 runs at most;
with `start(symbols=)`'s DJGPP table held, until one stops in the program's own 32-bit code,
never the DPMI host's 16-bit code. The machine has then moved on, so what the earlier stop
read (screen, memory, registers) no longer describes it; a stop already where the runs would
end is answered as it stands. `cpu_mode` says where it ended.

Reply: `interrupted` (`true` with the stop reply and `via: "break"`; `false` when already
stopped, with a `note`), `runs_to_protected` (with `until`), a `note` if it did not arrive.
INVALID `not_settled`: after the `BREAK`, `RUNSTATE` did not say stopped; ask again.

Reference: REFERENCE.md, Running and stopping.
Tools