TraceWeave

Start from a single normalized failure_event and combine waveform, hierarchy, and source information to return recommended instances, signals, and source files.

Core failure-analysis tool. Focuses on the first occurrence of a single failure group and returns the log summary, raw error context, and waveform snapshot. FSDB support depends on fsdb_runtime.enabled.

Auto-build a Verdi KDB from a parsed compile log using vericom + elabcom. Use this when the simulator is Xcelium (xrun) and the NPI backend reports no KDB, or to force-refresh a stale cached KDB. Output is cached under TRACEWEAVE_CACHE_DIR (default ~/.cache/traceweave/kdb/<hash>/); cache hits reuse the previous KDB without re-invoking Verdi. When TRACEWEAVE_NPI_EXECUTION=lsf, every cache-miss/rebuild runs on the configured LSF queue and never falls back to a local licensed build. A runnable build.sh is written next to the KDB for inspection or reproduction. Requires VERDI_HOME with bin/vericom and bin/elabcom.

Stream one compile/elaborate log plus optional complementary phase logs, scan source files, and cache the full testbench hierarchy server-side without retaining raw source bodies. For split VCS flows, prefer the source-compile log as compile_log and pass VHDL/source/elaboration companions in build order; later connectivity tools continue using that primary path. Returns a SLIM payload: project, stats, tree_skeleton (depth 2), interfaces, ambiguous_basenames, build_metrics, and hierarchy_handle. A configured timeout/source-byte guard returns build_status='blocked' plus a fixed blocker and no handle. Use a completed handle with get_tb_subtree / lookup_tb_files / find_tb_instance / get_tb_file_detail / get_tb_class_hierarchy / dump_tb_section to access the full data on demand.

Delete a named cursor. Returns whether the cursor existed.

List all cursors registered in the current session, ordered by time.

Register a named time anchor (in ps) for the current session. Other tools that take a time may reference '@<name>' instead of copying ps integers across calls. Cursors are process-scoped and dropped on server restart. Names must match [A-Za-z_][A-Za-z0-9_-]*.

Find the first time two signals hold unequal values. Works across two waveforms (passing run vs failing run) or within one waveform between two signals (expected vs actual). Auto-registers a cursor at the divergence time so downstream calls can reference it by name. Reads existing waveforms only — does NOT rerun simulation.

Compare normalized failure events from two simulation logs. Returns resolved, persistent, and newly introduced failures, plus changes in failure type, X/Z presence, first-failure timing, and a convergence summary. If a simulator overwrites the same log path between runs, pass new_log_path only after parse_sim_log has captured the baseline snapshot, or pass snapshot IDs returned by parse_sim_log.

Escape hatch: return a named raw section of the full hierarchy result. Prefer targeted handle tools — this is intentionally heavy.

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.

List places that consume (load) a signal: child instance input ports, RHS of assigns/procedural assignments, and always-block sensitivity lists. When a Verdi KDB is detected, an NPI backend transparently engages and resolves the cross-hierarchy / interface-positional / generate-block cases that the static source-regex backend cannot reach. If NPI is unavailable or cannot return a trustworthy result, TraceWeave next attempts the bounded, on-demand Source Graph; Legacy Static remains the normal final fallback (shallow_only). When allow_bounded_bootstrap=true and no full hierarchy exists, only proved positive Source Graph facts are returned; an inconclusive/blocker does not trigger a whole-source Static rescan. backend_status preserves the complete attempt chain and Source Graph coverage/build receipt. claim_semantics separates confidence in returned positive load facts from whole-artifact coverage; exhaustive_search is required before treating the list as all loads, and negative_claim_allowed is required before claiming there are none. A complete Source Graph not_connected is distinct from an inconclusive no-match, which falls through to Static only on the normal full-hierarchy route. Every backend publishes enumeration.{returned_count, output_limit, output_truncated, search_exhaustive, incomplete_reasons, continuation_supported}. High-fanout output is capped at 256; capped positive loads remain usable but are not a complete list, and no backend currently promises a continuation token. Each load query normalizes trailing numeric selects for Legacy Static matching, while Source Graph validates the selected bits against the declaration. Each load carries source_info_origin ('compile_log', 'npi', or 'source_graph') so consumers can tell which provenance produced its file:line.

Locate instance(s) in the component_tree by exact path OR by module name. `path` and `module` are mutually exclusive.

Cold-start accelerator that aggregates cached tool results into a single summary view. It never triggers sub-steps and only reads cache. Returns availability status, compact summaries, and suggested calls for missing steps. The result cache is process-global and survives across cases, so at the start of a new session pass your target case (verif_root and/or case_dir): the snapshot validates the cache against it and reports a clean cold start if the cache belongs to a different case. If you pass no target, a cached sim_paths is returned with summary.carried_over=true to signal it may belong to a previous case — confirm it or re-run get_sim_paths.

Extract raw log text around a given error line. Typically used with first_line returned by parse_sim_log.

Query a signal value in a waveform file at a specific time in ps. FSDB support depends on fsdb_runtime.enabled.

Return transitions for a signal over the strict closed time range [start_time_ps, end_time_ps] (capped at 1000 by default; truncated=true + hint mark a clipped result, transition_count is always the total found). FSDB support depends on fsdb_runtime.enabled. The last value-change strictly before the window is returned separately as predecessor and is never mixed into transitions.

Return values and transitions for multiple signals in a NARROW window around a target timestamp (typically the failure time). Designed for local causal-chain inspection; NOT for bulk trace extraction. For round-by-round or multi-cycle sampling use get_signals_by_cycle. Unit reminder: all times are picoseconds. If the sim log reports `Time: X ns`, set center_time_ps = X*1000 (example: 75,100 ns -> 75,100,000 ps). Typical window_ps: - Glitch inspection: 1,000 - 5,000 ps - One clock cycle: = clock_period_ps (NOT exposed by get_waveform_summary; use get_signals_by_cycle after you identify a clock_path, or read it from your sim environment / compile log) - N cycles around fail: N * clock_period_ps The server enforces a cap of MAX_WAVE_WINDOW_CYCLES (default 256) clock cycles per call, computed at runtime from an auto-detected clock_period_ps. It also rejects center_time_ps past the recorded simulation end. For multi-cycle sampling, get_signals_by_cycle still requires an explicit clock_path. FSDB support depends on fsdb_runtime.enabled. If a value_at_center is a SUB-CYCLE TRANSIENT — a combinational glitch at the clock edge that settles back within the same cycle (e.g. an interconnect mux re-settling to idle for ~1ns at each edge) — the result sets `transient_note` and the signal carries `center_transient`/`center_settles_to`/`center_settle_ps`. Treat the SETTLED value as the protocol value; do not attribute a root cause to an edge-sampled value that is flagged transient. return_mode="values_only" keeps the atomic multi-signal sample but strips the transition lists from every signal: each entry carries value_at_center + window_transition_count (+ any transient annotation, computed before stripping). Use it when you only need the values at one instant — e.g. comparing the same time point across several traces — instead of paying for transition history or falling back to one get_signal_at_time call per signal.

Return cycle-by-cycle sampled values for multiple signals aligned to a clock edge. Useful for state machines, pipelines, and round-by-round algorithm checks.

Discover compile logs, simulation logs, and waveform files under a verif directory. If case_name is omitted, the tool returns available cases. For non-standard layouts you may pass explicit sim_log / wave_file / compile_log paths; any provided field is used as-is and the omitted ones are still auto-discovered (a sim_log path also anchors discovery of the matching waveform and compile/elab logs).

Return UVM/class inheritance tree built from compiled-source scan results. Use `root_class` to start from a specific class; empty = all roots.

Return symbols (modules/classes/interfaces) defined in a single compiled file. If the path is not in the compile set, error includes basename-similar suggestions.

Return a slice of the component_tree starting at `root` (dotted instance path) with up to `depth` levels. Use after build_tb_hierarchy to drill into a branch without pulling the whole tree into context.

Return basic waveform metadata such as format, duration, and top modules. FSDB support depends on fsdb_runtime.enabled.

Classify a clocked valid/ready handshake cycle-by-cycle and report protocol facts that leave no value pattern in scoreboard logs: stalls (valid high, ready low), the longest/over-threshold stall windows, backpressure imbalance (ready high, valid low), and — when payload signals are given — payload-hold violations (a payload that changes while the transfer is still stalled), and premature valid deassertion (a stalled beat whose valid/htrans drops before ready/HREADY arrives — the AHB master-not-waiting-for-HREADY bug, which needs no payload to detect). For AHB (valid_htrans) it ALSO runs x_while_valid (a control field is x/z while valid is asserted) and, when hwrite+write_data are given, a write data-phase HWDATA-hold check (HWDATA must stay stable through a write data-phase wait state). Protocol-agnostic: AXI *valid/*ready, an AHB pair (ready=hready, valid=a 1-bit 'htrans!=IDLE' signal, payload=[haddr,hwrite,hsize] address-phase control which must hold while hready is low; HWDATA goes in write_data, not payload), a generic valid-ready stream, or a credit interface. Returns coverage facts for the checks it actually ran (stall, backpressure, payload-hold, valid-hold, x-while-valid, write-data-hold) without assigning protocol side. Auto-registers a cursor at the first problem (x-while-valid > payload-hold > write-data hold > premature deassertion > long stall > longest stall). On AHB it also returns a protocol_semantics receipt naming which metrics are faithful vs suppressed. For the one-sided violations (x-while-valid, payload-hold, write-data hold, premature deassertion) it also returns a structured `attribution` block (violating_side=valid_driver, exonerated_side=ready_driver) so the caller does NOT start in the slave driver/monitor — the responder cannot cause either; a plain two-sided stall leaves attribution empty. Reads existing waveforms only — does NOT rerun simulation.

Query the compiled file set by objective scan facts. At least one filter is required. Use this to disambiguate multi-version files (basename collisions are also reported via build_tb_hierarchy.ambiguous_basenames).

Parse a VCS or Xcelium simulation log and return grouped runtime failures by signature. The simulator argument is required and is not auto-detected here. candidate_previous_logs uses bounded evidence sampling and excludes compile/elaboration logs. The first error group automatically includes about 100 lines of surrounding log context in first_group_context; use get_error_context for other groups.

Estimate a signal's dominant period inside a window and flag the first beat that deviates from it. Use for rhythm/throughput questions an LLM cannot eyeball from a transition dump: stalled clocks, dropped burst beats, backpressure bubbles, irregular strobes. The dominant period is the median edge-to-edge interval; the first off-beat is auto-registered as a cursor. Reads existing waveforms only — does NOT rerun simulation.

Choose the highest-priority failure to investigate from the current log, waveform, and optional hierarchy, then recommend signals, instances, and suspected failure class. Also suggests a diff_sim_failure_results call to use on the next run.

Reconstruct id-correlated request/response transactions from two handshake channels: walk every clock edge, match accepted request beats to completion beats by id, and return per-transaction latency plus aggregate facts (outstanding curve incl. per-id peak, ordering, unmatched=hang signature). One generic core, not a tool per protocol. AXI READ: req=AR (req_valid=arvalid, req_ready=arready, req_id=arid), cmp=R (cmp_valid=rvalid, cmp_ready=rready, cmp_id=rid, cmp_last=rlast); AXI WRITE: req=AW (awvalid/awready/awid), cmp=B (bvalid/bready/bid, no cmp_last). Pass req_fields/cmp_fields (e.g. araddr,arlen / rresp) to capture payload per txn; pass req_len (arlen/awlen) to also check each txn's beat_count against AxLEN+1 (beat_count_mismatch). Out-of-order completion across ids is supported (per-id FIFO); reorder_count is an informational FACT (legal in AXI), latency is a distribution not an 'outlier' verdict. Reads waveforms only.

Run a Scope 1 regex-based structural risk scan on RTL/TB source files from the compile file list. This is a heuristic detector: it reports suspicious patterns, not confirmed root causes. Always read coverage_status: only complete with total_risks=0 supports a clean-scan observation; zero_coverage scanned no supported sources, and degraded covers only part of the source set.

Search for signals in a waveform file (FSDB/VCD) and return full hierarchical paths. Use this when the client knows a leaf signal name but not the full path. keyword accepts a single string OR a list of strings: pass a list to batch several lookups in one call (one result entry per keyword, in input order) instead of issuing consecutive single-keyword searches. Each result also carries `direction` (input/output/inout/implicit/...) and `var_type` (wire/reg/integer/real/parameter/memory/...), so callers can filter by port direction or language type within a scope by combining a hierarchical keyword with these fields — no separate listing tool is needed. Note: VCD format does not encode port direction; `direction` is always null for VCD waves, while `var_type` is populated. FSDB populates both. FSDB search uses a scope-tree index and does not read value changes, so it scales well to large files. FSDB support depends on fsdb_runtime.enabled returned by get_sim_paths.

Scan a waveform and propose ready-to-use inspect_handshake bundles: it pairs *valid/*ready signals by scope and stem, finds the clock, and groups the channel payload buses (the signals that must hold steady during a stall). Use this BEFORE inspect_handshake so you don't have to hand-assemble {clock, valid, ready, payload} signal paths. Covers AXI *valid/*ready, generic valid/ready, and req/ack. It does NOT synthesise an AHB 'valid' (there is no literal valid signal — it is htrans != IDLE); use suggest_protocol_bundles for AHB/APB. Reads existing waveforms only.

Scan a waveform for protocol-specific AHB/APB bundles. AHB candidates return ready-to-use inspect_handshake args with valid_htrans + ready + payload (address-phase control), plus hwrite/write_data (HWDATA, for the write data-phase hold check) ONLY on initiator-side interfaces (a responder's HWDATA is an interconnect-mux output that glitches at the clock edge, so the check is withheld there to stay zero-FP), because AHB has no literal valid signal. APB candidates return psel/penable/pready facts and loudly report that inspect_handshake still needs a derived valid signal for psel && penable. Direction tags are mechanical discovery facts only; unknown/conflicting markers degrade to direction_tag='unknown' rather than guessing a side. Reads existing waveforms only.

Whole-design handshake anomaly sweep: discover EVERY valid/ready interface and every AHB interface, then inspect each over the window in one call, returning a comparative fact table (per-interface stalls, deadlock signature ended_in_stall, x-while-valid, payload-hold, write-data-hold, premature valid deassertion, backpressure) ordered by a transparent mechanical key. Use on opaque global symptoms (timeout/hang) when you don't know which of many interfaces misbehaves — it collapses N suggest+inspect round-trips into one. Always interpret flagged_count together with coverage_status: zero_coverage means no protocol interfaces were checked and is NOT a pass; truncated/degraded means partial coverage. Workflow follow-ups relay only parameter-changing retries: an unscoped zero-coverage result is not blindly replayed, but remains inconclusive. FSDB native transition-buffer truncation is propagated per row and forces degraded coverage; zero findings then cover only returned prefixes. Returns FACTS, not a root-cause verdict; re-rank as the symptom warrants. Reads existing waveforms only.

Find a structural connectivity path between two signals. A trusted Verdi NPI result wins; otherwise TraceWeave tries a bounded, dual-endpoint Source Graph before Legacy Static. Source Graph follows only projected IR facts across bindings and supported combinational dependencies. claim_semantics reports confidence in a proved positive path independently from global coverage; a found path is not an exhaustive enumeration. A no-path result is exact only when negative_claim_allowed=true; an inconclusive result falls through to unsupported_reason='static_backend_no_path_api'. This is connectivity, NOT temporal driver direction — use explain_signal_driver for driver semantics.

When a signal shows X/Z at a target time, trace its propagation chain through upstream driver logic. Uses the selected connectivity route (trusted local/LSF NPI, bounded Source Graph, then Static). A Source Graph trace may expand to bounded direct-child frontiers when an unresolved parent net can be driven by a child output. Any backend or artifact change discards the partial chain and restarts from the original signal, so one returned chain never mixes provenance. Connectivity queries run outside waveform locks. backend_status reports selected versus actual backend; trace_restarted reports a whole-trace retry. Source Graph chain nodes preserve claim_semantics, so an exact positive edge can be used without implying global coverage or exclusive drive. NPI testbench-driven/cross-check evidence is preserved on the node.

Evaluate a temporal predicate over a clock window and return a precise verdict (holds) plus a concrete witness/counterexample (cycle + sampled values). You state the predicate; the tool checks it against the waveform over thousands of cycles you cannot read yourself. Templates, not a DSL: a term is {signal, op, value} (op: eq/ne/gt/ge/lt/le/is_x/is_known); a predicate is a list of terms (implicit AND — run two calls for OR). Modes: always(P), never(P), eventually(P), implication (A |-> B within N cycles, the protocol-response template; set overlap=false for |=> = a stability/hold property where B must STILL hold the NEXT cycle, e.g. HTRANS/valid held through a wait state), and sequence (the per-accepted-beat increment of a signal — address-stride checks like AHB haddr +stride; supports modulo for WRAP bursts and restart_when for burst boundaries). x/z cycles are reported as unknown (never silently passed); an implication whose response window runs past end-of-trace is reported inconclusive (never silently failed). On a finding it sets violating_signal + a next_action to explain_signal_driver (bus facts do not self-attribute master/slave). Use to prove/disprove an RTL inference in one call. Reads existing waveforms only.