veriforge 0.0.1__tar.gz

veriforge-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Chip Lukes
+
+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.

veriforge-0.0.1/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: veriforge
+Version: 0.0.1
+Summary: Parse, analyze, simulate, and generate Verilog/SystemVerilog from Python.
+Author-email: Chip Lukes <34627158+chiplukes@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/chiplukes/veriforge
+Project-URL: Changelog, https://github.com/chiplukes/veriforge/releases
+Project-URL: Issues, https://github.com/chiplukes/veriforge/issues
+Project-URL: CI, https://github.com/chiplukes/veriforge/actions
+Keywords: Verilog,Lark,Parse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark
+Requires-Dist: rich
+Requires-Dist: treelib
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: filelock; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: vulture; extra == "dev"
+Provides-Extra: bench
+Requires-Dist: cython; extra == "bench"
+Requires-Dist: setuptools; extra == "bench"
+Requires-Dist: myhdl; extra == "bench"
+Requires-Dist: filelock; extra == "bench"
+Provides-Extra: lsp
+Requires-Dist: pygls>=1.3; extra == "lsp"
+Requires-Dist: intervaltree>=3.1; extra == "lsp"
+Dynamic: license-file
+
+# veriforge
+[![CI](https://github.com/chiplukes/veriforge/actions/workflows/ci.yml/badge.svg)](https://github.com/chiplukes/veriforge/actions/workflows/ci.yml)
+[![Changelog](https://img.shields.io/github/v/release/chiplukes/veriforge?include_prereleases&label=changelog)](https://github.com/chiplukes/veriforge/releases)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/chiplukes/veriforge/blob/main/LICENSE)
+
+A Python library for parsing, analyzing, generating, and simulating Verilog/SystemVerilog designs, built on the [Lark](https://github.com/lark-parser/lark) parser.
+
+## Features
+
+- **Parse** Verilog 2005 (with SystemVerilog extensions) into a semantic model
+- **Preprocess** source files (`` `define ``, `` `ifdef ``, `` `include ``, `` `timescale ``, etc.)
+- **Multi-file project** support — parse directories, link cross-module instances
+- **Analyze** designs — width inference, constant folding, clock/reset extraction, lint checks
+- **Emit** formatted Verilog from the model (round-trip, configurable style)
+- **Python DSL** — build hardware with operator-overloaded Python, emit to Verilog or simulate directly
+- **Component library** — FIFO, CDC, codec, AXI-Stream, AXI4-Lite, DSP, RAM, Xilinx inference
+- **Auto-generate testbenches** from any module
+- **Convert** parsed Verilog to DSL code (Verilog → Python translation)
+- **Simulate** — event-driven 4-state simulator with three engines (reference, bytecode VM, compiled Cython)
+- **VCD output** — IEEE 1364-2001 waveform dumps, cross-simulator validation
+- **Inspect** semantic models through lookup helpers and JSON serialization
+- **Language Server** — `veriforge-lsp` provides editor diagnostics, symbols, navigation, hover, and custom hierarchy/trace commands (install [Verible](https://github.com/chipsalliance/verible) for fast between-save diagnostics; the server falls back to the built-in Lark parser when Verible is absent)
+
+## Documentation
+
+- [Getting Started](notes/getting_started.md) — installation and quick workflows
+- [User Guide](notes/user_guide.md) — detailed guide with API examples
+- [Architecture](notes/architecture.md) — layer overview and links to sub-topics
+- [Developer Guide](notes/developer_guide.md) — setup, testing, contributing
+- [Public API Guide](notes/public_api.md) — recommended imports for user code
+- [DSL Reference](notes/dsl/dsl_guide.md) — Python DSL syntax reference
+- [Support Matrix](notes/support_matrix.md) — practical support status across project surfaces
+- [LSP Server](notes/veriforge_lsp.md) — Verilog/SystemVerilog Language Server Protocol support
+- [Roadmap](notes/roadmap.md) — known future work items
+- [Grammar Support Status](docs/grammar_support.md) — parser-rule metadata table
+- [Grammar Dependencies (JSON)](docs/grammar_deps.json) — machine-readable rule dependency map
+
+## Quick Start
+
+### Parse a Verilog file
+
+```python
+from veriforge.project import parse_file
+from veriforge.codegen import emit_module
+
+design = parse_file("rtl/counter.v", preprocess=True)
+for mod in design.modules:
+    print(emit_module(mod))
+```
+
+### Build hardware with the Python DSL
+
+```python
+from veriforge.dsl import Module, posedge
+from veriforge.codegen import emit_module
+
+with Module("counter") as m:
+    clk = m.input("clk")
+    rst = m.input("rst")
+    count = m.output_reg("count", width=8)
+
+    with m.always(posedge(clk)):
+        with m.if_(rst):
+            count <<= 0
+        with m.else_():
+            count <<= count + 1
+
+print(emit_module(m.build()))
+```
+
+### Simulate directly from Python
+
+```python
+from veriforge.sim import Simulator, Clock
+
+sim = Simulator(m.build())
+sim.fork(Clock(sim.signal("clk"), period=10))
+
+def test(s):
+    s.drive("rst", 1)
+
+sim.run(test, max_time=200)
+print(sim.read("count"))
+```
+
+### Analyze a project
+
+```python
+from veriforge.project import parse_directory
+from veriforge.analysis import analyze_design, lint_design
+
+design = parse_directory("rtl/", preprocess=True)
+analyze_design(design)
+for w in lint_design(design):
+    print(f"[{w.code.name}] {w.message}")
+```
+
+## Installation
+
+### Prerequisites
+- Python (CPython 3.10+ or PyPy 3.10+)
+    - See [python.org](https://www.python.org) for standalone install
+    - For uv-based install see [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+### Dependencies
+- Lark
+- Rich
+- treelib
+
+### PyPy Support (Optional — ~4x Simulation Speedup)
+
+The full test suite passes under PyPy. Running the simulator under PyPy gives
+approximately **4x faster simulation** compared to CPython thanks to JIT
+compilation, with zero code changes required.
+
+1. Install PyPy 3.10+ from https://www.pypy.org/download.html
+2. Install dependencies: `pypy3 -m pip install lark rich treelib`
+3. Run: `pypy3 -m veriforge ...`
+
+### Install with uv (recommended)
+
+```bash
+git clone https://github.com/chiplukes/veriforge
+cd veriforge
+uv sync --extra test
+```
+
+### Install with pip
+
+```bash
+git clone https://github.com/chiplukes/veriforge
+cd veriforge
+python -m venv .venv
+# Activate:
+#   Linux/macOS:       source .venv/bin/activate
+#   Windows PowerShell: .venv\Scripts\activate
+pip install -e .[test]
+```
+
+## CLI Usage
+
+The CLI is subcommand-based (legacy `-f/-t/-r` flags remain supported):
+
+```bash
+# Parse a file and print the syntax tree
+uv run veriforge tree -f path/to/file.v
+
+# Reconstruct Verilog text from the parsed tree
+uv run veriforge reconstruct -f path/to/file.v
+
+# Parse summaries (support --json for automation)
+uv run veriforge parse-file -f rtl/top.v
+uv run veriforge parse-directory rtl/
+
+# Generate a Python testbench skeleton
+uv run veriforge generate-python-testbench --file rtl/top.v
+
+# Export a parsed project to Python DSL files
+uv run veriforge export-dsl rtl/ out_dsl/
+
+# Inspect hierarchy / wrapper candidates (--format text|dot|mermaid)
+uv run veriforge hierarchy graph rtl/
+
+# Grammar tree visualization
+uv run python -m veriforge.lark_file.gen_tree --all --depth 5
+```
+
+See `veriforge <command> --help` for full flag listings and
+[notes/cli_json_schema.md](notes/cli_json_schema.md) for the `--json` output contract.
+
+## Running Tests
+
+```bash
+# Same representative fast slice used by push/PR CI
+uv run --extra test pytest tests/test_verilog_parser/test_all.py tests/test_model/test_module.py tests/test_model/test_instances.py tests/test_model/test_roundtrip.py tests/test_model/test_tree_to_model_characterization.py tests/test_analysis/test_width_inference.py tests/test_analysis/test_const_fold.py tests/test_preprocessor/test_preprocessor.py tests/test_formatter/test_formatter.py --tb=no -q
+
+# Full local suite
+uv run --extra test pytest tests/ --tb=no -q
+```
+
+## Examples
+
+Runnable examples are in the `examples/` directory. See
+[`examples/README.md`](examples/README.md) for prerequisites and category
+guidance.
+
+- `examples/basics/` — counter, shift register, FSM, ALU, testbench
+- `examples/library/` — FIFO, CDC, codec, DSP, Xilinx components
+- `examples/axi/` — AXI-Stream and AXI4-Lite usage
+- `examples/composability/` — pipeline generators, design exploration, register banks
+- `examples/darkriscv/` — real-world RISC-V SoC integration target
+- `examples/femtorv/` — compact RISC-V processor integration target
+- `examples/picorv32/` — PicoRV32 processor integration target
+- `examples/serv/` — SERV bit-serial RISC-V processor integration target
+- `examples/ibex/` — Ibex-related validation assets
+- `examples/pulp/` — imported validation targets based on `pulp-platform` designs
+
+## Current Limitations
+
+veriforge targets RTL-level behavioral simulation and analysis. Before using it, it is worth knowing where the current boundaries are:
+
+**Simulation scope**
+- This is a behavioral RTL simulator, not a replacement for Icarus Verilog, Verilator, or commercial tools for full-chip verification. It is well-suited for unit-level testbenches, design exploration, and cross-validating specific behaviors.
+- X/Z propagation is modeled but corner cases in complex expressions may not match the IEEE spec in all situations. For designs where X-propagation correctness is critical, cross-validate with `IcarusCosim`.
+- Specify blocks (timing annotations) and gate-level / UDP primitives are parsed and emitted but not executed.
+- The compiled Cython engine falls back to reference coroutines for `#delay` / `@(posedge)` inside `initial`/`always` blocks; a `warnings.warn` is emitted when this happens. The workaround is to move timing control into the Python testbench layer.
+
+**SystemVerilog subset**
+- The SystemVerilog verification layer is out of scope: classes, SVA assertions, covergroups, `randomize`/constraints, dynamic arrays, queues, `bind`, and `program` blocks are not simulated.
+- Packed structs, interfaces, and parameterized interfaces work for common RTL patterns but may require flat wrapper modules for complex cases. The [support matrix](notes/support_matrix.md) has the per-construct breakdown.
+- Functions and tasks cover the common RTL patterns used by the validation examples; unusual calling conventions or recursive functions may fail.
+
+**Verilog-to-DSL conversion**
+- The converter (`export-dsl`) is intentionally conservative. Control-flow-heavy constructs, complex always blocks, and module-level generate blocks often require manual rewriting. See [notes/dsl/dsl_conversion_coverage.md](notes/dsl/dsl_conversion_coverage.md) for the detailed gap list.
+
+**Hierarchy refactor tooling**
+- Structural, behavioral, parameterized, and generate-containing wrappers are detected and classified but collapse is intentionally blocked pending safer transforms. Extract and boundary-move operations cover common direct-wiring cases; complex connectivity patterns fail closed with a diagnostic. See [notes/roadmap.md](notes/roadmap.md) for the backlog.
+
+**Performance**
+- Even with the compiled Cython engine, throughput is lower than C-based simulators. For simple sequential testbenches on medium-sized designs, performance is practical. For very large designs or workloads requiring millions of cycles, prefer a dedicated simulator and use veriforge for the analysis and testbench-generation layers.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)

veriforge-0.0.1/README.md

@@ -0,0 +1,224 @@
+# veriforge
+[![CI](https://github.com/chiplukes/veriforge/actions/workflows/ci.yml/badge.svg)](https://github.com/chiplukes/veriforge/actions/workflows/ci.yml)
+[![Changelog](https://img.shields.io/github/v/release/chiplukes/veriforge?include_prereleases&label=changelog)](https://github.com/chiplukes/veriforge/releases)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/chiplukes/veriforge/blob/main/LICENSE)
+
+A Python library for parsing, analyzing, generating, and simulating Verilog/SystemVerilog designs, built on the [Lark](https://github.com/lark-parser/lark) parser.
+
+## Features
+
+- **Parse** Verilog 2005 (with SystemVerilog extensions) into a semantic model
+- **Preprocess** source files (`` `define ``, `` `ifdef ``, `` `include ``, `` `timescale ``, etc.)
+- **Multi-file project** support — parse directories, link cross-module instances
+- **Analyze** designs — width inference, constant folding, clock/reset extraction, lint checks
+- **Emit** formatted Verilog from the model (round-trip, configurable style)
+- **Python DSL** — build hardware with operator-overloaded Python, emit to Verilog or simulate directly
+- **Component library** — FIFO, CDC, codec, AXI-Stream, AXI4-Lite, DSP, RAM, Xilinx inference
+- **Auto-generate testbenches** from any module
+- **Convert** parsed Verilog to DSL code (Verilog → Python translation)
+- **Simulate** — event-driven 4-state simulator with three engines (reference, bytecode VM, compiled Cython)
+- **VCD output** — IEEE 1364-2001 waveform dumps, cross-simulator validation
+- **Inspect** semantic models through lookup helpers and JSON serialization
+- **Language Server** — `veriforge-lsp` provides editor diagnostics, symbols, navigation, hover, and custom hierarchy/trace commands (install [Verible](https://github.com/chipsalliance/verible) for fast between-save diagnostics; the server falls back to the built-in Lark parser when Verible is absent)
+
+## Documentation
+
+- [Getting Started](notes/getting_started.md) — installation and quick workflows
+- [User Guide](notes/user_guide.md) — detailed guide with API examples
+- [Architecture](notes/architecture.md) — layer overview and links to sub-topics
+- [Developer Guide](notes/developer_guide.md) — setup, testing, contributing
+- [Public API Guide](notes/public_api.md) — recommended imports for user code
+- [DSL Reference](notes/dsl/dsl_guide.md) — Python DSL syntax reference
+- [Support Matrix](notes/support_matrix.md) — practical support status across project surfaces
+- [LSP Server](notes/veriforge_lsp.md) — Verilog/SystemVerilog Language Server Protocol support
+- [Roadmap](notes/roadmap.md) — known future work items
+- [Grammar Support Status](docs/grammar_support.md) — parser-rule metadata table
+- [Grammar Dependencies (JSON)](docs/grammar_deps.json) — machine-readable rule dependency map
+
+## Quick Start
+
+### Parse a Verilog file
+
+```python
+from veriforge.project import parse_file
+from veriforge.codegen import emit_module
+
+design = parse_file("rtl/counter.v", preprocess=True)
+for mod in design.modules:
+    print(emit_module(mod))
+```
+
+### Build hardware with the Python DSL
+
+```python
+from veriforge.dsl import Module, posedge
+from veriforge.codegen import emit_module
+
+with Module("counter") as m:
+    clk = m.input("clk")
+    rst = m.input("rst")
+    count = m.output_reg("count", width=8)
+
+    with m.always(posedge(clk)):
+        with m.if_(rst):
+            count <<= 0
+        with m.else_():
+            count <<= count + 1
+
+print(emit_module(m.build()))
+```
+
+### Simulate directly from Python
+
+```python
+from veriforge.sim import Simulator, Clock
+
+sim = Simulator(m.build())
+sim.fork(Clock(sim.signal("clk"), period=10))
+
+def test(s):
+    s.drive("rst", 1)
+
+sim.run(test, max_time=200)
+print(sim.read("count"))
+```
+
+### Analyze a project
+
+```python
+from veriforge.project import parse_directory
+from veriforge.analysis import analyze_design, lint_design
+
+design = parse_directory("rtl/", preprocess=True)
+analyze_design(design)
+for w in lint_design(design):
+    print(f"[{w.code.name}] {w.message}")
+```
+
+## Installation
+
+### Prerequisites
+- Python (CPython 3.10+ or PyPy 3.10+)
+    - See [python.org](https://www.python.org) for standalone install
+    - For uv-based install see [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+### Dependencies
+- Lark
+- Rich
+- treelib
+
+### PyPy Support (Optional — ~4x Simulation Speedup)
+
+The full test suite passes under PyPy. Running the simulator under PyPy gives
+approximately **4x faster simulation** compared to CPython thanks to JIT
+compilation, with zero code changes required.
+
+1. Install PyPy 3.10+ from https://www.pypy.org/download.html
+2. Install dependencies: `pypy3 -m pip install lark rich treelib`
+3. Run: `pypy3 -m veriforge ...`
+
+### Install with uv (recommended)
+
+```bash
+git clone https://github.com/chiplukes/veriforge
+cd veriforge
+uv sync --extra test
+```
+
+### Install with pip
+
+```bash
+git clone https://github.com/chiplukes/veriforge
+cd veriforge
+python -m venv .venv
+# Activate:
+#   Linux/macOS:       source .venv/bin/activate
+#   Windows PowerShell: .venv\Scripts\activate
+pip install -e .[test]
+```
+
+## CLI Usage
+
+The CLI is subcommand-based (legacy `-f/-t/-r` flags remain supported):
+
+```bash
+# Parse a file and print the syntax tree
+uv run veriforge tree -f path/to/file.v
+
+# Reconstruct Verilog text from the parsed tree
+uv run veriforge reconstruct -f path/to/file.v
+
+# Parse summaries (support --json for automation)
+uv run veriforge parse-file -f rtl/top.v
+uv run veriforge parse-directory rtl/
+
+# Generate a Python testbench skeleton
+uv run veriforge generate-python-testbench --file rtl/top.v
+
+# Export a parsed project to Python DSL files
+uv run veriforge export-dsl rtl/ out_dsl/
+
+# Inspect hierarchy / wrapper candidates (--format text|dot|mermaid)
+uv run veriforge hierarchy graph rtl/
+
+# Grammar tree visualization
+uv run python -m veriforge.lark_file.gen_tree --all --depth 5
+```
+
+See `veriforge <command> --help` for full flag listings and
+[notes/cli_json_schema.md](notes/cli_json_schema.md) for the `--json` output contract.
+
+## Running Tests
+
+```bash
+# Same representative fast slice used by push/PR CI
+uv run --extra test pytest tests/test_verilog_parser/test_all.py tests/test_model/test_module.py tests/test_model/test_instances.py tests/test_model/test_roundtrip.py tests/test_model/test_tree_to_model_characterization.py tests/test_analysis/test_width_inference.py tests/test_analysis/test_const_fold.py tests/test_preprocessor/test_preprocessor.py tests/test_formatter/test_formatter.py --tb=no -q
+
+# Full local suite
+uv run --extra test pytest tests/ --tb=no -q
+```
+
+## Examples
+
+Runnable examples are in the `examples/` directory. See
+[`examples/README.md`](examples/README.md) for prerequisites and category
+guidance.
+
+- `examples/basics/` — counter, shift register, FSM, ALU, testbench
+- `examples/library/` — FIFO, CDC, codec, DSP, Xilinx components
+- `examples/axi/` — AXI-Stream and AXI4-Lite usage
+- `examples/composability/` — pipeline generators, design exploration, register banks
+- `examples/darkriscv/` — real-world RISC-V SoC integration target
+- `examples/femtorv/` — compact RISC-V processor integration target
+- `examples/picorv32/` — PicoRV32 processor integration target
+- `examples/serv/` — SERV bit-serial RISC-V processor integration target
+- `examples/ibex/` — Ibex-related validation assets
+- `examples/pulp/` — imported validation targets based on `pulp-platform` designs
+
+## Current Limitations
+
+veriforge targets RTL-level behavioral simulation and analysis. Before using it, it is worth knowing where the current boundaries are:
+
+**Simulation scope**
+- This is a behavioral RTL simulator, not a replacement for Icarus Verilog, Verilator, or commercial tools for full-chip verification. It is well-suited for unit-level testbenches, design exploration, and cross-validating specific behaviors.
+- X/Z propagation is modeled but corner cases in complex expressions may not match the IEEE spec in all situations. For designs where X-propagation correctness is critical, cross-validate with `IcarusCosim`.
+- Specify blocks (timing annotations) and gate-level / UDP primitives are parsed and emitted but not executed.
+- The compiled Cython engine falls back to reference coroutines for `#delay` / `@(posedge)` inside `initial`/`always` blocks; a `warnings.warn` is emitted when this happens. The workaround is to move timing control into the Python testbench layer.
+
+**SystemVerilog subset**
+- The SystemVerilog verification layer is out of scope: classes, SVA assertions, covergroups, `randomize`/constraints, dynamic arrays, queues, `bind`, and `program` blocks are not simulated.
+- Packed structs, interfaces, and parameterized interfaces work for common RTL patterns but may require flat wrapper modules for complex cases. The [support matrix](notes/support_matrix.md) has the per-construct breakdown.
+- Functions and tasks cover the common RTL patterns used by the validation examples; unusual calling conventions or recursive functions may fail.
+
+**Verilog-to-DSL conversion**
+- The converter (`export-dsl`) is intentionally conservative. Control-flow-heavy constructs, complex always blocks, and module-level generate blocks often require manual rewriting. See [notes/dsl/dsl_conversion_coverage.md](notes/dsl/dsl_conversion_coverage.md) for the detailed gap list.
+
+**Hierarchy refactor tooling**
+- Structural, behavioral, parameterized, and generate-containing wrappers are detected and classified but collapse is intentionally blocked pending safer transforms. Extract and boundary-move operations cover common direct-wiring cases; complex connectivity patterns fail closed with a diagnostic. See [notes/roadmap.md](notes/roadmap.md) for the backlog.
+
+**Performance**
+- Even with the compiled Cython engine, throughput is lower than C-based simulators. For simple sequential testbenches on medium-sized designs, performance is practical. For very large designs or workloads requiring millions of cycles, prefer a dedicated simulator and use veriforge for the analysis and testbench-generation layers.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)