trace_data_flow
Trace how a C/C++ data type flows through call paths to a target function. Uses libclang to map cross-file data flow, revealing how structures reach their destination.
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 functions whose signature mentions type_name, then looks for call paths from those functions 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).
timeout_ms: Maximum total execution time in milliseconds
(default 30000). Clamped to 1000–300000.
variant: Build variant (multi-build project). Omit to use
default_variant. One query answers for ONE build.
image: Sysbuild image within the variant. Required when the
variant holds several: each image is a separate program.
Returns:
list of dicts with a leading _summary entry:
{_summary (str), _type (str), _target (str)}, followed by source
entries each with: source_name, source_qualified_name, source_kind,
source_file, source_line, caller_count, reachable (bool), and
paths (list of call path dicts — empty when unreachable).
A source entry with ``timed_out: True`` means that the path search
stopped at the time limit for that source. Its ``reachable: False``
thus means "not proved reachable", not "proved unreachable".
Never empty: one dict with ``info`` replaces an empty result.
Check that key first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| limit | No | Maximum source functions to trace (default 15, max 15). | |
| 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 | Build variant (multi-build project). Omit to use default_variant. 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 |