avl-apb 0.1.0__tar.gz

avl_apb-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_apb-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.3
+Name: avl-apb
+Version: 0.1.0
+Summary: Apheleia Verification Library - AMBA Advanced Peripheral Bus 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.
+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 (>=0.2.1)
+Requires-Dist: black (>=22.3.0) ; extra == "dev"
+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-APB - Apheleia Verification Library AMBA APB Verification Component
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.7%2B-blue)](https://www.python.org/)
+
+
+AVL-APB has been developed by experienced, industry professional verification engineers to provide a simple, \
+extensible verification component for the [AMBA APB Bus](https://developer.arm.com/documentation/ihi0024/latest/) \
+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.
+
+
+## Protocol Features
+
+| Version | Signal Name | Description | Driven By |
+|---------|-------------|-------------|-----------|
+| APB2    | PCLK        | APB clock signal; all APB transfers are synchronized to this clock. | Requester |
+| APB2    | PRESETn     | Asynchronous active-low reset for the APB interface. | Requester |
+| APB2    | PADDR       | Address bus; specifies the register address for the transfer. | Requester |
+| APB2    | PSELx       | Slave select; one per slave. High when the slave is selected. | Requester |
+| APB2    | PENABLE     | Indicates the second and subsequent cycles of an APB transfer. | Requester |
+| APB2    | PWRITE      | Write control signal; high for write, low for read. | Requester |
+| APB2    | PWDATA      | Write data bus from master to slave. | Requester |
+| APB2    | PRDATA      | Read data bus from slave to master. | Completer |
+| APB3    | PREADY      | Optional signal; indicates the slave is ready to complete the transfer. | Completer |
+| APB3    | PSLVERR     | Optional signal; indicates an error condition on the transfer. | Completer |
+| APB4    | PPROT       | Optional protection control signals for privilege, security, and instruction/data access. | Requester |
+| APB4    | PSTRB       | Optional byte lane strobe signals for write operations. | Requester |
+| APB5    | PNSE        | Optional signal; indicates whether the transfer is secure or non-secure. | Requester |
+| APB5    | PWAKEUP     | Optional wakeup signal from slave to master for low-power operation. | Completer |
+| APB5    | PAUSER      | Optional signal; specifies the user ID associated with the transfer for secure systems. | Requester |
+| APB5    | PRUSER      | Optional user-defined read data channel sideband signals. | Completer |
+| APB5    | PWUSER      | Optional user-defined write data channel sideband signals. | Requester |
+| APB5    | PBUSER      | Optional user-defined byte strobe channel sideband signals. | Requester |
+
+## Component Features
+
+- All protocol features supported
+- Simple RTL interface to interact with HDL and define parameter and configuration options
+- Requester sequence, sequencer and driver with easy to control rate limiter and wakeup control
+- Completer driver with vanilla, random and memory response patterns
+- Monitor
+- Bandwidth monitor generating bus activity plots over user defined windows during simulation
+- Functional coverage including performance measurements
+- Searchable trace file generation
+
+---
+
+## 📦 Installation
+
+### Using `pip`
+```sh
+# Standard build
+pip install avl-core
+
+# Development build
+pip install avl-core[dev]
+```
+
+### Install from Source
+```sh
+git clone https://github.com/projectapheleia/avl.git
+cd avl
+
+# 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-apb.git
+cd avl-apb
+source avl-apb.sh
+```
+
+## 📖 Documentation
+
+In order to build the documentation you must have installed the development build.
+
+### Build from Source
+```sh
+cd docs
+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_apb-0.1.0/README.md

@@ -0,0 +1,149 @@
+# AVL-APB - Apheleia Verification Library AMBA APB Verification Component
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.7%2B-blue)](https://www.python.org/)
+
+
+AVL-APB has been developed by experienced, industry professional verification engineers to provide a simple, \
+extensible verification component for the [AMBA APB Bus](https://developer.arm.com/documentation/ihi0024/latest/) \
+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.
+
+
+## Protocol Features
+
+| Version | Signal Name | Description | Driven By |
+|---------|-------------|-------------|-----------|
+| APB2    | PCLK        | APB clock signal; all APB transfers are synchronized to this clock. | Requester |
+| APB2    | PRESETn     | Asynchronous active-low reset for the APB interface. | Requester |
+| APB2    | PADDR       | Address bus; specifies the register address for the transfer. | Requester |
+| APB2    | PSELx       | Slave select; one per slave. High when the slave is selected. | Requester |
+| APB2    | PENABLE     | Indicates the second and subsequent cycles of an APB transfer. | Requester |
+| APB2    | PWRITE      | Write control signal; high for write, low for read. | Requester |
+| APB2    | PWDATA      | Write data bus from master to slave. | Requester |
+| APB2    | PRDATA      | Read data bus from slave to master. | Completer |
+| APB3    | PREADY      | Optional signal; indicates the slave is ready to complete the transfer. | Completer |
+| APB3    | PSLVERR     | Optional signal; indicates an error condition on the transfer. | Completer |
+| APB4    | PPROT       | Optional protection control signals for privilege, security, and instruction/data access. | Requester |
+| APB4    | PSTRB       | Optional byte lane strobe signals for write operations. | Requester |
+| APB5    | PNSE        | Optional signal; indicates whether the transfer is secure or non-secure. | Requester |
+| APB5    | PWAKEUP     | Optional wakeup signal from slave to master for low-power operation. | Completer |
+| APB5    | PAUSER      | Optional signal; specifies the user ID associated with the transfer for secure systems. | Requester |
+| APB5    | PRUSER      | Optional user-defined read data channel sideband signals. | Completer |
+| APB5    | PWUSER      | Optional user-defined write data channel sideband signals. | Requester |
+| APB5    | PBUSER      | Optional user-defined byte strobe channel sideband signals. | Requester |
+
+## Component Features
+
+- All protocol features supported
+- Simple RTL interface to interact with HDL and define parameter and configuration options
+- Requester sequence, sequencer and driver with easy to control rate limiter and wakeup control
+- Completer driver with vanilla, random and memory response patterns
+- Monitor
+- Bandwidth monitor generating bus activity plots over user defined windows during simulation
+- Functional coverage including performance measurements
+- Searchable trace file generation
+
+---
+
+## 📦 Installation
+
+### Using `pip`
+```sh
+# Standard build
+pip install avl-core
+
+# Development build
+pip install avl-core[dev]
+```
+
+### Install from Source
+```sh
+git clone https://github.com/projectapheleia/avl.git
+cd avl
+
+# 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-apb.git
+cd avl-apb
+source avl-apb.sh
+```
+
+## 📖 Documentation
+
+In order to build the documentation you must have installed the development build.
+
+### Build from Source
+```sh
+cd docs
+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_apb-0.1.0/avl_apb/__init__.py

@@ -0,0 +1,26 @@
+from ._agent import Agent
+from ._agent_cfg import AgentCfg
+from ._bandwidth import Bandwidth
+from ._cdriver import CplDriver, CplMemoryDriver, CplRandomDriver
+from ._coverage import Coverage
+from ._item import SequenceItem
+from ._monitor import Monitor
+from ._rdriver import ReqDriver
+from ._rsequence import ReqSequence
+
+# Add version
+__version__: str = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "AgentCfg",
+    "Bandwidth",
+    "CplDriver",
+    "CplMemoryDriver",
+    "CplRandomDriver",
+    "Coverage",
+    "SequenceItem",
+    "Monitor",
+    "ReqDriver",
+    "ReqSequence",
+]

avl_apb-0.1.0/avl_apb/_agent.py

@@ -0,0 +1,105 @@
+# Copyright 2025 Apheleia
+#
+# Description:
+# Apheleia Verification Library Agent
+
+import avl
+from cocotb.handle import HierarchyObject
+from cocotb.triggers import NextTimeStep, RisingEdge
+
+from ._agent_cfg import AgentCfg
+from ._bandwidth import Bandwidth
+from ._cdriver import CplDriver
+from ._coverage import Coverage
+from ._interface import Interface
+from ._monitor import Monitor
+from ._rdriver import ReqDriver
+from ._rsequence import ReqSequence
+
+
+class Agent(avl.Agent):
+    def __init__(self, name: str, parent: avl.Component) -> None:
+        """
+        Initialize the avl-apb 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 requester is enabled
+        if self.cfg.has_requester:
+            self.rsqr = avl.Sequencer("rsqr", self)
+            self.rseq = ReqSequence("rseq",self.rsqr)
+            self.rdrv = ReqDriver("rdrv", self)
+            self.rsqr.seq_item_export.connect(self.rdrv.seq_item_port)
+
+        if self.cfg.num_completer > 1:
+            self.cdrv = []
+            for i in range(self.cfg.num_completer):
+                avl.Factory.set_variable(f"{self.get_full_name()}.cdrv_{i}.idx", i)
+                self.cdrv.append(CplDriver(f"cdrv_{i}", self))
+        elif self.cfg.num_completer == 1:
+            self.cdrv = CplDriver("cdrv", self)
+
+        # 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 initializes the agent and starts the requester and completer if they are active.
+        """
+
+        self.raise_objection()
+        await NextTimeStep()
+
+        if self.cfg.has_requester:
+            await self.rseq.start()
+
+        # Run-off
+        for _ in range(10):
+            await RisingEdge(self.i_f.pclk)
+
+        self.drop_objection()
+
+__all__ = ["Agent"]

avl_apb-0.1.0/avl_apb/_agent_cfg.py

@@ -0,0 +1,36 @@
+# Copyright 2025 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-apb 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_requester = avl.Factory.get_variable(f"{self.get_full_name()}.has_requester", False)
+        """Has Requester Driver"""
+        self.num_completer = avl.Factory.get_variable(f"{self.get_full_name()}.num_completer", 0)
+        """Number Completer Driver"""
+        self.has_monitor = avl.Factory.get_variable(f"{self.get_full_name()}.has_monitor", False)
+        """Has Monitor Driver"""
+        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_apb-0.1.0/avl_apb/_bandwidth.py

@@ -0,0 +1,94 @@
+# Copyright 2025 Apheleia
+#
+# Description:
+# Apheleia Verification Library Bandwidth Monitor
+
+import avl
+import cocotb
+import matplotlib.pyplot as plt
+import numpy as np
+from cocotb.triggers import Timer
+from cocotb.utils import get_sim_time
+
+
+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 ime 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 coverage component.
+
+        """
+        async def counter():
+            while True:
+                self.item = await self.item_port.blocking_get()
+
+                incr = self.i_f.PSTRB_WIDTH
+                if self.item.get("pwrite"):
+                    pstrb = self.item.get("pstrb", None)
+                    if pstrb is not None:
+                        incr = bin(pstrb).count("1")
+                self.bandwidth[t] += incr
+
+        cocotb.start_soon(counter())
+
+        while True:
+            t = get_sim_time(units="ns")
+            self.bandwidth[t] = 0
+
+            self.raise_objection()
+            await Timer(self.window_ns, units="ns")
+            self.drop_objection()
+
+    async def report_phase(self) -> None:
+        """
+        Report phase for the bandwidth component.
+
+        Generate plot of bytes 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 (Bytes over Time)")
+        plt.xlabel("Time (ns)")
+        plt.ylabel("Byte Count")
+        plt.grid(True)
+
+        # Export to PNG
+        plt.savefig(f"{self.get_full_name()}.png")
+        plt.close()
+
+__all__ = ["Bandwidth"]