api.md

@page pAPI API Descriptions

The scoreboard presents several APIs that user-facing code can leverage. These APIs have been grouped based on their functionality, and are described in further detail in the sections below.

In general, all methods which are labeled with <b>API</b> are OK to call from user code. The only exception to this rule is methods labeled with <b>Compare Strategy API</b>.
These methods should not be called from outside of a compare strategy, but they are labeled as a separate API to simplify custom compare strategy implementations. See also \ref sCompareStrategyAPI and the included figure of the comparison flowchart.

In the sections below, a brief overview of the APIs is presented.
Selected methods from each API are listed here, but more exist. Follow the links to view each class' full list of methods.
All methods labeled with <b>API</b> are part of the user-facing API, and have more in-depth explanations of their functionality, parameters and return values. On the class reference pages, all internal methods are also described in detail to aid in further extensions, but should not be called outside of the given class.

@section sConfigAPI Configuration API

The configuration API is accessible in cl_syoscb_cfg and cl_syoscbs_cfg.
The methods of the configuration API are used to configure scoreboards and scoreboard wrappers.
These methods are generally called in the UVM \c build_phase, setting configuration values before starting simulation.

<b> Classes implementing this API </b>
-# cl_syoscb_cfg
-# cl_syoscbs_cfg

<b> Selected methods </b>

See \ref pExampleConf for an overview of all configuration knobs in cl_syoscb_cfg. cl_syoscbs_cfg itself does not contain many config knobs, but includes methods for easily modifying all wrapped configuration objects.

@section sCompareAPI Compare API

The compare API is used to start and control comparisons. The compare API is relatively small, whereas the \ref sCompareStrategyAPI contains the majority of the functions used to implement comparisons.
The class cl_syoscb_compare inherits from \c uvm_component and is used to instantiate the desired compare strategy which inherits from cl_syoscb_compare_base.

<b> Classes implementing this API </b>
-# cl_syoscb_compare
-# cl_syoscb_compare_base
-# cl_syoscb_compare_io
-# cl_syoscb_compare_iop
-# cl_syoscb_compare_io_2hp
-# cl_syoscb_compare_ooo

<b> Selected methods </b>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb_compare_base#compare_trigger</td>
    <td>Initiates a comparison when an item has been inserted. If cl_syoscb_compare_base.disable_compare is set, the comparison is not performed </td>
  </tr>
  <tr>
    <td>cl_syoscb_compare_base#compare_main</td>
    <td>Initiates a comparison, bypassing the check of \c disable_compare </td>
  </tr>
  <tr>
    <td>cl_syoscb_compare_base#compare_control</td>
    <td>Disable or enable comparisons by calling this method</td>
  </tr>
</table>

@section sQueueAPI Queue API
The queue API is primarily used to insert items in queues. When an item has been added to the scoreboard via either the function-based API or a TLM connection, the scoreboard adds the item to a queue through the queue API. If other types of queues than the std. queues and hash queues are desired, these should also implement this API.

<b>Classes implementing this API </b>
-# cl_syoscb_queue_base
-# cl_syoscb_queue_std
-# cl_syoscb_queue_hash
-# cl_syoscb_queue_hash_md5

<b> Selected methods </b>
<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb_queue_base#add_item</td>
    <td>Adds an item to the queue, placing it at the end of the queue. </td>
  </tr>
  <tr>
    <td>cl_syoscb_queue_base#insert_item</td>
    <td>Inserts an item at a specified index instead of placing it at the end of the queue. </td>
  </tr>
  <tr>
    <td>cl_syoscb_queue_base#flush_queue</td>
    <td>Flushes the queue, removing all items that previously occupied the queue</td>
  </tr>
  <tr>
    <td>cl_syoscb_queue_base#create_iterator</td>
    <td>Creates an iterator over this queue. See \ref sIteratorAPI for information on how iterators are used to traverse queues.
  </tr>
  <tr>
    <td>cl_syoscb_queue_base#get_item </td>
    <td> Takes a proxy item as input, and uses this proxy item to return a specific item from the queue </td>
  </tr>
</table>


@section sHashAPI Hash API
The hash API is used by hash algorithms to hash sequence items for use in hash queues.

<b>Classes implementing this API </b>

-# cl_syoscb_hash_base
-# cl_syoscb_hash_md5

<b> Selected methods </b>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb_hash_base#hash</td>
    <td>Hashes a cl_syoscb_item using the specified hash algorithm, returning the bitstream representing that hash </td>
  </tr>
  <tr>
    <td>cl_syoscb_hash_base#hash_str</td>
    <td>Hashes a string using the specified hash algorithm </td>
  </tr>
  <tr>
    <td>cl_syoscb_hash_base#do_hash</td>
    <td>The underlying method which implements hashing of a bitstream. Can be used to hash items which are not strings or objects that extend cl_syoscb_item</td>
  </tr>
</table>

@section sItemAPI Item API

The SyoSCB leverages multiple types of wrapper items to manage separation of concerns. The item API encompasses three different items' APIs, all of which are used to wrap sequence items when stored inside the scoreboard.


<b>Classes implementing this API </b>

-# cl_syoscb_item
  - Wraps a \c uvm_sequence_item generated by the DUT or a reference model with additional metadata used for comparisons.
-# cl_syoscb_hash_item
  - Used in hash queues to ensure that hash collisions, although unlikely, do not overwrite items in the underlying datastructure.
-# cl_syoscb_proxy_item_base
  - cl_syoscb_proxy_item_std
  - cl_syoscb_proxy_item_hash
  - Used with iterators and locators to separate the underlying queue's implementation and the act of iterating over it.

<b> Selected methods </b>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb_item#get_item</td>
    <td>Gets the \c uvm_sequence_item wrapped by this scoreboard item </td>
  </tr>
  <tr>
    <td>cl_syoscb_hash_item#get_item</td>
    <td>Gets the first of possibly multiple items that have the same hash </td>
  </tr>
  <tr>
    <td>cl_syoscb_proxy_item_base#get_item</td>
    <td>Gets the item which this proxy item represents. The proxy item contains a handle to the queue, and the queue knows how to parse proxy items (see \ref sQueueAPI)</td>
  </tr>
</table>

@section sIteratorAPI Iterator API

Iterators are used to iterate over queues in an implementation-agnostic manner. To iterate over all items in a queue,
a loop of the following kind may be used:

@code
if(iter.first()) begin //Reset the iterator, returns false if the queue is empty
  while(!iter.is_done()) begin
    //do something
    void'(iter.next());
  end
end
@endcode

<b>Classes implementing this API</b>
-# cl_syoscb_queue_iterator_base
-# cl_syoscb_queue_iterator_std
-# cl_syoscb_queue_iterator_hash
-# cl_syoscb_queue_iterator_hash_md5

<b> Selected methods </b>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb_queue_iterator_base#next</td>
    <td>Moves the iterator one item forward</td>
  </tr>
  <tr>
    <td>cl_syoscb_queue_iterator_base#get_item_proxy</td>
    <td>Gets a cl_syoscb_proxy_item_base representing the item that the iterator currently points to </td>
  </tr>
  <tr>
    <td>cl_syoscb_queue_iterator_base#is_done</td>
    <td>Checks whether the iterator has reached the end of the queue. </td>
  </tr>
</table>

@section sLocatorAPI Locator API

Locators are used to find a specific item in a queue in an implementation-agnostic manner. Locators are primarily used for the OOO compare algorithm, where the item being searched for may exist anywhere in the queue.


<b>Classes implementing this API</b>
-# cl_syoscb_queue_locator_base
-# cl_syoscb_queue_locator_std
-# cl_syoscb_queue_locator_hash
-# cl_syoscb_queue_locator_hash_md5

<b> Selected methods </b>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb_queue_locator_base#search</td>
    <td>Searches the underlying queue for an item which matches the argument.</td>
  </tr>
  <tr>
    <td>cl_syoscb_queue_locator_base#get_queue</td>
    <td>Gets a handle to the queue that this locator is operating on </td>
  </tr>
  <tr>
    <td>cl_syoscb_queue_locator_base#set_queue</td>
    <td>Sets the queue over which a locator should operate </td>
  </tr>
</table>

@section sScoreboardAPI Scoreboard API

The scoreboard API is used to insert items, either through the function-based API or through a TLM-based connection. Once inserted, the scoreboard contains a number of functions that can be used to generate statistics or dump items to log files.

<b>Classes implementing this API</b>
-# cl_syoscb

<b> Selected methods </b>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb#add_item</td>
    <td>Adds an item to the scoreboard through the function based API. The item is inserted in a specific queue based on the arguments passed to the function. </td>
  </tr>
  <tr>
    <td>cl_syoscb#get_subscriber</td>
    <td>Gets a handle to a cl_syoscb_subscriber for a given queue/producer combination.
    Items written to this subscriber are added to the specified queue, tagged with the specified producer. </td>
  </tr>
  <tr>
    <td>cl_syoscb#add_item_mutexed</td>
    <td>Adds an item to the scoreboard, but acquires a mutex before doing so, ensuring that at most one insertion is ever taking place at once. Can only be used if cl_syoscb_cfg#mutexed_add_item_enable is set.</td>
  </tr>
  <tr>
    <td>cl_syoscb#flush_queues</td>
    <td>Flushes one or all queues of the scoreboard </td>
  </tr>
</table>

@section sWrapperAPI Scoreboard Wrapper API

The scoreboard wrapper API is primarily used to easily manage and configure multiple identical scoreboards inside of a wrapper. The API is similar to the one presented for scoreboards, but may affect all scoreboards at the same time.

The wrapper API does not support adding items directly via the function based API.
Instead, filter transforms are connected to agents as described in \ref sMultipleSCBintances, or a handle to specific scoreboard may be extracted.

<b>Classes implementing this API</b>
-# cl_syoscbs_base
-# cl_syoscbs

<b> Selected methods </b>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscbs#get_scb</td>
    <td>Gets a handle to the scoreboard with index <i>i</i>. </td>
  </tr>
  <tr>
    <td>cl_syoscbs#get_filter_trfm_base</td>
    <td>Gets a filter transform component used to transform inputs to a specific queue from a specific producer. </td>
  </tr>
  <tr>
    <td>cl_syoscb#flush_queues_all</td>
    <td>Flushes all queues in all scoreboards at the same time</td>
  </tr>
</table>


@section sCompareStrategyAPI Compare Strategy API

The compare strategy API shall be used as a baseline in case custom comparisons must be implemented.
By leveraging the compare strategy API, custom compare strategies should be interoperable with the compare strategies shipped with the SyoSil UVM Scoreboard.

<b> Classes implementing this API </b>
-# cl_syoscb_compare_base
-# cl_syoscb_compare_io
-# cl_syoscb_compare_iop
-# cl_syoscb_compare_io_2hp
-# cl_syoscb_compare_ooo

<b> Selected methods </b>
<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>cl_syoscb_compare_base#primary_loop_do</td>
    <td>A loop over the primary queue, selecting the item which should be found in all secondary queues</td>
  </tr>
  <tr>
    <td>cl_syoscb_compare_base#secondary_loop_do</td>
    <td>A loop over all secondary queues, attempting to find the same item as was selected from the primary queue. The manner of looping and which items are considered is defined by the compare strategy</td>
  </tr>
  <tr>
    <td>cl_syoscb_compare_base#compare_do_greed</td>
    <td>Initiates a comparison at the desired greed level. The scoreboard supports greedy comparisons (perform comparisons until a match is no longer found), or non-greedy comparisons (only perform 1 comparison whenever triggered, no matter if the comparison was successful or not)</td>
  </tr>
</table>