cocotbext-interface 0.1.3__tar.gz → 0.1.4__tar.gz

{cocotbext_interface-0.1.3 → cocotbext_interface-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocotbext-interface
-Version: 0.1.3
+Version: 0.1.4
 Summary: System Verilog style interface class for connecting Cocotb to DUT
 Author-email: Rasmus Grøndahl Olsen <simplhdl@gmail.com>
 Maintainer-email: Rasmus Grøndahl Olsen <simplhdl@gmail.com>
@@ -83,11 +83,21 @@ By mimicking the SystemVerilog `interface` structure, verification engineers can
 
 ---
 
-## 2. Part I: Designing the Interface
+## 2. Installation
+
+Install the package from PyPI using pip:
+
+```bash
+pip install cocotbext-interface
+```
+
+---
+
+## 3. Part I: Designing the Interface
 
 This section covers how to define the structure, timing, and access rules for a interface protocol.
 
-### 2.1 The Interface Class
+### 3.1 The Interface Class
 
 To define a bus, inherit from the Interface class. Signals are now defined as class attributes using type hints, which
 determines whether they are required or optional during RTL binding.
@@ -112,7 +122,7 @@ class MyBus(Interface):
 
 These attribute names are used directly by the framework to search for matching signal names within the RTL hierarchy.
 
-### 2.2 Defining Clocking Blocks
+### 3.2 Defining Clocking Blocks
 
 Use the `@clocking` decorator on an inner class. This defines the temporal behavior for synchronous signals.
 
@@ -121,7 +131,7 @@ Use the `@clocking` decorator on an inner class. This defines the temporal behav
 - `input`: Input skew (Sample delay). Can be a `Timer` or another `Trigger`.
 - `output`: Output skew (Drive delay).
 
-### 2.3 Defining Modports
+### 3.3 Defining Modports
 
 Use the `@modport` decorator to group signals and clocking blocks for specific roles like `source`, `sink` or `monitor`.
 
@@ -130,12 +140,13 @@ Use the `@modport` decorator to group signals and clocking blocks for specific r
 - `Input`/`Output`/`InOut`: Signals accessible in this modport.
 - `Import`: Method names (APIs) exposed to this modport.
 
-### 2.4 Complete Definition Example
+### 3.4 Complete Definition Example
 
 ```python
+from typing import Callable
 from cocotb.handles import LogicArrayObject, LogicObject
 from cocotb.triggers import RisingEdge, FallingEdge, Timer
-from interface_framework import Interface, modport, clocking, Import, Input, Output
+from cocotbext.interface import Interface, modport, clocking, Import, Input, Output
 
 class AxiStream(Interface):
     clk:    LogicObject
@@ -175,11 +186,11 @@ class AxiStream(Interface):
 
 ---
 
-## 3. Part II: Using the Interface
+## 4. Part II: Using the Interface
 
 This section covers how to connect the interface to the DUT and use it in a test.
 
-### 3.1 Instantiation & Connection
+### 4.1 Instantiation & Connection
 
 Interfaces are connected to the RTL using named constructors. These methods automatically map your class attributes to
 the corresponding signals in the HDL hierarchy.
@@ -192,8 +203,7 @@ Use `from_entity` when the signal names in the RTL match your class attribute na
 level. This is a strict connection method that does not support overrides or pattern substitutions.
 
 ```python
-# Connects to dut.tdata and
-dut.rdy directly
+# Connects to dut.data and dut.rdy directly
 bus = MyBus.from_entity(dut)
 ```
 
@@ -244,7 +254,8 @@ bus = MyBus.from_pattern(dut, pattern="/u_axi_[0-9]_%/")
 While `from_entity` is strict, `from_pattern` allows for flexibility when the RTL structure is non-standard:
 
 - **Keyword Overrides:** Pass a signal handle as a keyword argument to skip the pattern search for that specific
-  attribute.Indexing: Use the `idx` argument to index into all signals discovered via the pattern (e.g.,
+  attribute.
+- **Indexing:** Use the `idx` argument to index into all signals discovered via the pattern (e.g.,
   `dut.u_axi_tdata[1]`).
 
 ```python
@@ -255,29 +266,38 @@ bus = MyBus.from_pattern(dut, pattern="u_axi_%", idx=1, rdy=dut.global_rdy)
 > [!TIP] To confirm your signals are correctly bound, you can print `print(bus)` or `print(f"{bus=}")` the bus object to
 > inspect the resolved RTL paths.
 
-### 3.2 Synchronous Driving (Non-Blocking)
+### 4.2 Synchronous Driving (Non-Blocking)
 
 When using a modport's clocking block, driving a signal schedules an update for the next clock edge + output skew. It
 does not block the current coroutine.
 
 ```python
 # Drive data through the source modport
-bus.source.src_cb.tdata.value = 0xABCD
-bus.source.src_cb.tvalid.value = 1
+bus.source.cb.tdata.value = 0xABCD
+bus.source.cb.tvalid.value = 1
 ```
 
-### 3.3 Synchronous Sampling (Blocking)
+### 4.3 Synchronous Sampling (Blocking)
 
 To read a signal synchronously, you **must** use `await ...capture()`. This ensures the simulation waits for the clock
 edge and the defined input skew before returning the value.
 
+The `capture()` method accepts two optional arguments:
+
+- **`resolver`**: A resolution function (e.g., `cocotb.types.Logic.resolve`) to resolve 4-state logic values ('X', 'Z')
+  to a simpler 2-state representation.
+- **`default`**: The value returned if the signal is an **optional signal** that is unconnected.
+
 ```python
 # Wait until sink is ready
-while await bus.source.src_cb.tready.capture() == 0:
-    await bus.source.src_cb.wait() # Wait for 1 clock cycle
+while await bus.source.cb.tready.capture() == 0:
+    await bus.source.cb.wait() # Wait for 1 clock cycle
+
+# Capture with resolution and a default value for optional signals
+data = await bus.sink.cb.tdata.capture(resolver=Logic.resolve, default=0)
 ```
 
-### 3.4 Using Interface APIs
+### 4.4 Using Interface APIs
 
 Methods defined in the interface and imported in the modport can be called directly.
 
@@ -288,7 +308,7 @@ await bus.source.reset()
 
 ---
 
-## 4. Technical Summary
+## 5. Technical Summary
 
 | SystemVerilog Concept | Framework Implementation            | Behavior                               |
 | :-------------------- | :---------------------------------- | :------------------------------------- |
@@ -303,7 +323,7 @@ await bus.source.reset()
 
 ---
 
-## 5. Best Practices
+## 6. Best Practices
 
 1. Define separate clocking blocks for Source and Sink roles to account for different signal access and physical skews.
 2. Don't give access to synchronous signals in the `modport`, this forces the user to use the clocking block.

{cocotbext_interface-0.1.3 → cocotbext_interface-0.1.4}/README.md

@@ -29,11 +29,21 @@ By mimicking the SystemVerilog `interface` structure, verification engineers can
 
 ---
 
-## 2. Part I: Designing the Interface
+## 2. Installation
+
+Install the package from PyPI using pip:
+
+```bash
+pip install cocotbext-interface
+```
+
+---
+
+## 3. Part I: Designing the Interface
 
 This section covers how to define the structure, timing, and access rules for a interface protocol.
 
-### 2.1 The Interface Class
+### 3.1 The Interface Class
 
 To define a bus, inherit from the Interface class. Signals are now defined as class attributes using type hints, which
 determines whether they are required or optional during RTL binding.
@@ -58,7 +68,7 @@ class MyBus(Interface):
 
 These attribute names are used directly by the framework to search for matching signal names within the RTL hierarchy.
 
-### 2.2 Defining Clocking Blocks
+### 3.2 Defining Clocking Blocks
 
 Use the `@clocking` decorator on an inner class. This defines the temporal behavior for synchronous signals.
 
@@ -67,7 +77,7 @@ Use the `@clocking` decorator on an inner class. This defines the temporal behav
 - `input`: Input skew (Sample delay). Can be a `Timer` or another `Trigger`.
 - `output`: Output skew (Drive delay).
 
-### 2.3 Defining Modports
+### 3.3 Defining Modports
 
 Use the `@modport` decorator to group signals and clocking blocks for specific roles like `source`, `sink` or `monitor`.
 
@@ -76,12 +86,13 @@ Use the `@modport` decorator to group signals and clocking blocks for specific r
 - `Input`/`Output`/`InOut`: Signals accessible in this modport.
 - `Import`: Method names (APIs) exposed to this modport.
 
-### 2.4 Complete Definition Example
+### 3.4 Complete Definition Example
 
 ```python
+from typing import Callable
 from cocotb.handles import LogicArrayObject, LogicObject
 from cocotb.triggers import RisingEdge, FallingEdge, Timer
-from interface_framework import Interface, modport, clocking, Import, Input, Output
+from cocotbext.interface import Interface, modport, clocking, Import, Input, Output
 
 class AxiStream(Interface):
     clk:    LogicObject
@@ -121,11 +132,11 @@ class AxiStream(Interface):
 
 ---
 
-## 3. Part II: Using the Interface
+## 4. Part II: Using the Interface
 
 This section covers how to connect the interface to the DUT and use it in a test.
 
-### 3.1 Instantiation & Connection
+### 4.1 Instantiation & Connection
 
 Interfaces are connected to the RTL using named constructors. These methods automatically map your class attributes to
 the corresponding signals in the HDL hierarchy.
@@ -138,8 +149,7 @@ Use `from_entity` when the signal names in the RTL match your class attribute na
 level. This is a strict connection method that does not support overrides or pattern substitutions.
 
 ```python
-# Connects to dut.tdata and
-dut.rdy directly
+# Connects to dut.data and dut.rdy directly
 bus = MyBus.from_entity(dut)
 ```
 
@@ -190,7 +200,8 @@ bus = MyBus.from_pattern(dut, pattern="/u_axi_[0-9]_%/")
 While `from_entity` is strict, `from_pattern` allows for flexibility when the RTL structure is non-standard:
 
 - **Keyword Overrides:** Pass a signal handle as a keyword argument to skip the pattern search for that specific
-  attribute.Indexing: Use the `idx` argument to index into all signals discovered via the pattern (e.g.,
+  attribute.
+- **Indexing:** Use the `idx` argument to index into all signals discovered via the pattern (e.g.,
   `dut.u_axi_tdata[1]`).
 
 ```python
@@ -201,29 +212,38 @@ bus = MyBus.from_pattern(dut, pattern="u_axi_%", idx=1, rdy=dut.global_rdy)
 > [!TIP] To confirm your signals are correctly bound, you can print `print(bus)` or `print(f"{bus=}")` the bus object to
 > inspect the resolved RTL paths.
 
-### 3.2 Synchronous Driving (Non-Blocking)
+### 4.2 Synchronous Driving (Non-Blocking)
 
 When using a modport's clocking block, driving a signal schedules an update for the next clock edge + output skew. It
 does not block the current coroutine.
 
 ```python
 # Drive data through the source modport
-bus.source.src_cb.tdata.value = 0xABCD
-bus.source.src_cb.tvalid.value = 1
+bus.source.cb.tdata.value = 0xABCD
+bus.source.cb.tvalid.value = 1
 ```
 
-### 3.3 Synchronous Sampling (Blocking)
+### 4.3 Synchronous Sampling (Blocking)
 
 To read a signal synchronously, you **must** use `await ...capture()`. This ensures the simulation waits for the clock
 edge and the defined input skew before returning the value.
 
+The `capture()` method accepts two optional arguments:
+
+- **`resolver`**: A resolution function (e.g., `cocotb.types.Logic.resolve`) to resolve 4-state logic values ('X', 'Z')
+  to a simpler 2-state representation.
+- **`default`**: The value returned if the signal is an **optional signal** that is unconnected.
+
 ```python
 # Wait until sink is ready
-while await bus.source.src_cb.tready.capture() == 0:
-    await bus.source.src_cb.wait() # Wait for 1 clock cycle
+while await bus.source.cb.tready.capture() == 0:
+    await bus.source.cb.wait() # Wait for 1 clock cycle
+
+# Capture with resolution and a default value for optional signals
+data = await bus.sink.cb.tdata.capture(resolver=Logic.resolve, default=0)
 ```
 
-### 3.4 Using Interface APIs
+### 4.4 Using Interface APIs
 
 Methods defined in the interface and imported in the modport can be called directly.
 
@@ -234,7 +254,7 @@ await bus.source.reset()
 
 ---
 
-## 4. Technical Summary
+## 5. Technical Summary
 
 | SystemVerilog Concept | Framework Implementation            | Behavior                               |
 | :-------------------- | :---------------------------------- | :------------------------------------- |
@@ -249,7 +269,7 @@ await bus.source.reset()
 
 ---
 
-## 5. Best Practices
+## 6. Best Practices
 
 1. Define separate clocking blocks for Source and Sink roles to account for different signal access and physical skews.
 2. Don't give access to synchronous signals in the `modport`, this forces the user to use the clocking block.

cocotbext_interface-0.1.4/cocotbext/interface/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.4"

{cocotbext_interface-0.1.3 → cocotbext_interface-0.1.4}/cocotbext/interface/interface.py

@@ -112,6 +112,7 @@ class ClockedSignal:
                 else:
                     logger.warning(f"{self._handle} is not resolvable")
             return value
+        return default
 
     def __getattr__(self, name):
         """Forward other cocotb handle methods (like ._name, etc)"""
@@ -204,12 +205,21 @@ class ModportView:
             origin = getattr(_type, "__origin__", None)
 
             if origin is Import:
-                # 1. Map Method from parent Interface
-                if hasattr(parent, name):
-                    setattr(self, name, getattr(parent, name))
+                # Resolve class methods before instance attributes, which may
+                # contain an HDL signal with the same name as the imported method.
+                imported = inspect.getattr_static(type(parent), name, None)
+                if imported is not None:
+                    descriptor_get = getattr(imported, "__get__", None)
+                    if descriptor_get is not None:
+                        imported = descriptor_get(parent, type(parent))
+                else:
+                    imported = getattr(parent, name, None)
+
+                if callable(imported):
+                    setattr(self, name, imported)
                 else:
                     raise AttributeError(
-                        f"Modport '{mp_cls.__name__}' expected imported method '{name}', "
+                        f"Modport '{mp_cls.__name__}' expected imported callable '{name}', "
                         f"but it was not found in {parent.__class__.__name__}"
                     )
 

{cocotbext_interface-0.1.3 → cocotbext_interface-0.1.4}/cocotbext_interface.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocotbext-interface
-Version: 0.1.3
+Version: 0.1.4
 Summary: System Verilog style interface class for connecting Cocotb to DUT
 Author-email: Rasmus Grøndahl Olsen <simplhdl@gmail.com>
 Maintainer-email: Rasmus Grøndahl Olsen <simplhdl@gmail.com>
@@ -83,11 +83,21 @@ By mimicking the SystemVerilog `interface` structure, verification engineers can
 
 ---
 
-## 2. Part I: Designing the Interface
+## 2. Installation
+
+Install the package from PyPI using pip:
+
+```bash
+pip install cocotbext-interface
+```
+
+---
+
+## 3. Part I: Designing the Interface
 
 This section covers how to define the structure, timing, and access rules for a interface protocol.
 
-### 2.1 The Interface Class
+### 3.1 The Interface Class
 
 To define a bus, inherit from the Interface class. Signals are now defined as class attributes using type hints, which
 determines whether they are required or optional during RTL binding.
@@ -112,7 +122,7 @@ class MyBus(Interface):
 
 These attribute names are used directly by the framework to search for matching signal names within the RTL hierarchy.
 
-### 2.2 Defining Clocking Blocks
+### 3.2 Defining Clocking Blocks
 
 Use the `@clocking` decorator on an inner class. This defines the temporal behavior for synchronous signals.
 
@@ -121,7 +131,7 @@ Use the `@clocking` decorator on an inner class. This defines the temporal behav
 - `input`: Input skew (Sample delay). Can be a `Timer` or another `Trigger`.
 - `output`: Output skew (Drive delay).
 
-### 2.3 Defining Modports
+### 3.3 Defining Modports
 
 Use the `@modport` decorator to group signals and clocking blocks for specific roles like `source`, `sink` or `monitor`.
 
@@ -130,12 +140,13 @@ Use the `@modport` decorator to group signals and clocking blocks for specific r
 - `Input`/`Output`/`InOut`: Signals accessible in this modport.
 - `Import`: Method names (APIs) exposed to this modport.
 
-### 2.4 Complete Definition Example
+### 3.4 Complete Definition Example
 
 ```python
+from typing import Callable
 from cocotb.handles import LogicArrayObject, LogicObject
 from cocotb.triggers import RisingEdge, FallingEdge, Timer
-from interface_framework import Interface, modport, clocking, Import, Input, Output
+from cocotbext.interface import Interface, modport, clocking, Import, Input, Output
 
 class AxiStream(Interface):
     clk:    LogicObject
@@ -175,11 +186,11 @@ class AxiStream(Interface):
 
 ---
 
-## 3. Part II: Using the Interface
+## 4. Part II: Using the Interface
 
 This section covers how to connect the interface to the DUT and use it in a test.
 
-### 3.1 Instantiation & Connection
+### 4.1 Instantiation & Connection
 
 Interfaces are connected to the RTL using named constructors. These methods automatically map your class attributes to
 the corresponding signals in the HDL hierarchy.
@@ -192,8 +203,7 @@ Use `from_entity` when the signal names in the RTL match your class attribute na
 level. This is a strict connection method that does not support overrides or pattern substitutions.
 
 ```python
-# Connects to dut.tdata and
-dut.rdy directly
+# Connects to dut.data and dut.rdy directly
 bus = MyBus.from_entity(dut)
 ```
 
@@ -244,7 +254,8 @@ bus = MyBus.from_pattern(dut, pattern="/u_axi_[0-9]_%/")
 While `from_entity` is strict, `from_pattern` allows for flexibility when the RTL structure is non-standard:
 
 - **Keyword Overrides:** Pass a signal handle as a keyword argument to skip the pattern search for that specific
-  attribute.Indexing: Use the `idx` argument to index into all signals discovered via the pattern (e.g.,
+  attribute.
+- **Indexing:** Use the `idx` argument to index into all signals discovered via the pattern (e.g.,
   `dut.u_axi_tdata[1]`).
 
 ```python
@@ -255,29 +266,38 @@ bus = MyBus.from_pattern(dut, pattern="u_axi_%", idx=1, rdy=dut.global_rdy)
 > [!TIP] To confirm your signals are correctly bound, you can print `print(bus)` or `print(f"{bus=}")` the bus object to
 > inspect the resolved RTL paths.
 
-### 3.2 Synchronous Driving (Non-Blocking)
+### 4.2 Synchronous Driving (Non-Blocking)
 
 When using a modport's clocking block, driving a signal schedules an update for the next clock edge + output skew. It
 does not block the current coroutine.
 
 ```python
 # Drive data through the source modport
-bus.source.src_cb.tdata.value = 0xABCD
-bus.source.src_cb.tvalid.value = 1
+bus.source.cb.tdata.value = 0xABCD
+bus.source.cb.tvalid.value = 1
 ```
 
-### 3.3 Synchronous Sampling (Blocking)
+### 4.3 Synchronous Sampling (Blocking)
 
 To read a signal synchronously, you **must** use `await ...capture()`. This ensures the simulation waits for the clock
 edge and the defined input skew before returning the value.
 
+The `capture()` method accepts two optional arguments:
+
+- **`resolver`**: A resolution function (e.g., `cocotb.types.Logic.resolve`) to resolve 4-state logic values ('X', 'Z')
+  to a simpler 2-state representation.
+- **`default`**: The value returned if the signal is an **optional signal** that is unconnected.
+
 ```python
 # Wait until sink is ready
-while await bus.source.src_cb.tready.capture() == 0:
-    await bus.source.src_cb.wait() # Wait for 1 clock cycle
+while await bus.source.cb.tready.capture() == 0:
+    await bus.source.cb.wait() # Wait for 1 clock cycle
+
+# Capture with resolution and a default value for optional signals
+data = await bus.sink.cb.tdata.capture(resolver=Logic.resolve, default=0)
 ```
 
-### 3.4 Using Interface APIs
+### 4.4 Using Interface APIs
 
 Methods defined in the interface and imported in the modport can be called directly.
 
@@ -288,7 +308,7 @@ await bus.source.reset()
 
 ---
 
-## 4. Technical Summary
+## 5. Technical Summary
 
 | SystemVerilog Concept | Framework Implementation            | Behavior                               |
 | :-------------------- | :---------------------------------- | :------------------------------------- |
@@ -303,7 +323,7 @@ await bus.source.reset()
 
 ---
 
-## 5. Best Practices
+## 6. Best Practices
 
 1. Define separate clocking blocks for Source and Sink roles to account for different signal access and physical skews.
 2. Don't give access to synchronous signals in the `modport`, this forces the user to use the clocking block.

{cocotbext_interface-0.1.3 → cocotbext_interface-0.1.4}/tests/test_interface.py

@@ -32,7 +32,7 @@ from cocotb.triggers import RisingEdge, FallingEdge
 
 @pytest.fixture(autouse=True)
 def mock_cocotb_scheduler(monkeypatch):
-    """Auto-patch cocotb.start_soon to avoid scheduler errors in tests.
+    """Auto-patch cocotb.start_soon and ReadOnlyManager to avoid scheduler errors in tests.
 
     Properly closes coroutines to avoid RuntimeWarning about unawaited coroutines.
     """
@@ -42,7 +42,11 @@ def mock_cocotb_scheduler(monkeypatch):
         if inspect.iscoroutine(coro):
             coro.close()
 
+    async def mock_wait():
+        pass
+
     monkeypatch.setattr("cocotb.start_soon", mock_start_soon)
+    monkeypatch.setattr("cocotbext.interface.interface.ReadOnlyManager.wait", mock_wait)
 
 
 # ============================================================================
@@ -121,6 +125,7 @@ def mock_hierarchy():
     hierarchy.add_signal("clk")
     hierarchy.add_signal("rst")
     hierarchy.add_signal("data")  # Generic data signal
+    hierarchy.add_signal("write")
     hierarchy.add_signal("data_in")
     hierarchy.add_signal("data_out")
     hierarchy.add_signal("valid")
@@ -162,6 +167,24 @@ class InterfaceWithModport(Interface):
         pass
 
 
+class InterfaceWithCollidingImport(Interface):
+    """Test a modport callable sharing its name with an HDL signal."""
+
+    clk: Output[object]
+    write: Input[object]
+
+    @clocking(clock="clk")
+    class cb:
+        write: Input[object]
+
+    @modport(clocking="cb")
+    class master:
+        write: Import[Callable]
+
+    def write(self) -> str:
+        return "method"
+
+
 class InterfaceWithClocking(Interface):
     """Test interface with clocking block."""
 
@@ -385,6 +408,13 @@ class TestModports:
         assert hasattr(iface, "send")
         assert hasattr(master, "send")
 
+    def test_modport_import_callable_wins_signal_name_collision(self, mock_hierarchy):
+        iface = InterfaceWithCollidingImport.from_entity(mock_hierarchy)
+
+        assert callable(iface.master.write)
+        assert iface.master.write() == "method"
+        assert iface.cb.write._handle is mock_hierarchy._children["write"]
+
     def test_modport_dont_contains_callable(self, mock_hierarchy):
         """Test that modport contains the mapped callable."""
         iface = InterfaceWithModport.from_entity(mock_hierarchy)
@@ -577,6 +607,24 @@ class TestClockedSignal:
 
         asyncio.run(inner())
 
+    def test_clocked_signal_capture_default(self, mock_hierarchy):
+        """Test capturing with a default value for unconnected signals."""
+
+        async def inner():
+            clk = mock_hierarchy._children["clk"]
+            # Signal with no handle
+            cs = ClockedSignal(None, clk, RisingEdge, is_input=True)
+
+            # Capture should return the default value
+            val = await cs.capture(default=123)
+            assert val == 123
+
+            # Capture without default should return None
+            val_none = await cs.capture()
+            assert val_none is None
+
+        asyncio.run(inner())
+
 
 # ============================================================================
 # Tests: Modport + Clocking Integration

cocotbext_interface-0.1.3/cocotbext/interface/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.3"