trace_data_flow
Trace how a C/C++ data type flows to a target function by mapping call paths via libclang, revealing data movement across translation units.
Instructions
Trace how C/C++ data of a given type flows to a target function via libclang call paths. libclang-powered: finds functions by type signature and maps call paths through the full call graph, which text-based search cannot trace across translation units.
Finds definitions whose signature mentions type_name (substring match, any symbol kind, most-called first), then looks for call paths from those to to_symbol. Returns a data flow map — useful for understanding how a data structure travels through the system to its destination.
Works best for synchronous driver stacks (e.g. sensor read → I2C write).
Cannot follow async flows (message queues, interrupts, RS485 callbacks).
For exact call-graph queries use the find_* family;
verify specific paths with find_call_path.
Read-only. No side effects. Requires the reference index
(fw-context index — refs on by default).
Args:
type_name: Type name to trace. E.g. 'SensorData' or
'Config::SensorData'.
to_symbol: Target symbol name. E.g. 'uart_send' or
'UART_DRIVER::send'.
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 call path depth (default 8, max 20).
limit: Maximum source functions to trace (default 15, max 15).
offset: Skip this many source functions. Reads the next page;
the page notice names the offset to use.
timeout_ms: Maximum total execution time in milliseconds
(default 30000). Clamped to 1000–300000. The budget is for
one page.
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:
The page notice {total, offset, shown, more, hint} comes
before the rows of the answer: total counts every source function that matches. Then
a _summary entry for this page:
{_summary (str), _type (str), _target (str)}, followed by source
entries each with: source_name, source_qualified_name, source_kind,
source_file (absolute), source_line, caller_count, reachable
(bool), and paths (up to 3 path dicts as find_call_path gives
them; the key is absent when unreachable). When to_symbol
matches more than one symbol, a source entry also holds the
warning that names them, and each path its
target_qualified_name.
A source entry with ``timed_out: True`` means that the time budget
ran out before the search for that source began. Its
``reachable: False`` thus means "not checked", not "proved
unreachable". Such a source counts as shown, thus the hint goes
past it. To check it, call again with the same ``offset``: each
page gets the whole time budget.
A source entry with ``budget_spent: True`` means that the path
search of that source spent its budget of node expansions. Its
``reachable: False`` thus means "not found", not "proved
unreachable".
A page after the last source function gives one ``info`` dict
that names the total. Never empty: one dict with ``error`` or
``info`` replaces an empty result. Check both keys first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 source functions to trace (default 15, max 15). | |
| offset | No | Skip this many source functions. Reads the next page. | |
| 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 call path depth (default 8, max 20). | |
| to_symbol | Yes | Target symbol name. E.g. 'uart_send' or 'UART_DRIVER::send'. | |
| type_name | Yes | Type name to trace. E.g. 'SensorData' or 'Config::SensorData'. | |
| timeout_ms | No | Maximum total execution time in milliseconds (default 30000). | |
| 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 |