ChipIQ

Intelligent EDA AI-Agents for chip design.

ChipIQ provides powerful tools for analyzing digital simulation waveform files (VCD format) with advanced pattern matching capabilities.

Installation

Install ChipIQ using uv:

uv add chipiq

Quick Start

View the user manual:

chipiq simiq docs

Build MacOS/Linux/Windows executable:

source ./scripts/make

Analyze a VCD waveform file:

chipiq simiq vcd path/to/waveform.vcd

For convenience: build if needed and run

chipiq_dev <options>

Run regression tests:

uv run pytest

Command Line Interface

Basic Usage

chipiq <COMMAND> <REPORT> [OPTIONS]

Available commands: simiq, version

Available reports: docs, info, modules, signals, vcd, license

Report Types

Each report type has specific options:

Common Options:

• -h, --help - Show help message

vcd report (show signal value changes):

• FILE - VCD file path or URI (required)
• -f, --first FIRST - Starting timestamp for parsing (default: start of file)
• -i, --include PATTERN [PATTERN ...] - Signal name patterns to include (default: .* = top level signals)
• -e, --exclude PATTERN [PATTERN ...] - Signal name patterns to exclude (default: none)
• -n N - Maximum number of timestamps to report (default: 10)
• -g, --group-by {time,name} - Group results by timestamp or signal name (default: time)

info report (file metadata):

• FILE - VCD file path or URI (required)

modules report (module hierarchy):

• FILE - VCD file path or URI (required)
• -i, --include PATTERN [PATTERN ...] - Signal name patterns to include
• -e, --exclude PATTERN [PATTERN ...] - Signal name patterns to exclude

signals report (list signals):

• FILE - VCD file path or URI (required)
• -i, --include PATTERN [PATTERN ...] - Signal name patterns to include
• -e, --exclude PATTERN [PATTERN ...] - Signal name patterns to exclude

docs report (show documentation):

• No arguments required

license report (show license info):

• No arguments required

Report Types

1. docs - Display detailed help and examples

chipiq simiq docs

2. info - Show file metadata and statistics

chipiq simiq info waveform.vcd

Example output:

timescale:        1 fs
date:             Fri Nov 21 16:56:29 2014
version:          GHDL v0
timestamp range:  0 to 210000000
filename:         waveform.vcd
file size:        2,195 bytes

3. modules - List all module hierarchies

chipiq simiq modules waveform.vcd --include "**"

4. signals - List all signals with properties

chipiq simiq signals waveform.vcd --include "cpu.*"

5. vcd - Parse and display signal value changes

chipiq simiq vcd waveform.vcd --include "clk" -n 10

6. license - Display license properties and status

chipiq simiq license

Example output:

SimIQ: License Properties:

is_valid:        True
lic_company:     chipiq
lic_product:     simiq
lic_user:        user@example.com
lic_valid_to:    1767225599
message:         Valid until 2025-12-31 23:59:59 UTC.

Signal Pattern Matching

ChipIQ uses powerful pattern matching with * and ** to filter signals in the hierarchy:

• * matches zero or more characters except . (within a single hierarchy level)
• ** matches zero or more characters including . (across hierarchy levels)
• . matches a literal dot character
• Pattern preprocessing: Simple patterns without leading ., without *. prefix, and without ** are automatically expanded:
  • data → **.data and **.data.* (matches any leaf named "data" - signal or module)
  • .data → .data (no expansion, matches only root-level)
  • *.data → *.data (no expansion, starts with *.)
  • cpu.alu → **.cpu.alu and **.cpu.alu.* (matches hierarchy path anywhere)
  • data* → **.data* and **.data*.* (matches leaves starting with "data")
  • **data** → **data** (no expansion, contains **)

Pattern Examples

Consider these signal names in a CPU design:

• .data
• .clk
• .dut.data
• .dut.clk
• .cpu.alu.data
• .cpu.ctrl.enable
• .tb.dut.data_in
• .tb.dut.cpu.alu.result

Pattern	Matches	Explanation
**	All signals	Universal match
data	.data, .dut.data, .cpu.alu.data	Expands to **.data and **.data.*, matches any leaf "data"
.data	.data only	Exact root-level match (no expansion)
**.data	.data, .dut.data, .cpu.alu.data	Explicit form, matches leaf "data" anywhere
data*	.data, .tb.dut.data_in	Expands to **.data* and **.data*.*, matches leaves starting with "data"
.data*	.data only	Root-level names starting with "data"
*data*	.data, .dut.data, .tb.dut.data_in	Expands to **.*data* and **.*data*.*, any leaf containing "data"
**data**	All with "data" substring	Matches "data" anywhere in full path
cpu.*	Direct children of "cpu"	Expands to **.cpu.* and **.cpu.*.*
**.cpu.*	.cpu.alu, .cpu.ctrl	Explicit form, direct children of "cpu" anywhere
**.cpu.**	.cpu.alu.data, .cpu.ctrl.enable, .tb.dut.cpu.alu.result	"cpu" module with all descendants
**.alu.*	.cpu.alu.data, .tb.dut.cpu.alu.result	Direct children of "alu" anywhere
**.alu.**	.cpu.alu.data, .cpu.alu.adder.sum, .tb.dut.cpu.alu.result	"alu" module with all descendants
.*	.data, .clk	Top-level leaves only
.*.*.*	.cpu.alu.data, .cpu.ctrl.enable	Exactly 3 segments from root

Real-World CLI Examples

Debugging Clock and Data Signals

# Find all clock-related signals in the design
chipiq simiq signals processor.vcd --include "*clk*" "*clock*"

# Find all data signals anywhere in hierarchy
chipiq simiq signals design.vcd --include "data"

# Analyze data signal changes in the CPU module
chipiq simiq vcd processor.vcd --include "**.cpu.**data*" -n 20

# Check specific signal anywhere in hierarchy
chipiq simiq vcd processor.vcd --include "data" --first 1000000 -n 5

Analyzing a Specific Module

# List all signals in the ALU module (at any hierarchy level)
chipiq simiq signals design.vcd --include "alu.**"

# Monitor ALU inputs and outputs only (direct children)
chipiq simiq vcd design.vcd --include "alu.*" -n 50

# Watch ALU operations excluding internal debug signals
chipiq simiq vcd design.vcd --include "alu.**" --exclude "*debug*" "*test*"

Memory Interface Debugging

# Monitor all memory controller signals
chipiq simiq vcd soc.vcd --include "mem_ctrl.**" --group-by name

# Check memory write operations
chipiq simiq vcd soc.vcd --include "*mem*wr*" "*mem*write*" -n 30

# Analyze top-level memory interface only
chipiq simiq signals soc.vcd --include ".mem_*"

Finding Reset Signals

# Find all reset signals in the design
chipiq simiq signals chip.vcd --include "*rst*" "*reset*"

# Monitor reset behavior across all modules
chipiq simiq vcd chip.vcd --include "*rst*" -n 15 --group-by time

Pipeline Analysis

# Analyze all pipeline stages
chipiq simiq vcd cpu.vcd --include "pipeline.**" -n 100

# Monitor specific pipeline stage
chipiq simiq vcd cpu.vcd --include "pipeline.execute.*" --group-by name

# Check pipeline control signals only
chipiq simiq vcd cpu.vcd --include "pipeline.**ctrl*" "pipeline.**valid*"

Excluding Noise

# Analyze design without clocks and resets
chipiq simiq vcd design.vcd --include "**" --exclude "*clk*" "*rst*"

# Monitor CPU excluding testbench signals
chipiq simiq vcd test.vcd --include "cpu.**" --exclude "*tb*" "*test*" "*monitor*"

# Check signals at top-level, excluding debug
chipiq simiq vcd design.vcd --include ".*" --exclude ".*debug*"

Bus Interface Debugging

# Monitor all AXI bus signals
chipiq simiq vcd soc.vcd --include "*axi*" -n 40

# Check specific AXI channel (read address)
chipiq simiq vcd soc.vcd --include "*axi*ar*" --group-by name

# Analyze APB peripheral at any level
chipiq simiq vcd soc.vcd --include "apb_peripheral.**"

State Machine Analysis

# Monitor FSM state changes
chipiq simiq vcd controller.vcd --include "*fsm*state*" -n 20 --group-by time

# Check all FSM signals
chipiq simiq vcd controller.vcd --include "fsm.**" --group-by name

# Multiple state machines comparison
chipiq simiq vcd design.vcd --include "*state*" --exclude "*next_state*" -n 50

Pattern Matching Examples

# Match leaf named "data" anywhere (as signal or module)
chipiq simiq design.vcd --include "data"
# Expands to: **.data and **.data.*
# Matches: .data, .dut.data, .cpu.alu.data, .data.valid

# Match "data" only at root level
chipiq simiq design.vcd --include ".data"
# Matches: .data only (no expansion)

# Match direct children of "alu" module anywhere in hierarchy
chipiq simiq design.vcd --include "**.alu.*"
# Matches: .cpu.alu.result, .cpu.alu.overflow (NOT .cpu.alu or .cpu.alu.adder.sum)

# Match "alu" module with ALL descendants (recursive)
chipiq simiq design.vcd --include "**.alu.**"
# Matches: .cpu.alu.result, .cpu.alu.adder.sum, .tb.dut.alu.flags
# Does NOT match: .alu alone (needs descendants)

# Match leaves containing "data" at any hierarchy level
chipiq simiq design.vcd --include "*data*"
# Expands to: **.*data* and **.*data*.*
# Matches: .data, .raw_data, .dut.input_data, .data_bus.width

# Match "data" substring anywhere in the full hierarchical path
chipiq simiq design.vcd --include "**data**"
# Matches: .data, .raw_data, .dut.input_data, .data.valid

# Match all signals at all levels
chipiq simiq design.vcd --include "**"

# Match only root-level signals (direct children of root)
chipiq simiq design.vcd --include ".*"
# Matches: .data, .clk (NOT .cpu.data)

# Match exactly 3 levels deep in hierarchy
chipiq simiq design.vcd --include ".*.*.*"
# Matches: .cpu.alu.data (NOT .alu.data or .cpu.alu.ctrl.enable)

# Combine multiple patterns with OR logic
chipiq simiq design.vcd --include "data" "clk" "enable"

# Include CPU signals but exclude debug/test infrastructure
chipiq simiq design.vcd --include "**.cpu.**" --exclude "*debug*" "*test*" "*monitor*"

# Match specific hierarchy path from root
chipiq simiq design.vcd --include ".tb.dut.cpu.*"
# Matches: .tb.dut.cpu.pc, .tb.dut.cpu.ir
# Does NOT match: .other.tb.dut.cpu.pc

Python API

The simiq() Function

Use the simiq() function to analyze VCD files programmatically:

from exe.simiq import simiq

Function Signature

def simiq(
    file: str = "",         # File path or URI to the VCD file
    report: str = "",       # Report type (docs, modules, signals, info, vcd)
    first: int = -1,        # First timestamp for report (default: from start)
    include: list = [".*"], # By default match names at top-level (root) only
    exclude: list = [],     # Do not exclude anything
    n: int = 10,            # Max number of timestamps to report on
    group: str = "time"     # Group value changes by "time" or by "name"
) -> str:

Parameters

• file (str): Path or URI to VCD file (default: "")

  • Local paths: "path/to/file.vcd"
  • File URIs: "file:///absolute/path/file.vcd"
  • HTTP(S): "https://example.com/file.vcd"
  • Data URIs: "data:text/plain;base64,..."

• report (str): Type of report (default: smart default)

  • "docs" - Display help documentation
  • "modules" - List module hierarchies
  • "signals" - List signals with properties
  • "info" - File metadata and statistics
  • "vcd" - Signal value changes
  • Default behavior: Returns "docs" when no file is provided, "vcd" when file is provided

• first (int): Starting timestamp (default: -1 = start of file)

  • Set to specific timestamp to start parsing from that point
  • Only relevant for report="vcd"

• include (list): Signal patterns to include (default: [] = all)

  • Empty list [] matches all signals (same as ["**"])
  • Supports Unix-style glob wildcards: * and **
  • See pattern matching rules above

• exclude (list): Signal patterns to exclude (default: [])

  • Same pattern matching rules as include
  • Exclusions are applied after inclusions

• n (int): Maximum number of timestamps to report (default: 10)

  • Only relevant for report="vcd"

• group (str): Grouping mode (default: "time")

  • "time" - Group by timestamp
  • "name" - Group by signal name
  • Only relevant for report="vcd"

API Usage Examples

Example 1: View User Manual

from exe.simiq import simiq

manual = simiq(report="docs")
print(manual)

Example 2: Get File Information

info = simiq(
    report="info",
    file="path/to/waveform.vcd"
)
print(info)

Example 3: List All Modules

modules = simiq(
    report="modules",
    file="path/to/waveform.vcd",
    include=["**"]  # All signals at all levels
)
print(modules)

Example 4: List Signals in Specific Module

# Direct children of CPU module anywhere
signals = simiq(
    report="signals",
    file="design.vcd",
    include=["**.cpu.*"]
)
print(signals)

# CPU module with all descendants (recursive)
signals = simiq(
    report="signals",
    file="design.vcd",
    include=["**.cpu.**"]
)
print(signals)

Example 5: Analyze Signal Value Changes

# Parse 20 signal changes for data signals
changes = simiq(
    report="vcd",
    file="path/to/waveform.vcd",
    include=["*data*"],
    n=20,
    group="time"
)
print(changes)

Example 6: Monitor Specific Signals with Exclusions

# Monitor CPU module signals, exclude debug
changes = simiq(
    report="vcd",
    file="design.vcd",
    include=["**.cpu.**"],
    exclude=["*debug*", "*test*"],
    first=1000,
    n=50,
    group="name"
)
print(changes)

Example 7: Root-Level Signals Only

signals = simiq(
    report="signals",
    file="chip.vcd",
    include=[".data", ".clk", ".enable"]  # Leading dot = root-level
)
print(signals)

Example 8: Complex Pattern Matching

# Find all state machine signals except next_state
changes = simiq(
    report="vcd",
    file="controller.vcd",
    include=["*state*"],
    exclude=["*next_state*"],
    n=30,
    group="name"
)
print(changes)

Example 9: Pipeline Analysis

# Monitor pipeline module with all stages anywhere
pipeline_signals = simiq(
    report="vcd",
    file="cpu.vcd",
    include=["**.pipeline.**"],
    first=5000,
    n=100,
    group="time"
)
print(pipeline_signals)

Example 10: Bus Interface Monitoring

# Analyze AXI bus signals
axi_changes = simiq(
    report="vcd",
    file="soc.vcd",
    include=["*axi*"],
    exclude=["*axi*debug*"],
    n=40,
    group="name"
)
print(axi_changes)

Development

Running Tests

Run all tests using pytest:

uv run pytest

Run specific test file:

uv run pytest tests/test_simiq.py

Run tests with verbose output:

uv run pytest -v

Run tests matching a pattern:

uv run pytest -k "test_pattern"

Project Structure

chipiq/
├── src/chipiq/
│   ├── simiq/          # VCD analysis engine
│   │   ├── simiq.py    # Main simiq() function
│   │   ├── VCDFile.py  # VCD file parser
│   │   └── ...
│   ├── cli/            # Command-line interface
│   └── utils/          # Utility functions
├── tests/              # Test suite
│   ├── vcd/           # Sample VCD files
│   └── ...
└── examples/          # Usage examples

License

Copyright (c) 2025 ChipIQ. All rights reserved.

Links

• Documentation: https://github.com/ChipIQ/chipiq#readme
• Issues: https://github.com/ChipIQ/chipiq/issues
• Source: https://github.com/ChipIQ/chipiq