# Objection Mechanism

The following classes define the objection mechanism and end-of-test functionality, which is based on uvm_objection.

Contents

Objection Mechanism | The following classes define the objection mechanism and end-of-test functionality, which is based on uvm_objection.
uvm_objection | Objections provide a facility for coordinating status information between two or more participating components, objects, and even module-based IP.
uvm_objection_callback | The uvm_objection is the callback type that defines the callback implementations for an objection callback.

## uvm_objection

Objections provide a facility for coordinating status information between two or more participating components, objects, and even module-based IP.

Tracing of objection activity can be turned on to follow the activity of the objection mechanism. It may be turned on for a specific objection instance with uvm_objection::trace_mode, or it can be set for all objections from the command line using the option +UVM_OBJECTION_TRACE.

Summary

uvm_objection
Objections provide a facility for coordinating status information between two or more participating components, objects, and even module-based IP.
Class Hierarchy
uvm_void
uvm_object
uvm_report_object
uvm_objection
Class Declaration
> class uvm_objection extends uvm_report_object
new | Creates a new objection instance.
trace_mode | Set or get the trace mode for the objection object.
Objection Control |
set_propagate_mode | Sets the propagation mode for this objection.
get_propagate_mode | Returns the propagation mode for this objection.
raise_objection | Raises the number of objections for the source object by count, which defaults to 1.
drop_objection | Drops the number of objections for the source object by count, which defaults to 1.
clear | Immediately clears the objection state.
set_drain_time | Sets the drain time on the given object to drain.
Callback Hooks |
raised | Objection callback that is called when a raise_objection has reached obj.
dropped | Objection callback that is called when a drop_objection has reached obj.
all_dropped | Objection callback that is called when a drop_objection has reached obj, and the total count for obj goes to zero.
Objection Status |
get_objectors | Returns the current list of objecting objects (objects that raised an objection but have not dropped it).
wait_for | Waits for the raised, dropped, or all_dropped event to occur in the given obj.
get_objection_count | Returns the current number of objections raised by the given object.
get_objection_total | Returns the current number of objections raised by the given object and all descendants.
get_drain_time | Returns the current drain time set for the given object (default: 0 ns).
display_objections | Displays objection information about the given object.

### new

> function new(
> | string | name | = | ""
> )

Creates a new objection instance. Accesses the command line argument +UVM_OBJECTION_TRACE to turn tracing on for all objection objects.

### trace_mode

> function bit trace_mode (
> | int | mode | = | -1
> )

Set or get the trace mode for the objection object. If no argument is specified (or an argument other than 0 or 1) the current trace mode is unaffected. A trace_mode of 0 turns tracing off. A trace mode of 1 turns tracing on. The return value is the mode prior to being reset.

### Objection Control

### set_propagate_mode

> function void set_propagate_mode (
> | bit | prop_mode
> )

Sets the propagation mode for this objection.

By default, objections support hierarchical propagation for components. For example, if we have the following basic component tree:

>     uvm_top.parent.child

Any objections raised by ‘child’ would get propagated down to parent, and then to uvm_test_top. Resulting in the following counts and totals:

>                          | count | total |
>     uvm_top.parent.child |     1 |    1  |
>     uvm_top.parent       |     0 |    1  |
>     uvm_top              |     0 |    1  |

While propagations such as these can be useful, if they are unused by the testbench then they are simply an unnecessary performance hit. If the testbench is not going to use this functionality, then the performance can be improved by setting the propagation mode to 0.

When propagation mode is set to 0, all intermediate callbacks between the source and top will be skipped. This would result in the following counts and totals for the above objection:

>                          | count | total |
>     uvm_top.parent.child |     1 |    1  |
>     uvm_top.parent       |     0 |    0  |
>     uvm_top              |     0 |    1  |

Since the propagation mode changes the behavior of the objection, it can only be safely changed if there are no objections raised or draining. Any attempts to change the mode while objections are raised or draining will result in an error.

### get_propagate_mode

> function bit get_propagate_mode()

Returns the propagation mode for this objection.

### raise_objection

> virtual function void raise_objection (
> | uvm_object | obj | = | null,
> | string | description | = | "",
> | int | count | = | 1
> )

Raises the number of objections for the source object by count, which defaults to 1. The object is usually the this handle of the caller. If object is not specified or null, the implicit top-level component, uvm_root, is chosen.

Raising an objection causes the following.

- The source and total objection counts for object are increased by count. description is a string that marks a specific objection and is used in tracing/debug.
- The objection’s raised virtual method is called, which calls the uvm_component::raised method for all of the components up the hierarchy.

### drop_objection

> virtual function void drop_objection (
> | uvm_object | obj | = | null,
> | string | description | = | "",
> | int | count | = | 1
> )

Drops the number of objections for the source object by count, which defaults to 1. The object is usually the this handle of the caller. If object is not specified or null, the implicit top-level component, uvm_root, is chosen.

Dropping an objection causes the following.

- The source and total objection counts for object are decreased by count. It is an error to drop the objection count for object below zero.
- The objection’s dropped virtual method is called, which calls the uvm_component::dropped method for all of the components up the hierarchy.
- If the total objection count has not reached zero for object, then the drop is propagated up the object hierarchy as with raise_objection. Then, each object in the hierarchy will have updated their source counts--objections that they originated--and total counts--the total number of objections by them and all their descendants.

If the total objection count reaches zero, propagation up the hierarchy is deferred until a configurable drain-time has passed and the uvm_component::all_dropped callback for the current hierarchy level has returned. The following process occurs for each instance up the hierarchy from the source caller:

A process is forked in a non-blocking fashion, allowing the drop call to return. The forked process then does the following:

- If a drain time was set for the given object, the process waits for that amount of time.
- The objection’s all_dropped virtual method is called, which calls the uvm_component::all_dropped method (if object is a component).
- The process then waits for the all_dropped callback to complete.
- After the drain time has elapsed and all_dropped callback has completed, propagation of the dropped objection to the parent proceeds as described in raise_objection, except as described below.

If a new objection for this object or any of its descendants is raised during the drain time or during execution of the all_dropped callback at any point, the hierarchical chain described above is terminated and the dropped callback does not go up the hierarchy. The raised objection will propagate up the hierarchy, but the number of raised propagated up is reduced by the number of drops that were pending waiting for the all_dropped/drain time completion. Thus, if exactly one objection caused the count to go to zero, and during the drain exactly one new objection comes in, no raises or drops are propagated up the hierarchy,

As an optimization, if the object has no set drain-time and no registered callbacks, the forked process can be skipped and propagation proceeds immediately to the parent as described.

### clear

> virtual function void clear(
> | uvm_object | obj | = | null
> )

Immediately clears the objection state. All counts are cleared and the any processes waiting on a call to wait_for(UVM_ALL_DROPPED, uvm_top) are released.

The caller, if a uvm_object-based object, should pass its ‘this’ handle to the obj argument to document who cleared the objection. Any drain_times set by the user are not affected.

### set_drain_time

Sets the drain time on the given object to drain.

The drain time is the amount of time to wait once all objections have been dropped before calling the all_dropped callback and propagating the objection to the parent.

If a new objection for this object or any of its descendants is raised during the drain time or during execution of the all_dropped callbacks, the drain_time/all_dropped execution is terminated.

### Callback Hooks

### raised

> virtual function void raised (
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection callback that is called when a raise_objection has reached obj. The default implementation calls uvm_component::raised.

### dropped

> virtual function void dropped (
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection callback that is called when a drop_objection has reached obj. The default implementation calls uvm_component::dropped.

### all_dropped

> virtual task all_dropped (
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection callback that is called when a drop_objection has reached obj, and the total count for obj goes to zero. This callback is executed after the drain time associated with obj. The default implementation calls uvm_component::all_dropped.

### Objection Status

### get_objectors

> function void get_objectors(
> | ref | uvm_object | list[$]
> )

Returns the current list of objecting objects (objects that raised an objection but have not dropped it).

### wait_for

> task wait_for(
> | uvm_objection_event | objt_event, |  |
> | uvm_object | obj | = | null
> )

Waits for the raised, dropped, or all_dropped event to occur in the given obj. The task returns after all corresponding callbacks for that event have been executed.

### get_objection_count

> function int get_objection_count (
> | uvm_object | obj | = | null
> )

Returns the current number of objections raised by the given object.

### get_objection_total

> function int get_objection_total (
> | uvm_object | obj | = | null
> )

Returns the current number of objections raised by the given object and all descendants.

### get_drain_time

> function time get_drain_time (
> | uvm_object | obj | = | null
> )

Returns the current drain time set for the given object (default: 0 ns).

### display_objections

> function void display_objections(
> | uvm_object | obj | = | null,
> | bit | show_header | = | 1
> )

Displays objection information about the given object. If object is not specified or null, the implicit top-level component, uvm_root, is chosen. The show_header argument allows control of whether a header is output.

## uvm_objection_callback

The uvm_objection is the callback type that defines the callback implementations for an objection callback. A user uses the callback type uvm_objection_cbs_t to add callbacks to specific objections.

#### For example

>     class my_objection_cb extends uvm_objection_callback;
>       function new(string name);
>         super.new(name);
>       endfunction

>       virtual function void raised (uvm_objection objection, uvm_object obj,
>           uvm_object source_obj, string description, int count);
>           `uvm_info("RAISED","%0t: Objection %s: Raised for %s", $time, objection.get_name(),
>           obj.get_full_name());
>       endfunction
>     endclass
>     ...
>     initial begin
>       my_objection_cb cb = new("cb");
>       uvm_objection_cbs_t::add(null, cb); //typewide callback
>     end

Summary

uvm_objection_callback
The uvm_objection is the callback type that defines the callback implementations for an objection callback.
Class Hierarchy
uvm_void
uvm_object
uvm_callback
uvm_objection_callback
Class Declaration
> class uvm_objection_callback extends uvm_callback
Methods |
raised | Objection raised callback function.
dropped | Objection dropped callback function.
all_dropped | Objection all_dropped callback function.

### Methods

### raised

> virtual function void raised (
> | uvm_objection | objection,
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection raised callback function. Called by uvm_objection::raised.

### dropped

> virtual function void dropped (
> | uvm_objection | objection,
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection dropped callback function. Called by uvm_objection::dropped.

### all_dropped

> virtual task all_dropped (
> | uvm_objection | objection,
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection all_dropped callback function. Called by uvm_objection::all_dropped.

> class uvm_objection extends uvm_report_object

Objections provide a facility for coordinating status information between two or more participating components, objects, and even module-based IP.

> class uvm_objection_callback extends uvm_callback

The uvm_objection is the callback type that defines the callback implementations for an objection callback.

> virtual class uvm_void

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.

> class uvm_report_object extends uvm_object

The uvm_report_object provides an interface to the UVM reporting facility.

> function new(
> | string | name | = | ""
> )

Creates a new objection instance.

> function bit trace_mode (
> | int | mode | = | -1
> )

Set or get the trace mode for the objection object.

> function void set_propagate_mode (
> | bit | prop_mode
> )

Sets the propagation mode for this objection.

> function bit get_propagate_mode()

Returns the propagation mode for this objection.

> virtual function void raise_objection (
> | uvm_object | obj | = | null,
> | string | description | = | "",
> | int | count | = | 1
> )

Raises the number of objections for the source object by count, which defaults to 1.

> virtual function void drop_objection (
> | uvm_object | obj | = | null,
> | string | description | = | "",
> | int | count | = | 1
> )

Drops the number of objections for the source object by count, which defaults to 1.

> virtual function void clear(
> | uvm_object | obj | = | null
> )

Immediately clears the objection state.

> virtual function void raised (
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection callback that is called when a raise_objection has reached obj.

> virtual function void dropped (
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection callback that is called when a drop_objection has reached obj.

> virtual task all_dropped (
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection callback that is called when a drop_objection has reached obj, and the total count for obj goes to zero.

> function void get_objectors(
> | ref | uvm_object | list[$]
> )

Returns the current list of objecting objects (objects that raised an objection but have not dropped it).

> task wait_for(
> | uvm_objection_event | objt_event, |  |
> | uvm_object | obj | = | null
> )

Waits for the raised, dropped, or all_dropped event to occur in the given obj.

> function int get_objection_count (
> | uvm_object | obj | = | null
> )

Returns the current number of objections raised by the given object.

> function int get_objection_total (
> | uvm_object | obj | = | null
> )

Returns the current number of objections raised by the given object and all descendants.

> function time get_drain_time (
> | uvm_object | obj | = | null
> )

Returns the current drain time set for the given object (default: 0 ns).

> function void display_objections(
> | uvm_object | obj | = | null,
> | bit | show_header | = | 1
> )

Displays objection information about the given object.
The uvm_root class serves as the implicit top-level and phase controller for all UVM components.

> virtual function void raised (
> | uvm_objection | objection,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

The raised callback is called when this or a descendant of this component instance raises the specified objection.

> virtual function void dropped (
> | uvm_objection | objection,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

The dropped callback is called when this or a descendant of this component instance drops the specified objection.

> virtual task all_dropped (
> | uvm_objection | objection,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

The all_droppped callback is called when all objections have been dropped by this component and all its descendants.

> class uvm_callback extends uvm_object

The uvm_callback class is the base class for user-defined callback classes.

> virtual function void raised (
> | uvm_objection | objection,
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection raised callback function.

> virtual function void dropped (
> | uvm_objection | objection,
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection dropped callback function.

> virtual task all_dropped (
> | uvm_objection | objection,
> | uvm_object | obj,
> | uvm_object | source_obj,
> | string | description,
> | int | count
> )

Objection all_dropped callback function.