Debugger: Trace Call Tree

The Trace Call Tree window reconstructs the call hierarchy of all functions executed by a single thread over the entire recorded trace. It does this by:

• Iterating over every snapshot associated with the active thread
• Reading the program counter (PC) register at each step
• Mapping the dynamic address to a statically-analyzed program via the Static Mappings service
• Detecting function entries, call instructions, returns, and tail calls.
• There are some limitations for how accurate the call tree will be.

The resulting tree shows the sequence of function invocations in the order they occurred, with each call nested under its caller.

For the tree to be populated, the following conditions must be met:

• A trace must be open and a thread must be active.
• The trace must contain at least one snapshot whose event thread matches the active thread.
• The modules visited during execution must be imported, analyzed, and mapped to the trace via the Static Mappings service.
• Functions must be defined in the mapped program databases at the addresses visited.

The window is divided into two panels: the Call Tree Table on top and the (toggleable) Log Window on the bottom. The divider between them can be dragged to resize each panel. The log window can be hidden using the Show/Hide Log Window action.

Call Tree Table Columns

The call tree table has the following columns:

• Function - The name of the function, displayed as a tree. Each row is indented under its caller. The tree data prefix indicates the node type:
  • Plain name - a regular function call. The PC was observed at the entry point of a function. The function's parameters are captured from registers, stack, or memory at this snapshot.
  • Return: <name> - a return from the named function. A terminal (return) instruction was executed inside a known function. The function's return value is captured at this snapshot. Return nodes can be hidden with the Show/Hide Returns action.
  • Tail Call: <name> - a tail call from this named function to another. A call-terminator instruction (e.g., a jump used as a tail call) was executed inside a known function. Tail call nodes can be hidden with the Show/Hide Tail Calls action.
  • External: <name> - a call to an external (thunked) function. The PC was observed at the entry point of a thunk function whose target is an external symbol (e.g., a shared library function). External nodes are always shown.
• Snapshot - The snapshot key when the function was entered, returned from, or tail-called. Double-clicking a row activates this snapshot in the Debugger.
• Module - The name of the module where the function is defined.
• Return - The raw bytes of the return value, displayed as a hex string, captured at the moment the function returned. Only populated for return nodes.
• Parameter 0, Parameter 1, ... - One column per parameter, up to the maximum number of parameters found across all functions in the tree. Each cell shows the parameter name and its raw byte value captured at the moment the function was entered. The number of parameter columns adjusts automatically when the tree is rebuilt.

Log Window

The log window displays diagnostic messages generated while building the call tree. Each row describes a snapshot at which the tree builder encountered a problem, such as:

• The PC register was null or could not be read.
• The dynamic address could not be mapped to a static program location (e.g., the module is not imported or not mapped).
• The static address is not inside any known function.
• A call instruction had no default fall-through address.
• A return was encountered with an empty call stack.

Log entries are automatically removed when the condition that caused them is resolved on a subsequent rebuild. The log table has the following columns:

• Trace - The name of the trace in which the problem occurred.
• Snap - The snapshot key at which the problem occurred.
• Message - A human-readable description of the problem.
• Dynamic Address - The raw dynamic (trace) address of the PC at the time of the problem, if available.
• Static Address - The mapped static address, if the mapping was successful.

Actions

Rebuild Call Tree

Cancels any in-progress build and restarts the call tree generation from scratch using the current trace and thread. Use this action after changing static mappings, adding function definitions, or any other change that may affect the tree's contents. The tree is rebuilt automatically when new snapshots are appended to the trace.

Jump to Current

Scrolls the call tree table to the node that corresponds to the current debugger coordinates. The node is selected and its ancestors are expanded so it is visible.

Expand from Selected Cell Recursively

Expands the currently selected node and all of its descendants in the tree.

Collapse from Selected Cell Recursively

Collapses the currently selected node and all of its descendants in the tree.

Show/Hide Returns

Toggles the visibility of return nodes in the tree.

Show/Hide Tail Calls

Toggles the visibility of tail call nodes in the tree.

Show/Hide Log Window

Toggles the visibility of the log panel.

Clear Log

Removes all entries from the log table.

Popup (Right-Click) Actions

Right-clicking a row in the call tree table provides the following context actions:

• Go To Snapshot N - Activates snapshot N in the Debugger.
• View <param> - For each parameter whose raw byte value can be interpreted as a valid address, navigates the main Debugger Listing to that address.
• View <param> -> View In <listing> - Navigates an additional open Debugger Listing window to the parameter's address.
• View <param> -> View In New Listing - Opens a new Debugger Listing window and navigates it to the parameter's address.
• View Return - Same as the parameter actions above, but for the function's return value. Only available for return nodes whose return value can be interpreted as a valid address.
• Expand - Expands the selected node(s) one level.
• Collapse - Collapses the selected node(s) one level.
• Expand Recursively - Expands the selected node(s) and all descendants.
• Collapse Recursively - Collapses the selected node(s) and all descendants.

Double-Click

Double-clicking any row in the call tree table activates the snapshot recorded in that row's Snapshot column.

Limitations

• The tree is built per-thread. Switching to a different thread triggers a separate build. Previously built trees are cached per trace and thread and reused when switching back.
• The tree relies on static mappings being present and correct. If a module is not imported or not mapped, all snapshots where the PC falls in that module will be skipped and logged as errors.
• If the trace does not record every instruction, the tree may miss calls or returns that occurred between recorded snapshots. The fall-through tracking heuristic attempts to recover from missed returns, but it is not guaranteed to be correct.
• Parameter and return values are read directly from registers, stack memory, or data memory at the snapshot where the function entry or return was detected. If the calling convention is not correctly defined in the program database, the values shown may be incorrect or absent. Additionally, if the storage location of the parameter is stale/unknown the values may be incorrect
• The tree is marked stale (with a status bar message) when functions or symbols change in an open program database. Use Rebuild Call Tree to refresh it.