Overview
########


PyStim provides a way to interact with Python data types in SystemVerilog. This is
done by using a set of thin wrappers around the Python types. Consider the following
use cases:


.. rubric:: 1. Wrapper in SystemVerilog, native type in Python

We have a type which is native to Python, like a ``tuple`` or a ``list``. One way to get this data into SystemVerilog is
with the :class:`pystim_pkg::py_object` family of wrappers. These are explained in more
detail in the :doc:`/advanced/pysv/object` section. We'll just give a quick
example here:

.. code-block:: systemverilog

    function void print_list(pystim_pkg::py_list my_list) ;
        for(int i = 0; i < my_list.size(); i++) begin
            $display("%0d", my_list.get(i).cast_int().get_value());
        end
    endfunction


The Python ``list`` is not converted in any way -- it's just thin wrapped in a SystemVerilog
:class:`pystim_pkg::py_list` class. At its core it's still a Python object. Cloning the `py_list` 
will do the usual reference-counting like in Python. The SystemVerilog
list wrapper should be explicitly released when it's no longer needed.


.. rubric:: 2. Converting between native SystemVerilog and Python types

In the previous  cases we had a native type in Python and a wrapper in
the SystemVerilog. Now, we have native types on both sides and we have SystemVerilog wrapper
for each native Python type. This is the most common case and the one that PyStim
is designed to handle. For example, consider the following function:

.. code-block:: cpp

    function void print_vector(pystim_pkg::int_ [$] v) ;
        foreach (v[i])
            $display("%0d", v[i].get_value());
    endfunction


The SystemVerilog type `py_int` is a thin wrapper around a Python integer.
Lots of these native types mapping are supported out of the box, as shown in the table
below. 

.. _conversion_table:

List of all builtin native type mappings
----------------------------------------

The following basic data types are supported out of the box.


+----------------------------------------+----------------+-----------------+
| SystemVerilog data type                | PyStim wrapper | Python datatype |
+========================================+================+=================+
| ``byte\shortint\int\longint unsigned`` | ``py_uint``    | ``int``         |
+----------------------------------------+----------------+-----------------+
| ``byte\shortint\int\longint``          | ``py_int``     | ``int``         |
+----------------------------------------+----------------+-----------------+
| ``real``, ``shortreal``                | ``py_float``   | ``float``       |
+----------------------------------------+----------------+-----------------+
| ``bit``                                | ``py_bool``    | ``bool``        |
+----------------------------------------+----------------+-----------------+
| ``string``                             | ``py_str``     | ``str``         |
+----------------------------------------+----------------+-----------------+
| queue/array                            | ``py_list``    | ``list``        |
+----------------------------------------+----------------+-----------------+
| queue/array                            | ``py_tuple``   | ``tuple``       |
+----------------------------------------+----------------+-----------------+
| associative array                      | ``py_dict``    | ``dict``        |
+----------------------------------------+----------------+-----------------+
| -                                      | ``py_object``  | python object   |
+----------------------------------------+----------------+-----------------+