TraceWeave

🐙 TraceWeave

英語 · 簡体字中国語

証拠に基づくシミュレーションデバッグのための MCP サーバー

TraceWeave は、RTL／SoC デバッグ用の MCP サーバーです。コンパイル記録、シミュレーションログ、VCD／FSDB 波形、RTL ソースを AI アシスタントに接続し、シミュレーションの失敗から関連する時刻、信号、駆動ロジックの特定を支援します。

Claude Code、Codex、Copilot、またはその他の MCP クライアントと一緒に使用できます。問題を自然言語で説明すると、アシスタントがツールを使って調査、追跡、検証を行い、確認可能な証拠を提示します。

ユースケース · インストール · クライアントの設定 · デバッグを開始 · ツールのクイックリファレンス · FAQ · ドキュメントとフィードバック

ユースケース

問題	TraceWeave の支援内容
シミュレーションがタイムアウトまたはハングし、明確な手掛かりがない	失敗を要約し、インターフェースのハンドシェイクをスキャンして、影響を受けたインターフェースと時間範囲を絞り込みます
スコアボードの不一致、または実行ごとに結果が異なる	失敗記録と波形を比較し、観測された差異を特定して、両側のデータソースと制御ソースを追跡します
信号が X／Z になる	ドライバーをたどり、波形履歴を確認して、レジスターが未知の値をサンプリングして保持したかどうかを調べます
パックされたバスが読み取りにくい、または TL-UL リクエストが完了しない	アドレス、データ、制御フィールドを個別に調べたうえで、リクエスト／レスポンスのハンドシェイク、レイテンシ、完了を確認します
タイ定数、未接続入力、またはマジックワード条件が疑われる	調査の手掛かりとして、ソースコードを静的にスキャンし、定数接続、未接続入力、定数との比較を探します。シミュレーション実行や波形は不要です
モジュールとインターフェースが多数ある深い SoC 階層	必要に応じて階層を参照し、インスタンスとソースファイルを特定して、ドライバー、コンシューマー、接続経路をたどります
デバッグ仮説の証拠が必要	サイクル単位でサンプリングし、タイミング条件、ハンドシェイクの安定性、トランザクションの完了を確認します

VCS／Xcelium／Verilator のシミュレーションログと、VCD／FSDB／FST の波形をサポートしています。エクスポートされたフォーマル波形も照会できます。成果物の自動検出が現在サポートされているのは JasperGold です。

Linux でのオプションの FST サポートでは、検出、基本的な読み取り、固定ビット選択、式、サイクルサンプリング、プロトコルおよびトランザクション分析、フォーマット間比較、X 履歴を利用できます。現在受け付けているツールは概要に記載されています。 信号トレース（ドライバー、負荷、接続経路のクエリ）は、デフォルトで Verdi NPI → Source Graph → 基本静的解析（Legacy Static） の順に実行されます。まずエラボレーション済みの KDB をクエリします。NPI を利用できない場合、または信頼できる結果を取得できない場合は、商用ライセンスを必要としない Source Graph を試し、その後、対応している場合は基本静的解析にフォールバックします。

Source Graph は、独立した構造上のライターを代入文とは別にカウントします。保持されたすべての分岐の証拠は引き続き利用でき、traversal ではライター、代入の検査、証拠の制限を個別に報告します。重複するライターは構造上の証拠であり、値の競合が実際に観測されたことを示すものではありません。ビットの来歴では、found、proved_no_driver、unknown を明示的に区別し、理由コードと driver_set_complete も示します。予算超過や未対応の書き込みによって、ドライバーが存在しないと証明されることはありません。Source Graph のクエリが決定的でなく、Static も処理できない場合は、制限付きの Source Graph の証拠と両方の試行が引き続き表示されます。

ドライバーチェーンと来歴の各行では、同一のライター内でメタデータが一致します。statement_evidence には、すべてのソース行と列が保持されます。従来の source_line は最初の項目を示します。query_instance_path はクエリ対象のインスタンスを示し、resolved_instance_path は従来どおりヘッドドライバーを示します。VCD 検索では、direction=null はメタデータを利用できないことを意味すると説明されます。

ドライバー出力の移行： explain_signal_driver のデフォルトは traceweave.driver.compact.v1 になりました。各レスポンスには保持されたすべての証拠が含まれ、型付きの evidence_tables 内で、同一の文の意味と順序付けされた位置／インデックスが共有されます。従来のスクリプトで元の JSON 形式とインデントを維持するには、output_format="full" を指定するか、レスポンスをデコードしてください。

from src.evidence_output import expand_compact_result
driver = expand_compact_result(text_content.text)
print(driver["driver_chain"])

response["result"] のみを読み取っても、参照先は展開されません。テーブル項目と位置の出現回数は、ライター数を示すものではありません。他のツールは、従来のデフォルトと traceweave.compact.v1 の契約を維持します。異なる証拠が含まれる場合、レスポンスが大きくなることがあります。また、この形式では、すべてのクライアントによるインライン配信は保証されません。

階層ハンドルはサーバープロセス内にのみ存在します。明示的なドライバー compile_context は、ハンドルが見つからない場合に、30 秒、4,096 個のソースファイル、128 MiB の読み取り予算の範囲で一度だけ復元できます（より厳しい階層設定が適用されます）。hierarchy_recovery には、再利用、再構築、または阻害要因が報告されます。指定された ID トークンは再検証されます。過去のソースフィンガープリントがない場合、復元で確定できるのは現在のソースのみです。構造スキャンは別のステップとして実行されます。

大規模な設計向けの機能と、検証済みスケールの例を以下に示します。

• 必要に応じた階層とソースのブラウジング：サーバーは階層インデックスとファイルインデックスを構築して保持し、インスタンス、サブツリー、またはファイル単位でローカルな結果を返します。これにより、アシスタントのコンテキスト内で大規模な SoC クエリを管理しやすくなります。階層構築とローカルクエリは、論理インスタンス数 50,500 個の合成設計で検証済みです。初回の構築では、引き続きコンパイルレコードとソースをスキャンします。
• 一括ハンドシェイク検査：sweep_handshakes は AHB／valid-ready インターフェースを検出し、ストール、ペイロードの安定性、valid／HTRANS の早期デアサーションを検査します。合計 78,817 個の信号と 2.59 ms の波形を含む記録済み設計では、クロック／プロトコル信号を 262 個含む候補インターフェースが 49 個特定されました。そのうち 35 個のインターフェースを約 4.65 分で検査し、14 個はスキップされ、カバレッジは部分的でした。実行時間とカバレッジは、波形、インターフェースの種類、リソース制限によって異なります。
• GiB 規模のログ解析：parse_sim_log は、2,097,152 行の 1 GiB の合成ログで検証済みです。先頭、中間、末尾にある 4 件すべてのエラーを検出します。

インストール

Python 3.11 以降が必要です。環境に合ったインストール方法を選択してください。

インストール方法	想定用途
リポジトリ	FSDB、Source Graph、オプションの NPI／LSF を利用する、既存の Verdi インストール環境があるシミュレーションホスト
PyPI	ログおよび VCD の解析、または商用ライセンスを必要としない Source Graph

リポジトリのインストール

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

インストーラーは Python 環境、Source Graph、FSDB リーダーを準備し、その後ランタイムを確認します。シェルの起動ファイルや MCP クライアントの設定は変更しません。FSDB のサポートは VERDI_HOME にある Synopsys FSDB Reader SDK を使用してビルドされます。TraceWeave はそのヘッダーやライブラリを再配布しません。FSDB Reader の使用には、該当する VC Apps Access Program Agreement（またはその後継契約）が適用されます。NPI および KDB の操作にも、サイトで適切な EDA ランタイムとライセンスが必要です。

既存のインストールでは、まず読み取り専用のチェックを実行します。

bash scripts/install.sh --check

PyPI からのインストール

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

ログ、VCD、基本的な静的解析のみを使用する場合は、[source-graph] を付けずに traceweave-mcp をインストールします。PyPI パッケージには FSDB リーダーが含まれていません。FSDB を使用するには、リポジトリからインストールしてください。

FST の読み取り（オプション）

MCP サーバーの Python 環境に追加機能をインストールします。python3.11 -m pip install "traceweave-mcp[fst]"。リポジトリからインストールした場合は、.venv/bin/python -m pip install "pylibfst==0.2.1" を使用します。サーバーに再接続してから、traceweave-mcp --doctor または get_sim_paths を確認してください。既存の VCD/FSDB ユーザーは、この依存関係を追加する必要はありません。

たとえば、次のように依頼できます。「/path/to/run 以下にある FST 波形を見つけて、概要を表示し、top.data を見つけて、10 ns から 20 ns までの遷移を読み取ってください。」基本ツールは X/Z を保持し、記録がない区間と観測された値を区別します。ゼロ以外の時間オフセット、実数型／文字列型信号、外部階層ファイル、ファイル全体を gzip で圧縮したコンテナーは現在サポートされていません。上限のあるインデックス、ネイティブメモリ、結果、または時間の制限を超える読み取りは、明示的に停止します。クエリの範囲を絞るか、より小さいダンプを使用してください。FST の制限とリソース上限を参照してください。

同じ解析ツールを使って、FST のハンドシェイクを調査したり、トランザクションを再構築したり、FST の信号を VCD/FSDB と比較したり、入力が回復した後に以前の X を追跡したりできます。ソースベースの解析では、通常どおりコンパイルコンテキストの前提条件が適用されます。記録の欠落や不完全なクロック履歴は、引き続き部分的な証拠です。

クライアントの設定

リポジトリからインストールした後、絶対パスを含むクライアント設定テンプレートを生成します。

クライアント	設定テンプレートの生成
Claude Code	bash scripts/install.sh --print-config claude
Codex	bash scripts/install.sh --print-config codex
Copilot	bash scripts/install.sh --print-config copilot

これらのコマンドはテンプレートを表示するだけです。出力をクライアントの MCP 設定に追加し、必要なサイトの EDA 環境変数を設定して、サーバーに再接続します。完全な例については、クライアント設定のリファレンスを参照してください。

stdio に対応するその他の MCP クライアントでは、次の接続設定を使用できます。

インストール方法	command	args
リポジトリ	<absolute-repository-path>/.venv/bin/python	["<absolute-repository-path>/server.py"]
PyPI	traceweave-mcp、またはその絶対パス	[]

LSF 専用の NPI ライセンス

Verdi/NPI ライセンスを LSF 計算ノードでのみ使用できる場合は、MCP サーバープロセスに次の設定を渡します。digital を使用するキュー名に置き換えてください。

export TRACEWEAVE_NPI_EXECUTION=lsf
export TRACEWEAVE_NPI_LSF_QUEUE="digital"

クライアントはこれらの変数を継承するか、明示的に渡す必要があります。プロジェクトファイル、TraceWeave のインストール先、キャッシュディレクトリは、投入ノードと計算ノードで同じ絶対パスから参照できる必要があります。bash / tcsh の例、クライアントへの環境変数の転送、確認手順については、LSF 設定のリファレンスを参照してください。

デバッグを開始する

接続したら、パスをプロジェクトのディレクトリに置き換えて、次のようなリクエストを試してください。

TraceWeave を使って、/path/to/verif にある my_case のシミュレーション失敗を調査してください。まずログ、設計構造、インターフェースのハンドシェイクを確認し、次に疑わしい信号を追跡してください。調査結果には、タイムスタンプ、信号、ソースへの参照を含めてください。

具体的な質問から始めることもできます。

2 つの波形の tb.dut.result を比較し、それぞれで差異を生じさせているロジックを追跡してください。

ディープモードを使って、このコンパイルログに記載された設計をスキャンし、疑わしいタイ、未接続入力、定数との比較を見つけてください。

アシスタントのデフォルトの調査では、次の手順に従います。

1. 実行時の成果物を見つける： コンパイルログ、シミュレーションログ、波形を特定します。
2. 設計のコンテキストを把握する： 同じコンパイルログを使って、階層構造を構築し、構造上のリスクを並行してスキャンします。
3. 調査対象を絞り込む： 波形がある失敗実行について、失敗を解析し、ハンドシェイクをスキャンします。
4. 追跡して検証する： 信号、ドライバー、コンシューマーを調べ、ウィンドウまたはサイクルのチェックで仮説を検証します。
5. 修正後に比較する： 次の実行で、失敗の記録と波形がどのように変わったかを確認します。

初回の接続確認では、アシスタントに get_sim_paths を呼び出すよう依頼し、実際の MCP ツール呼び出しが実行されることを確認してください。全手順については、デバッグワークフローを参照してください。

EDA ライセンスなしでリポジトリの読み戻しを確認するには、 .venv/bin/python scripts/check_waveform_readback.py --work-dir /tmp/traceweave-readback-check を実行してください。 このスクリプトは、サーバーカタログと、MCP 経由で取得した実際のポイント値／バッチ値を確認し、 別途実施する AI クライアントのスモークセッション用に明示的なリクエストを表示します。サーバーチェックだけでは、 AI クライアントからの可視性とモデルの利用状況は検証されません。読み戻しチェックの手順を参照してください。

波形の差異を見つけ、X/Z の発生源を追跡する

2 つのシミュレーション実行で結果が異なる場合、TraceWeave は選択した信号を比較し、時間ウィンドウ内で確認できる最も早い差異を特定して、両方の側で関連するデータ、制御、RTL ロジックを追跡できます。

X/Z については、対象時刻の伝播経路を調べるか、履歴をさかのぼって、レジスターが不定値をサンプリングして保持し続けたかを確認してください。入力が現在は既知であっても、過去のイベントを調査できます。

tb.dut.q は 36 ns で X ですが、現在は入力値が既知です。0～36 ns の波形を確認し、それ以前のサンプリングと保持の動作を調べ、考えられる発生源を追跡してください。

結果では、証拠に裏付けられた関係と、さらなる調査が必要な手がかりを区別します。履歴が欠けている場合や、未対応の構造がある場合は、TraceWeave は追跡がどこで停止したかを説明します。最初に記録された異常が、必ずしも真の発生源とは限りません。

ツールのパラメーターと詳細なサポート範囲については、波形比較とX/Z 履歴の追跡を参照してください。

SV 式を評価する

既存の波形ツールは、{ "expr": "a[b] + c", ... } のような明示的な入力を受け付けます。式では、SV の優先順位、幅、符号の有無、4 状態値が使われます。インデックスは観測のたびに再サンプリングされます。ポイント、サイクル、遷移、ウィンドウ、ハンドシェイク、トランザクション、TL-UL の各クエリは、RTL の逆追跡と同じ中核機能を共有します。追加の MCP ツールは必要ありません。

正確な bindings と明示的な types を使うか、typing: "wave_bits" を指定して、ダンプされたベクターを符号なしの4状態値として扱ってください。固定配列では、要素を範囲内にマッピングします。式の値を読み取っても、記録された出力信号は置き換えられません。式の入力、例、制限を参照してください。

バスフィールドと TL-UL インターフェースの検査

アドレス、データ、制御情報がパックされたバスを共有している場合、TraceWeave は波形と一致するソース型からフィールド位置を特定できます。その後、アシスタントは個々のフィールドを検査できるため、幅を調べてオフセットを計算する手作業を減らせます。自動解決できない場合は、フィールドとビット位置の対応を指定することもできます。

TL-UL インターフェースでは、アシスタントがフィールドの対応とクロックを確認すると、指定した時間範囲内でハンドシェイクの停滞、要求と応答の対応、応答レイテンシ、未完了の要求を確認できます。

tb.dut 配下の TL-UL インターフェースについて、10～20 μs の範囲でハンドシェイクの停滞や未完了の要求がないか確認してください。該当する時刻と信号を一覧表示してください。

結果には、実行したチェックと不足している情報が示されます。時間範囲の終了時点で未完了の要求があっても、自動的にデッドロックとは判定されません。また、これらのチェックは TL-UL プロトコルの完全な検証に代わるものではありません。

長いデバッグ会話では、簡潔なエビデンス出力を依頼してください。繰り返されるフィールドの対応は一度だけ表示されますが、チェックした範囲、不足しているエビデンス、時間境界、次の手順は引き続き確認できます。これらの波形ツールは、デフォルトで通常どおりの出力を維持します。ドライバーの出力については、上記の移行に従います。例とクライアント統合については、簡潔なエビデンス出力を参照してください。

フィールド設定と詳細なサポート範囲については、バスフィールドと TL-ULを参照してください。

カスタムランタイムエラー形式

Verilator ランタイムログ

parse_sim_log(log_path=..., simulator="verilator") は、ネイティブのランタイム アサーション／$error／$fatal／$stop、Python のトレースバックを一定範囲に制限した cocotb テスト失敗、 X-HEEP example_dma の比較結果とソフトウェアの終了値、および OpenTitan のソフトウェア比較／ステータス失敗を認識します。コンパイラーの警告とエラー、 ERROR:cocotb: ロガーのラッパー、ソースコードのエコー、通常の $finish、ソフトウェアの終了コード 0 は除外されます。 その他のカスタム TB テキストには、明示的なカスタムパターンが必要です。

単位のないネイティブタイムスタンプは、独立して検証済みの TB／コンテキストのエビデンスとともに native_time_unit="ps"（または fs/ns/us/ms/s）が指定されていない限り、time_ps=None のままです。 この設定は、単位のないネイティブ／カスタム／UVM シミュレーションタイムスタンプにのみ適用されます。 単位が明示されている場合は、その単位が優先されます。変換には正確な十進演算を使用し、 1 ps 未満の時間は整数 ps に切り上げます。サイクル数、UART の行、ホストの実時間には、 波形タイムスタンプが付与されません。オプションの TraceWeave 受け入れオブザーバーが提供するのは、 ソフトウェア終了または停止のアンカーであり、不正な RTL トランザクションの最初の発生箇所ではありません。 検出元として示されるソース位置はチェッカーの位置であり、根本原因ではありません。 解析とスナップショット／ログの差分呼び出しで、同じ検証済み単位設定を使用してください。 設定が異なるスナップショットは比較できません。不明な時刻の解析では、0ps を照会せずにログのコンテキストを返します。

Verilator の検出では、遅れて表示される cocotb バナーも含め、長さを制限したログの先頭と末尾のサンプルを読み取ります。 階層解析と構造解析には、明示的な --top-module、実行時の作業ディレクトリ （たとえば Make のディレクトリ移動を示す行）、利用可能な順序付きの -f／-F 入力を指定した、実際の HDL 呼び出し（verilator --cc/--xml-only ...）が必要です。 インクルードパス、マクロ、トップモジュールのパラメーター上書きは、既存の Source Graph フロントエンドに引き継がれます。 C++ ファイルと .vlt 制御ファイルは HDL ではありません。ウェイバー／トレース／オプティマイザーの制御項目は、 サポート入力としてフィンガープリントされます。モデル化されていない制御項目は、明示的なカバレッジ対象外のままです。 HDL コマンド、ファイルリスト、トップモジュールがない場合は、引き続き不足項目として扱われます。 C++ ビルドログだけでは HDL コンテキストは得られません。無関係なサイドカーファイルやベンダーツリーを 自動的に探索して復元する機能はありません。 同じコンパイルログに対して、まず get_sim_paths を実行し、続いて build_tb_hierarchy と scan_structural_risks を並行して実行してから、実行結果を解析してください。波形がある失敗実行では sweep_handshakes が必要です。カバレッジがゼロまたは不完全でも、OBI の失敗が除外されるわけではありません。ソースクエリでは、実際にエラボレーションされた HDL のトップパスを使用します。Verilator の合成波形にある TOP. プレフィックスは HDL のインスタンスではありません（後続のセグメントがコンパイルされたトップであることを確認してから削除してください）。Static/Source Graph のカバレッジには引き続き制限があり、Verilator NPI/KDB バックエンドは導入されません。

parse_sim_log は、標準的な UVM_ERROR / UVM_FATAL メッセージと、VCS / Xcelium のアサーション失敗をすでに認識します。また、汎用の ERROR フォールバックもあります。プロジェクト固有のチェッカー、スコアボード、または $display の出力には、custom_patterns.yaml に Python 正規表現を追加してください。カスタムメッセージに UVM_ERROR や ERROR を含める必要はありません。Python の変更も不要です。

メッセージに共通のラベルがあり、その後のテキストが変化する場合は、そのラベルに一致させるだけで十分です。

MY_CHECK_FAIL @ 12.5 ns expected=0x12 actual=0x34
MY_CHECK_FAIL @ 20 ns timeout waiting for response

デフォルトの patterns: [] を次の内容に置き換えるか、既存の patterns リストにルールを追加してください。

patterns:
  - name: my_checker
    severity: ERROR
    regex: '^MY_CHECK_FAIL'

^ は行の先頭を意味します。ラベルの後は何が続いてもよく、追加の正規表現は必要ありません。タイムスタンプなどのテキストがラベルの前にある場合は、regex: 'MY_CHECK_FAIL' を使用して行内の任意の位置に一致させてください。

• name は失敗グループを識別します。severity のデフォルトは ERROR です。FATAL と WARNING もサポートされています。一致したカスタム警告は、実行時の失敗件数に含まれます。description はメンテナー向けです。
• regex はログの各行に個別に一致させます。バックスラッシュを保持するには、YAML のシングルクォートを使用してください。組み込みのアサーションおよび UVM の解析が最初に実行され、続いてカスタムルールがリスト順に処理されます（一致した最初のルールが採用されます）。その後、汎用の ERROR フォールバックが実行されます。認識済みのコンパイル／エラボレーション診断は引き続き除外されます。

上記の expected=0x12 actual=0x34 形式はすでに自動認識されるため、シンプルなラベルルールだけで十分であり、名前付きキャプチャは不要です。ログで独自のフィールド名を使用している場合は、次のようになります。

MY_CHECK_FAIL @ 12.5 ns want=0x12 have=0x34

regex: '^MY_CHECK_FAIL' でもエラーは認識され、メッセージ全体が保持されます。want と have を期待値および実際の値として抽出するには、上記のルールの regex を次の内容に置き換えてください。

regex: '^MY_CHECK_FAIL.*want=(?P<expected>\S+)\s+have=(?P<actual>\S+)'

リポジトリへのインストールでは、デフォルトでルートの custom_patterns.yaml が使用されます。プロジェクトルールを別の場所に保持する場合、または PyPI 版を使用する場合は、上記の YAML を独自のファイルに保存し、その絶対パスを MCP サーバープロセスに渡してください。

export TRACEWEAVE_CUSTOM_PATTERNS_FILE="/absolute/path/to/custom_patterns.yaml"

これにより、デフォルトのカスタムルールではなく、そのファイルが選択されます。組み込み形式は引き続き有効です。MCP クライアントでは、環境変数を継承するか、明示的に転送する必要があります。変更後はサーバーを再起動するか再接続してから、ログをもう一度解析してください。選択した YAML の編集内容は、次回の parse_sim_log 呼び出し時に読み込まれます。

ツールのクイックリファレンス

通常は、デバッグの目的を説明すれば、アシスタントが適切なツールを選択します。この表では目的別にすべてのツールを一覧にしています。パラメーターについては MCP ツールの定義を参照してください。

カテゴリ	ツール	説明
セッションとアーティファクト	get_sim_paths	シミュレーションケース、コンパイルログ、実行時ログ、波形を検索します
	get_formal_paths	フォーマル検証プロジェクト、ログ、エクスポートされた波形を検索します。現在はJasperGoldをサポートしています
	get_diagnostic_snapshot	収集されたデバッグ情報と未完了の手順を確認します
階層とソース	build_tb_hierarchy	コンパイル記録からRTL／テストベンチの階層ビューを構築します
	get_tb_subtree	選択したインスタンスのローカル階層を参照します
	find_tb_instance	パスまたはモジュール名でインスタンスを検索します
	lookup_tb_files	実際にコンパイルされたファイルセット内のソースファイルを検索します
	get_tb_file_detail	ソースファイル内で定義されたモジュール、インターフェース、クラスを調べます
	get_tb_class_hierarchy	UVM／SystemVerilogクラスの継承関係を参照します
	dump_tb_section	階層解析データのセクション全体を取得します
ログと障害	parse_sim_log	実行時の障害を分類し、タイムスタンプとエラーの概要を抽出します
	get_error_context	エラー発生箇所の前後にある元のログを読み取ります
	diff_sim_failure_results	実行間で新規、継続、解消した障害を比較します
	analyze_failures	障害グループのログと波形の情報を組み合わせます
	analyze_failure_event	1件の障害について、候補となるインスタンス、信号、ソースファイルを特定します
	recommend_failure_debug_next_steps	調査対象と、次に呼び出すツールを提案します
静的な構造スキャン	scan_structural_risks	ソースコードを静的にスキャンして疑わしい構造を検出します。セマンティックモードでは、タイ結線、未接続入力、定数比較を確認します
信号トレース	explain_signal_driver	信号の駆動元と関連するRTLをトレースします
	find_signal_loads	信号の受け手と潜在的な影響を特定します
	trace_signal_path	2つの信号間の構造的な接続を調べます
	trace_x_source	X／Zの伝播をトレースし、過去のレジスタのサンプリングと保持動作を調べます
波形クエリ	get_waveform_summary	波形の形式、期間、タイムスケール、トップモジュールを調べます
	search_signals	名前で信号の完全なパスを検索します
	get_signal_at_time	特定の時刻における信号の値を読み取ります
	get_signal_transitions	指定した時間範囲内の信号遷移を調べます
	get_signals_around_time	選択した時刻の前後における複数の信号を調べます
	get_signals_by_cycle	クロックエッジで複数の信号をサンプリングします
差分とタイミング	diff_first_divergence	2つの信号間で、最初に観測された既知値の差を特定します
	trace_divergence	波形の差を検証し、両側の関連するデータ、制御、前状態をトレースします
	period	信号の周期と周期性の異常を確認します
	verify_window	波形ウィンドウ内の時間条件を検証し、具体的な証拠を返します
プロトコルとトランザクション	suggest_handshakes	検査対象となるvalid／readyインターフェースと信号バンドルを検出します
	suggest_protocol_bundles	AHB／APBインターフェースの信号バンドルを検出します
	sweep_handshakes	設計全体で検出済みのvalid／readyインターフェースとAHBインターフェースをスキャンし、異常を要約します
	inspect_handshake	1つのインターフェースについて、停止、安定性、ハンドシェイクの異常を確認します
	reconstruct_transactions	リクエストとレスポンスを再構築し、レイテンシ、未処理リクエスト、順序を調べます
	resolve_packed_fields	パックされたバスフィールドを特定し、アドレス、データ、制御信号を個別に調べます
	inspect_tlul	TL-ULのリクエストとレスポンスについて、ハンドシェイクの停止、レスポンスのレイテンシ、未処理リクエストを確認します
時間カーソル	cursor_set	後続のクエリで再利用する重要なタイムスタンプに名前を付けます
	cursor_list	現在のセッションの時間カーソルを一覧表示します
	cursor_delete	時間カーソルを削除します
EDA統合	build_kdb	NPIクエリ用に、コンパイル記録からVerdi KDBを構築してキャッシュします

## よくある質問

商用ライセンスなしで TraceWeave を使用できますか？

ログ解析、VCD クエリ、静的構造スキャン、Source Graph には商用ライセンスは不要です。既存の波形に対する直接値クエリと遷移クエリには NPI ライセンスは不要です。VCD では組み込みパーサーを使用しますが、FSDB ではローカルの Verdi FSDB Reader を使用し、上記の契約が引き続き適用されます。Verdi NPI による信号トレースと KDB のビルドには、対応する EDA 環境とライセンスが必要です。

不足しているパス変数を自動的に復元できますか？

はい。プロジェクトのセットアップスクリプトを読み込んでいないターミナルで CLI エージェントを使用する場合や、別のターミナルから起動した実行のログや波形を渡す場合に利用できます。値を一意に特定できる場合、TraceWeave は VCS のコンパイルログとファイルリストからコンパイル入力パス変数を復元し、階層解析、KDB のビルド、Source Graph クエリを可能にします。

復元の対象はコンパイル入力パスです。対応するソースファイルとインクルードファイルには引き続きアクセスできる必要があります。実行時の前提条件も、あらかじめ満たしておく必要があります。KDB のビルドには VERDI_HOME、インストール済みの EDA ツール、ライセンス設定が必要です。また、Source Graph には Python と pyslang の依存関係が必要です。

信号トレースの精度はどのように判断すればよいですか？

NPI は現在の設計に一致する展開済み KDB を使用し、Source Graph はソースから意味的な接続グラフを構築します。コンパイルコンテキストが完全で、対象のセマンティクスがサポートされ、クエリの対象範囲が完全で、解決が正確であり、切り詰めがない場合、ドライバー、負荷、接続経路の解析結果は、現在のクエリ範囲内における正確な構造上の接続事実として扱えます。

シミュレーション結果なしで静的構造スキャンを実行できますか？

はい。scan_structural_risks は、シミュレーションを実行せず、シミュレーション実行ログや VCD／FSDB 波形も読み取らずに、ソースの静的解析を実行します。現在のインターフェースでは、コンパイル／展開ログ（compile_log）と、対応するソースファイルおよびインクルードファイルへのアクセスが必要です。そのため、シミュレーション実行前でも、コンパイル／展開後に使用できます。

静的構造スキャンでは、auto と deep をどのように選べばよいですか？

デフォルトの auto モードでは、ソーステキストのチェックを実行し、利用可能な互換性のある意味解析結果を再利用します。定数接続、未接続の入力などについて新たな意味解析スキャンが必要な場合は、アシスタントに deep を使用するよう依頼してください。analysis_mode パラメーターは呼び出しごとに適用され、クライアントの設定変更は不要です。検出結果は調査の手掛かりです。正当なタイオフやプロトコル定数も検出される場合があります。

スキャンで何も検出されなければ、設計に問題がないということですか？

結論は実際のカバレッジに左右されます。信号の欠落、リソース制限、未対応の構造によって解析が制限されることがあります。カバレッジがゼロまたは部分的な状態で検出結果がゼロであっても、設計に問題がないことの証明にはなりません。ツールはカバレッジと切り詰めの有無を報告するため、アシスタントはスコープを絞ってさらに調査すべきか判断できます。

フォーマル波形を調べることはできますか？

エクスポートされた VCD／FSDB ファイルをクエリし、JasperGold の成果物を自動検出できます。プロパティ結果、トレースの分類、到達可能性のセマンティクスは、フォーマルツールまたはユーザーが提供する必要があります。

スタンドアロンのエクスポートには、認識済みのフォーマルプロジェクトは必要ありません。プロジェクトエントリーのない波形が検出された場合、get_formal_paths は既存のポイント読み取り機能とバッチ読み取り機能に関する簡単なヒントを含めます。呼び出し側が波形、信号、タイムスタンプを選択します。

設計データはどこで処理されますか？

ファイルの解析と EDA クエリは、ローカルまたは設定済みの LSF コンピュートノードで実行されます。返されたデバッグ情報は、AI クライアントのコンテキストに取り込まれます。TraceWeave の利用状況テレメトリーはデフォルトでオフになっており、有効にした場合もローカルファイルにのみ書き込まれます。

ドキュメントとフィードバック

詳細	リソース
デバッグの手順とツールの連携	デバッグワークフロー
根本原因を証拠に基づいて検証する	デバッグの指針
アーキテクチャ、バックエンドの機能、リソースの制限	アーキテクチャ
環境設定の全項目と詳細設定	設定リファレンス
問題の報告や機能の提案	GitHub Issues

コントリビュートする前に、AGENTS.mdをお読みください。テスト用の依存関係をインストールしたうえで、リポジトリのルートからpython3.11 -m pytestを実行してください。

TraceWeaveはMIT Licenseの下で利用できます。

WeChat

プロジェクトの最新情報やデバッグの例については、WeChat公式アカウントをフォローしてください。