SCRYMAMEReferenceRunstepAlso in DOSBox-X

MAMERun

step

Execute a few instructions of one cpu, going into calls or over them.

step(count=1, mode="into", cpu="")

Try it

On Gridlee, a free ROM from mamedev.org, stopped at count_coin, where the run_to example above ends.
Ask

Execute one instruction and show me where the cpu is now.

Call
step(count=1)
Reply 6 of 13 fields
{
  "summary": "step 1 into: pc 0x0000b586",
  "mode": "into",
  "instructions_completed": 1,
  "pc": "0x0000b586",
  "cpu": ":maincpu",
  "frame": 552
}

One instruction ran, going into any call, and the main cpu is now at 0xb586, in frame 552. The whole reply shows the instruction that runs next.

The whole reply
JSON
{
  "summary": "step 1 into: pc 0x0000b586",
  "status": "ok",
  "mode": "into",
  "instructions_completed": 1,
  "cause": "step 1",
  "stop_seq": 19,
  "pc": "0x0000b586",
  "cpu": ":maincpu",
  "frame": 552,
  "regs": {
    "A": "0x01",
    "B": "0xcf",
    "D": "0x01cf",
    "X": "0xe199",
    "Y": "0xf2e6",
    "U": "0x7acf",
    "PC": "0xb586",
    "S": "0x07fc",
    "CC": "0xa0",
    "DP": "0x00"
  },
  "instruction": {"address": "B586", "bytes": "8601", "text": "LDA    #$01", "symbol": "count_coin", "delta": 3},
  "following": ["B588: BB 04 2C ADDA   $042C", "B58B: 19       DAA", "B58C: B7 04 2C STA    $042C", "B58F: 39       RTS", "B590: 96 F4    LDA    <$F4", "B592: 27 21    BEQ    $B5B5", "... 8 more"],
  "errorlog": "<volatile>"
}

The two modes

mode what it does
into Executes one instruction, and enters a call.
over Runs a call to its return as one step.

Arguments

count integer (>= 1, <= 300), default 1
How many instructions to execute. Left out, one.
mode one of "into", "over", default "into"
into or over, as above.
cpu string, default ""
The cpu to step, made visible first. Left empty, the visible one.

What comes back

instructions_completed
How many instructions ran. Fewer than count when a stop on another cpu ended the steps, which note says.
mode
The mode the steps ran in.
others
Every other cpu's program counter before and after the steps, with its register's name in reg. Only on a MAME built with one debugger thread per cpu.
All 16 reply fields
  • command_chars (integer)
  • cpu (string)
  • following (array of string)
  • instruction (StopInstruction)
  • errorlog (object)
  • frame (integer or object)
  • instructions_completed (integer)
  • limit_chars (integer)
  • mode (string)
  • others (object)
  • pc (string)
  • regpoint_hit (object)
  • regs (object)
  • stop_seq (integer)
  • watch_hit (object)
  • watches (array)

What it refuses

Why it works this way

Each step is confirmed on the program counter, because MAME's console answers an over while the machine is still running to the call's return.

The largest count is what keeps the longest run of over steps inside the time limit every wait has. Past it the tool to use is run_to or run_for.

Naming a cpu makes it the visible one first, which runs nothing, and others shows what the rest did meanwhile. That needs a MAME built with one debugger thread per cpu: without it another cpu cannot be shown without running, so naming one is refused.

More on why

An over still moving at its time limit is interrupted, and whether the call would have returned is not seen. An over MAME refused may still have been taken, so the session is marked as running and stop brings it back; if stop fails as well, close then start.

An into whose stop is late still has that stop to come, and stop waits for it. The not_settled reply carries mode and instructions_completed.

An into that reads anything else in a stop's place, a failed connection, or an over the console did not answer in time is session_broken. That stays set until close, because the late answer would otherwise be read as the next request's.

The contract your client receives
Text
Execute `count` (1..300) instructions of `cpu` (the visible one when empty): `into`
is one instruction, `over` runs a call to its return as one step. A named cpu is made
visible first; `others` gives every other cpu's program counter before and after. A stop on
another cpu ends the steps (`note`). Needs the machine STOPPED (else `not_stopped`).

Reply: `mode`, `instructions_completed`, `others` (on a build with a thread per cpu), and
the stop survey of `run_to`. A refused `over` may have run: the machine is marked RUNNING,
and `stop` recovers it. INVALID: `not_settled`, `session_broken`.

Reference: REFERENCE.md, Running and stopping.
Tools