Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Embedding the interpreter

PyStim mainly focuses on extending SystemVerilog using Python, by embedding the Python interpreter into a SystemVerilog program. This allows the SystemVerilog program to execute Python code and interact with Python objects. All of the other documentation pages still apply here, so refer to them for general PyStim usage.

## Getting started

A basic simulation with an embedded interpreter can be created with just a few lines of bash code and the `pystim_pkg` package methods, as shown below. For more information, see Build systems.

    source ../../scripts/environment.sh
    ./run.sh questa

The essential structure of the `hello_world.sv` file looks like this:

    import pystim_pkg::*;

    module hello_world();
        typedef pystim py;

        initial begin
            py::initialize_interpreter();
            py::print(py::str_("Hello world."));
            py::finalize_interpreter();
        end
    endmodule

The interpreter must be initialized before using any Python, which includes all the functions and classes in PyStim. The methods class `initialize_interpreter()`, and `finalize_interpreter()` are used to manage interpreter lifetime. After the `finalize_interpreter()` call, the Python interpreter shuts down and clears its memory. No Python functions can be called after this.

## Importing modules

Python modules can be imported using `py_module::import_()`:

    py_module sys = py_module::import_("sys");
    py::print(sys.attr("path").obtain());

For convenience, the current working directory is included in `sys.path` when embedding the interpreter. This makes it easy to import local Python files:

    """calc.py located in the working directory"""

    def add(i, j):
        return i + j

    begin
        py_module calc = py_module::import_("add_numbers");
        py_object res = calc.attr("add").call(py::int_(1), py::float_(2.2));
        int n = res.cast_int().get_value();
        assert (n == 3.2)
    end

## Interpreter lifetime

The Python interpreter starts up with `initialize_interpreter` and shuts down when `finalize_interpreter` is called. HDL simulation permits only one pair of `initialize_interpreter` and `finalize_interpreter` function calls. After this, creating a new instance of interpreter not possible. The `initialize_interpreter` / `finalize_interpreter` methods can be used anywhere in the SystemVerilog code to set the state of the interpreter at any time.

Warning

Starting two python interpreters is a fatal error. So is calling `initialize_interpreter` for a second time after the interpreter has already been initialized will case a fatal error. The same applies to calling `finalize_interpreter` for a second time after the interpreter has already been finalized.

Do not use the raw CPython API functions `initialize_interpreter` and `finalize_interpreter` as these do not properly handle the lifetime of PyStim’s internal data.

## Restarting the interpter

When using the HDL simulator GUI (intractive mode) for mixed-language (HDL and C/Python) simulations, it’s essential to understand how the simulation state for HDL and C/Python code are managed during a simulation restart in the already running context.

In HDL simulators, restarting the simulation in the GUI primarily affects the HDL side of the simulation. It resets the state of the HDL simulation, including all signal values, registers, and memories to their initial state as defined at simulation zero time. However, the state of the C/Python code used in the simulation (for instance, through DPI, VPI, or PLI) is not automatically reset by this action.

While the HDL simulation is restarted in already running context, PyStim library does automatically restart the Python interpreter. However, this may not apply to third-party extension Python modules.The issue is that Python itself cannot completely unload extension modules and there are several caveats with regard to interpreter restarting. In short, not all memory may be freed, either due to Python reference cycles or user-created global data. All the details can be found in the CPython documentation.

Recommendation for Developers:

  - Plan Initialization and Reset: Ensure your Python code includes well-defined

initialization and reset functions that can be called from HDL.

  - Simulation Hooks: Use simulator-specific mechanisms (e.g., callbacks or $restart commands) to integrate the reset process.

  - Testing: Regularly test the behavior of your mixed-language simulation during restarts to verify proper synchronization between HDL and Python states.

By understanding this distinction and explicitly managing the Python code state during HDL simulation restarts, you can maintain consistency and avoid unintended simulation behavior.

## Sub-interpreter support

Creating multiple copies of interpreter is not possible because it represents the main Python interpreter. Sub-interpreters are something different and they do permit the existence of multiple interpreters. This is an advanced feature of the CPython API and should be handled with care. PyStim does not currently offer a interface for sub-interpreters, so refer to the CPython documentation for all the details regarding this feature.