pysv integration

[Kuree]

This is a thread to keep track of pysv integration and any related discussion.

Background info:

For a large scale simulation, static test bench compilation is not feasible since it increases the code size. In cases where the ordering or cycle-accurate values are non-deterministic, it would be challenging given current fault semantics. See #280 for an example.

What does pysv do

It is a lightweight library to compile arbitrary Python code into a shared object as well as generating binding code for various targets. Here is a list of supported simulators:

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

Here is an example of usage:

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):
        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

and here is the SystemVerilog usage:

// import Array
import demo::*;

Array a = new();
a.add_element(1);
assert(a.exists(1));
assert(!a.exists(2));

Integration issues

Although pysv is designed to be framework independent, depends on the semantics of the underlying framework, some tasks might be difficult to do. Here are some questions in my mind:

1. Is there any high demand to let pysv be a required package for fault? Or optional is fine?

2. What is the convenient semantics in fault?
   There are two ways to get the function call objects from pysv:

   • Use the function make_call, e.g.

     @sv()
     def foo(a, b):
         pass
     call_inst = make_call(foo, 1, 2)

   • turn off the evaluation on function call globally

     set_run_function(False)
     call_inst = foo(1, 2)

   Personally I prefer to use the first one in fault since there is no ambiguity. However it doesn't match the functional call syntax people usually use.

   Similar question also goes to how to create a class.

3. pysv supports all SystemVerilog primitive types, such as logic, int, and string. Are user responsible for the type casting? For most parts, logc can be used directly in liu of actual integral values, but width match can still happen. Should we also support to strings or arrays?

@leonardt Please let me know your thoughts.

[leonardt]

Thanks for the writeup.

1. Can pysv be installed as a wheel? If so, I don't see much reason not to include it by default (as long as it's easy to install and not huge). I would say making it optional would only be necessary if (a) it's difficult to install portably or (b) it's a large binary that takes a while to download or consumes a lot of space. I think the way ipython jupyter works (e.g. pip install jupyter[notebook] where you can choose options is pretty nice, but it may not be worth the effort (we could always add this later on if it becomes problematic).
2. I think the make_call approach could work, since for now we'd probably use it like tester.call(foo, 1, 2) so we can do that internally.
3. for logic, we could use BitVector, but I think implicitly converting integers to logic would be convenient and useful. Perhaps we can support conversions as long as they don't truncate (the value has too many bits required to represent). If the number is too large, then we should issue an error since that's probably an accident (they can truncate explicitly). python int to sv int seems fine (there's probably a size limit on SV integers, so we should issue an error here if we would need to truncate, since Python uses infinite sized integers). python string to sv string seems fine to convert. for arrays, we could do nested lists, python arrays, or numpy.ndarrays. This seems useful/convenient (we support lists for poking magma arrays in fault, so it's already a pattern we use).

[Kuree]

1. Yes. It's actually a pure-Python wheel so it can run on any machine (Windows not tested but theoretically should work). After zipping it's only 304kb.
2. Sounds good. I will use that approach when adding the wrapper to fault
3. SV-DPI standards supports open array with arbitrary dimensions. One caveat with that is the array access implementation is vendor-dependent, so it is typically leave as undefined symbols in the shared library and let simulator/linker figures out the function pointers. I vaguely remember having issue with Verilator on MacOS where clang is complaining about undefined symbols when creating a shared library, whereas it is fine on Linux. I might need your help when we come to that.

[leonardt]

For 3., it's likely you'll need the -undefined dynamic_lookup if you haven't tried that already. A safer option is -Wl,-U,symbol_name which does this for a specific symbol, but is annoying if you have a lot of undefined symbols (but this way you don't accidentally think a missing symbol is dynamically looked up when it really is a compile time bug)

[Kuree]

No I haven't. I tend to avoid debugging builds on MacOS since the only access I have is via CI. I will try that out when I start to implement arrays.

[leonardt]

With #289 merged lets closed this and use new issues to track anything that comes up.