SCRYDOSBox-XReferenceReadcall_stack
call_stack
Guess the chain of calls that led to the stop, by following the frame pointers on the stack.
call_stack()
Try it
brick_hit as the ball knocks out its first brick.Who called the routine the game is stopped in?
call_stack(){
"summary": "call_stack: 1 call, innermost brick_hit, heuristic",
"heuristic": true,
"truncated": false,
"ended_why": "the return address beside the frame at SS:91C follows no call instruction"
}One call, the stop itself in brick_hit. Bricks keeps no frame pointer, so no caller is found, and ended_why says where the chain broke.
The whole reply
{
"summary": "call_stack: 1 call, innermost brick_hit, heuristic",
"status": "ok",
"heuristic": true,
"code_bits": 16,
"calls": [
{
"seg_off": "08DF:000002C8",
"via": "stop",
"call": {"available": false, "why": "the stop itself: no call leads to it"},
"bp": {"available": false, "why": "no frame was read beside it"},
"addr": "0x000090b8",
"symbol": "brick_hit",
"delta": 0
}
],
"truncated": false,
"ended_why": "the return address beside the frame at SS:91C follows no call instruction"
}Arguments
Takes no argument.
What comes back
- calls
- One row per call, innermost first; row 0 is the stop. Each has
seg_off,addr,symbol,delta,via,callandbp. - heuristic
- Always
true: the chain is a guess, never proof of who called whom. - ended_why
- Why the chain ends where it does.
- truncated
truewhen the chain was cut at the most rows a reply lists, with frames still to read.- code_bits
- 16 or 32, the width of the code at the stop.
All 5 reply fields
calls(array)code_bits(integer)ended_why(string)heuristic(boolean)truncated(boolean)
What it refuses
- A stop whose registers came back without
SS,ESPorEBP(unexpected_answer).
Why it works this way
A routine that keeps no frame pointer shows its caller's caller in its place, or nothing.
At a routine's push bp or enter, the mov bp, sp after it, or its ret, the stop is outside the frame. The caller is then read from the stack pointer, and its row says via entry. The other rows come from the frame chain (bp_chain), near or far as the call before each says.
The chain ends at a saved frame pointer that is zero or does not rise, or at a frame past the stack segment's end. A return address no call precedes ends it unlisted; one outside the loaded symbol table ends it listed.
More on why
call is unavailable on row 0, and bp on row 0 and on an entry row.
Related tools
The contract your client receives
A heuristic chain of the stop's callers, never a verdict: frame pointers walked (`push
bp`/`mov bp, sp`, `enter`), each return kept only when a call instruction ends there. Row 0
is the stop.
Reply: `heuristic`, `code_bits`, `calls` (innermost first: `seg_off`, `addr`, `symbol`,
`delta`, `via`, `call`, `bp`), `truncated`, `ended_why`. Refused when the registers come
back without SS, ESP or EBP. A routine with no frame pointer is invisible.
Reference: REFERENCE.md, Reading and writing.