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 API are OK to call from user code. The only exception to this rule is methods labeled with Compare Strategy API. 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 Compare Strategy API 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 API 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.

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 build_phase, setting configuration values before starting simulation.

Classes implementing this API

1. cl_syoscb_cfg
2. cl_syoscbs_cfg

Selected methods

See 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.

Compare API

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

Classes implementing this API

1. cl_syoscb_compare
2. cl_syoscb_compare_base
3. cl_syoscb_compare_io
4. cl_syoscb_compare_iop
5. cl_syoscb_compare_io_2hp
6. cl_syoscb_compare_ooo

Selected methods

Name	Description
cl_syoscb_compare_base::compare_trigger	Initiates a comparison when an item has been inserted. If cl_syoscb_compare_base.disable_compare is set, the comparison is not performed
cl_syoscb_compare_base::compare_main	Initiates a comparison, bypassing the check of disable_compare
cl_syoscb_compare_base::compare_control	Disable or enable comparisons by calling this method

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.

Classes implementing this API

1. cl_syoscb_queue_base
2. cl_syoscb_queue_std
3. cl_syoscb_queue_hash
4. cl_syoscb_queue_hash_md5

Selected methods

Name	Description
cl_syoscb_queue_base::add_item	Adds an item to the queue, placing it at the end of the queue.
cl_syoscb_queue_base::insert_item	Inserts an item at a specified index instead of placing it at the end of the queue.
cl_syoscb_queue_base::flush_queue	Flushes the queue, removing all items that previously occupied the queue
cl_syoscb_queue_base::create_iterator	Creates an iterator over this queue. See Iterator API for information on how iterators are used to traverse queues.
cl_syoscb_queue_base::get_item	Takes a proxy item as input, and uses this proxy item to return a specific item from the queue

Hash API

The hash API is used by hash algorithms to hash sequence items for use in hash queues.

Classes implementing this API

1. cl_syoscb_hash_base
2. cl_syoscb_hash_md5

Selected methods

Name	Description
cl_syoscb_hash_base::hash	Hashes a cl_syoscb_item using the specified hash algorithm, returning the bitstream representing that hash
cl_syoscb_hash_base::hash_str	Hashes a string using the specified hash algorithm
cl_syoscb_hash_base::do_hash	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

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.

Classes implementing this API

1. cl_syoscb_item
   • Wraps a uvm_sequence_item generated by the DUT or a reference model with additional metadata used for comparisons.
2. cl_syoscb_hash_item
   • Used in hash queues to ensure that hash collisions, although unlikely, do not overwrite items in the underlying datastructure.
3. 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.

Selected methods

Name	Description
cl_syoscb_item::get_item	Gets the uvm_sequence_item wrapped by this scoreboard item
cl_syoscb_hash_item::get_item	Gets the first of possibly multiple items that have the same hash
cl_syoscb_proxy_item_base::get_item	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 Queue API)

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:

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

Classes implementing this API

1. cl_syoscb_queue_iterator_base
2. cl_syoscb_queue_iterator_std
3. cl_syoscb_queue_iterator_hash
4. cl_syoscb_queue_iterator_hash_md5

Selected methods

Name	Description
cl_syoscb_queue_iterator_base::next	Moves the iterator one item forward
cl_syoscb_queue_iterator_base::get_item_proxy	Gets a cl_syoscb_proxy_item_base representing the item that the iterator currently points to
cl_syoscb_queue_iterator_base::is_done	Checks whether the iterator has reached the end of the queue.

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.

Classes implementing this API

1. cl_syoscb_queue_locator_base
2. cl_syoscb_queue_locator_std
3. cl_syoscb_queue_locator_hash
4. cl_syoscb_queue_locator_hash_md5

Selected methods

Name	Description
cl_syoscb_queue_locator_base::search	Searches the underlying queue for an item which matches the argument.
cl_syoscb_queue_locator_base::get_queue	Gets a handle to the queue that this locator is operating on
cl_syoscb_queue_locator_base::set_queue	Sets the queue over which a locator should operate

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.

Classes implementing this API

1. cl_syoscb

Selected methods

Name	Description
cl_syoscb::add_item	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.
cl_syoscb::get_subscriber	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.
cl_syoscb::add_item_mutexed	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.
cl_syoscb::flush_queues	Flushes one or all queues of the scoreboard

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 Multiple SCB instances & filter transforms, or a handle to specific scoreboard may be extracted.

Classes implementing this API

1. cl_syoscbs_base
2. cl_syoscbs

Selected methods

Name	Description
cl_syoscbs::get_scb	Gets a handle to the scoreboard with index i.
cl_syoscbs::get_filter_trfm_base	Gets a filter transform component used to transform inputs to a specific queue from a specific producer.
cl_syoscb::flush_queues_all	Flushes all queues in all scoreboards at the same time

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.

Classes implementing this API

1. cl_syoscb_compare_base
2. cl_syoscb_compare_io
3. cl_syoscb_compare_iop
4. cl_syoscb_compare_io_2hp
5. cl_syoscb_compare_ooo

Selected methods

Name	Description
cl_syoscb_compare_base::primary_loop_do	A loop over the primary queue, selecting the item which should be found in all secondary queues
cl_syoscb_compare_base::secondary_loop_do	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
cl_syoscb_compare_base::compare_do_greed	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)