Doc publisher-subscriber package

docs/library/utilities/index.rst

@@ -8,5 +8,6 @@ Contents
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
-   Test Harness <test_harness/index>
+   */index

docs/library/utilities/pub_sub/index.rst

@@ -0,0 +1,19 @@
+.. _pub_sub:
+
+Publisher-Subscriber package
+================================================================================
+
+.. toctree::
+   :hidden:
+
+   Publisher <publisher>
+   Subscriber <subscriber>
+
+The publisher-subscriber package is a collection of small packages that are used
+inside VIP monitors, scoreboards and checkers.
+
+Contents
+-------------------------------------------------------------------------------
+
+#. :ref:`publisher`: Class that publishes new data arrived in the monitor
+#. :ref:`subscriber`: Class that receives new data published

docs/library/utilities/pub_sub/publisher.rst

@@ -0,0 +1,63 @@
+.. _publisher:
+
+Publisher
+================================================================================
+
+Overview
+-------------------------------------------------------------------------------
+
+This class is designed to manage a list of subscribers, has the ability to
+notify subscribers with the received data. The class is parameterized with a
+``data_type``. It is mainly used in VIP monitors, but it can also be integrated
+in other environments as well.
+
+.. svg:: library/utilities/pub_sub/publisher.svg
+   :align: center
+
+Variables
+-------------------------------------------------------------------------------
+
+None are available for direct external access.
+
+Functions
+-------------------------------------------------------------------------------
+
+function new(input string name, input adi_component parent = null);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The class constructor function initializes the object with the provided name and
+parent component.
+
+function void subscribe(input adi_subscriber #(data_type) subscriber);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The subscribe function adds a subscriber to the subscriber_list if it does not
+already exist. Gives an error message, if the subscriber is already added to the
+list.
+
+function void unsubscribe(input adi_subscriber #(data_type) subscriber);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The unsubscribe function removes a subscriber if it exists in the list.
+
+function void notify(input adi_fifo #(data_type) data);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The notify function is responsible for notifying all subscribers with the data.
+
+Usage and recommendations
+-------------------------------------------------------------------------------
+
+Basic usage of the publisher:
+
+* Declare the publisher and create an instance
+* Use the subscribe function to add subscribers to the list
+* Create a packet that needs to be published
+* Call the notify function to publish the packet
+* Unsubscribe the subscribed modules if needed
+
+.. important::
+
+  The publisher and subscriber modules must operate on the same data type.
+
+.. include:: ../../../common/support.rst

docs/library/utilities/pub_sub/publisher.txt

@@ -0,0 +1,28 @@
+# Classes
+
+# Base
+adi_reporter: {shape: class}
+adi_component: {shape: class}
+
+# Components
+adi_publisher: {
+  shape: class
+  \#subscriber_list
+  +subscribe()
+  +unsubscribe()
+  +notify()
+}
+adi_subscriber: {shape: class}
+
+# Inheritances
+
+# Base
+adi_reporter <- adi_component: {shape: triangle; source-arrowhead.style.filled: false}
+
+# Components
+adi_component <- adi_publisher: {shape: triangle; source-arrowhead.style.filled: false}
+
+# Aggregations
+
+# Components
+adi_publisher <- adi_subscriber: {source-arrowhead: * {shape: diamond; style.filled: true}}

docs/library/utilities/pub_sub/subscriber.rst

@@ -0,0 +1,62 @@
+.. _subscriber:
+
+Subscriber
+================================================================================
+
+Overview
+-------------------------------------------------------------------------------
+
+This class is designed to be used in conjunction with a publisher class. The
+class is parameterized with a data_type. It is mainly used in scoreboard and
+checker classes which need data inputs from various other modules.
+
+.. important::
+
+  The subscriber base class must be inherited and a new implementation must be
+  written in a subclass.
+
+.. svg:: library/utilities/pub_sub/subscriber.svg
+   :align: center
+
+Variables
+-------------------------------------------------------------------------------
+
+It has a variable ID that is public, which is used to identify the current
+instance. It is also used by the publisher when adding/removing the subscribing
+class to/from the list.
+
+Functions
+-------------------------------------------------------------------------------
+
+function new(input string name, input adi_component parent = null);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The class constructor function initializes the object with the provided name and
+parent component. A static variable is counting the number of subscribers that
+have been created up until this point, this ensures that all subscribers receive
+a unique identification number.
+
+virtual function void update(input adi_fifo #(data_type) data);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function is intended to be overridden by subclasses. When a publisher has
+new data, it calls each subscriber's update function, which ensures that each
+implementation will use the published data in the way it was intended to be used
+in the class where the subscriber is instantiated.
+
+Usage and recommendations
+-------------------------------------------------------------------------------
+
+Basic usage of the subscriber:
+
+* Create a subscriber subclass
+* Implement the update function
+* Add extra functionality if needed
+* Subscribe to the publisher
+* Unsubscribe from the publisher
+
+.. important::
+
+  The publisher and subscriber modules must operate on the same data type.
+
+.. include:: ../../../common/support.rst