Merge branch 'schwarz-feat-connect_probe_to_driver' into 'devel'

Support for probing MVB and MFB drivers using Throughput Probe and improve wording in comments and hints

See merge request ndk/ndk-fpga!370

Author: jakubcabal

comp/mfb_tools/storage/fifox/cocotb/cocotb_test.py

@@ -45,10 +45,14 @@ def __init__(self, dut, debug=False):
         # setting up driver of the DST_RDY so it randomly fluctuates between 0 and 1
         self.backpressure = BitDriver(dut.TX_DST_RDY, dut.CLK)
 
-        # setting up the probe measuring throughput
-        self.throughput_probe = ThroughputProbe(ThroughputProbeMfbInterface(self.stream_out), throughput_units="bits")
-        self.throughput_probe.add_log_interval(0, None)
-        self.throughput_probe.set_log_period(10)
+        # setting up the probes measuring throughput
+        self.in_throughput_probe = ThroughputProbe(ThroughputProbeMfbInterface(self.stream_in), throughput_units="bits", name="ThroughputProbe - IN")
+        self.in_throughput_probe.add_log_interval(0, None)
+        self.in_throughput_probe.set_log_period(10)
+
+        self.out_throughput_probe = ThroughputProbe(ThroughputProbeMfbInterface(self.stream_out), throughput_units="bits", name="ThroughputProbe - OUT")
+        self.out_throughput_probe.add_log_interval(0, None)
+        self.out_throughput_probe.set_log_period(10)
 
         # counter of sent transactions
         self.pkts_sent = 0
@@ -123,9 +127,12 @@ async def run_test(dut, pkt_count=10000, frame_size_min=60, frame_size_max=512):
         # if not all packets have been received yet, waiting 100 cycles so the simulation doesn't stop prematurelly
         await ClockCycles(dut.CLK, 100)
 
-    # logging values measured by throughput probe
-    tb.throughput_probe.log_max_throughput()
-    tb.throughput_probe.log_average_throughput()
+    # logging values measured by throughput probes
+    tb.in_throughput_probe.log_max_throughput()
+    tb.in_throughput_probe.log_average_throughput()
+
+    tb.out_throughput_probe.log_max_throughput()
+    tb.out_throughput_probe.log_average_throughput()
 
     # displaying result of the test
     raise tb.scoreboard.result

doc/source/cocotb_tips_and_tricks.rst

@@ -0,0 +1,78 @@
+====================
+Cocotb tips & tricks
+====================
+
+This section consists of simple problems you may encounter when creating testbenches
+using ``cocotb/cocotbext-ndk`` frameworks and the solutions to those problems.
+
+Using probes
+============
+
+``cocotbext-ndk`` framework includes a base class for creating probes for various purposes.
+It can be found at ``ndk-fpga/python/cocotbext/cocotbext/ofm/base/probe.py``. The
+probes typically read attributes of their connected agents, usually a monitor or a driver,
+perform calculations with them, and display the results to the terminal either at a specific
+time, periodically, or on request.
+
+The base ``Probe`` class offers a couple of methods to make this possible.
+
+To log a specific time interval, use the ``add_log_interval`` method. If you want the time interval
+to go to infinity, set the ``stop_time`` argument to ``None``; however, don’t forget to also set a period,
+otherwise the probe will never log.
+
+Periodic logging can be achieved by setting a period using the ``set_log_period`` method.
+
+For cases where full control over when the probe starts and stops logging is needed, the ``start_log``
+and ``stop_log`` methods are implemented.
+
+When it comes to specific implementations of probes, at the time of writing, there is only one,
+and that is ``ThroughputProbe`` for measuring throughput and efficiency.
+Check out ``ndk-fpga/python/cocotbext/cocotbext/ofm/utils/throughput_probe.py`` for the implementation.
+
+Class ``ThroughputProbe`` further adds the ``log_average_throughput`` and ``log_max_throughput`` methods
+to log the average throughput and efficiency and the maximal possible average throughput,
+respectively. It is recommended to call these methods at the end of the test when all the transactions
+have been processed.
+
+To perform its task, a probe typically needs to read attributes from the probed agent synchronously.
+However, the names of the attributes of the agent may differ from the names of the attributes of the probe,
+or they may not be present at all; in that case, they need to be either calculated or set to a fixed value.
+
+To resolve this, it is recommended to use interfaces derived from the ``ProbeInterface`` class. This class
+offers two approaches for passing a value to the probe – a translation dictionary ``interface_dict`` and
+properties.
+
+The translation dictionary ``interface_dict`` should contain all needed attributes as its keys.
+The values linked to the keys should be either the names of the equivalent attributes of the agent,
+or ``None`` to indicate that the value is returned by a property of the interface.
+
+If the value cannot be simply read from the agent object because some logic needs to be performed
+(e.g., the value must be calculated from multiple attributes, or the behavior depends on the type of the
+agent), a property with the same name as the key in ``interface_dict`` can be created, which overrides the
+dictionary entry.
+
+.. note:: The interface always looks for a property first. Only after it is not found does it try to get the value
+   from the connected agent using ``interface_dict``.
+
+For a specific implementation of a probe interface, check out the different interfaces for
+``ThroughputProbe`` in ``ndk-fpga/python/cocotbext/cocotbext/ofm/utils/throughput_probe.py``.
+
+The setup of a probe can, for example, look like this:
+
+.. code-block:: python
+
+    self.out_throughput_probe = ThroughputProbe(
+        ThroughputProbeMfbInterface(self.stream_out),
+        throughput_units="bits",
+        name="ThroughputProbe - OUT"
+    )
+    self.out_throughput_probe.add_log_interval(0, None)
+    self.out_throughput_probe.set_log_period(10)
+
+Which then produces output like this:
+
+.. code-block::
+
+    #  10000.00ns INFO     cocotb.ThroughputProbe - OUT       Immediate throughput at 10.0 us: 134.5104 Gb/s, Immediate efficiency: 32.8395%
+    #  20000.00ns INFO     cocotb.ThroughputProbe - OUT       Immediate throughput at 20.0 us: 134.8456 Gb/s, Immediate efficiency: 32.9213%
+    #  30000.00ns INFO     cocotb.ThroughputProbe - OUT       Immediate throughput at 30.0 us: 134.9 Gb/s, Immediate efficiency: 32.9346%

doc/source/index.rst

@@ -98,6 +98,7 @@ it also provides converters:
 
     basic_cocotb_test
     cocotbext
+    cocotb_tips_and_tricks
 
 .. toctree::
     :caption: GitLab CI/CD Tools

python/cocotbext/cocotbext/ofm/base/probe.py

@@ -8,6 +8,8 @@
 from cocotb.triggers import RisingEdge
 from cocotb.log import SimLog
 from cocotb.utils import get_sim_time
+from cocotb_bus.drivers import BusDriver
+from cocotb_bus.monitors import BusMonitor
 from ofm.utils.units import convert_units
 from abc import ABC, abstractmethod
 from typing import Any
@@ -20,16 +22,19 @@ class ProbeInterface:
     Atributes:
         interface_dict(dict): keys are names of parameters that the probe wants to retrieve and items are tuples,
                               where the first item is the conversion function and second is tuple with arguments
-                              for the convertion function.
-        _monitor(BusMonitor): monitor object including the attributes required for probing
+                              for the conversion function. It is also possible to override a value in the interface
+                              dict by creating a class property with the same name as the key being overriden in the
+                              interface dict. This can be useful if it's necessary to calculate the value of the attribute
+                              or to implement different behavior based on the type of the agent.
+        _agent(BusMonitor | BusDriver): monitor or driver object including the attributes required for probing
     """
     interface_dict = {}
 
-    def __init__(self, monitor):
-        self._monitor = monitor
+    def __init__(self, agent: BusMonitor | BusDriver):
+        self._agent = agent
 
     def __getattr__(self, name: str) -> Any:
-        return getattr(self._monitor, self.interface_dict.get(name, None))
+        return getattr(self._agent, self.interface_dict.get(name, None))
 
 
 class Probe(ABC):

python/cocotbext/cocotbext/ofm/mfb/drivers.py

@@ -20,6 +20,7 @@ def __init__(self, entity, name, clock, array_idx=None, mfb_params=None):
         super().__init__(entity, name, clock, array_idx=array_idx)
         self.clock = clock
         self.frame_cnt = 0
+        self.item_cnt = 0
         self._regions, self._region_size, self._block_size, self._item_width, self._meta_width, self._os_valid_with = get_mfb_params(
             self.bus, mfb_params
         )
@@ -201,6 +202,7 @@ async def _send_thread(self):
 
                 await self._write_frame(transaction)
                 self.frame_cnt += 1
+                self.item_cnt += (len(transaction.data) * 8) // self._item_width
                 # Notify the world that this transaction is complete
                 if event:
                     event.set()

python/cocotbext/cocotbext/ofm/utils/throughput_probe.py

@@ -9,6 +9,8 @@
 from ofm.utils import convert_units
 from cocotbext.ofm.mvb.monitors import MVBMonitor
 from cocotbext.ofm.mfb.monitors import MFBMonitor
+from cocotbext.ofm.mvb.drivers import MVBDriver
+from cocotbext.ofm.mfb.drivers import MFBDriver
 
 
 class ThroughputProbeInterface(ProbeInterface):
@@ -35,12 +37,33 @@ class ThroughputProbeMvbInterface(ThroughputProbeInterface):
         "item_cnt"  : "item_cnt"
     }
 
-    def __init__(self, monitor: MVBMonitor):
-        super().__init__(monitor)
+    def __init__(self, agent: MVBMonitor | MVBDriver):
+        super().__init__(agent)
+
+    @property
+    def in_reset(self):
+        """
+        Overrides 'in_reset' in interface_dict.
+
+        Implements different behavior of in_reset based on
+        the type of the agent.
+        """
+        in_reset = self.interface_dict.get("in_reset", None)
+
+        # check if in_reset has a valid translation in
+        # the interface dict and if the agent has a
+        # variable with this name. If yes, return
+        # it's value
+        if in_reset is not None:
+            if hasattr(self._agent, in_reset):
+                return getattr(self._agent, in_reset)
+
+        # if no, return False as default
+        return False
 
 
 class ThroughputProbeMfbInterface(ThroughputProbeInterface):
-    """Throughput probe interface for the MFB monitor."""
+    """Throughput probe interface for the MFB monitor or driver."""
     interface_dict = {
         "clock"     : "clock",
         "in_reset"  : "in_reset",
@@ -49,12 +72,34 @@ class ThroughputProbeMfbInterface(ThroughputProbeInterface):
         "item_cnt"  : "item_cnt"
     }
 
-    def __init__(self, monitor: MFBMonitor):
-        super().__init__(monitor)
+    def __init__(self, agent: MFBMonitor | MFBDriver):
+        super().__init__(agent)
+
+    @property
+    def in_reset(self):
+        """
+        Overrides 'in_reset' in interface_dict.
+
+        Implements different behavior of in_reset based on
+        the type of the agent.
+        """
+        in_reset = self.interface_dict.get("in_reset", None)
+
+        if in_reset is not None:
+            if hasattr(self._agent, in_reset):
+                return getattr(self._agent, in_reset)
+
+        return False
 
     @property
     def items(self):
-        return self._monitor._regions * self._monitor._region_items
+        """
+        Overrides 'items' in interface_dict.
+
+        Calculates number of items from number of regions
+        and items per region on the connected MFB bus.
+        """
+        return self._agent._regions * self._agent._region_items
 
 
 class ThroughputProbe(Probe):