SCRYDOSBox-XReferenceRunresumeAlso in MAME

DOSBox-XRun

resume

Let the machine run, either with no deadline or waiting a while for it to stop.

resume(seconds=0.0, detail=false)

Try it

On Bricks, the game this repository builds, stopped inside brick_hit, with a change watch set on score.
Ask

Let the game run until the score changes, for a minute at most.

Call
resume(seconds=60)
Reply 5 of 15 fields
{
  "summary": "resume: OTHER_STOP, stopped at 08DF:000002EB",
  "verdict": "OTHER_STOP",
  "pc": "08DF:000002EB",
  "cpu_mode": "real",
  "frame": 36
}

OTHER_STOP says something stopped the machine before the minute ran out: here the watch on the score, at 08DF:000002EB in frame 36.

The whole reply
JSON
{
  "summary": "resume: OTHER_STOP, stopped at 08DF:000002EB",
  "status": "ok",
  "verdict": "OTHER_STOP",
  "omitted": ["output", "output_chars", "clipped"],
  "how": "detail=True adds what the debugger printed for this command",
  "waited_s": "<volatile>",
  "pc": "08DF:000002EB",
  "cpu_mode": "real",
  "frame": 36,
  "regs": {
    "EAX": "0x0000003c",
    "EBX": "0x00000700",
    "ECX": "0x005b001e",
    "EDX": "0x00000000",
    "ESI": "0x00000007",
    "EDI": "0x00001ee1",
    "EBP": "0x0000091c",
    "ESP": "0x0000fffa",
    "EIP": "0x000002eb",
    "CS": "0x08df",
    "DS": "0x08df",
    "ES": "0xa000",
    "FS": "0x0000",
    "GS": "0x0000",
    "SS": "0x08df"
  },
  "watches": [
    {
      "ref": "ball_x",
      "by": "symbol",
      "mode": "show",
      "length": 8,
      "fmt": "{x:i16,y:i16,dx:i16,dy:i16}",
      "state": "evaluated",
      "value": {"x": 230, "y": 78, "dx": 2, "dy": -2},
      "bytes": "e6004e000200feff"
    },
    {
      "ref": "score",
      "by": "symbol",
      "mode": "change",
      "length": 2,
      "fmt": "u16",
      "state": "armed",
      "value": 60,
      "bytes": "3c00"
    }
  ],
  "cause": "no declared code breakpoint at 08DF:000002EB, and the debugger does not say which row stopped the machine, so what made this stop cannot be told",
  "e9": {"lines_total": 0, "truncated": false, "lines": [], "mark": "<volatile>"},
  "stop_seq": 6,
  "instruction": {
    "address": "08DF:000002EB",
    "bytes": "F71E2706",
    "text": "neg word ptr [0x627]",
    "flow": "sequential",
    "code_bits": 16,
    "bytes_from": "memory",
    "symbol": "brick_hit",
    "delta": 35
  }
}

Arguments

seconds number (>= 0, <= 600.0), default 0.0
How long to wait for a stop, in real seconds. Left at 0, the call returns at once and the machine keeps running.
detail boolean, default false
true adds output, the end of what the debugger printed for its RUN command. Left out, omitted names the fields not sent.

What comes back

verdict
With seconds: OTHER_STOP, a breakpoint or a watch stopped the machine, and the stop's readings follow; TIMEOUT, nothing did, and it is left running with a note.
waited_s
With seconds: how long the call waited.
output
With detail: the end of the debugger's own text. output_chars is its whole length and clipped says whether it was cut.
e9
With a stop: the lines the program wrote to port E9, the emulator's debug output port, since the previous stop. They come with or without detail.
All 16 reply fields
  • cause (string)
  • regpoint_hit (object)
  • clipped (boolean)
  • cpu_mode (string or object)
  • e9 (object)
  • enrichment (object)
  • frame (integer or object)
  • instruction (DosboxInstruction)
  • pc (string)
  • regs (object)
  • output (string)
  • output_chars (integer)
  • stop_seq (integer)
  • verdict (string)
  • waited_s (number)
  • watches (array)

What it refuses

Why it works this way

A machine that is already running is refused, because the debugger's RUN does nothing there and an ok would read as if it had been resumed. No breakpoint has to be set first: stop brings a running machine back.

With seconds at 0 the call returns straight after resuming and does not look for a stop, so a machine that stops at once is found by the next call. With seconds, such a stop is this call's OTHER_STOP, and the call reports progress while it waits.

A conf whose autoexec runs boot stops once more on its own. boot restarts the machine at the boot sector, 0000:7C00, and the break at every start that start asks the debugger for fires there too. cause names it, and a second resume lets the operating system run.

More on why

On a DOSBox-X whose debugger has no RUNSTATE command no reply can see that stop at the boot sector. stop brings the machine back from wherever it is, and its position shows it is still there.

The contract your client receives
Text
Let the machine run. `seconds` 0 (the default) returns at once with no deadline; a bound
up to 600 waits for a stop and, if none comes, leaves it running. Needs a stopped
machine. The guest's E9 lines come with the stop it waited for, with or without `detail`.

Reply: with a bound, `waited_s` and `verdict` (`OTHER_STOP` with the stop reply of `run_to`;
`TIMEOUT`, left running, with a `note`). `output` (with `detail=True`: the last
2000 characters the debugger itself printed for `RUN`; else `omitted`).

Reference: REFERENCE.md, Running and stopping.
Tools