Merge pull request #1 from bhavayarora-bosch/main

Extend SCVPI with additional VPI support, examples, and CI workflow

Author: mballance

.github/workflows/ci.yaml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  COCOTB_ANSI_OUTPUT: 1
+  FORCE_COLOR: 1
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: "0.9.27"
+        enable-cache: true
+
+    - name: Install dependencies
+      env:
+        DEBIAN_FRONTEND: noninteractive
+      run: |
+        echo "::group::apt-get update"
+        sudo apt-get update
+        echo "::endgroup::"
+
+        echo "::group::apt-get install"
+        sudo apt-get install --yes --no-install-recommends \
+          iverilog \
+          cpp \
+          cmake \
+          libsystemc \
+          libsystemc-dev
+        echo "::endgroup::"
+
+    - name: Run tests on Python ${{ matrix.python-version }}
+      run: |
+        uv venv
+        source .venv/bin/activate
+        uv sync --locked --all-extras --dev
+
+        for ex in basic adder TinyALU_SystemC; do
+          make -C examples/$ex show-config
+          make -C examples/$ex run-icarus
+        done

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -1,18 +1,90 @@
-# scvpi
-Provides a stub implementation of (System)Verilog VPI functions for SystemC. 
-Currently, this is just enough to allow cocotb to schedule coroutines. 
-Access to signals, and other RTL-like things is not currently implemented. The purpose
-of this package is to enable running a Python testbench with high-level SystemC
-models.
+# SCVPI
 
+SCVPI is a VPI-compatible interface for SystemC that enables **cocotb**
+and cocotb-based frameworks such as **PyUVM** to run on SystemC models.
 
-## Using scvpi
+By providing a VPI-compatible layer, SCVPI allows Python-based
+verification environments to be reused across both RTL and SystemC,
+eliminating duplicated verification infrastructure and enabling a
+unified verification flow.
 
-- Compile scvpi with your SystemC model
-    - Add <scvpi>/src/scvpi.cpp to your SystemC files
-    - Add <scvpi>/src as an include path
-    
-- Specify VPI libraries to load at runtime
-    - Add +vpi=<path_to_so> to the SystemC command line
-    
+---
 
+## Motivation
+
+Python-based verification frameworks such as cocotb and PyUVM are widely
+used for RTL verification due to their productivity and reusability.
+However, these frameworks rely on the Verilog Procedural Interface (VPI)
+and therefore cannot be applied directly to SystemC models.
+
+SystemC is commonly used for high-level modeling and virtual prototyping.
+This separation often leads to duplicated testbenches and inconsistent
+verification behavior between RTL and high-level models.
+
+SCVPI bridges this gap by exposing a VPI-compatible interface for
+SystemC, allowing cocotb and PyUVM testbenches to execute on SystemC
+models without modification.
+
+---
+
+## What SCVPI Provides
+
+- A VPI-compatible interface for SystemC
+- Coroutine scheduling support required by cocotb
+- Signal access and callback mechanisms required by PyUVM
+- Reuse of Python testbenches without modification
+- A unified verification flow across RTL and SystemC models
+
+---
+
+## Supported SystemC Signal Types
+
+SCVPI currently supports direct value access for a subset of SystemC
+signal types, including:
+
+- `sc_signal<bool>`
+- `sc_signal<int>` (treated as 32-bit)
+- `sc_signal<sc_int<4>>`
+- `sc_signal<sc_uint<3>>`
+- `sc_signal<sc_uint<8>>`
+- `sc_signal<sc_uint<16>>`
+
+Signals with unsupported types are reported as unknown.
+
+---
+
+## Examples
+
+The repository includes several examples demonstrating different usage
+scenarios:
+
+- **examples/basic**  
+  Minimal sanity check demonstrating cocotb coroutine scheduling on a
+  SystemC model.
+
+- **examples/adder**  
+  A simple functional example with deterministic and randomized tests.
+
+- **examples/TinyALU_SystemC**  
+  A SystemC implementation of the official PyUVM TinyALU example.
+  The original PyUVM testbench is reused unchanged, demonstrating
+  verification reuse between RTL and SystemC using SCVPI.
+
+These examples serve as reference implementations for integrating SCVPI
+with SystemC models and reusing Python-based verification environments.
+
+---
+
+## Scope and Limitations
+
+SCVPI is intended for verification of high-level SystemC models.
+It does not aim to replace RTL simulators or provide full Verilog
+compatibility. Performance characteristics may differ from RTL-based
+verification flows.
+
+---
+
+## License
+
+This project is released under the applicable open-source license.
+Third-party examples and testbenches retain their original licenses.

examples/TinyALU_SystemC/Makefile

@@ -0,0 +1,47 @@
+SYSTEMC ?= /usr
+CXX ?= g++
+
+ROOT ?= ../..
+SCVPI_SRC := $(ROOT)/src
+
+CXXFLAGS += -I$(SYSTEMC)/include -I./hdl -I$(SCVPI_SRC) -export-dynamic
+LDFLAGS  += -L$(SYSTEMC)/lib-linux64 -ldl -lsystemc
+
+COCOTB_CMD           = $(shell command -v uv >/dev/null 2>&1 && echo "uv run cocotb-config" || echo "cocotb-config")
+COCOTB_LIBPYTHON     = $(shell $(COCOTB_CMD) --libpython 2>/dev/null || echo "")
+COCOTB_LIBPYTHON_DIR = $(dir $(COCOTB_LIBPYTHON))
+COCOTB_PYTHON_BIN    = $(shell $(COCOTB_CMD) --python-bin 2>/dev/null || echo "python3")
+COCOTB_LIB_DIR       = $(shell $(COCOTB_CMD) --lib-dir 2>/dev/null || echo "")
+COCOTB_VPI_ICARUS    = $(COCOTB_LIB_DIR)/libcocotbvpi_icarus.vpl
+
+COCOTB_ENV = \
+	PYTHONPATH=.:$$PYTHONPATH \
+	PYGPI_PYTHON_BIN=$(COCOTB_PYTHON_BIN) \
+	COCOTB_TEST_MODULES=testbench \
+	LD_LIBRARY_PATH=$(SYSTEMC)/lib-linux64:$(COCOTB_LIBPYTHON_DIR):$$LD_LIBRARY_PATH
+
+.PHONY: all
+all: test
+
+test: hdl/main.cpp hdl/tinyalu_systemc.h $(SCVPI_SRC)/scvpi.cpp
+	$(CXX) $(CXXFLAGS) $(SCVPI_SRC)/scvpi.cpp hdl/main.cpp -o test $(LDFLAGS)
+
+.PHONY: run-icarus
+run-icarus: test
+	@$(COCOTB_ENV) ./test -m $(COCOTB_VPI_ICARUS)
+
+.PHONY: clean
+clean:
+	rm -f test
+
+.PHONY: show-config
+show-config:
+	@echo "=== TinyALU SystemC Configuration ==="
+	@echo "SYSTEMC: $(SYSTEMC)"
+	@echo "CXX: $(CXX)"
+	@echo "SCVPI_SRC: $(SCVPI_SRC)"
+	@echo ""
+	@echo "=== Cocotb Configuration ==="
+	@echo "COCOTB_PYTHON_BIN: $(COCOTB_PYTHON_BIN)"
+	@echo "COCOTB_LIBPYTHON: $(COCOTB_LIBPYTHON)"
+	@echo "COCOTB_VPI_ICARUS: $(COCOTB_VPI_ICARUS)"

examples/TinyALU_SystemC/hdl/main.cpp

@@ -0,0 +1,40 @@
+#include <systemc>
+#include "tinyalu_systemc.h"
+
+extern "C" void scvpi_autoregister_all();
+
+SC_MODULE(Top) {
+  sc_signal<bool> reset_n{"reset_n"};
+  sc_signal<bool> clk{"clk"};
+  sc_signal<bool> start{"start"};
+
+  sc_signal<sc_dt::sc_uint<8>>  A{"A"};
+  sc_signal<sc_dt::sc_uint<8>>  B{"B"};
+  sc_signal<sc_dt::sc_uint<3>>  op{"op"};
+
+  sc_signal<bool>               done{"done"};
+  sc_signal<sc_dt::sc_uint<16>> result{"result"};
+
+  tinyalu dut{"tinyalu"};
+
+  SC_CTOR(Top) {
+    dut.reset_n(reset_n);
+    dut.clk(clk);
+    dut.start(start);
+    dut.A(A);
+    dut.B(B);
+    dut.op(op);
+    dut.done(done);
+    dut.result(result);
+  }
+};
+
+int sc_main(int argc, char* argv[]) {
+
+  Top top{"top"};
+  scvpi_autoregister_all();
+
+  sc_core::sc_set_stop_mode(sc_core::SC_STOP_IMMEDIATE);
+  sc_core::sc_start();
+  return 0;
+}