vcd-waveform-debug

name

vcd-waveform-debug

description

VCD waveform analysis for RTL debug. Use when the user has a .vcd file and wants to inspect, search, compare, or summarize digital simulation waveforms. Triggers include any mention of VCD files, waveform analysis, signal dump inspection, RTL debug, simulation results, value change dump, or specific VCD signal queries like "what is the value of X at time Y", "when does valid go high", "compare state at T1 vs T2", "find all AXI handshakes". Also triggers when the user uploads a .vcd file or references one by path. Do NOT use for FSDB, SHM, WLF, or other proprietary waveform formats — those require vendor tools to convert to VCD first.

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.3.12/vcd_analyzer.py -o vcd_analyzer.py
python3 vcd_analyzer.py --version   # expect: vcd_analyzer 1.3.12

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-change snapshots (with --changed)

Command reference

Universal options (apply to every command)

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

Time argument format

Bare integer = raw VCD ticks. With unit suffix = converted using the file's $timescale.

Valid: 0, 100ns, 17.5us, 1ms, 500ps, 200fs, .5ns Invalid: 10.5 (ambiguous — use 10.5ns), 5 ns (no space allowed)

Filter pattern format (--filter)

Comma-separated. Plain text = case-insensitive substring match. * and ? = glob (but [ is literal, safe for bus ranges like data[7:0]).

--filter clk,rst                       # substring: matches tb.clk, tb.rst_n
--filter '*_valid,*_ready'             # glob: matches any signal ending in _valid or _ready
--filter 'top.u_dma.*'                # glob: all signals under top.u_dma scope

---

1. info — file overview

python3 vcd_analyzer.py --json info <file>

Key JSON fields: signal_count, time_min_ticks, time_max_ticks, duration_h, timescale, scopes[], version (simulator ID), var_types (wire/reg/real counts), synthesized_buses (auto-reassembled bit-exploded buses).

Use first on any new VCD file to learn the time range, signal count, scope hierarchy, and timescale before issuing further commands.

2. list — find signals

python3 vcd_analyzer.py --json list <file> [--filter K1,K2]

Key JSON fields: signals[].path, signals[].width, signals[].type.

Signal paths use dot-separated scope hierarchy: tb.u_cpu.u_alu.result[31:0].

3. dump — raw value changes

python3 vcd_analyzer.py --json dump <file> [--begin T] [--end T] [--filter K1,K2]

Key JSON fields: events[].time_ticks, events[].time_h, events[].path, events[].value.

Values are formatted: scalars as 0/1/x/z, vectors as decimal (0xhex), 4-state vectors as b01xz, reals as float strings, events as triggered.

Always provide --begin and --end to avoid dumping the entire file. Always provide --filter to avoid flooding output with every signal.

4. summary — signal activity overview

python3 vcd_analyzer.py --json summary <file> [--begin T] [--end T] [--filter K1,K2]

Key JSON fields: rows[].path, rows[].kind (active/static), rows[].changes, rows[].rise_count/fall_count (1-bit signals only), rows[].init, rows[].last, rows[].unique.

Use to quickly identify which signals are toggling in a time window and which are stuck.

5. snapshot — signal values at a point

python3 vcd_analyzer.py --json snapshot <file> --at T [--filter K1,K2]

Key JSON fields: signals[].path, signals[].value. Also known (how many have values) and undefined (selected but never assigned).

6. compare — diff between two times

python3 vcd_analyzer.py --json compare <file> --at T1,T2 [--filter K1,K2]

Key JSON fields: diffs[].path, diffs[].at_t1, diffs[].at_t2. Only signals whose value differs are included.

7. search — condition-based query (three modes)

This is the most powerful command. Mode is selected by which options are present:

Interval mode (no --show, no --changed)

"When is the condition true?"

python3 vcd_analyzer.py --json search <file> --condition "state=5" [--begin T] [--end T]
python3 vcd_analyzer.py --json search <file> --condition "valid=1,ready=1" [--begin T] [--end T]

Returns intervals[] with begin_ticks, begin_h, end_ticks, end_h.

Segment mode (with --show)

"When is the condition true, and what are the observed signal values during each sub-interval?"

python3 vcd_analyzer.py --json search <file> --condition "arvalid=1,arready=1" --show araddr,arlen,arid

Returns segments[] with begin_h, end_h, values: {path: formatted_value}. A new segment starts whenever any --show signal changes value while the condition remains true.

This is the primary tool for protocol transaction extraction — e.g., capturing every AXI handshake with its address and length.

Important: the JSON output key differs by mode — intervals (no --show/--changed), segments (with --show), events (with --changed). Always check the mode field.

Event mode (with --changed)

"Show me a snapshot each time a specific signal changes, while the condition holds."

python3 vcd_analyzer.py --json search <file> --changed data_out --condition "valid=1" --show data_out,valid

Returns events[] with time_ticks, time_h, values: {path: formatted_value}.

Each event fires when the --changed signal genuinely transitions (not initial assignment, not same-value re-dump). If --show is omitted, the changed signal itself becomes the show list.

Condition syntax

Comma-separated AND list. Each item: SIGNAL=VALUE, SIGNAL==VALUE, or SIGNAL!=VALUE.

• Signal pattern must match exactly one signal (use list first to find the right path).
• Values: decimal (5, 255), hex (0xff), binary (b1010, 0b1010), 4-state (b1x0z), or the literal x/z.
• != does not match x/z/undefined. Unknown is not evidence of difference. To find unknowns, use signal=x.
• No OR operator. To search for state=3 OR state=5, run two searches and merge results.

---

Workflow patterns

Pattern 1: First contact with a VCD file

1. info           → learn time range, signal count, scopes, timescale
2. list           → find signals of interest (use --filter to narrow)
3. summary        → identify active vs static signals in the relevant window
4. dump or search → drill into specifics

Pattern 2: "What happened at time T?"

1. snapshot --at T                          → see all values at that moment
2. dump --begin T-delta --end T+delta       → see what changed around T
3. compare --at T-delta,T+delta             → diff view of the window

Pattern 3: Protocol transaction extraction (e.g., AXI)

1. list --filter '*valid,*ready,*addr,*data,*len'   → find channel signals
2. search --condition "arvalid=1,arready=1" --show araddr,arlen
   → extract all read-address handshakes with address and burst length
3. search --condition "wvalid=1,wready=1" --show wdata,wstrb
   → extract all write-data beats

Pattern 4: Find when a signal enters an unexpected state

1. search --condition "state=x"             → find when state goes unknown
2. search --condition "error!=0"            → find when error is asserted (excludes x/z)
3. snapshot --at <first_hit_time>           → see full system state at that moment
4. dump --begin <before_hit> --end <first_hit> --filter relevant_signals
   → trace what led to the bad state

Pattern 5: Clock and reset sanity check

1. summary --filter clk,rst,reset          → check toggle counts and rise/fall edges
   → clk should be active with balanced rise/fall
   → rst should be static after initial assertion

---

Environment variables

For exceptionally large VCD files, tune resource limits:

Variable	Default	Effect
VCD_ANALYZER_MAX_VARS	1,000,000	Max $var declarations
VCD_ANALYZER_MAX_REASSEMBLE_BITS	65,536	Max bits per bit-exploded bus

Increase if the tool reports too many $var declarations or bit-exploded group has more than N bits.

---

Important behaviors to know

--json placement

--json can appear before or after the subcommand:

python3 vcd_analyzer.py --json info sim.vcd
python3 vcd_analyzer.py info sim.vcd --json

Output truncation

Default --limit is 200 results. If truncated: true appears in JSON output, there are more results. Use --limit 0 for unlimited, or increase the limit. The total_is_exact field tells you whether total is the true count or a lower bound (streaming commands stop counting after the first unshown result).

Time fields in JSON

Every time value appears in three forms:

• *_ticks: integer, raw VCD timestamp (use for computation)
• *_h: human-readable string with unit (use for display to user)
• Some legacy fields without suffix equal *_ticks

Value formatting

• 1-bit: 0, 1, x, z
• Multi-bit clean: decimal (0xhex) — e.g., 255 (0xff)
• Multi-bit with unknowns: b01xz prefix notation
• Real/realtime: float string as-is from simulator
• Event type: triggered

Filter vs condition signal matching

--filter allows multiple matches (substring/glob, returns all hits). --condition signal patterns must resolve to exactly one signal. If ambiguous, the error message lists matching candidates — use a more specific path.

Bit-exploded bus reassembly

QuestaSim writes a 32-bit bus as 32 separate 1-bit $var declarations with [N] suffixes. The tool auto-reassembles these into a single bus[31:0] signal. The info command reports synthesized_buses count. This is transparent — reassembled buses appear as normal multi-bit signals in all commands.

---

Error handling

Errors go to stderr and exit with code 1. The error message is a single human-readable line starting with Error:. Common errors:

Error	Cause	Fix
condition signal pattern 'X' matches no signals	Signal name not found	Use list to find correct path
condition signal pattern 'X' matches N signals	Ambiguous pattern	Use full path from list output
end time must be >= begin time	Reversed time range	Swap begin/end
cannot open VCD file	File not found	Check path
VCD data section contains no value changes	Empty or header-only VCD	File may be incomplete

---

What this tool does NOT do

• Does not read FSDB, SHM, WLF, or any non-VCD format (convert to VCD first using vendor tools)
• Does not modify or write VCD files
• Does not support OR in conditions (use multiple searches)
• Does not support arithmetic expressions in conditions (no addr > 0xff)
• Does not support bit-select in show/condition (no data[7:4]=0xF — filter by the full signal)
• Does not provide waveform visualization (text/JSON only)
• Default limit is 200 — always check truncated field and increase --limit if needed