uvm_component

Creates a new component with the given leaf instance name and handle to its parent.  If the component is a top-level component (i.e. it is created in a static module or interface), parent should be null.

The component will be inserted as a child of the parent object, if any.  If parent already has a child by the given name, an error is produced.

If parent is null, then the component will become a child of the implicit top-level component, uvm_top.

All classes derived from uvm_component must call super.new(name,parent).

Returns a handle to this component’s parent, or null if it has no parent.

Returns the full hierarchical name of this object.  The default implementation concatenates the hierarchical name of the parent, if any, with the leaf name of this object, as given by uvm_object::get_name.

This function populates the end of the children array with the list of this component’s children.

uvm_component array[$];
my_comp.get_children(array);
foreach(array[i])
  do_something(array[i]);

These methods are used to iterate through this component’s children, if any.  For example, given a component with an object handle, comp, the following code calls uvm_object::print for each child:

string name;
uvm_component child;
if (comp.get_first_child(name))
  do begin
    child = comp.get_child(name);
    child.print();
  end while (comp.get_next_child(name));

Returns the number of this component’s children.

Returns 1 if this component has a child with the given name, 0 otherwise.

Looks for a component with the given hierarchical name relative to this component.  If the given name is preceded with a ‘.’  (dot), then the search begins relative to the top level (absolute lookup).  The handle of the matching component is returned, else null.  The name must not contain wildcards.

Returns the component’s depth from the root level. uvm_top has a depth of 0.  The test and any other top level components have a depth of 1, and so on.

The uvm_build_phase phase implementation method.

Any override should call super.build_phase(phase) to execute the automatic configuration of fields registered in the component by calling apply_config_settings.  To turn off automatic configuration for a component, do not call super.build_phase(phase).

This method should never be called directly.

The uvm_connect_phase phase implementation method.

This method should never be called directly.

The uvm_end_of_elaboration_phase phase implementation method.

This method should never be called directly.

The uvm_start_of_simulation_phase phase implementation method.

This method should never be called directly.

The <uvm_run_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  Thus the phase will automatically end once all objections are dropped using phase.drop_objection().

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

The run_phase task should never be called directly.

The <uvm_pre_reset_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_reset_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_post_reset_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_pre_configure_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_configure_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_post_configure_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_pre_main_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_main_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_post_main_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_pre_shutdown_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_shutdown_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_post_shutdown_phase> phase implementation method.

This task returning or not does not indicate the end or persistence of this phase.  It is necessary to raise an objection using phase.raise_objection() to cause the phase to persist.  Once all components have dropped their respective objection using phase.drop_objection(), or if no components raises an objection, the phase is ended.

Any processes forked by this task continue to run after the task returns, but they will be killed once the phase ends.

This method should not be called directly.

The <uvm_extract_phase> phase implementation method.

This method should never be called directly.

The <uvm_check_phase> phase implementation method.

This method should never be called directly.

The <uvm_report_phase> phase implementation method.

This method should never be called directly.

The uvm_final_phase phase implementation method.

This method should never be called directly.

Invoked at the start of each phase.  The phase argument specifies the phase being started.  Any threads spawned in this callback are not affected when the phase ends.

Invoked when all objections to ending the given phase and all sibling phases have been dropped, thus indicating that phase is ready to begin a clean exit.  Sibling phases are any phases that have a common successor phase in the schedule plus any phases that sync’d to the current phase.  Components needing to consume delta cycles or advance time to perform a clean exit from the phase may raise the phase’s objection.

phase.raise_objection(this,"Reason");

It is the responsibility of this component to drop the objection once it is ready for this phase to end (and processes killed).  If no objection to the given phase or sibling phases are raised, then phase_ended() is called after a delta cycle.  If any objection is raised, then when all objections to ending the given phase and siblings are dropped, another iteration of phase_ready_to_end is called.  To prevent endless iterations due to coding error, after 20 iterations, phase_ended() is called regardless of whether previous iteration had any objections raised.

Invoked at the end of each phase.  The phase argument specifies the phase that is ending.  Any threads spawned in this callback are not affected when the phase ends.

Apply a phase domain to this component and, if hier is set, recursively to all its children.

Calls the virtual define_domain method, which derived components can override to augment or replace the domain definition of its base class.

Return handle to the phase domain set on this component

Builds custom phase schedules into the provided domain handle.

This method is called by set_domain, which integrators use to specify this component belongs in a domain apart from the default ‘uvm’ domain.

Custom component base classes requiring a custom phasing schedule can augment or replace the domain definition they inherit by overriding their defined_domain.  To augment, overrides would call super.define_domain().  To replace, overrides would not call super.define_domain().

The default implementation adds a copy of the uvm phasing schedule to the given domain, if one doesn’t already exist, and only if the domain is currently empty.

Calling set_domain with the default uvm domain (i.e.  uvm_domain::get_uvm_domain ) on a component with no define_domain override effectively reverts the that component to using the default uvm domain.  This may be useful if a branch of the testbench hierarchy defines a custom domain, but some child sub-branch should remain in the default uvm domain, call set_domain with a new domain instance handle with hier set.  Then, in the sub-branch, call set_domain with the default uvm domain handle, obtained via uvm_domain::get_uvm_domain.

Alternatively, the integrator may define the graph in a new domain externally, then call set_domain to apply it to a component.

Override the default implementation for a phase on this component (tree) with a custom one, which must be created as a singleton object extending the default one and implementing required behavior in exec and traverse methods

The hier specifies whether to apply the custom functor to the whole tree or just this component.

Suspend this component.

This method must be implemented by the user to suspend the component according to the protocol and functionality it implements.  A suspended component can be subsequently resumed using resume().

Resume this component.

This method must be implemented by the user to resume a component that was previously suspended using suspend().  Some component may start in the suspended state and may need to be explicitly resumed.

Processes all port, export, and imp connections.  Checks whether each port’s min and max connection requirements are met.

It is called just before the end_of_elaboration phase.

Users should not call directly.

Check all configuration settings in a components configuration table to determine if the setting has been used, overridden or not used.  When recurse is 1 (default), configuration for this and all child components are recursively checked.  This function is automatically called in the check phase, but can be manually called at any time.

To get all configuration information prior to the run phase, do something like this in your top object:

function void start_of_simulation_phase(uvm_phase phase);
  check_config_usage();
endfunction

Searches for all config settings matching this component’s instance path.  For each match, the appropriate set_*_local method is called using the matching config setting’s field_name and value.  Provided the set_*_local method is implemented, the component property associated with the field_name is assigned the given value.

This function is called by uvm_component::build_phase.

The apply_config_settings method determines all the configuration settings targeting this component and calls the appropriate set_*_local method to set each one.  To work, you must override one or more set_*_local methods to accommodate setting of your component’s specific properties.  Any properties registered with the optional `uvm_*_field macros do not require special handling by the set_*_local methods; the macros provide the set_*_local functionality for you.

If you do not want apply_config_settings to be called for a component, then the build_phase() method should be overloaded and you should not call super.build_phase(phase).  Likewise, apply_config_settings can be overloaded to customize automated configuration.

When the verbose bit is set, all overrides are printed as they are applied.  If the component’s print_config_matches property is set, then apply_config_settings is automatically called with verbose = 1.

Returns 1 if the component should call apply_config_settings in the build_phase; otherwise, returns 0.

Called without arguments, print_config_settings prints all configuration information for this component, as set by previous calls to <uvm_config_db::set()>.  The settings are printing in the order of their precedence.

If field is specified and non-empty, then only configuration settings matching that field, if any, are printed.  The field may not contain wildcards.

If comp is specified and non-null, then the configuration for that component is printed.

If recurse is set, then configuration information for all comp’s children and below are printed as well.

This function has been deprecated.  Use print_config instead.

Print_config prints all configuration information for this component, as set by previous calls to <uvm_config_db::set()> and exports to the resources pool.  The settings are printed in the order of their precedence.

If recurse is set, then configuration information for all children and below are printed as well.

if audit is set then the audit trail for each resource is printed along with the resource name and value

@uvm-accellera The details of this API are specific to the Accellera implementation, and are not being considered for contribution to 1800.2

Operates the same as print_config except that the audit bit is forced to 1.  This interface makes user code a bit more readable as it avoids multiple arbitrary bit settings in the argument list.

If recurse is set, then configuration information for all children and below are printed as well.

The raised callback is called when this or a descendant of this component instance raises the specified objection.  The source_obj is the object that originally raised the objection.  The description is optionally provided by the source_obj to give a reason for raising the objection.  The count indicates the number of objections raised by the source_obj.

The dropped callback is called when this or a descendant of this component instance drops the specified objection.  The source_obj is the object that originally dropped the objection.  The description is optionally provided by the source_obj to give a reason for dropping the objection.  The count indicates the number of objections dropped by the source_obj.

The all_droppped callback is called when all objections have been dropped by this component and all its descendants.  The source_obj is the object that dropped the last objection.  The description is optionally provided by the source_obj to give a reason for raising the objection.  The count indicates the number of objections dropped by the source_obj.

A convenience function for <uvm_factory::create_component_by_name>, this method calls upon the factory to create a new child component whose type corresponds to the preregistered type name, requested_type_name, and instance name, name.  This method is equivalent to:

factory.create_component_by_name(requested_type_name,
                                 get_full_name(), name, this);

If the factory determines that a type or instance override exists, the type of the component created may be different than the requested type.  See set_type_override and set_inst_override.  See also uvm_factory for details on factory operation.

A convenience function for uvm_factory::create_object_by_name, this method calls upon the factory to create a new object whose type corresponds to the preregistered type name, requested_type_name, and instance name, name.  This method is equivalent to:

factory.create_object_by_name(requested_type_name,
                              get_full_name(), name);

If the factory determines that a type or instance override exists, the type of the object created may be different than the requested type.  See uvm_factory for details on factory operation.

A convenience function for uvm_factory::set_type_override_by_type, this method registers a factory override for components and objects created at this level of hierarchy or below.  This method is equivalent to:

factory.set_type_override_by_type(original_type, override_type,replace);

The relative_inst_path is relative to this component and may include wildcards.  The original_type represents the type that is being overridden.  In subsequent calls to uvm_factory::create_object_by_type or uvm_factory::create_component_by_type, if the requested_type matches the original_type and the instance paths match, the factory will produce the override_type.

The original and override type arguments are lightweight proxies to the types they represent.  See set_inst_override_by_type for information on usage.

A convenience function for uvm_factory::set_inst_override_by_type, this method registers a factory override for components and objects created at this level of hierarchy or below.  In typical usage, this method is equivalent to:

factory.set_inst_override_by_type( original_type,
                                   override_type,
                                   {get_full_name(),".",
                                    relative_inst_path});

The relative_inst_path is relative to this component and may include wildcards.  The original_type represents the type that is being overridden.  In subsequent calls to uvm_factory::create_object_by_type or uvm_factory::create_component_by_type, if the requested_type matches the original_type and the instance paths match, the factory will produce the override_type.

The original and override types are lightweight proxies to the types they represent.  They can be obtained by calling type::get_type(), if implemented by type, or by directly calling type::type_id::get(), where type is the user type and type_id is the name of the typedef to uvm_object_registry #(T,Tname) or uvm_component_registry #(T,Tname).

If you are employing the `uvm_*_utils macros, the typedef and the get_type method will be implemented for you.  For details on the utils macros refer to Utility and Field Macros for Components and Objects.

The following example shows `uvm_*_utils usage

class comp extends uvm_component;
  `uvm_component_utils(comp)
  ...
endclass

class mycomp extends uvm_component;
  `uvm_component_utils(mycomp)
  ...
endclass

class block extends uvm_component;
  `uvm_component_utils(block)
  comp c_inst;
  virtual function void build_phase(uvm_phase phase);
    set_inst_override_by_type("c_inst",comp::get_type(),
                                       mycomp::get_type());
  endfunction
  ...
endclass

A convenience function for uvm_factory::set_type_override_by_name, this method configures the factory to create an object of type override_type_name whenever the factory is asked to produce a type represented by original_type_name.  This method is equivalent to:

factory.set_type_override_by_name(original_type_name,
                                  override_type_name, replace);

The original_type_name typically refers to a preregistered type in the factory.  It may, however, be any arbitrary string.  Subsequent calls to create_component or create_object with the same string and matching instance path will produce the type represented by override_type_name.  The override_type_name must refer to a preregistered type in the factory.

A convenience function for uvm_factory::set_inst_override_by_name, this method registers a factory override for components created at this level of hierarchy or below.  In typical usage, this method is equivalent to:

factory.set_inst_override_by_name(original_type_name,
                                  override_type_name,
                                  {get_full_name(),".",
                                   relative_inst_path}
                                   );

The relative_inst_path is relative to this component and may include wildcards.  The original_type_name typically refers to a preregistered type in the factory.  It may, however, be any arbitrary string.  Subsequent calls to create_component or create_object with the same string and matching instance path will produce the type represented by override_type_name.  The override_type_name must refer to a preregistered type in the factory.

This factory debug method performs the same lookup process as create_object and create_component, but instead of creating an object, it prints information about what type of object would be created given the provided arguments.

These methods recursively associate the specified verbosity with reports of the given severity, id, or severity-id pair.  A verbosity associated with a particular severity-id pair takes precedence over a verbosity associated with id, which takes precedence over a verbosity associated with a severity.

For a list of severities and their default verbosities, refer to uvm_report_handler.

These methods recursively associate the specified action with reports of the given severity, id, or severity-id pair.  An action associated with a particular severity-id pair takes precedence over an action associated with id, which takes precedence over an action associated with a severity.

For a list of severities and their default actions, refer to uvm_report_handler.

These methods recursively associate the specified FILE descriptor with reports of the given severity, id, or severity-id pair.  A FILE associated with a particular severity-id pair takes precedence over a FILE associated with id, which take precedence over an a FILE associated with a severity, which takes precedence over the default FILE descriptor.

For a list of severities and other information related to the report mechanism, refer to uvm_report_handler.

This method recursively sets the maximum verbosity level for reports for this component and all those below it.  Any report from this component subtree whose verbosity exceeds this maximum will be ignored.

See uvm_report_handler for a list of predefined message verbosity levels and their meaning.

This callback is executed when the message system is executing a UVM_EXIT action.  The exit action causes an immediate termination of the simulation, but the pre_abort callback hook gives components an opportunity to provide additional information to the user before the termination happens.  For example, a test may want to executed the report function of a particular component even when an error condition has happened to force a premature termination you would write a function like:

function void mycomponent::pre_abort();
  report();
endfunction

The pre_abort() callback hooks are called in a bottom-up fashion.

This function marks the acceptance of a transaction, tr, by this component.  Specifically, it performs the following actions:

• Calls the tr’s uvm_transaction::accept_tr method, passing to it the accept_time argument.
• Calls this component’s do_accept_tr method to allow for any post-begin action in derived classes.
• Triggers the component’s internal accept_tr event.  Any processes waiting on this event will resume in the next delta cycle.

The accept_tr method calls this function to accommodate any user-defined post-accept action.  Implementations should call super.do_accept_tr to ensure correct operation.

Implementation of uvm_component::begin_tr as described in IEEE 1800.2-2017.

function int begin_tr( uvm_transaction tr,
                       string stream_name="main",
                       string label="",
                       string desc="",
                       time begin_time=0,
                       int parent_handle=0 );

As an added feature, this implementation will attempt to get a non-0 parent_handle from the parent sequence of the transaction tr if the parent_handle argument is 0 and the transaction can be cast to a uvm_sequence_item.

This function marks the start of a child transaction, tr, by this component.  Its operation is identical to that of begin_tr, except that an association is made between this transaction and the provided parent transaction.  This association is vendor-specific.

This function is deprecated

The begin_tr and begin_child_tr methods call this function to accommodate any user-defined post-begin action.  Implementations should call super.do_begin_tr to ensure correct operation.

This function marks the end of a transaction, tr, by this component.  Specifically, it performs the following actions:

• Calls tr’s uvm_transaction::end_tr method, passing to it the end_time argument.  The end_time must at least be greater than the begin time.  By default, when end_time = 0, the current simulation time is used.

The transaction’s properties are recorded to the database-transaction on which it was started, and then the transaction is ended.  Only those properties handled by the transaction’s do_record method (and optional `uvm_*_field macros) are recorded.

• Calls the component’s do_end_tr method to accommodate any post-end action in derived classes.
• Triggers the component’s internal end_tr event.  Any processes waiting on this event will resume in the next delta cycle.

The free_handle bit indicates that this transaction is no longer needed.  The implementation of free_handle is vendor-specific.

The end_tr method calls this function to accommodate any user-defined post-end action.  Implementations should call super.do_end_tr to ensure correct operation.

This function marks an error transaction by a component.  Properties of the given uvm_object, info, as implemented in its uvm_object::do_record method, are recorded to the transaction database.

An error_time of 0 indicates to use the current simulation time.  The keep_active bit determines if the handle should remain active.  If 0, then a zero-length error transaction is recorded.  A handle to the database-transaction is returned.

Interpretation of this handle, as well as the strings stream_name, label, and desc, are vendor-specific.

This function marks an event transaction by a component.

An event_time of 0 indicates to use the current simulation time.

A handle to the transaction is returned.  The keep_active bit determines if the handle may be used for other vendor-specific purposes.

The strings for stream_name, label, and desc are vendor-specific identifiers for the transaction.