Metadata-Version: 2.4
Name: gowin2vcd
Version: 0.9.1
Summary: Convert Gowin GAO CSV captures to VCD waveform format.
Author: Dan Shirley
License: MIT License
        
        Copyright (c) 2026 Dan Shirley
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/TSltd/gowin2vcd
Project-URL: Repository, https://github.com/TSltd/gowin2vcd
Project-URL: Issues, https://github.com/TSltd/gowin2vcd/issues
Project-URL: Documentation, https://github.com/TSltd/gowin2vcd/tree/main/docs
Keywords: gowin,logic-analyzer,vcd,waveform,csv,fpga
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gowin2vcd

Convert Gowin GAO CSV captures to VCD waveform format.

[![PyPI version](https://img.shields.io/pypi/v/gowin2vcd.svg)](https://pypi.org/project/gowin2vcd/)
[![Python](https://img.shields.io/pypi/pyversions/gowin2vcd.svg)](https://pypi.org/project/gowin2vcd/)
[![License](https://img.shields.io/pypi/l/gowin2vcd.svg)](LICENSE)
[![Tests](https://github.com/TSltd/gowin2vcd/actions/workflows/tests.yml/badge.svg)](https://github.com/TSltd/gowin2vcd/actions/workflows/tests.yml)

## Features

- **Single-pass streaming parser** — opens the file exactly once, no matter how large
- **Automatic GAO format detection** — handles all known CSV variants
- **Real GAO capture validated**
- **Hierarchical signal reconstruction** — scope walker, no tree in memory
- **Deterministic VCD output** — same input always produces identical output
- **Gzip-compressed output** — use `.vcd.gz` to save space automatically
- **Signal filtering** — `--include` and `--exclude` options
- **JSON output**
- **GTKWave save files** — generates `.gtkw` files with groups and expanded scopes
- **Signal aliases** — preserves aliases from `path/to/sig=alias_name` CSV columns
- **X/Z value propagation** — handles unknown and high-impedance states
- **Progress callback** — for large captures
- **Conversion statistics**
- **Zero runtime dependencies** — pure Python 3.10+
- **Golden regression tests**

## Supported outputs

- VCD
- JSON
- GTKWave save files

## Installation

```bash
pip install gowin2vcd
```

Or from source:

```bash
git clone https://github.com/TSltd/gowin2vcd.git
cd gowin2vcd
pip install .
```

## Usage

### Command line

```bash
# Basic conversion
gowin2vcd capture.csv output.vcd

# Compressed output
gowin2vcd capture.csv output.vcd.gz

# Include only selected signals
gowin2vcd capture.csv output.vcd \
    --include top/clk top/rst

# Exclude selected signals
gowin2vcd capture.csv output.vcd \
    --exclude top/debug_state

# Override the VCD timescale
gowin2vcd capture.csv output.vcd \
    --timescale ns

# Omit the VCD date/version headers
gowin2vcd capture.csv output.vcd \
    --no-date --no-version

# Diagnostic mode
gowin2vcd capture.csv output.vcd \
    --verify

# Quiet mode
gowin2vcd capture.csv output.vcd \
    --quiet

# Verbose logging
gowin2vcd capture.csv output.vcd \
    --verbose
```

### Python library

```python
from gowin2vcd import GowinCSVParser
from gowin2vcd import VCDWriter

# Parse a capture
parser = GowinCSVParser("capture.csv")

# Access metadata
print(f"Time unit: {parser.metadata.time_unit}")
print(f"Signals: {[s.fullname for s in parser.signals]}")
print(f"Groups: {[g.name for g in parser.groups]}")

# Print stats
print(f"Signals: {stats.signals}")
print(f"Samples: {stats.samples}")
print(f"Changes: {stats.value_changes}")
print(f"Runtime: {stats.runtime:.2f}s")
print(f"Output:  {stats.output_path}")

# Convert to VCD
writer = VCDWriter("output.vcd")
stats = writer.write(parser)
print(f"Wrote {stats.num_samples} samples with {stats.num_changes} changes")

# Or iterate lazily
for sample in parser.iter_samples():
    print(f"t={sample.timestamp} clk={sample.values.get('top/clk')}")
```

### JSON

```python
from gowin2vcd import JSONWriter

writer = JSONWriter("capture.json")
writer.write(parser)
```

### GTKWave save files

```python
from gowin2vcd import GowinCSVParser
from gowin2vcd import GTKWSaveWriter

parser = GowinCSVParser("capture.csv")
capture = parser.parse()

writer = GTKWSaveWriter("output.gtkw")
writer.write(capture)
```

## Architecture

See [docs/architecture.md](docs/architecture.md) for details.

```

CSV
 │
 ▼             ┌──────────► VCD
Scanner ─► Parser ─┬──────► JSON
                   ├──────► GTKWave
                   └──────► FST (planned)
```

## File Format

See [docs/file_format.md](docs/file_format.md) for the GAO CSV format specification.

## Status

The project is feature-complete for VCD conversion and has been validated against
real Gowin GAO captures.

Current outputs:

- VCD
- JSON
- GTKWave save files

Python 3.10+
Zero runtime dependencies

## Roadmap

Planned for v1.0:

- VCD reader
- Round-trip verification
- Fuzz testing
- Performance benchmarks

## License

MIT
