hardware-debug-waveform

Category: Data & AI | Uploader: trace1729 | Downloads: 0 | Version: v1.0（Latest）

Use when debugging or explaining hardware behavior from a waveform together with a XiangShan-style Scala/Chisel source tree and optional emitted RTL.

Changelog: Source: GitHub https://github.com/trace1729/hardware-debug-skill

Directory Structure

Current level: tree/main/

📁 scripts/
- 📁 lib/
  - 📄 __init__.py 35 B
  - 📄 build_debug_packet.py 5.7 KB
  - 📄 build_rtl_authority.py 4.1 KB
  - 📄 ingest_waveform_wellen.py 3.1 KB
  - 📄 query_waveform_wellen.py 14.3 KB
  - 📄 rtl_build_hierarchy.py 2.0 KB
  - 📄 rtl_models.py 658 B
  - 📄 rtl_parse_modules.py 3.7 KB
  - 📄 stream_vcd_reader.py 923 B
- 📄 hw_debug_cli.py 13.8 KB
- 📄 plan_hw_debug_artifacts.py 405 B
📁 wellen/
- 📁 pywellen/
  - 📁 pywellen/
    
    📄 __init__.py 32 B
    
    📄 pywellen.cpython-312-x86_64-linux-gnu.so 21.6 MB
    
    📄 pywellen.pyi 3.2 KB
- 📄 LICENSE 1.5 KB
📄 .gitignore 73 B
📄 artifact.md 3.3 KB
📄 README.md 4.5 KB
📄 README_en.md 5.0 KB
📄 SKILL.md 7.2 KB
📄 wavedrom.md 6.8 KB

SKILL.md

---
name: hardware-debug-waveform
description: Use when debugging or explaining hardware behavior from a waveform together with a XiangShan-style Scala/Chisel source tree and optional emitted RTL.
---

# Hardware Debug Waveform

## Overview

Use this skill to debug or explain behavior from large waveform files (VCD or FST) together with a Scala/Chisel source tree and, when available, emitted RTL.

Path note for future runs: this checkout still has a vendored `pywellen` tree at `wellen/pywellen/pywellen`. Record the path if needed for orientation, but do not treat it as the default main-branch query path.

Core approach:

- use direct waveform queries as the default evidence path
- use emitted RTL to recover exact ownership and hierarchy
- use Scala/Chisel source as the primary material for root-cause analysis
- only inspect generated SystemVerilog if Scala-first analysis is blocked

Direct `wellen` queries now use two cache levels:

- level 1: waveform metadata cache
- level 2: direct query-result cache for repeated packet and signal-value queries


## Workflow

### Step 0 - Resolve inputs

If the user has not already provided them, first try to discover them reliably from local context. Only ask the user when one or more required inputs cannot be found with high confidence.

Required or useful inputs:

- waveform path
- Chisel source root
- optional emitted RTL root (`build/rtl`)
- optional focus scope (e.g. `TOP.SimTop.core.rob`) or debug hint

Recommended prompt when discovery is insufficient:

> Please provide the waveform path, the Chisel source root, and optionally the emitted RTL root (build/rtl), plus any focus scope or debug hint.


All commands run from the skill root directory. Use `cd` once at the start:

```bash
cd ~/.codex/skills/hardware-debug-waveform
```

### Step 1 — Inspect inputs

```bash
python scripts/hw_debug_cli.py inspect-inputs \
  --scala-root /path/to/src/main/scala/xiangshan \
  --waveform /path/to/run.vcd_or_run.fst \
  [--rtl-root /path/to/build/rtl] \
  [--focus-scope TOP.SimTop.core.rob] \
  [--suggestion "hang near rob tail"] \
  [--top SimTop] \
  [--window-len 1000]
```

`inspect-inputs` validates paths, reports artifact sizes, checks cache status, and **prints the exact commands to run next**. Use those printed commands as the next steps.

If it warns that artifacts are large, tell the user before proceeding.

### Step 2 — Build RTL authority (skip if no `--rtl-root`)

```bash
python scripts/hw_debug_cli.py build-authority \
  --rtl-root /path/to/build/rtl \
  --top SimTop \
  [--out-dir <authority-out>]
```

Reuses cache automatically. Add `--force` to rebuild.

### Step 3 — Query a debug packet directly from the waveform

```bash
python scripts/hw_debug_cli.py query-packet \
  --waveform /path/to/run.vcd_or_run.fst \
  --window-id w42 \
  --window-len 1000 \
  --out <packet-out>/packet_w42.json \
  [--authority <authority-out>/rtl_authority.sqlite3] \
  [--focus-scope TOP.SimTop.core.rob]
```

Use the window ID that covers the suspected failure. Let `inspect-inputs` suggest the exact command form.

### Step 3b — (Optional) Query one signal value at one time directly from the waveform

```bash
python scripts/hw_debug_cli.py query-signal-value \
  --waveform /path/to/run.vcd_or_run.fst \
  --signal TOP.SimTop.core.rob.commit_valid \
  --time 123456 \
  [--window-len 1000]
```

Use this when you need the value of one specific signal at one specific simulation time.

### Step 4 — (Optional) Add rough Chisel candidates

```bash
python scripts/hw_debug_cli.py rough-map-chisel \
  --packet <packet-out>/packet_w42.json \
  --mapping /path/to/rough-mapping.json \
  --out <packet-out>/packet_w42_rough.json
```

Only run this step if a rough mapping artifact is available. Treat results as guesses, not exact source truth.

### Step 5 — Analyze

1. Read `focus_signals[*].changes` as raw waveform evidence.
2. If `rtl.match_status == "exact"`, use `module_type` and `local_signal_name` to narrow the search to the most relevant Scala/Chisel source candidates.
3. Search the Scala root by module name, signal name, and nearby subsystem names to find the best candidates.
4. Analyze the Scala/Chisel code first.
5. Present rough Chisel candidates from step 4 only as secondary, lower-confidence hints.
6. Only inspect generated SystemVerilog if Scala cannot explain the behavior.

If you need a point lookup instead of a window summary, use `query-signal-value`.


## Output

Write the answer in two parts:

**Summary** (2-4 sentences)

- For a debug request, include:
  - `Phenomenon`: one sentence describing the anomaly seen in the waveform
  - `Root Cause Category`: a standard hardware bug class such as state machine deadlock, data hazard, backpressure stall, or flush-handling miss
  - `Confidence`: state whether this is high confidence or low confidence
- For an exploration request, include:
  - `Function`: what the module does
  - `Structure`: its main internal buffers, state, and submodules
  - `Interconnect`: how it connects to other modules

**Detailed Analysis**

- For a debug request:
  1. Expand the `Root Cause Category` from the summary.
  2. Cite the most relevant waveform evidence and Scala/Chisel logic that support the hypothesis.
  3. Give a fix recommendation if confidence is high.
  4. Otherwise give the next best debugging steps.
- For an exploration request:
  1. Support `Function` by using the Scala/Chisel source to explain what the module does, and by using waveform evidence to analyze its key pipeline signals and timing behavior when sufficient evidence is available.
  2. Support `Structure` with the main state, buffers, queues, or submodules.
  3. Support `Interconnect` with the other modules, or interfaces that matter most.

Use precise terms in the detailed analysis:

- signals/timing: `rising edge`, `falling edge`, `valid`, `ready`, `handshake`, `backpressure`, `stall`, `flush`, `state transition`
- architecture/control: `pipeline stage`, `hazard detection`, `forwarding`, `cache hierarchy`, `fetch/decode/execute`, `instruction set architecture`, `bus arbitration`, `memory consistency`, `reorder buffer`, `issue queue`, `commit/retire`

Avoid: raw per-cycle value dumps, long exact-signal lists, large artifact path inventories, large SystemVerilog excerpts, and preprocessing detail.
Include only the few source files or artifact paths that materially support the analysis.

## Rules

- Let `inspect-inputs` choose default artifact paths; only override when the user asks.
- If direct `wellen` query fails, surface the error clearly and remind the user that `main` expects `pywellen`; recommend the `no-pywellen` branch only when they explicitly want to avoid that dependency.
- Reuse cached artifacts; rebuild only when needed or explicitly requested.
- Reuse both waveform metadata cache and direct query-result cache when available.
- Treat `rtl_authority.sqlite3` matches as exact RTL ownership.
- If no `build/rtl` is provided, label the result `waveform-only analysis`.
- Avoid reading large SystemVerilog files unless Scala-first analysis is blocked.

## Reference

For command flags, artifact layout, and schema details:

- `README_en.md` (English reference)
- `README.md` (Chinese reference)

For wavedrom language:

- `wavedrom.md`

For artifact json format or database schema:

- `artifact.md`

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

hardware-debug-waveform

Directory Structure

SKILL.md

Report

Notice