TraceWeave

🐙 TraceWeave

English · 简体中文

An MCP server for evidence-driven simulation debugging

TraceWeave is an MCP server for RTL / SoC debugging. It connects compile records, simulation logs, VCD/FSDB waveforms, and RTL source to your AI assistant, helping you work from a failed simulation to the relevant time, signals, and driving logic.

Use it with Claude Code, Codex, Copilot, or another MCP client. Describe the problem in natural language; the assistant uses tools to investigate, trace, and verify, with evidence you can review.

Use Cases · Installation · Client Setup · Start Debugging · Tool Quick Reference · FAQ · Documentation and Feedback

Use Cases

Supports VCS / Xcelium / Verilator simulation logs and VCD / FSDB / FST waveforms. Exported formal waveforms can also be queried; automatic artifact discovery currently supports JasperGold.

Optional FST support on Linux provides discovery, basic reads, fixed bit selections, expressions, cycle sampling, protocol and transaction analysis, cross-format comparison and X history. The summary lists the currently accepted tools.

Signal tracing (driver, load, and connectivity path queries) follows Verdi NPI → Source Graph → basic static analysis (Legacy Static) by default. It first queries the elaborated KDB; when NPI is unavailable or cannot provide a trustworthy result, it tries Source Graph without a commercial license, then falls back to basic static analysis where supported.

Source Graph counts independent structural writers separately from assignment statements. All retained branch evidence remains available; traversal reports writer, assignment inspection, and evidence limits separately. Overlapping writers are structural evidence, not proof of an observed value conflict. Bit provenance explicitly distinguishes found, proved_no_driver, and unknown, with reason codes and driver_set_complete. A budget or unsupported write never proves absence. If Static also cannot handle an inconclusive Source Graph query, the bounded Source Graph evidence and both attempts remain visible. Driver-chain and provenance rows share identical metadata within a writer; statement_evidence retains every source line and column. The legacy source_line names the first entry. query_instance_path names the queried instance, while resolved_instance_path keeps its historical head-driver meaning. VCD searches explain that direction=null means unavailable metadata.

Driver output migration: explain_signal_driver now defaults to traceweave.driver.compact.v1. Each response contains all retained evidence, with identical statement semantics and ordered locations/indices shared in typed evidence_tables. Legacy scripts should request output_format="full" to retain the original JSON shape and indentation, or decode the response:

from src.evidence_output import expand_compact_result

driver = expand_compact_result(text_content.text) print(driver["driver_chain"])

Reading only response["result"] does not expand its references. Table entries and location occurrences are not writer counts. Other tools keep their defaults and traceweave.compact.v1 contract. Distinct evidence can still produce large responses; this format does not guarantee inline delivery by every client.

Hierarchy handles live only in the server process. An explicit driver compile_context can recover a missing handle once under a 30-second, 4,096-source-file, 128-MiB read budget (stricter hierarchy settings apply). hierarchy_recovery reports reuse, rebuilding or a blocker. Supplied identity tokens are revalidated; without a historical source fingerprint, recovery establishes current sources only. Structural scanning remains a separate step.

Capabilities for large designs, with selected examples of validated scale:

• Hierarchy and source browsing on demand: the server builds and retains hierarchy and file indexes, then returns local results by instance, subtree, or file to keep large SoC queries manageable in the assistant's context. Hierarchy construction and local queries have been verified on a synthetic design with 50,500 logical instances; the initial build still scans compilation records and sources.
• Bulk handshake checks: sweep_handshakes discovers AHB / valid-ready interfaces and checks stalls, payload stability, and premature valid/HTRANS deassertion. A recorded design with 78,817 total signals and a 2.59 ms waveform yielded 49 candidate interfaces involving 262 clock/protocol signals; 35 interfaces were checked in about 4.65 minutes, with 14 skipped and partial coverage. Runtime and coverage depend on the waveform, interface types, and resource limits.
• GiB-scale log parsing: parse_sim_log has been verified on a 1 GiB synthetic log with 2,097,152 lines, finding all four errors at the beginning, middle, and end.

Installation

Requires Python 3.11+. Choose the installation that fits your environment:

Repository Installation

git clone https://github.com/gokeshenzhen/TraceWeave.git

cd TraceWeave export VERDI_HOME=/path/to/verdi bash scripts/install.sh

The installer prepares the Python environment, Source Graph, and FSDB reader, then checks the runtime. It leaves shell startup files and MCP client configuration untouched. FSDB support builds against the Synopsys FSDB Reader SDK in VERDI_HOME; TraceWeave does not redistribute its headers or libraries. Use of the FSDB Reader is subject to the applicable VC Apps Access Program Agreement (or successor). NPI and KDB operations also require the appropriate EDA runtime and license from your site.

For an existing installation, start with a read-only check:

bash scripts/install.sh --check

PyPI Installation

python3.11 -m pip install "traceweave-mcp[source-graph]"

traceweave-mcp --doctor

For logs, VCD, and basic static analysis only, install traceweave-mcp without [source-graph]. The PyPI package does not include the FSDB reader; use the repository installation for FSDB.

Optional FST reads

Install the extra in the MCP server's Python environment: python3.11 -m pip install "traceweave-mcp[fst]". For a repository installation, use .venv/bin/python -m pip install "pylibfst==0.2.1". Reconnect the server, then check traceweave-mcp --doctor or get_sim_paths. Existing VCD/FSDB users do not need this dependency.

For example, ask: “Find the FST waveform under /path/to/run, show its summary, find top.data, and read its transitions from 10 ns to 20 ns.” The basic tools preserve X/Z and distinguish missing recording intervals from observed values. Nonzero time offsets, real/string signals, external hierarchy files, and whole-file gzip containers are currently unsupported. Reads exceeding the bounded index, native memory, result, or time limits stop explicitly; narrow the query or use a smaller dump. See FST boundaries and resource limits.

Use the same analysis tools to inspect FST handshakes, reconstruct transactions, compare an FST signal against VCD/FSDB, or trace an earlier X after its input has recovered. Source-based analysis keeps its usual compile-context prerequisites. Recording gaps and incomplete clock history remain partial evidence.

Client Setup

After a repository installation, generate a client configuration template with absolute paths:

These commands only print templates. Add the output to your client's MCP configuration, supply any required site EDA environment variables, and reconnect the server. See the client configuration reference for complete examples.

Other MCP clients supporting stdio can use these connection settings:

LSF-only NPI licenses

If Verdi/NPI licenses are available only on LSF compute nodes, provide these settings to the MCP server process. Replace digital with your queue:

export TRACEWEAVE_NPI_EXECUTION=lsf

export TRACEWEAVE_NPI_LSF_QUEUE="digital"

The client must inherit or explicitly pass these variables. Project files, the TraceWeave installation, and cache directories must be visible at the same absolute paths on submission and compute nodes. See the [LSF configuration reference](https://github.com/gokeshenzhen/TraceWeave/blob/main/docs/