avl-spi 0.1.0__tar.gz

avl_spi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [avl@projectapheleia.net]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

avl_spi-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: avl-spi
+Version: 0.1.0
+Summary: Apheleia Verification Library - Serial Peripheral Interface verification component.
+License: MIT License
+         
+         Copyright (c) [2025] [avl@projectapheleia.net]
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+License-File: LICENSE
+Author: avl
+Author-email: avl@projectapheleia.net
+Maintainer: avl
+Maintainer-email: avl@projectapheleia.net
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Provides-Extra: dev
+Requires-Dist: avl-core (>=1.1.0)
+Requires-Dist: black (>=22.3.0) ; extra == "dev"
+Requires-Dist: cocotb (>=2.1.0)
+Requires-Dist: matplotlib (>=3.10.0)
+Requires-Dist: mypy (>=0.910) ; extra == "dev"
+Requires-Dist: pytest (>=7.0) ; extra == "dev"
+Requires-Dist: ruff (>=0.11.0) ; extra == "dev"
+Requires-Dist: sphinx (>=8.1.3) ; extra == "dev"
+Requires-Dist: sphinx_rtd_theme (>=3.0.2) ; extra == "dev"
+Description-Content-Type: text/markdown
+
+# AVL-SPI - Apheleia Verification Library SPI Verification Component
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
+
+
+AVL-SPI has been developed by experienced, industry professional verification engineers to provide a simple, \
+extensible verification component for the [Serial Peripheral Interface](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface) \
+developed in [Python](https://www.python.org/) and the [AVL](https://avl-core.readthedocs.io/en/latest/index.html) library.
+
+AVL is built on the [CocoTB](https://docs.cocotb.org/en/stable/) framework, but aims to combine the best elements of \
+[UVM](https://accellera.org/community/uvm) in a more engineer friendly and efficient way.
+
+## CocoTB 2.0
+
+AVL-SPI supports [CocoTB 2.0](https://docs.cocotb.org/en/development/upgrade-2.0.html) and requires CocoTB 2.1 or later.
+
+## Protocol Features
+
+| Signal Name | Description | Driven By |
+|-------------|-------------|-----------|
+| SCLK        | Serial clock. Idles at CPOL. | Master |
+| CS          | Chip select; one per slave. Polarity configurable per slave. | Master |
+| MOSI        | Master out, slave in serial data. | Master |
+| MISO        | Master in, slave out serial data. | Slave |
+
+> **Note:** At present only single bit, uni-directional SPI is supported. Each SCLK cycle transfers one bit on MOSI (master to slave) and one bit on MISO (slave to master). Bi-directional (3-wire), dual, quad and QPI modes are not supported.
+
+## Component Features
+
+- Simple RTL interface to interact with HDL and define parameter and configuration options
+- Multiple chip selects with individual polarity
+- Clock polarity and individual drive and sample edges for master and slave (all 4 SPI modes and beyond)
+- Variable transfer length, MSB or LSB first
+- Chip select onehot0, setup, hold and inter-frame gap checks in the RTL interface
+- Master sequence, sequencer and driver with rate limiter, SCLK frequency and chip select timing control
+- Slave sequence, sequencer and driver with vanilla, random and memory response patterns
+- Monitor
+- Bandwidth monitor generating bus activity plots over user defined windows during simulation
+- Functional coverage
+- Searchable trace file generation
+
+---
+
+## 📦 Installation
+
+### Using `pip`
+```sh
+# Standard build
+pip install avl-spi
+
+# Development build
+pip install avl-spi[dev]
+```
+
+### Install from Source
+```sh
+git clone https://github.com/projectapheleia/avl-spi.git
+cd avl-spi
+
+# Standard build
+pip install .
+
+# Development build
+pip install .[dev]
+```
+
+Alternatively if you want to create a [virtual environment](https://docs.python.org/3/library/venv.html) rather than install globally a script is provided. This will install, with edit privileges to local virtual environment.
+
+This script assumes you have [Graphviz](https://graphviz.org/download/) and appropriate simulator installed, so all examples and documentation will build out of the box.
+
+
+```sh
+git clone https://github.com/projectapheleia/avl-spi.git
+cd avl-spi
+source avl-spi.sh
+```
+
+## 📖 Documentation
+
+In order to build the documentation you must have installed the development build.
+
+### Build from Source
+```sh
+cd doc
+make html
+<browser> build/html/index.html
+```
+## 🏃 Examples
+
+In order to run all the examples you must have installed the development build.
+
+To run all examples:
+
+```sh
+cd examples
+
+# To run
+make -j 8 sim
+
+# To clean
+make -j 8 clean
+```
+
+To run an individual example:
+
+```sh
+cd examples/THE EXAMPLE YOU WANT
+
+# To run
+make sim
+
+# To clean
+make clean
+```
+
+The examples use the [CocoTB Makefile](https://docs.cocotb.org/en/stable/building.html) and default to [Verilator](https://www.veripool.org/verilator/) with all waveforms generated. This can be modified using the standard CocoTB build system.
+
+---
+
+
+## 🧹 Code Style & Linting
+
+This project uses [**Ruff**](https://docs.astral.sh/ruff/) for linting and formatting.
+
+Check code for issues:
+
+```sh
+ruff check .
+```
+
+Automatically fix common issues:
+
+```sh
+ruff check . --fix
+```
+
+
+
+## 📧 Contact
+
+- Email: avl@projectapheleia.net
+- GitHub: [projectapheleia](https://github.com/projectapheleia)
+

avl_spi-0.1.0/README.md

@@ -0,0 +1,143 @@
+# AVL-SPI - Apheleia Verification Library SPI Verification Component
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
+
+
+AVL-SPI has been developed by experienced, industry professional verification engineers to provide a simple, \
+extensible verification component for the [Serial Peripheral Interface](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface) \
+developed in [Python](https://www.python.org/) and the [AVL](https://avl-core.readthedocs.io/en/latest/index.html) library.
+
+AVL is built on the [CocoTB](https://docs.cocotb.org/en/stable/) framework, but aims to combine the best elements of \
+[UVM](https://accellera.org/community/uvm) in a more engineer friendly and efficient way.
+
+## CocoTB 2.0
+
+AVL-SPI supports [CocoTB 2.0](https://docs.cocotb.org/en/development/upgrade-2.0.html) and requires CocoTB 2.1 or later.
+
+## Protocol Features
+
+| Signal Name | Description | Driven By |
+|-------------|-------------|-----------|
+| SCLK        | Serial clock. Idles at CPOL. | Master |
+| CS          | Chip select; one per slave. Polarity configurable per slave. | Master |
+| MOSI        | Master out, slave in serial data. | Master |
+| MISO        | Master in, slave out serial data. | Slave |
+
+> **Note:** At present only single bit, uni-directional SPI is supported. Each SCLK cycle transfers one bit on MOSI (master to slave) and one bit on MISO (slave to master). Bi-directional (3-wire), dual, quad and QPI modes are not supported.
+
+## Component Features
+
+- Simple RTL interface to interact with HDL and define parameter and configuration options
+- Multiple chip selects with individual polarity
+- Clock polarity and individual drive and sample edges for master and slave (all 4 SPI modes and beyond)
+- Variable transfer length, MSB or LSB first
+- Chip select onehot0, setup, hold and inter-frame gap checks in the RTL interface
+- Master sequence, sequencer and driver with rate limiter, SCLK frequency and chip select timing control
+- Slave sequence, sequencer and driver with vanilla, random and memory response patterns
+- Monitor
+- Bandwidth monitor generating bus activity plots over user defined windows during simulation
+- Functional coverage
+- Searchable trace file generation
+
+---
+
+## 📦 Installation
+
+### Using `pip`
+```sh
+# Standard build
+pip install avl-spi
+
+# Development build
+pip install avl-spi[dev]
+```
+
+### Install from Source
+```sh
+git clone https://github.com/projectapheleia/avl-spi.git
+cd avl-spi
+
+# Standard build
+pip install .
+
+# Development build
+pip install .[dev]
+```
+
+Alternatively if you want to create a [virtual environment](https://docs.python.org/3/library/venv.html) rather than install globally a script is provided. This will install, with edit privileges to local virtual environment.
+
+This script assumes you have [Graphviz](https://graphviz.org/download/) and appropriate simulator installed, so all examples and documentation will build out of the box.
+
+
+```sh
+git clone https://github.com/projectapheleia/avl-spi.git
+cd avl-spi
+source avl-spi.sh
+```
+
+## 📖 Documentation
+
+In order to build the documentation you must have installed the development build.
+
+### Build from Source
+```sh
+cd doc
+make html
+<browser> build/html/index.html
+```
+## 🏃 Examples
+
+In order to run all the examples you must have installed the development build.
+
+To run all examples:
+
+```sh
+cd examples
+
+# To run
+make -j 8 sim
+
+# To clean
+make -j 8 clean
+```
+
+To run an individual example:
+
+```sh
+cd examples/THE EXAMPLE YOU WANT
+
+# To run
+make sim
+
+# To clean
+make clean
+```
+
+The examples use the [CocoTB Makefile](https://docs.cocotb.org/en/stable/building.html) and default to [Verilator](https://www.veripool.org/verilator/) with all waveforms generated. This can be modified using the standard CocoTB build system.
+
+---
+
+
+## 🧹 Code Style & Linting
+
+This project uses [**Ruff**](https://docs.astral.sh/ruff/) for linting and formatting.
+
+Check code for issues:
+
+```sh
+ruff check .
+```
+
+Automatically fix common issues:
+
+```sh
+ruff check . --fix
+```
+
+
+
+## 📧 Contact
+
+- Email: avl@projectapheleia.net
+- GitHub: [projectapheleia](https://github.com/projectapheleia)

avl_spi-0.1.0/avl_spi/__init__.py

@@ -0,0 +1,29 @@
+from ._agent import Agent
+from ._agent_cfg import AgentCfg
+from ._bandwidth import Bandwidth
+from ._coverage import Coverage
+from ._item import SequenceItem
+from ._mdriver import MstDriver
+from ._monitor import Monitor
+from ._msequence import MstMemorySequence, MstSequence
+from ._sdriver import SlvDriver, SlvMemoryDriver, SlvRandomDriver
+from ._ssequence import SlvSequence
+
+# Add version
+__version__: str = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "AgentCfg",
+    "Bandwidth",
+    "Coverage",
+    "SequenceItem",
+    "Monitor",
+    "MstDriver",
+    "MstSequence",
+    "MstMemorySequence",
+    "SlvDriver",
+    "SlvRandomDriver",
+    "SlvMemoryDriver",
+    "SlvSequence",
+]

avl_spi-0.1.0/avl_spi/_agent.py

@@ -0,0 +1,119 @@
+# Copyright 2026 Apheleia
+#
+# Description:
+# Apheleia Verification Library Agent
+
+import avl
+import cocotb
+from cocotb.handle import HierarchyObject
+from cocotb.triggers import NextTimeStep, RisingEdge
+
+from ._agent_cfg import AgentCfg
+from ._bandwidth import Bandwidth
+from ._coverage import Coverage
+from ._interface import Interface
+from ._mdriver import MstDriver
+from ._monitor import Monitor
+from ._msequence import MstSequence
+from ._sdriver import SlvDriver
+from ._ssequence import SlvSequence
+
+
+class Agent(avl.Agent):
+    def __init__(self, name: str, parent: avl.Component) -> None:
+        """
+        Initialize the avl-spi Agent
+
+        :param name: Name of the agent instance
+        :type name: str
+        :param parent: Parent component
+        :type parent: Component
+        """
+        super().__init__(name, parent)
+
+        # Create configuration and export to children
+        self.cfg = avl.Factory.get_variable(f"{self.get_full_name()}.cfg", AgentCfg("cfg", self))
+        avl.Factory.set_variable(f"{self.get_full_name()}.*.cfg", self.cfg)
+
+        # Bind HDL to establish parameters and configuration
+        self._bind_(avl.Factory.get_variable(f"{self.get_full_name()}.hdl", None))
+
+        # Create sequencer and driver if master is enabled
+        if self.cfg.has_master:
+            self.msqr = avl.Sequencer("msqr", self)
+            self.mseq = MstSequence("mseq", self.msqr)
+            self.mdrv = MstDriver("mdrv", self)
+            self.msqr.seq_item_export.connect(self.mdrv.seq_item_port)
+
+        # Create sequencer, sequence and driver for each slave
+        if self.cfg.num_slave > 1:
+            self.ssqr, self.sseq, self.sdrv = [], [], []
+            for i in range(self.cfg.num_slave):
+                avl.Factory.set_variable(f"{self.get_full_name()}.sdrv_{i}.idx", i)
+                self.ssqr.append(avl.Sequencer(f"ssqr_{i}", self))
+                self.sseq.append(SlvSequence("sseq", self.ssqr[i]))
+                self.sdrv.append(SlvDriver(f"sdrv_{i}", self))
+                self.ssqr[i].seq_item_export.connect(self.sdrv[i].seq_item_port)
+        elif self.cfg.num_slave == 1:
+            self.ssqr = avl.Sequencer("ssqr", self)
+            self.sseq = SlvSequence("sseq", self.ssqr)
+            self.sdrv = SlvDriver("sdrv", self)
+            self.ssqr.seq_item_export.connect(self.sdrv.seq_item_port)
+
+        # Create monitor if enabled
+        if self.cfg.has_monitor:
+            self.monitor = Monitor("monitor", self)
+
+            if self.cfg.has_coverage:
+                self.coverage = Coverage("coverage", self)
+                self.monitor.item_export.connect(self.coverage.item_port)
+
+            if self.cfg.has_bandwidth:
+                self.bandwidth = Bandwidth("bandwidth", self)
+                self.monitor.item_export.connect(self.bandwidth.item_port)
+
+            if self.cfg.has_trace:
+                self.trace = avl.Trace("trace", self)
+                self.monitor.item_export.connect(self.trace.item_port)
+
+    def _bind_(self, hdl) -> None:
+        """
+        Bind the agent to a hardware description language (HDL) interface.
+        This method is used to associate the agent with a specific HDL interface,
+        allowing it to interact with the hardware model.
+
+        :param hdl: The HDL interface to bind to the agent
+        :type hdl: HierarchyObject
+        :raises TypeError: If `hdl` is not an instance of HierarchyObject
+        """
+        if not isinstance(hdl, HierarchyObject):
+            raise TypeError(f"Expected HierarchyObject, got {type(hdl)}")
+
+        # Assign Interface
+        self.i_f = Interface(hdl)
+        avl.Factory.set_variable(f"{self.get_full_name()}.*.i_f", self.i_f)
+
+    async def run_phase(self) -> None:
+        """
+        Run the agent's phase. This method is called to start the agent's operation.
+        It starts the slave sequences, and the master sequence if the master is enabled.
+        Slave sequences are not awaited, as they depend on transfers from the master.
+        """
+
+        self.raise_objection()
+        await NextTimeStep()
+
+        if self.cfg.num_slave > 0:
+            for s in (self.sseq if isinstance(self.sseq, list) else [self.sseq]):
+                cocotb.start_soon(s.start())
+
+        if self.cfg.has_master:
+            await self.mseq.start()
+
+        # Run-off
+        for _ in range(10):
+            await RisingEdge(self.i_f.clk)
+
+        self.drop_objection()
+
+__all__ = ["Agent"]

avl_spi-0.1.0/avl_spi/_agent_cfg.py

@@ -0,0 +1,36 @@
+# Copyright 2026 Apheleia
+#
+# Description:
+# Apheleia Verification Library Agent Configuration
+
+import avl
+
+
+class AgentCfg(avl.Object):
+
+    def __init__(self, name: str, parent: avl.Component) -> None:
+        """
+        Initialize the avl-spi Agent Configuration
+
+        :param name: Name of the agent instance
+        :type name: str
+        :param parent: Parent component
+        :type parent: Component
+        """
+        super().__init__(name, parent)
+
+        # Agent Attributes
+        self.has_master = avl.Factory.get_variable(f"{self.get_full_name()}.has_master", False)
+        """Has Master Driver"""
+        self.num_slave = avl.Factory.get_variable(f"{self.get_full_name()}.num_slave", 0)
+        """Number of Slave Drivers"""
+        self.has_monitor = avl.Factory.get_variable(f"{self.get_full_name()}.has_monitor", False)
+        """Has Monitor"""
+        self.has_coverage = avl.Factory.get_variable(f"{self.get_full_name()}.has_coverage", False)
+        """Has Functional Coverage"""
+        self.has_bandwidth = avl.Factory.get_variable(f"{self.get_full_name()}.has_bandwidth", False)
+        """Has Bandwidth Monitor"""
+        self.has_trace = avl.Factory.get_variable(f"{self.get_full_name()}.has_trace", False)
+        """Has Trace Generator"""
+
+__all__ = ["AgentCfg"]

avl_spi-0.1.0/avl_spi/_bandwidth.py

@@ -0,0 +1,91 @@
+# Copyright 2026 Apheleia
+#
+# Description:
+# Apheleia Verification Library Bandwidth Monitor
+
+import avl
+import cocotb
+from avl._core._lazy import lazy_import
+from cocotb.triggers import Timer
+from cocotb.utils import get_sim_time
+
+# Deferred until the report phase
+plt = lazy_import("matplotlib.pyplot")
+np = lazy_import("numpy")
+
+
+class Bandwidth(avl.Component):
+
+    def __init__(self, name: str, parent: avl.Component) -> None:
+        """
+        Initialize Bandwidth Monitor
+
+        Class contains variable window_ns which defines the time window in nanoseconds. This
+        is configurable via the factory.
+
+        :param name: Name of the bandwidth monitor.
+        :type name: str
+        :param parent: Parent component.
+        :type parent: Component
+        """
+        super().__init__(name, parent)
+        self.i_f = avl.Factory.get_variable(f"{self.get_full_name()}.i_f", None)
+
+        self.window_ns = avl.Factory.get_variable(f"{self.get_full_name()}.window_ns", 1000)
+        """ Rolling time window in nanoseconds for bandwidth calculation. Default is 1000 ns. """
+
+        self.item_port = avl.List()
+        self.bandwidth = {}
+
+    async def run_phase(self) -> None:
+        """
+        Run phase for the bandwidth component.
+
+        """
+        async def counter():
+            while True:
+                self.item = await self.item_port.blocking_get()
+                self.bandwidth[t] += int(self.item.get("length"))
+
+        cocotb.start_soon(counter())
+
+        while True:
+            t = get_sim_time(unit="ns")
+            self.bandwidth[t] = 0
+
+            self.raise_objection()
+            await Timer(self.window_ns, unit="ns")
+            self.drop_objection()
+
+    async def report_phase(self) -> None:
+        """
+        Report phase for the bandwidth component.
+
+        Generate plot of bits on bus over time windows
+
+        """
+        times = list(self.bandwidth.keys())
+        counts = list(self.bandwidth.values())
+
+        if len(times) > 1:
+            # For unevenly spaced data, calculate individual widths
+            # This uses the minimum spacing to avoid overlapping bars
+            spacings = np.diff(times)
+            bar_width = np.min(spacings)
+        else:
+            # For single bar, use a default width
+            bar_width = 1
+
+        # Create plot
+        plt.figure(figsize=(8, 4))
+        plt.bar(times, counts, width=bar_width, align='center')
+        plt.title("Bus Bandwidth (Bits over Time)")
+        plt.xlabel("Time (ns)")
+        plt.ylabel("Bit Count")
+        plt.grid(True)
+
+        # Export to PNG
+        plt.savefig(f"{self.get_full_name()}.png")
+        plt.close()
+
+__all__ = ["Bandwidth"]