explain_signal_driver
Trace waveform signals upstream to the most likely RTL driver, crossing instance boundaries and handling mixed port bindings through recursive fan-in or source-graph projection.
Instructions
Trace a waveform signal path back to the most likely RTL driver. Supports direct assigns, simple always blocks, and module output ports. Set recursive=true to walk multiple hops upstream across instance boundaries. When a Verdi KDB is detected, an NPI backend transparently engages and walks the elaborated netlist with fan_in_reg_list, crossing instance port boundaries the static source-regex backend cannot reach. Recursive NPI fan-in is admitted inside the native traversal (4,096 states, 32 returned facts); Source Graph and NPI both publish traversal counts, limits, truncation, exhaustive-search, and fixed incomplete reasons. A partial positive prefix is usable evidence but not a complete or exclusive driver-set claim. If NPI is unavailable or cannot return a trustworthy result, TraceWeave next attempts a bounded, on-demand Source Graph projection; Legacy Static remains the normal final fallback. The explicit allow_bounded_bootstrap path is the resource-bounded exception: without a full hierarchy it returns only proved positive Source Graph facts, and an inconclusive/blocker result does not start a whole-source Static scan. Source Graph preserves per-bit port-binding provenance, so mixed bindings such as concatenations, constants, truncation, and width extension are reported as segments instead of forcing an all-or-nothing exact-width match. When a dynamic segment reaches a projection boundary, bounded sibling-scope expansion re-runs the original query from a fresh artifact; constant segments are terminal and never trigger expansion. Signal-not-declared and bit-selection-out-of-range are distinct Source Graph blockers. Legacy Static normalizes trailing numeric selects to the bare RTL symbol, but stops honestly at composite port expressions that need per-bit provenance. Parameter specializations and named generate scopes remain instance-specific; dotted packed struct/union members are mapped from their field-local indices onto exact root-aggregate bits. backend_status records the selected/attempted/actual backends, fixed fallback reason, Source Graph coverage and cache/build receipt. The legacy confidence field remains coverage-combined and conservative. For Source Graph results, claim_semantics separates positive_fact_confidence and target_bit_coverage from global_coverage_status; require exclusive_driver_proved before calling a returned driver unique, and negative_claim_allowed before claiming no driver. Warm Source Graph traversal is work-bounded; query_truncated and the query_*_limit coverage gap mean returned positive facts are usable but the driver set is not exhaustive. Each driver_chain hop carries source_info_origin ('compile_log', 'npi', or 'source_graph') so consumers can tell which provenance produced its file:line. driver_status='testbench_driven' (with cross_check.conflict=true) means NPI found NO RTL driver: the only 'driver' it reported is also a LOAD of the same net (an interface-slice alias or a register that reads the net), so the real driver is testbench/behavioral — a UVM driver writing through a virtual interface + clocking block, invisible to RTL fan-in. Treat that as 'start in the TB driver/BFM', NOT as a mis-wire or a DUT-register driver; for an AHB master's HTRANS/HADDR this is the expected, correct answer.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top_hint | No | ||
| max_depth | No | Maximum recursive depth when recursive=true | |
| recursive | No | Whether to trace the upstream driver chain recursively | |
| simulator | No | vcs / xcelium / auto. Optional — if omitted, server auto-injects the value discovered by get_sim_paths. | |
| wave_path | Yes | ||
| compile_log | Yes | ||
| signal_path | Yes | ||
| allow_bounded_bootstrap | No | If true and full hierarchy is unavailable, prove a hard-bounded single-endpoint Source Graph context. Only positive facts may be returned; no-match remains inconclusive and never triggers a whole-source Static rescan. | |
| supplementary_compile_logs | No | Optional complementary compile/elaboration logs used by bounded bootstrap when no hierarchy handle exists. |