Callbacks Classes

This section defines the classes used for callback registration, management, and user-defined callbacks.

Contents
Callbacks ClassesThis section defines the classes used for callback registration, management, and user-defined callbacks.
uvm_callbacks #(T,CB)The uvm_callbacks class provides a base class for implementing callbacks, which are typically used to modify or augment component behavior without changing the component class.
uvm_callback_iterThe uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type.
uvm_callbackThe uvm_callback class is the base class for user-defined callback classes.

uvm_callbacks #(T,CB)

The uvm_callbacks class provides a base class for implementing callbacks, which are typically used to modify or augment component behavior without changing the component class.  To work effectively, the developer of the component class defines a set of “hook” methods that enable users to customize certain behaviors of the component in a manner that is controlled by the component developer.  The integrity of the component’s overall behavior is intact, while still allowing certain customizable actions by the user.

To enable compile-time type-safety, the class is parameterized on both the user-defined callback interface implementation as well as the object type associated with the callback.  The object type-callback type pair are associated together using the `uvm_register_cb macro to define a valid pairing; valid pairings are checked when a user attempts to add a callback to an object.

To provide the most flexibility for end-user customization and reuse, it is recommended that the component developer also define a corresponding set of virtual method hooks in the component itself.  This affords users the ability to customize via inheritance/factory overrides as well as callback object registration.  The implementation of each virtual method would provide the default traversal algorithm for the particular callback being called.  Being virtual, users can define subtypes that override the default algorithm, perform tasks before and/or after calling super.<method> to execute any registered callbacks, or to not call the base implementation, effectively disabling that particalar hook.  A demonstration of this methodology is provided in an example included in the kit.

Summary
uvm_callbacks #(T,CB)
The uvm_callbacks class provides a base class for implementing callbacks, which are typically used to modify or augment component behavior without changing the component class.
TThis type parameter specifies the base object type with which the CB callback objects will be registered.
CBThis type parameter specifies the base callback type that will be managed by this callback class.
Add/ delete inteface
addRegisters the given callback object, cb, with the given obj handle.
add_by_nameRegisters the given callback object, cb, with one or more uvm_components.
deleteDeletes the given callback object, cb, from the queue associated with the given obj handle.
delete_by_nameRemoves the given callback object, cb, associated with one or more uvm_component callback queues.
Iterator interfaceThis set of functions provide an iterator interface for callback queues.
get_firstreturns the first enabled callback of type CB which resides in the queue for obj.
get_lastreturns the last enabled callback of type CB which resides in the queue for obj.
get_nextreturns the next enabled callback of type CB which resides in the queue for obj, using itr as the starting point.
get_prevreturns the previous enabled callback of type CB which resides in the queue for obj, using itr as the starting point.
Debug
displayThis function displays callback information for obj.

T

This type parameter specifies the base object type with which the CB callback objects will be registered.  This object must be a derivative of uvm_object.

CB

This type parameter specifies the base callback type that will be managed by this callback class.  The callback type is typically a interface class, which defines one or more virtual method prototypes that users can override in subtypes.  This type must be a derivative of uvm_callback.

add

static function void add( obj,   
uvm_callback  cb,   
uvm_apprepend  ordering  =  UVM_APPEND )

Registers the given callback object, cb, with the given obj handle.  The obj handle can be null, which allows registration of callbacks without an object context.  If ordreing is UVM_APPEND (default), the callback will be executed after previously added callbacks, else the callback will be executed ahead of previously added callbacks.  The cb is the callback handle; it must be non-null, and if the callback has already been added to the object instance then a warning is issued.  Note that the CB parameter is optional.  For example, the following are equivalent:

uvm_callbacks#(my_comp)::add(comp_a, cb);
uvm_callbacks#(my_comp, my_callback)::add(comp_a,cb);

add_by_name

static function void add_by_name( string  name,   
uvm_callback  cb,   
uvm_component  root,   
uvm_apprepend  ordering  =  UVM_APPEND )

Registers the given callback object, cb, with one or more uvm_components.  The components must already exist and must be type T or a derivative.  As with add the CB parameter is optional.  root specifies the location in the component hierarchy to start the search for name.  See uvm_root::find_all for more details on searching by name.

delete

static function void delete( obj,
uvm_callback  cb )

Deletes the given callback object, cb, from the queue associated with the given obj handle.  The obj handle can be null, which allows de-registration of callbacks without an object context.  The cb is the callback handle; it must be non-null, and if the callback has already been removed from the object instance then a warning is issued.  Note that the CB parameter is optional.  For example, the following are equivalent:

uvm_callbacks#(my_comp)::delete(comp_a, cb);
uvm_callbacks#(my_comp, my_callback)::delete(comp_a,cb);

delete_by_name

static function void delete_by_name( string  name,
uvm_callback  cb,
uvm_component  root )

Removes the given callback object, cb, associated with one or more uvm_component callback queues.  As with delete the CB parameter is optional.  root specifies the location in the component hierarchy to start the search for name.  See uvm_root::find_all for more details on searching by name.

Iterator interface

This set of functions provide an iterator interface for callback queues.  A facade class, uvm_callback_iter is also available, and is the generally preferred way to iterate over callback queues.

get_first

static function CB get_first ( ref  int  itr,
input  obj )

returns the first enabled callback of type CB which resides in the queue for obj.  If obj is null then the typewide queue for T is searched.  itr is the iterator; it will be updated with a value that can be supplied to get_next to get the next callback object.

If the queue is empty then null is returned.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

get_last

static function CB get_last ( ref  int  itr,
input  obj )

returns the last enabled callback of type CB which resides in the queue for obj.  If obj is null then the typewide queue for T is searched.  itr is the iterator; it will be updated with a value that can be supplied to get_prev to get the previous callback object.

If the queue is empty then null is returned.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

get_next

static function CB get_next ( ref  int  itr,
input  obj )

returns the next enabled callback of type CB which resides in the queue for obj, using itr as the starting point.  If obj is null then the typewide queue for T is searched.  itr is the iterator; it will be updated with a value that can be supplied to get_next to get the next callback object.

If no more callbacks exist in the queue, then null is returned.  get_next will continue to return null in this case until get_first or get_last has been used to reset the iterator.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

get_prev

static function CB get_prev ( ref  int  itr,
input  obj )

returns the previous enabled callback of type CB which resides in the queue for obj, using itr as the starting point.  If obj is null then the typewide queue for T is searched.  itr is the iterator; it will be updated with a value that can be supplied to get_prev to get the previous callback object.

If no more callbacks exist in the queue, then null is returned.  get_prev will continue to return null in this case until get_first or get_last has been used to reset the iterator.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

display

static function void display( obj  =  null )

This function displays callback information for obj.  If obj is null, then it displays callback information for all objects of type T, including typewide callbacks.

uvm_callback_iter

The uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type.  The typical usage of the class is:

uvm_callback_iter#(mycomp,mycb) iter = new(this);
for(mycb cb = iter.first(); cb != null; cb = iter.next())
   cb.dosomething();

The callback iteration macros, `uvm_do_callbacks and `uvm_do_callbacks_exit_on provide a simple method for iterating callbacks and executing the callback methods.

Summary
uvm_callback_iter
The uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type.
Class Declaration
class uvm_callback_iter#( type  T  =  uvm_object,
type  CB  =  uvm_callback )
Methods
newCreates a new callback iterator object.
firstReturns the first valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
lastReturns the last valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
nextReturns the next valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
prevReturns the previous valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
get_cbReturns the last callback accessed via a first() or next() call.

new

function new( obj )

Creates a new callback iterator object.  It is required that the object context be provided.

first

function CB first()

Returns the first valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.  If the queue is empty then null is returned.

last

function CB last()

Returns the last valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.  If the queue is empty then null is returned.

next

function CB next()

Returns the next valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.  If there are no more valid callbacks in the queue, then null is returned.

prev

function CB prev()

Returns the previous valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.  If there are no more valid callbacks in the queue, then null is returned.

get_cb

function CB get_cb()

Returns the last callback accessed via a first() or next() call.

uvm_callback

The uvm_callback class is the base class for user-defined callback classes.  Typically, the component developer defines an application-specific callback class that extends from this class.  In it, he defines one or more virtual methods, called a callback interface, that represent the hooks available for user override.

Methods intended for optional override should not be declared pure.  Usually, all the callback methods are defined with empty implementations so users have the option of overriding any or all of them.

The prototypes for each hook method are completely application specific with no restrictions.

Summary
uvm_callback
The uvm_callback class is the base class for user-defined callback classes.
Class Hierarchy
uvm_callback
Class Declaration
class uvm_callback extends uvm_object
Methods
newCreates a new uvm_callback object, giving it an optional name.
callback_modeEnable/disable callbacks (modeled like rand_mode and constraint_mode).
is_enabledReturns 1 if the callback is enabled, 0 otherwise.
get_type_nameReturns the type name of this callback object.

new

function new( string  name  =  "uvm_callback" )

Creates a new uvm_callback object, giving it an optional name.

callback_mode

function bit callback_mode( int  on  =  -1 )

Enable/disable callbacks (modeled like rand_mode and constraint_mode).

is_enabled

function bit is_enabled()

Returns 1 if the callback is enabled, 0 otherwise.

get_type_name

virtual function string get_type_name()

Returns the type name of this callback object.

class uvm_callback_iter#( type  T  =  uvm_object,
type  CB  =  uvm_callback )
The uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type.
class uvm_callback extends uvm_object
The uvm_callback class is the base class for user-defined callback classes.
This type parameter specifies the base callback type that will be managed by this callback class.
static function void add( obj,   
uvm_callback  cb,   
uvm_apprepend  ordering  =  UVM_APPEND )
Registers the given callback object, cb, with the given obj handle.
static function void add_by_name( string  name,   
uvm_callback  cb,   
uvm_component  root,   
uvm_apprepend  ordering  =  UVM_APPEND )
Registers the given callback object, cb, with one or more uvm_components.
static function void delete( obj,
uvm_callback  cb )
Deletes the given callback object, cb, from the queue associated with the given obj handle.
static function void delete_by_name( string  name,
uvm_callback  cb,
uvm_component  root )
Removes the given callback object, cb, associated with one or more uvm_component callback queues.
static function CB get_first ( ref  int  itr,
input  obj )
returns the first enabled callback of type CB which resides in the queue for obj.
static function CB get_last ( ref  int  itr,
input  obj )
returns the last enabled callback of type CB which resides in the queue for obj.
static function CB get_next ( ref  int  itr,
input  obj )
returns the next enabled callback of type CB which resides in the queue for obj, using itr as the starting point.
static function CB get_prev ( ref  int  itr,
input  obj )
returns the previous enabled callback of type CB which resides in the queue for obj, using itr as the starting point.
static function void display( obj  =  null )
This function displays callback information for obj.
function void find_all ( string  comp_match,   
ref  uvm_component  comps[$],   
input  uvm_component  comp  =  null )
Returns the component handle (find) or list of components handles (find_all) matching a given string.
function new( obj )
Creates a new callback iterator object.
function CB first()
Returns the first valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
function CB last()
Returns the last valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
function CB next()
Returns the next valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
function CB prev()
Returns the previous valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
function CB get_cb()
Returns the last callback accessed via a first() or next() call.
The uvm_void class is the base class for all UVM classes.
virtual class uvm_object extends uvm_void
The uvm_object class is the base class for all UVM data and hierarchical classes.
function new( string  name  =  "uvm_callback" )
Creates a new uvm_callback object, giving it an optional name.
function bit callback_mode( int  on  =  -1 )
Enable/disable callbacks (modeled like rand_mode and constraint_mode).
function bit is_enabled()
Returns 1 if the callback is enabled, 0 otherwise.
virtual function string get_type_name()
Returns the type name of this callback object.