🐙 TraceWeave

English · 简体中文

Workflow-oriented MCP server for evidence-driven RTL simulation debugging

Connect compile evidence, logs, waveforms, source, and elaborated connectivity in one verifiable debug workflow.

TraceWeave turns local VCS/Xcelium simulation artifacts into a guided investigation. It discovers the active compile, simulation, and VCD/FSDB waveform inputs; builds the compiled hierarchy and an independent structural-risk view; normalizes failures; runs a whole-design runtime handshake sweep; and recommends the next evidence-gathering call.

Formal workflows have a separate artifact-only entry point. get_formal_paths performs bounded local discovery through tool-specific providers (currently JasperGold) and returns project directories, role-labeled logs, and exported VCD/FSDB files. It deliberately does not classify traces or interpret property or proof status.

For driver, load, structural-path, and X/Z-source questions, TraceWeave uses a provenance-preserving backend ladder: trusted Verdi NPI when a usable KDB is available, a bounded on-demand Slang Source Graph when NPI is unavailable or inconclusive, and Legacy Static as the final fallback. Results expose backend provenance, coverage, truncation, and fallback status rather than turning partial evidence into certainty.

_{Default workflow and connectivity-routing overview; every conclusion remains bounded by reported coverage.}

TraceWeave is a workflow-oriented debug server rather than a loose collection of parsers. It combines:

• A guided MCP workflow from artifact discovery through parallel hierarchy/structural analysis, failure parsing, runtime protocol scanning, and focused verification
• Compile-evidence hierarchy construction, handle-based browsing, and source-aware structural analysis
• VCD/FSDB point, transition, window, cycle, divergence, and period queries
• Whole-design handshake scanning, targeted protocol checks, temporal predicates, and transaction reconstruction
• Driver/load/path/X tracing through trusted NPI -> bounded Source Graph -> Legacy Static
• Structured next actions plus coverage, provenance, truncation, and resource receipts designed for MCP clients

Architecture · Installation · Client Setup · Standard MCP Workflow · Tool Quick Reference · Testing · WeChat

When TraceWeave helps most

TraceWeave adds the most value when debugging requires correlating evidence across artifacts rather than reading one obvious RTL line. It is especially useful for:

• Opaque runtime symptoms such as timeouts, hangs, scoreboard mismatches, X/Z propagation, first divergence, or a broken cadence. Waveform queries and protocol/transaction analysis locate the first bad time, interface, or beat.
• Cross-hierarchy cause-and-effect questions where a suspicious signal must be followed through ports, interfaces, assignments, drivers, and consumers.
• Large or interface-rich designs where whole-design handshake sweeps and bounded hierarchy/Source Graph scopes reduce an otherwise open-ended search.
• Falsifiable hypothesis checks that need a concrete witness or counterexample from verify_window, divergence, period, handshake, or reconstructed-transaction evidence.
• License-constrained environments where Source Graph provides semantic connectivity without NPI, while a usable KDB can still enable deeper local or LSF-hosted Verdi NPI analysis.

For a small readable block with an obvious source-local logic error, direct source and log inspection may be faster. TraceWeave also cannot reveal behavior absent from every available source, log, waveform, and KDB artifact; with protected IP it can follow only the evidence exposed at visible boundaries, in the waveform, or in the elaborated database.

Architecture

• Architecture map: docs/architecture.md
• New-session bootstrap: read AGENTS.md first, then follow its first-read file list
• Fast path for code understanding:
  • server.py
  • config.py
  • src/analyzer.py
  • src/log_parser.py
  • src/fsdb_parser.py

Repository Layout

TraceWeave/
├── config.py                 # Environment-sensitive constants and discovery rules
├── server.py                 # MCP entry point, session state, and workflow gating
├── custom_patterns.yaml      # User-extensible log patterns
├── fsdb_wrapper.cpp          # Native FSDB wrapper source
├── build_wrapper.sh          # Builds libfsdb_wrapper.so
├── scripts/                  # Full installer plus Source Graph / FSDB setup and verification
├── tests/                    # Unit and integration tests
└── src/
    ├── path_discovery.py
    ├── compile_log_parser.py
    ├── tb_hierarchy_builder.py
    ├── vcd_parser.py
    ├── fsdb_parser.py
    ├── fsdb_signal_index.py
    ├── waveform_batch.py         # FSDB+VCD time-window batch reader
    ├── log_parser.py
    ├── analyzer.py
    ├── signal_driver.py
    ├── signal_load.py            # Load/fanout finder, Static + NPI
    ├── connectivity_backend.py   # ConnectivityBackend protocol + select_backend
    ├── verdi_backend.py          # KDB / license probe + kdb_hint generator
    ├── verdi_npi_backend.py      # NPI-backed driver/load/path resolution
    ├── npi_lsf.py                # Optional LSF transport + Verdi/NPI worker protocol
    ├── npi_worker.py             # Compute-node Verdi/NPI worker entry point
    ├── kdb_builder.py            # Auto-build Verdi KDB (vericom + elabcom) for Xcelium flows
    ├── structural_scanner.py
    ├── x_trace.py
    ├── cycle_query.py
    ├── schemas.py
    ├── problem_hints.py
    ├── hierarchy_provider.py     # Bounded lexical/semantic instance-binding views
    ├── hierarchy_handles.py      # HandleStore + content-addressed handle for build_tb_hierarchy
    ├── handle_tools.py           # get_tb_subtree / lookup_tb_files / find_tb_instance / ...
    ├── cursor_store.py           # Named, process-scoped time anchors (cursor_set/list/delete)
    ├── timespec.py               # Resolve @cursor / unit literals (12.34ns) to ps on time inputs
    ├── verify_condition.py       # diff_first_divergence, period, inspect_handshake
    ├── window_verify.py          # verify_window: temporal predicate over a clock window
    ├── handshake_suggest.py      # suggest_handshakes / suggest_protocol_bundles
    ├── handshake_sweep.py        # sweep_handshakes: whole-design handshake anomaly sweep
    ├── txn_reconstruct.py        # reconstruct_transactions: id-correlated transaction layer
    ├── cancellation.py           # Cooperative cancellation for worker-thread waveform scans
    └── usage_telemetry.py        # Local-only per-call usage telemetry (default off; opt-in)

Installation

TraceWeave requires Python 3.11+.

Choose an installation profile

Use one installation profile from the start:

When a user gives an AI coding agent this repository URL and asks it to install TraceWeave, that means the repository-local full EDA profile unless the user explicitly asks for the portable PyPI profile. Do not extend a PyPI environment with repository FSDB setup scripts: the wheel and the repository resolve the native wrapper from different runtime roots.

Repository-local full EDA installation

This is the recommended profile on simulation hosts and for users who have a local Verdi installation. It keeps Python packages, the FSDB wrapper, and the runtime links together under one repository root:

git clone https://github.com/gokeshenzhen/TraceWeave.git
cd TraceWeave
export VERDI_HOME=/path/to/verdi
bash scripts/install.sh

Alternatively, pass the Verdi root for this installer process only:

bash scripts/install.sh --verdi-home /path/to/verdi