Doc scoreboard

docs/library/drivers/common/index.rst

@@ -8,7 +8,6 @@ Contents
 
 .. toctree::
    :maxdepth: 1
+   :glob:
 
-   Monitor <monitor/index>
-   Scoreboard <scoreboard/index>
-   Watchdog <watchdog/index>
+   */index

docs/library/drivers/common/scoreboard/index.rst

@@ -3,3 +3,107 @@
 Scoreboard
 ================================================================================
 
+Overview
+-------------------------------------------------------------------------------
+
+The scoreboard class is designed for transaction comparison in a verification
+environment. This class extends adi_component and is parameterized by a
+datatype data_type, which allows the verification of different datatypes without
+the need of inheriting this class. The scoreboard class contains an inner class
+subscriber_class which extends adi_subscriber and is responsible for receiving
+and storing data streams. The scoreboard can operate in oneshot or in
+cyclic mode, which allows the verification of repeating sequence verification.
+
+.. svg:: library/drivers/common/scoreboard/scoreboard.svg
+   :align: center
+
+Variables
+-------------------------------------------------------------------------------
+
+The scoreboard class itself has two instances of subscriber_class, named
+subscriber_source and subscriber_sink, which represent the source and sink of
+the data streams. These are subscribed to a publisher, which calls the
+respective functions when new data is available.
+
+Functions
+-------------------------------------------------------------------------------
+
+function new(input string name, input adi_component parent = null);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates the scoreboard object. The name gives the scoreboard a name that is
+relevant in the current environment it is instantiated in and the parent sets
+the parent object in which it resides.
+
+task run();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enables the scoreboard and clears the data streams.
+
+task stop();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Disables the scoreboard and clears the data streams.
+
+function void set_sink_type(input bit sink_type);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allows the setting of the sink type, which defines if the output data may or may
+not repeat. If set to oneshot, then the source data is verified only once. If
+set to cyclic, then the source data is verified against the sink data as long as
+new data is coming in on the sink side. This value can only be set when the
+scoreboard is disabled.
+
+function bit get_sink_type();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Get the sink type.
+
+protected function void clear_streams();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Clear the source and sink data streams.
+
+task wait_until_complete();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Wait until the source and the sink datastreams are clear of data, which means
+that all source data was verified against all sink data.
+
+virtual function void compare_transaction();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Compares the source and the sink datastreams against each other. This method is
+called by the subscriber when new data arrives. If the scoreboard is disabled,
+the comparison is ommited.
+
+Usage and recommendations
+-------------------------------------------------------------------------------
+
+Basic usage of the scoreboard:
+
+* Declare the scoreboard
+* Link the source and sink subscribers to the publishers where you want to
+  verify data
+* Optional: set the sink type; default is oneshot
+* Call the run function to start the verification
+* Wait until the scoreboard completes verification
+* Stop the scoreboard
+
+.. important::
+
+  * The scoreboard must be started before the data transmission begins,
+    otherwise, data will be lost and the verification will fail!
+
+Other use-cases:
+
+* The scoreboard can be dynamically reconfigured to use other inputs. Stop the
+  scoreboard, unsubscribe the subscribers from the publishers and subscribe them
+  to the other publisher where you want to verify data.
+
+.. important::
+
+  * The datatype cannot be changed during runtime, only the publisher, to which
+    they are subscribed to.
+
+.. include:: ../../../../common/support.rst

docs/library/drivers/common/scoreboard/scoreboard.txt

@@ -0,0 +1,40 @@
+# Classes
+
+# Base
+adi_reporter: {shape: class}
+adi_component: {shape: class}
+
+# Component
+adi_subscriber: {shape: class}
+
+# Scoreboard
+scoreboard: {
+  shape: class
+  +subscriber_source
+  +subscriber_sink
+  \#sink_type
+  \#enabled
+  \#bytestream_empty_sig
+  \#byte_streams_empty
+  \#stop_scoreboard
+  +run()
+  +stop()
+  +set_sink_type()
+  +get_sink_type()
+  \#clear_streams()
+  +wait_until_complete()
+  +compare_transaction()
+}
+
+# Inheritances
+
+# Base
+adi_reporter <- adi_component: {shape: triangle; source-arrowhead.style.filled: false}
+
+# Scoreboard
+adi_component <- scoreboard: {shape: triangle; source-arrowhead.style.filled: false}
+
+# Aggregations
+
+# Scoreboard
+scoreboard <- adi_subscriber: {source-arrowhead: 2 {shape: diamond; style.filled: true}}

docs/library/drivers/common/scoreboard_pack/index.rst

@@ -0,0 +1,46 @@
+.. _scoreboard_pack:
+
+Scoreboard Pack
+================================================================================
+
+Overview
+-------------------------------------------------------------------------------
+
+This class is a specialized version of a generic scoreboard class, parameterized
+by the data type and packer mode. The scoreboard pack class is designed to
+handle and compare data streams in a verification environment.
+
+.. svg:: library/drivers/common/scoreboard_pack/scoreboard_pack.svg
+   :align: center
+
+Variables
+-------------------------------------------------------------------------------
+
+No additional variables are available for direct external access.
+
+Functions
+-------------------------------------------------------------------------------
+
+function new(...);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates the scoreboard object. The name gives the scoreboard a name that is
+relevant in the current environment it is instantiated in, the channels set the
+number of channels that are present on the packer module, the sample value sets
+the number of samples that are set in the converter, the width specifies the
+width of one sample for one channel, the mode is set based on the current pack
+module, which can be a packer or unpacker and the parent sets the parent object
+in which it resides.
+
+virtual function void compare_transaction();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The compare module's base functionality is the same as the base class, but it
+specifically verifies the input and output of the packer and unpacker modules.
+
+Usage and recommendations
+-------------------------------------------------------------------------------
+
+Same as the base class.
+
+.. include:: ../../../../common/support.rst