HDL Wave AI

AI-assisted hardware verification for VS Code. Connect your active simulation waveform to an LLM — ask questions about signal behavior, debug logic errors, and cross-reference transitions against your HDL source in natural language. Features 10 waveform query tools, multi-ISA instruction decoding (RISC-V, ARM, x86, MIPS, and more via Capstone), and automatic HDL source ranking.

Built as a companion to the VaporView waveform viewer.

How it works

1. Open a VCD/FST file in VaporView and add signals to the viewer
2. Optionally place VaporView's markers to define a time window of interest
3. Open the HDL Wave AI chat (HDL Wave AI: Open Chat from the Command Palette)
4. Ask questions — the extension automatically injects:
   • Signal transition data for the marked (or full) time range
   • Relevant HDL module source ranked by match to your tracked signals
5. Continue the conversation — subsequent messages use the same context without re-fetching

Requirements

• VaporView — VS Code will prompt you to install it automatically
• An LLM provider:
  • Anthropic API key (Claude)
  • NVIDIA TRT-LLM (local GPU inference, including DGX Spark)
  • Ollama (local CPU/GPU inference)
  • Any OpenAI-compatible API (vLLM, NVIDIA NIM, text-generation-inference, etc.)

Quick Start

Using Claude (Anthropic)

1. Install the extension
2. Open VS Code Settings (Ctrl+,) and search hdlWaveAi
3. Set Provider to anthropic
4. Paste your Anthropic API key into Anthropic: Api Key
5. Open a VCD in VaporView, add signals, then run HDL Wave AI: Open Chat

Using a local model via Ollama

# Install Ollama and pull a model (recommended: deepseek-coder-v2:32b)
ollama pull deepseek-coder-v2:32b

Recommended models:

• qwen3:32b — best balance of code reasoning, tool-use reliability, and Verilog/SystemVerilog comprehension
• qwen3:8b — faster (~49 tok/s on DGX Spark) with good quality for interactive use
• deepseek-coder-v2:32b — strong alternative for HDL analysis

Smaller models (8B and below) work but produce shallower analysis and less reliable tool calling.

Set in VS Code Settings:

• Provider → openai-compatible
• Openai Compatible: Base Url → http://localhost:11434/v1
• Openai Compatible: Model → deepseek-coder-v2:32b

Or run Ollama via Docker — see the Dockerfile in the repo for GPU-accelerated setup.

Using NVIDIA TRT-LLM (DGX Spark / local GPU)

TRT-LLM provides high-performance local inference for models like Qwen3-32B-FP4, Nemotron-49B, and others on NVIDIA GPUs.

# Start TRT-LLM server (example with Qwen3-32B-FP4)
docker run --rm -it --gpus all --ipc host --network host \
    -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
    nvcr.io/nvidia/tensorrt_llm:v1.3.0rc7-trtllm \
    trtllm-serve nvidia/Qwen3-32B-FP4 --port 8000

Set in VS Code Settings:

• Provider → openai-compatible
• Openai Compatible: Base Url → http://localhost:8000/v1
• Openai Compatible: Model → nvidia/Qwen3-32B-FP4
• Openai Compatible: Use Completions Endpoint → true (required for TRT-LLM models where the chat endpoint is broken)
• Prompt: Max Tokens → 28000 (for models served with max_num_tokens=32768)

Note: Some TRT-LLM models (e.g. Nemotron NAS, Qwen3) have a broken /v1/chat/completions endpoint. Enable the completions endpoint setting to use /v1/completions with ChatML formatting instead.

Usage

Workflow

1. Simulate your design and open the resulting VCD/FST file in VaporView
2. Add the signals you care about to the VaporView signal list
3. (Optional) Place VaporView's primary and alt markers to focus on a specific time window
4. Run HDL Wave AI: Open Chat from the Command Palette (Ctrl+Shift+P)
5. Ask questions — the first message automatically collects and injects waveform + HDL context

Tips

• Markers: If no markers are set the extension samples the entire simulation. Setting both VaporView markers to bracket the region of interest gives the LLM a tighter, more relevant window.
• HDL source: Open your RTL directory as the VS Code workspace, or configure hdlWaveAi.hdl.searchPaths to point at it. The extension finds modules whose signal names match what's in the viewer.
• Stop: A Stop button appears during streaming — click it to cancel a response mid-generation without losing conversation history.

Generating a VCD for testing

If you don't have a VCD handy, Icarus Verilog can generate one from any Verilog testbench:

sudo apt install iverilog
iverilog -o sim testbench.v design.v && ./sim
# produces output.vcd

Add $dumpfile("output.vcd"); $dumpvars(0, tb); to your testbench's initial block.

Tool-Use (RAG) Mode

For large designs with millions of signal transitions, the extension uses a tool-calling approach instead of dumping all transitions into the LLM context. The LLM receives a compact waveform summary and queries signal data on-demand through tools.

This is enabled by default (hdlWaveAi.waveform.useToolMode: true) and works with both Anthropic and OpenAI-compatible providers. If the provider doesn't support tool calling, it falls back to legacy mode automatically.

Instruction Decoding

When analyzing CPU designs, the extension can automatically decode instruction bus values into assembly mnemonics using Capstone — the same disassembly engine used by Ghidra, IDA Pro, and radare2.

Supported ISAs

Setup

Set hdlWaveAi.isa in VS Code Settings to match your design's CPU core (e.g. rv32 for DarkRISCV, mips32 for MIPS). Instruction bus signals (inst, IDATA, IM_DATA, opcode, etc.) are automatically decoded inline in snapshot and transition results — the model gets exact assembly without needing to call any tool.

Example

Instead of the model guessing "0x00050663 might be a branch instruction", the snapshot output now includes:

cpu_tb.mips1.inst: 0xFFF68693 → addi a3, a3, -1
darksimv.soc0.bridge0.IDATA: 0x00050663 → beq a0, zero, 0xc

The model sees the exact mnemonic, registers, and immediates — eliminating hex-decoding errors and enabling accurate program flow analysis.

Tested architectures

• RISC-V — DarkRISCV SoC (darksocv), instruction fetch pipeline tracing
• MIPS — 5-stage pipelined CPU, instruction decode and ALU operation analysis

MCP Server

The extension includes a standalone MCP (Model Context Protocol) server that exposes waveform query tools to any MCP-compatible client — Claude Code, Claude Desktop, Cursor, and others. This runs independently of VS Code.

Setup

Build the server (if not already built):

cd hdl-wave-ai
npm install
npm run compile

This produces dist/mcp-server.js.

Claude Code

claude mcp add hdl-wave-ai node /path/to/hdl-wave-ai/dist/mcp-server.js

Or to pre-load a waveform on startup:

claude mcp add hdl-wave-ai node -- /path/to/hdl-wave-ai/dist/mcp-server.js /path/to/waveform.vcd

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hdl-wave-ai": {
      "command": "node",
      "args": ["/path/to/hdl-wave-ai/dist/mcp-server.js"]
    }
  }
}

Project-level config (.mcp.json)

{
  "mcpServers": {
    "hdl-wave-ai": {
      "command": "node",
      "args": ["/path/to/hdl-wave-ai/dist/mcp-server.js", "/path/to/waveform.vcd"]
    }
  }
}

Available Tools

Example Prompts

After loading a waveform, try:

Load the waveform at /path/to/design.vcd, then analyze signal activity between t=4200000 and t=4220000. What instructions is the CPU fetching and are there any anomalies?

Load /path/to/riscv_soc.vcd and find all HDL modules in /path/to/rtl/. Decode the instructions on the IDATA bus between t=3800000 and t=3900000. Is there a branch misprediction?

FST Support

FST files require fst2vcd (part of GTKWave) to be installed and on your PATH.

Extension Settings

Tuning for larger models

Models with bigger context windows (32b+) can handle more data. Increase these settings:

"hdlWaveAi.waveform.maxTransitions": 1000,
"hdlWaveAi.hdl.maxModules": 10,
"hdlWaveAi.hdl.maxCharsPerModule": 8000

Commands

Troubleshooting

No waveform context / "No signals tracked yet" Add signals to VaporView before opening the chat. The extension reads whatever is currently displayed in the signal list.

HDL context not found Either open your RTL directory as the VS Code workspace root, or add the path to hdlWaveAi.hdl.searchPaths in settings.

LLM not responding / very slow For large VCDs with no markers set, the extension may sample many time steps. Set markers in VaporView to limit the time range, or increase sampleStepSize.

Check the Output channel Run HDL Wave AI: Debug VaporView State and open the HDL Wave AI output channel (View → Output) to see what signals, URIs, and state are being read.

License

AGPL-3.0 — see LICENSE.