Metadata-Version: 2.4
Name: cocotbext-interface
Version: 0.1.0
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>
License: BSD 3-Clause License
        
        Copyright (c) 2026, Rasmus Olsen
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cocotb>=2
Dynamic: license-file

# Interface Documentation

This interface package provides a Pythonic implementation of SystemVerilog-style
**Interface**, **Modport**, and **Clocking Block** for cocotb. It is designed
to bridge the gap between hardware-centric verification concepts and the
flexibility of Python, ensuring race-free simulations and clean, reusable
verification IP.

---

## 1. Project Overview

In standard cocotb, signal assignments are immediate and reads are subject to
simulator delta-cycle races. This package introduces a timing-accurate
**Clocking Block** mechanism.

By mimicking the SystemVerilog `interface` structure, verification engineers
can:

* **Group Signals:** Define structural signal groups once in a central class.
* **Restrict Access:** Use **Modports** to define directional access for
  different VIP components (e.g., Sources, Sinks and Monitors).
* **Enforce Synchronicity:** Use **Clocking Blocks** to ensure signals are
  driven and sampled at the correct time relative to clock edges, supporting
  both time-based and event-based skews.
* **Define Functional APIs:** Using Python methods (`def` and `async def`)
  within the interface to build API tasks for implementing interface protocols
  such as AXI, Avalon, I2C, SPI, etc.

---

## 2. 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

Inherit from `Interface` and define a the signals. Mandatory signal are defined
in the `signals` list and optional signals are defined in the `optional` list.
These are the signal names that can be searched for in the RTL.

### 2.2 Defining Clocking Blocks

Use the `@clocking` decorator on an inner class. This defines the temporal
behavior for synchronous signals.

* `clock`: The name of the clock signal in the `signals` list.
* `edge`: The trigger (e.g., `RisingEdge`, `FallingEdge`, `Edge`).
* `input`: Input skew (Sample delay). Can be a `Timer` or another `Trigger`.
* `output`: Output skew (Drive delay).

### 2.3 Defining Modports

Use the `@modport` decorator to group signals and clocking blocks for specific
roles like `source`, `sink` or `monitor`.

* `name`: Name of the modport
* `clocking`: Name of the clocking block to link.
* `inputs`/`outputs`: Lists of signals accessible in this modport.
* `callables`: List of method names (APIs) exposed to this modport.

### 2.4 Complete Definition Example

```python
from cocotb.triggers import RisingEdge, FallingEdge, Timer
from interface_framework import Interface, modport, clocking

class AxiStream(Interface):
    signals = ["clk", "rst_n", "tdata", "tvalid", "tready"]

    async def reset(self):
        self.rst_n.value = 0
        await Timer(10, 'ns')
        self.rst_n.value = 1

    # Define Source-side timing
    @clocking(clock="clk", edge=RisingEdge, input=Timer(1, 'ns'), output=Timer(2, 'ns'))
    class source_cb:
        inputs = ["tready"]
        outputs = ["tdata", "tvalid"]

    # Define Sink-side timing
    @clocking(clock="clk", edge=RisingEdge, input=Timer(1, 'ns'))
    class sink_cb:
        inputs = ["tdata", "tvalid"]
        outputs = ["tready"]

    @modport(clocking="source_cb")
    class source:
        outputs = ["rst_n"]
        callables = ["reset"]

    @modport(clocking="sink_cb")
    class sink:
        callables = ["reset"]
```

---

## 3. 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

The `pattern` argument is optional, but if used must contain the `%` wildcard.
The `%` is substituted with each name in the `signals` and `optional` lists.
You can also use globbing or regex (if wrapped in `/.../`).

```python
@cocotb.test()
async def test_tx(dut):
    # Pattern matching + Explicit Override
    # Replaces % with signal names: e.g. 'u_axi_tdata'
    bus = AxiStream(dut, pattern="u_axi_%", clk=dut.sys_clock)
```

> [!TIP]
> To confirm your signal are correctly connected and the interface, you can
> the `bus` object to inspect it.
>
> ```python
> print(bus)
> print(f"{bus=}")
> ```

### 3.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
```

### 3.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.

```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
```

### 3.4 Using Interface APIs

Methods defined in the interface and exposed in the modport `callables` can be
called directly.

```python
# Call the reset task defined by the VIP developer
await bus.source.reset()
```

---

## 4. Technical Summary

| SystemVerilog Concept | Framework Implementation | Behavior |
| :--- | :--- | :--- |
| `interface` | `class MyBus(Interface):` | Structural container. |
| `.*` | `pattern="%"` | Substitution-based wildcard discovery. |
| `.clk(sys_clk)` | `clk=dut.sys_clk` | Explicit named mapping override. |
| `modport` | `@modport` | Role-based grouping (Source/Sink). |
| `clocking` | `@clocking` | Temporal skews and edge triggers. |
| `cb.sig <= val` | `cb_name.sig.value = val` | Non-blocking drive (Setter). |
| `val = cb.sig` | `val = await cb_name.sig.capture()` | Synchronous sample (Coroutine). |
| `##N` | `await cb_name.wait(N)` | Cycle-based delay. |

---

## 5. 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.
3. Leverage the `%` wildcard in patterns to avoid manually connecting dozens of
   signals.
