vcd-waveform-debug

VCD Waveform Analyzer — Agent Skill

What this tool does

vcd_analyzer.py is a single-file, zero-dependency Python CLI that parses IEEE 1364 VCD files and exposes seven query commands. It reads VCD files in streaming mode (constant memory regardless of file size), handles QuestaSim bit-exploded buses, Extended VCD port states, and malformed/hostile inputs safely.

All commands support --json for structured output. Always use --json when calling from an agent.

Setup (one-time)

curl -fsSL https://raw.githubusercontent.com/neveltyc/VCD_ANALYZER/v1.5.2/vcd_analyzer.py -o vcd_analyzer.py
python3 vcd_analyzer.py --version   # expect: vcd_analyzer 1.5.2

No pip install, no virtualenv, no dependencies. Python 3.9+.

Decision tree: which command to use

User wants to know...
├─ "What's in this VCD file?"
│   └─ info           → file overview, signal count, time span, scopes
├─ "What signals exist?" / "Find signals matching X"
│   └─ list           → signal paths with width and type
├─ "What happened between T1 and T2?"
│   └─ dump           → raw value-change events in time order
├─ "Which signals are active/static?"
│   └─ summary        → per-signal change count, rise/fall edges, unique values
├─ "What is the value of X at time T?"
│   └─ snapshot       → all known signal values at one time point
├─ "What changed between T1 and T2?"
│   └─ compare        → diff of signal values at two time points
├─ "When does condition C hold?" / "Find handshakes" / "Find state=X"
│   └─ search         → condition-based search with three sub-modes:
│       ├─ interval   → time ranges where condition is true (no --show)
│       ├─ segment    → intervals + observed signal values (with --show)
│       └─ event      → per-transition snapshots (with a changed(SIG) term)

Command reference

Universal options (apply to every command)

Option	Effect
--json	Always use this. Compact JSON to stdout.
--limit N	Max results. Default 500. --limit 0 = unlimited.
--verbose	Extra fields (width, type, raw values). Disables default limit.