Merge pull request #48 from fvutils/mballance/struct

Add support for passing structs

Author: mballance

README.md

@@ -6,6 +6,7 @@ hardware description languages, with a current focus on SystemVerilog.
 - Call SystemVerilog functions and tasks from Python, and invoke Python methods from SystemVerilog
 - Use the Python C API, and a SystemVerilog convenience API, to call Python
 - **Run async pytest tests from SystemVerilog testbenches**
+- **Pass structured data between Python and SystemVerilog using ctypes.Structure**
 
 ## Key Features
 
@@ -24,6 +25,26 @@ endmodule
 
 See [doc/pytest_runner.md](doc/pytest_runner.md) for complete documentation and examples.
 
+### Struct Type Support
+Pass complex structured data between Python and SystemVerilog using `ctypes.Structure`:
+
+```python
+import ctypes as ct
+import hdl_if as hif
+
+class Point(ct.Structure):
+    _fields_ = [("x", ct.c_int32), ("y", ct.c_int32)]
+
+@hif.api
+class GeometryAPI(object):
+    @hif.imp
+    async def draw_point(self, p: Point):
+        """Called from SystemVerilog"""
+        pass
+```
+
+PyHDL-IF automatically generates SystemVerilog struct typedefs and conversion functions. See [doc/struct.md](doc/struct.md) for complete documentation.
+
 ## Installing PyHDL-IF
 Installing PyHDL-IF in your own Python virtual environment is easy:
 

doc/source/index.rst

@@ -18,6 +18,7 @@ variety of abstraction levels.
    overview  
    sim_integ
    pytest_runner
+   structs
    uvm
    cmdref
    py_api

doc/source/overview.rst

@@ -27,6 +27,10 @@ Call-Interface API
 The *Call Interface* API enables users to create pairs of communicating 
 objects, where one object lives in Python, the other lives in HDL.
 
+The Call Interface supports passing structured data between Python and 
+SystemVerilog using ``ctypes.Structure`` types. This enables efficient 
+interchange of complex data structures. See :doc:`structs` for details.
+
 TLM API
 *******
 The TLM interface implements a FIFO-based interface between Python and

doc/source/quickstart.rst

@@ -52,3 +52,31 @@ Then, run tests from your SystemVerilog testbench:
 
 For complete details, see :doc:`pytest_runner`.
 
+Using Structured Data (Structs)
+================================
+
+PyHDL-IF supports passing structured data between Python and SystemVerilog using 
+``ctypes.Structure`` types:
+
+.. code-block:: python
+
+    import ctypes as ct
+    import hdl_if as hif
+
+    class Point(ct.Structure):
+        _fields_ = [
+            ("x", ct.c_int32),
+            ("y", ct.c_int32),
+        ]
+
+    @hif.api
+    class GeometryAPI(object):
+        @hif.imp
+        async def draw_point(self, p: Point):
+            """Called from SystemVerilog"""
+            pass
+
+PyHDL-IF automatically generates SystemVerilog struct typedefs and conversion 
+functions. For complete details and a working example, see :doc:`structs`.
+
+

doc/source/structs.rst

@@ -0,0 +1,234 @@
+######################
+Struct Type Support
+######################
+
+PyHDL-IF supports using Python ``ctypes.Structure`` types as function parameters 
+and return types in API methods. This enables efficient passing of structured data 
+between Python and SystemVerilog.
+
+Overview
+========
+
+When you define an API method that uses a struct type, PyHDL-IF automatically:
+
+1. Generates a SystemVerilog ``typedef struct`` definition
+2. Creates bidirectional conversion functions between Python and SystemVerilog
+3. Handles the struct in method calls transparently
+
+Defining Struct Types
+======================
+
+Struct types are defined as Python classes inheriting from ``ctypes.Structure``:
+
+.. code-block:: python
+
+    import ctypes as ct
+    import hdl_if as hif
+
+    class Point(ct.Structure):
+        _fields_ = [
+            ("x", ct.c_int32),
+            ("y", ct.c_int32),
+        ]
+
+    class Color(ct.Structure):
+        _fields_ = [
+            ("r", ct.c_uint8),
+            ("g", ct.c_uint8),
+            ("b", ct.c_uint8),
+            ("a", ct.c_uint8),
+        ]
+
+Using Structs in APIs
+=====================
+
+Once defined, structs can be used as parameters and return types in API methods:
+
+.. code-block:: python
+
+    @hif.api
+    class GraphicsAPI(object):
+        
+        @hif.imp
+        async def set_point(self, p: Point):
+            """Called from SV to set a point"""
+            pass
+        
+        @hif.imp
+        async def get_point(self) -> Point:
+            """Called from SV to get a point"""
+            pass
+        
+        @hif.imp
+        async def set_color(self, c: Color):
+            """Called from SV to set a color"""
+            pass
+
+Supported Field Types
+=====================
+
+PyHDL-IF supports all standard ctypes in struct fields:
+
+.. list-table:: Type Mapping
+    :header-rows: 1
+    :widths: 30 30 40
+
+    * - Python Type
+      - SystemVerilog Type
+      - Description
+    * - ``ctypes.c_int8``
+      - ``byte``
+      - Signed 8-bit integer
+    * - ``ctypes.c_uint8``
+      - ``byte unsigned``
+      - Unsigned 8-bit integer
+    * - ``ctypes.c_int16``
+      - ``shortint``
+      - Signed 16-bit integer
+    * - ``ctypes.c_uint16``
+      - ``shortint unsigned``
+      - Unsigned 16-bit integer
+    * - ``ctypes.c_int32``
+      - ``int``
+      - Signed 32-bit integer
+    * - ``ctypes.c_uint32``
+      - ``int unsigned``
+      - Unsigned 32-bit integer
+    * - ``ctypes.c_int64``
+      - ``longint``
+      - Signed 64-bit integer
+    * - ``ctypes.c_uint64``
+      - ``longint unsigned``
+      - Unsigned 64-bit integer
+    * - ``ctypes.c_float``
+      - ``shortreal``
+      - 32-bit floating point
+    * - ``ctypes.c_double``
+      - ``real``
+      - 64-bit floating point
+    * - ``ctypes.c_bool``
+      - ``bit``
+      - Boolean
+    * - ``str``
+      - ``string``
+      - String type
+
+Generated SystemVerilog Code
+=============================
+
+For the ``Point`` example above, PyHDL-IF generates:
+
+Typedef
+-------
+
+.. code-block:: systemverilog
+
+    typedef struct packed {
+        int x;
+        int y;
+    } Point_t;
+
+Conversion Functions
+--------------------
+
+**Python to SystemVerilog:**
+
+.. code-block:: systemverilog
+
+    function Point_t pyhdl_if_py_to_struct_Point(pyhdl_if::PyObject py_obj);
+        Point_t result;
+        pyhdl_if::PyObject __field_x, __field_y;
+        __field_x = pyhdl_if::PyObject_GetAttrString(py_obj, "x");
+        result.x = int'(pyhdl_if::PyLong_AsLong(__field_x));
+        pyhdl_if::Py_DecRef(__field_x);
+        __field_y = pyhdl_if::PyObject_GetAttrString(py_obj, "y");
+        result.y = int'(pyhdl_if::PyLong_AsLong(__field_y));
+        pyhdl_if::Py_DecRef(__field_y);
+        return result;
+    endfunction
+
+**SystemVerilog to Python:**
+
+.. code-block:: systemverilog
+
+    function pyhdl_if::PyObject pyhdl_if_struct_to_py_Point(Point_t sv_struct);
+        pyhdl_if::PyObject __module, __class, __args, result;
+        __module = pyhdl_if::PyImport_ImportModule("your_module");
+        __class = pyhdl_if::PyObject_GetAttrString(__module, "Point");
+        __args = pyhdl_if::PyTuple_New(2);
+        void'(pyhdl_if::PyTuple_SetItem(__args, 0, 
+              pyhdl_if::PyLong_FromLong(longint'(sv_struct.x))));
+        void'(pyhdl_if::PyTuple_SetItem(__args, 1, 
+              pyhdl_if::PyLong_FromLong(longint'(sv_struct.y))));
+        result = pyhdl_if::PyObject_Call(__class, __args, null);
+        pyhdl_if::Py_DecRef(__args);
+        pyhdl_if::Py_DecRef(__class);
+        pyhdl_if::Py_DecRef(__module);
+        return result;
+    endfunction
+
+Using Structs from SystemVerilog
+=================================
+
+In your SystemVerilog testbench, implement the interface methods using the 
+generated struct types:
+
+.. code-block:: systemverilog
+
+    class GraphicsAPI_Impl implements graphics_api_pkg::GraphicsAPI_imp_if;
+        graphics_api_pkg::Point_t m_point;
+
+        virtual task set_point(input graphics_api_pkg::Point_t p);
+            $display("Received point: x=%0d, y=%0d", p.x, p.y);
+            m_point = p;
+        endtask
+
+        virtual task get_point(output graphics_api_pkg::Point_t retval);
+            $display("Returning point: x=%0d, y=%0d", m_point.x, m_point.y);
+            retval = m_point;
+        endtask
+    endclass
+
+Packed vs Unpacked Structs
+===========================
+
+PyHDL-IF automatically determines whether to use ``packed`` or unpacked structs:
+
+- **Packed structs**: Used when all fields are synthesizable types (integers, bits)
+- **Unpacked structs**: Used when any field is a floating-point type (``real``, ``shortreal``)
+
+This is necessary because SystemVerilog does not allow real types in packed structs.
+
+Complete Example
+================
+
+A complete working example is available at ``examples/call/dpi/struct_passing/``. 
+The example demonstrates:
+
+- Defining multiple struct types (Point, Color, Rectangle)
+- Using structs as both parameters and return values
+- Bidirectional struct passing between Python and SystemVerilog
+- A simple graphics API implementation
+
+Run the example:
+
+.. code-block:: bash
+
+    cd examples/call/dpi/struct_passing
+    dfm run -Dsim=vlt sim-run
+
+Limitations
+===========
+
+1. **Nested Structs**: Structs containing other structs as fields are not currently tested
+2. **Arrays in Structs**: Array fields (using ctypes array types) are not currently supported
+3. **Module Name**: The SV-to-Python conversion function needs to import the Python module 
+   containing the struct definition. Ensure the module is in the Python path.
+
+See Also
+========
+
+- :doc:`quickstart` - Getting started guide
+- :doc:`py_api` - Python API reference
+- :doc:`sv_api` - SystemVerilog API reference
+- Full struct documentation: `doc/struct.md <https://github.com/fvutils/pyhdl-if/blob/main/doc/struct.md>`_

examples/Examples.md

@@ -65,4 +65,13 @@ You can see the detailed commands used to run the example by running:
 % dfm --log-level=INFO run -Dsim=<sim> sim-run
 ```
 
+## Available Examples
+
+### call/dpi/call_sv_bfm
+Demonstrates calling SystemVerilog tasks and functions from Python using a Wishbone initiator BFM.
+
+### call/dpi/struct_passing
+Demonstrates passing structured data (ctypes.Structure) between Python and SystemVerilog. Shows how to define and use custom struct types for complex data interchange.
+
+