chipiq 0.0.9.2
ChipIQ - Intelligent EDA AI-Agents for Chip Design
Requires Python: >=3.13

# 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`:

```bash
uv add chipiq
```

## Quick Start

View the user manual:

```bash
chipiq simiq docs
```

Build MacOS/Linux/Windows executable:

```bash
source ./scripts/make
```

Analyze a VCD waveform file:

```bash
chipiq simiq vcd path/to/waveform.vcd
```

For convenience: build if needed and run

```bash
chipiq_dev <options>
```

Run regression tests:

```bash
uv run pytest
```




## Command Line Interface

### Basic Usage

```bash
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
```bash
chipiq simiq docs
```

#### 2. `info` - Show file metadata and statistics
```bash
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
```bash
chipiq simiq modules waveform.vcd --include "**"
```

#### 4. `signals` - List all signals with properties
```bash
chipiq simiq signals waveform.vcd --include "cpu.*"
```

#### 5. `vcd` - Parse and display signal value changes
```bash
chipiq simiq vcd waveform.vcd --include "clk" -n 10
```

#### 6. `license` - Display license properties and status
```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```python
from exe.simiq import simiq
```

#### Function Signature

```python
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
```python
from exe.simiq import simiq

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

##### Example 2: Get File Information
```python
info = simiq(
    report="info",
    file="path/to/waveform.vcd"
)
print(info)
```

##### Example 3: List All Modules
```python
modules = simiq(
    report="modules",
    file="path/to/waveform.vcd",
    include=["**"]  # All signals at all levels
)
print(modules)
```

##### Example 4: List Signals in Specific Module
```python
# 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
```python
# 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
```python
# 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
```python
signals = simiq(
    report="signals",
    file="chip.vcd",
    include=[".data", ".clk", ".enable"]  # Leading dot = root-level
)
print(signals)
```

##### Example 8: Complex Pattern Matching
```python
# 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
```python
# 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
```python
# 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:

```bash
uv run pytest
```

Run specific test file:

```bash
uv run pytest tests/test_simiq.py
```

Run tests with verbose output:

```bash
uv run pytest -v
```

Run tests matching a pattern:

```bash
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](https://github.com/ChipIQ/chipiq#readme)
- **Issues**: [https://github.com/ChipIQ/chipiq/issues](https://github.com/ChipIQ/chipiq/issues)
- **Source**: [https://github.com/ChipIQ/chipiq](https://github.com/ChipIQ/chipiq)