Metadata-Version: 2.4
Name: svling
Version: 0.4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
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 :: Rust
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Dist: pyslang-dev
License-File: LICENSE
Summary: SystemVerilog simulator: pyslang frontend + Rust runtime + time-travel + RTL-as-Python-callable + cocotb adapter + WASM-buildable
Keywords: systemverilog,verilog,simulation,vvp,iverilog,eda
Author: Chaitanya Sharma
License: GPL-2.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/cheeksthegeek/svling
Project-URL: Issues, https://github.com/cheeksthegeek/svling/issues
Project-URL: Source, https://github.com/cheeksthegeek/svling

# svling

**S**ystem**V**erilog compiler + runtime + **time-travel debugger** +
**RTL-as-Python-callable** — in one package.

`svling` bundles:

- **`sling`** — a SystemVerilog → VVP compiler frontend built on
  [pyslang](https://github.com/MikePopoloski/slang) (full IEEE
  1800-2023 LRM coverage).
- **`evvp`** — a Rust reimplementation of Icarus Verilog's `vvp`
  runtime, exposed to Python via pyo3 and invoked in-process.
- **`sling.Simulator`** — time-travel-capable Python wrapper:
  `.checkpoint() / .restore() / .fork()` for parallel-universe debugging.
- **`sling.Design`** — pyslang AST access, `.compile_as_function()` to
  turn combinational modules into Python callables, `.compile_as_object()`
  for stateful ones, auto-generated Python `IntEnum` / `dataclass` from
  RTL `typedef`s.
- **`sling.features`** — protocol detection (AXI4-Lite, APB, etc.), FSM
  identification, auto-assertion synthesis, mutation testing, coverage,
  recorder→pandas/numpy, counterfactual sim, invariant discovery,
  differential testing, git-bisect-RTL, design space sweep, and more.

The whole stack ships as a single wheel containing the Python compiler
sources and one `sling/_native.abi3.so` carrying the entire runtime.

## Highlights

### Time-travel debugging

```python
import sling

sim = sling.Simulator.from_sv("counter.sv")
sim.step_cycles(50)
cp = sim.checkpoint()             # O(N) deep clone

sim.step_cycles(50)
print(sim.read_int("tb.count"))   # value at t=100

sim.restore(cp)                   # rewind
print(sim.read_int("tb.count"))   # value at t=50

fork = sim.fork(cp)               # independent timeline
```

### RTL module as a Python callable

```python
d = sling.Design.from_sv("alu.sv")
alu = d.compile_as_function("alu")
print(alu(a=42, b=17, op=0))      # → {'result': 59}

counter = d.compile_as_object("counter", clock="clk", reset="rst_n")
counter.reset()
print(counter.cycle(en=1))        # → {'count': 1}
```

### Auto-generated Python types from RTL

```python
d = sling.Design.from_string("""
    typedef enum logic [1:0] {IDLE, RUN, DONE} state_t;
    typedef struct packed { logic [7:0] addr; logic [3:0] cmd; } pkt_t;
    module top (output state_t s, output pkt_t p);  ...  endmodule
""")
State = d.py_enums()["state_t"]
Pkt   = d.py_structs()["pkt_t"]
print(State.RUN.value)            # → 1
print(Pkt(addr=0xAB, cmd=0x3).to_bits())
```

### Verification features

```python
f = sling.features
f.find_state_machines(d)          # AST-detected FSMs
f.detect_protocols(d, "axi_dut")  # AXI4-Lite/APB/SPI/I2C/UART/...
f.synthesize_assertions(d)        # enum-legality SVA strings
f.counterfactual(sim, until=100, overrides={"signal": 0xFF})
f.discover_invariants(recorder)
f.bisect_regression("rtl/alu.sv", test_fn, ...)
f.mutate(sv_source, test_fn)      # mutation testing
```

## Install

```sh
pip install svling
# or
uv tool install svling
```

## Use

```sh
# Compile and run in one go:
svling design.sv tb.sv

# Compile only (write a .vvp file):
sling -o design.vvp design.sv

# Run a pre-compiled .vvp through the Rust runtime in-process:
python -c "from sling._native import run_cli; run_cli(['evvp', '-N', 'design.vvp'])"
```

Anything that starts with `+` on the `svling` command line is forwarded
to the runtime as a Verilog plusarg (e.g. `+verbose`, `+seed=42`). Use
`--` to forward arbitrary extra flags to the runtime.

## Layout

```
svling/
├── sling/          Python frontend (pyslang → VVP)
├── evvp/           Rust crate: VVP runtime; produces both a standalone
│                   `evvp` binary and a pyo3 cdylib for the wheel
├── tests/          Sample SystemVerilog used by the docs
└── pyproject.toml  maturin build, project metadata, console scripts
```

## License

GPL-2.0-or-later. evvp is a clean-room reimplementation of Icarus
Verilog's `vvp`, which is GPL-2.0; this package keeps the same license.

