Metadata-Version: 2.4
Name: sc-cxxrtl
Version: 0.0.2
Summary: A CXXRTL (Yosys) cocotb simulator for SiliconCompiler — installed, not patched in
Author: sc-cxxrtl contributors
License-Expression: ISC
Project-URL: Homepage, https://github.com/lanserge/sc-cxxrtl
Project-URL: Repository, https://github.com/lanserge/sc-cxxrtl
Keywords: siliconcompiler,cxxrtl,yosys,cocotb,simulation,verification,eda
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: siliconcompiler
Requires-Dist: cxxrtl-vpi
Requires-Dist: cocotb>=2.0
Dynamic: license-file

# sc-cxxrtl

[![PyPI](https://img.shields.io/pypi/v/sc-cxxrtl)](https://pypi.org/project/sc-cxxrtl/)
[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)

**A CXXRTL cocotb simulator for [SiliconCompiler](https://github.com/siliconcompiler/siliconcompiler) — installed, not patched in.**

`pip install sc-cxxrtl` adds the Yosys **CXXRTL** engine as a cocotb simulator to
SiliconCompiler **without modifying SiliconCompiler**. SC executes whatever
`Task`/`Flowgraph` subclasses a flow contains, and those live in this package —
so no SC source change is needed.

Built on:
- [**cxxrtl-vpi**](https://github.com/lanserge/cxxrtl-vpi) — the engine adapter
  that makes cocotb drive a CXXRTL model (an IEEE-1364 VPI implementation over
  `cxxrtl_capi`),
- **cocotb** ≥ 2.0 — the Python testbench framework,
- **Yosys** — `write_cxxrtl` + a C++ compiler (external, like every SC simulator).

## Install

```sh
pip install sc-cxxrtl
```

This pulls in `cxxrtl-vpi`, `cocotb`, and `siliconcompiler`. Requires **Python
≤ 3.13** (cocotb's cap), plus **Yosys** (`yosys` / `yosys-config`) and a **C++
compiler** on `PATH` — the same external precondition as every SiliconCompiler
simulator. (Latest from git:
`pip install git+https://github.com/lanserge/sc-cxxrtl`.)

## Use

```python
from siliconcompiler import Design, Project
from sc_cxxrtl import CxxrtlDVFlow

design = Design("counter")
with design.active_fileset("rtl"):
    design.set_topmodule("counter")
    design.add_file("counter.v")
with design.active_fileset("tb"):
    design.add_file("test_counter.py")   # a cocotb test (filetype: python)

proj = Project(design)
proj.add_fileset("rtl")
proj.add_fileset("tb")
proj.set_flow(CxxrtlDVFlow())             # <- the only line that mentions cxxrtl
proj.run()
```

The flow is two nodes:

```
compile   (cxxrtl/cocotb_compile)  RTL -> CXXRTL model -> link cxxrtl-vpi + cocotb -> outputs/<top>.vexe
   │
simulate  (cxxrtl/exec_cocotb)     run the executable under cocotb -> results.xml
```

### Tool-named fileset

Like SiliconCompiler's built-in `verilator`/`icarus` tasks, the compile task is
**tool-fileset-aware**: if the design defines a fileset named after the tool
(`cxxrtl`), RTL is sourced from that fileset's subtree. Give it
`add_depfileset(self, "rtl")` to pull in the base RTL, and put any
CXXRTL-specific includes/defines there:

```python
with design.active_fileset("rtl"):
    design.set_topmodule("dut")
    design.add_file("dut.v")
with design.active_fileset("cxxrtl"):
    design.add_depfileset(design, "rtl")  # cxxrtl depends on rtl
```

This keeps a sibling `verilator` fileset (e.g. one carrying DPI/switchboard
shims) out of the CXXRTL build — the same fileset convention used across the SC
ecosystem. When the design has no `cxxrtl` fileset, all active filesets are used
(unchanged behavior).

### Init fuzzing (X-dependence detection)

CXXRTL is 2-state and inits flop state to 0, so a design that secretly relies on
uninitialized state passes silently. The compile task exposes Verilator-style
`--x-initial unique` fuzzing:

```python
from sc_cxxrtl import CxxrtlCocotbCompileTask
CxxrtlCocotbCompileTask.find_task(proj).set_randomize_init(True, seed=42)
```

This seeds uninitialized flops with `setundef -init -random`; vary the seed
across runs to expose X-dependence.

### Waveform tracing

Enable a VCD dump (written to `reports/<design>.vcd`) on the exec task:

```python
from sc_cxxrtl import CxxrtlCocotbExecTask
CxxrtlCocotbExecTask.find_task(proj).set_trace(True)
```

A complete, runnable example is in [`examples/counter/`](examples/counter)
(`python make.py`). It passes:

```
test_counter.test_count_up     PASS
TESTS=1 PASS=1 FAIL=0 SKIP=0
PASS: cocotb test ran on CXXRTL via SiliconCompiler
```

## Why no SC patch is needed

SC's flow/task model is open by composition: a flow instantiates `Task`
subclasses, which may live in any installed package. `CxxrtlDVFlow` wires
`CxxrtlCocotbCompileTask` + `CxxrtlCocotbExecTask` (the latter reuses SC's own
`CocotbTask` for environment setup, exactly like the built-in `verilator-cocotb`
tasks). The only thing SC's *built-in* `DVFlow(tool=…)` can't do is grow a
`"cxxrtl"` branch on its own — which is why this package ships its own flow.
(Making the built-in `DVFlow` auto-discover plugins via a `siliconcompiler.flows`
entry-point group would be a small, generic upstream contribution.)

## License

ISC.
