SCRYDOSBox-XReferenceRunstopAlso in MAME
stop
Stop a running machine where it is and read where it stopped.
stop(until="")
Try it
resume.Stop the game where it is.
stop(){
"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
{
"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"" protectedgoes 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
truewhen this call stopped the machine, with the stop's readings.falsewhen it was already stopped, with anote.- via
breakwhen the stop came from this call's own interrupt.- runs_to_protected
- With
until: how many short runs it took. Anotesays so when none ended in protected mode. - cpu_mode
- The cpu mode the machine stopped in:
real,protected,pagedorVM86.
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
- A machine that did not report stopped after the interrupt: ask again (
not_settled).
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.
Related tools
The contract your client receives
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.