Running Python code in SystemVerilog


License
BSD-2-Clause
Install
pip install pysv==0.3.1

Documentation

pysv: Running Python Code in SystemVerilog

Latest Documentation Status Github CI Buildkite CI PyPI package

pysv is a lightweight Python library that allows functional models to be written in Python and then executed inside standard SystemVerilog simulators, via DPI.

Documentation is here.

Core Features

pysv is designed to be versatile and can be used directly or as a library in other hardware generator frameworks. It offers the following features:

  • C/C++ and SystemVerilog binding code generation
  • Foreign modules, e.g. numpy or tensorflow.
  • Python functions
  • Python classes
  • Numpy array view of SV open array
  • Platform-independent compilation

Supported Simulators

Theoretically any simulator that supports SystemVerilog DPI semantics should work. Here is a list of simulators that have been tested:

  • Cadence® Xcelium™
  • Synopsys VCS®
  • Mentor Questa®
  • Vivado® Simulator
  • Verilator

Dependencies

pysv leverages pybind11 to execute arbitrary Python code. As a result, here is a list of dependencies

  • cmake 3.4 or newer
  • Any C++ compiler that supports C++11:
    • Clang/LLVM 3.3 or newer (for Apple Xcode’s clang, this is 5.0.0 or newer)
    • GCC 4.8 or newer
  • Python 3.6 or newer

Usage Example

Here is a simple example to show a Python class that uses numpy for computation.

import numpy as np
from pysv import sv, compile_lib, DataType, generate_sv_binding

class Array:
    def __init__(self):
        # constructor without any extra argument is exported to SV directly
        self.__array = []

    @sv()
    def add_element(self, i):
        self.__array.append(i)

    @sv()
    def min(self):
        # call the numpy function
        return np.min(self.__array)

    @sv(return_type=DataType.Bit)
    def exists(self, value):
        return self.__exists(value)

    def __exists(self, value):
        # this function is not exposed to SystemVerilog
        return value in self.__value

# compile the code into a shared library for DPI to load
# build the lib inside the ./build folder
# lib_path is the path to the shared library file
lib_path = compile_lib([Array], cwd="build")
# generate SV bindings
generate_sv_binding([Array], filename="array_pkg.sv", pkg_name="demo")

Now we can use the class directly with the SystemVerilog binding:

// import Array
import demo::*;

Array a = new();
a.add_element(1);
assert(a.exists(1));
assert(!a.exists(2));
// numpy under the hood!
assert(a.min() == 1);

To use an array as a function argument, use DataType.IntArray. As the name indicates, pysv currently only support int32_t arrays of any dimension. More data types supports will be worked on in the future. Here is an example of how to use it in Python:

@sv(a=DataType.IntArray)
def set_value(a):
    print(a)
    a[2] = 42

It is implemented via py::memoryview, which offers a mutable view of a raw array of any dimension. pysv assumes row-major ordering of the underlying multi-dimensional array. To use multi-dimensional array, use DataType.IntArray[n], where n is the number of dimension, e.g. DataType.IntArray[2] creates a 2-D array. Note that due to the usage of Python memoryview, only numpy style indexing is supported, e.g. a[1, 2]. To see more details, please check out the CPython discussion. If you don't need to modify the underlying array, you can use numpy to convert the data to a numpy array for further processing.