queues.md

@page pQueueImplementationNotes Queue implementation notes

The queues are used to store the items that needs to be compared.
It is possible to select the maximum number of items you can store before
obtaining an error by modifying the value of cl_syoscb_cfg.max_queue_size.

The scoreboard provides two different queue topologies. Standard queues, which are based on SV queues,
and hash queues, which use an associative array to store items.
In the following figure it is possible to see the format of the two different types of queues.

\image html queues.png width=50%
\image latex queues.pdf

The hash queue shows that multiple sequence items may be associated with the same hash value. This is a rare occurrence, and should almost never happen. In the cases where it does happen, the scoreboard tracks all items with matching hash values, ensuring that no sequence items are lost in case of a hash collision.

The two types of queues are further described in the table below:

<table>
 <tr>
   <th>Queue type</th>
   <th>Description</th>
 </tr>
 <tr>
   <td>cl_syoscb_queue_std</td>
   <td>SystemVerilog queue. New items are added at the end of the queue. </td>
 </tr>
 <tr>
   <td>cl_syoscb_queue_hash</td>
   <td>Associative array. Items are stored as key-value pairs, using the hash values of the packed item (using \c object.pack())
   as the key. The value is a SV queue storing all items with that hash value. The queue is used
   to handle the very rare cases where two seq. items have the same hash value.</td>
 </tr>
 </table>

Hash queues do not by themselves preserve insertion order. To do so, such that hash queues can be iterated in the same order as standard queues, the configuration knob cl_syoscb_cfg.ordered_next must be enabled.
- Configuration knob set to 1: Guarantees the order of insertions by maintaining some metadata.
  This ensures that when using an iterator and traversing the queue with the iterator's \c next method, items are returned in the same order as they were inserted.
  The OOO compare with hashed queues take a minor performance hit when this is enabled.

- Configuration knob set to 0: Uses the SystemVerilog implementation of the \c next
  method for associative arrays. This does not guarantee the iteration order to be the order that items were inserted in.
  For OOO compares using hash queues, this is the option which makes the OOO compare perform at its maximum.

The advantage of using hash queue can be seen when using OOO comparisons. To check if an element is in a queue or not, all that is required is to check if the hash value is in the associative array. This operation runs in <b>O(1)</b> time. Using the SystemVerilog queue, checking if an item is present runs in <b>O(n)</b> time, where n is the number of items in the queue.

In the following graph, the time needed to finish the comparison using out of order compare is shown for the standard queue vs. the MD5 hash queue. It is obvious that hash queues are much better suited for large queues when using OOO comparisons than standard queues.

\image html benchmark.png width=50%
\image latex benchmark.png