SCRYMAMEReferenceRunstepAlso in DOSBox-X
step
Execute a few instructions of one cpu, going into calls or over them.
step(count=1, mode="into", cpu="")
Try it
count_coin, where the run_to example above ends.Execute one instruction and show me where the cpu is now.
step(count=1){
"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
{
"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" intoorover, 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
countwhen a stop on another cpu ended the steps, whichnotesays. - mode
- The
modethe steps ran in. - others
- Every other cpu's program counter
beforeandafterthe steps, with its register's name inreg. 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
- A named
cpuon a MAME that cannot show another cpu without running it (bad_argument). - A step whose stop did not come in time: the machine may still be running, so call
stop(not_settled). - An answer that is not a stop where one was due, a failed connection, or an
overMAME did not answer in time (session_broken). - A machine that is running (
not_stopped).
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.
Related tools
The contract your client receives
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.