find_all_callers_recursive
Find all direct and indirect C/C++ callers of a symbol to assess change impact across the full call graph, including function-pointer and dispatch edges.
Instructions
Find all transitive C/C++ callers — who calls name, directly or indirectly, through the libclang call graph including function-pointer edges, implicit constructors, and synthetic dispatch edges. libclang-powered: follows function-pointer assignments and ISR vector registrations across the full call tree.
Use for impact analysis: "if I change this function, how far does the
ripple go?" Returns callers at depth 1 (direct), depth 2 (callers of
callers), up to max_depth (default 5). Results are deduplicated —
each caller appears once at its shortest distance to the target.
Edge types traversed: Includes call, indirect (function
pointers / ISRs), implicit_construct (constructors reachable through
file-scope global objects), and dispatch (synthetic edges through
event loops and thread starts).
Limitation — ambiguous name resolution: When a source-line fallback
cannot disambiguate which method is called (e.g. attach() matching
both Timeout::attach and SerialBase::attach), the edge is
conservatively omitted to avoid false callers. If you suspect a
missing caller, verify with search_bodies("target_name") and
find_indirect_targets.
For a flat, single-level caller list use find_callers (faster).
For the reverse direction use find_callees_recursive.
Read-only. No side effects. Requires the reference index
(fw-context index — refs on by default). BFS from the target
outward; performance scales with call-graph fan-out.
Args: name: Symbol name to find transitive callers of. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. max_depth: Maximum BFS depth for transitive search (default 5). limit: Maximum results (default 50). offset: Skip this many results. Reads the next page of a deep call tree; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name.
Returns: list of dicts, each with: name (str — the caller), qualified_name (str), kind (str), signature (str), depth (int — distance from the target), file (str — absolute).
This tool gives no line, because one caller can hold several call
sites. For the line of each call use ``find_callers`` on the name
that this tool reports.
When *name* matches more than one symbol, such as two classes with
a method of the same name, the answer holds the callers of all of
them. A ``warning`` dict then comes first and names the symbols,
and each result carries ``target_qualified_name``, which tells the
symbol that it calls. Give the full qualified name to ask about
one symbol only.
The page notice ``{total, offset, shown, more, hint}`` comes
before the rows of the answer. ``total``
counts every row of the whole answer. When ``more`` is true, the
``hint`` names the call that reads the next page. A page after
the last row gives one ``info`` dict that names the total.
Never empty: one dict with ``error`` (cannot resolve) or ``info``
(no results) replaces the results. Check both keys first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name to find transitive callers of. | |
| image | No | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. | |
| limit | No | Maximum results (default 50). | |
| offset | No | Skip this many results. Reads the next page of a deep call tree. | |
| project | No | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. | |
| variant | No | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. One query answers for ONE build. | |
| max_depth | No | Maximum BFS depth for transitive search (default 5). | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |