SCRYDOSBox-XReferenceReadcall_stack

DOSBox-XRead

call_stack

Guess the chain of calls that led to the stop, by following the frame pointers on the stack.

call_stack()

Try it

On Bricks, the game this repository builds, stopped at brick_hit as the ball knocks out its first brick.
Ask

Who called the routine the game is stopped in?

Call
call_stack()
Reply 4 of 7 fields
{
  "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
JSON
{
  "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, call and bp.
heuristic
Always true: the chain is a guess, never proof of who called whom.
ended_why
Why the chain ends where it does.
truncated
true when 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

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.

The contract your client receives
Text
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.
Tools