Factory Component and Object Wrappers

Contents
Factory Component and Object Wrappers
IntroThis section defines the proxy component and object classes used by the factory.
uvm_component_registry #(T,Tname)The uvm_component_registry serves as a lightweight proxy for a component of type T and type name Tname, a string.
uvm_object_registry #(T,Tname)The uvm_object_registry serves as a lightweight proxy for an uvm_object of type T and type name Tname, a string.

Intro

This section defines the proxy component and object classes used by the factory.  To avoid the overhead of creating an instance of every component and object that get registered, the factory holds lightweight wrappers, or proxies.  When a request for a new object is made, the factory calls upon the proxy to create the object it represents.

uvm_component_registry #(T,Tname)

The uvm_component_registry serves as a lightweight proxy for a component of type T and type name Tname, a string.  The proxy enables efficient registration with the uvm_factory.  Without it, registration would require an instance of the component itself.

See Usage section below for information on using uvm_component_registry.

Summary
uvm_component_registry #(T,Tname)
The uvm_component_registry serves as a lightweight proxy for a component of type T and type name Tname, a string.
Class Hierarchy
uvm_component_registry#(T,Tname)
Class Declaration
class uvm_component_registry #(
    type  T  =  uvm_component,
    string  Tname  =  "<unknown>"
) extends uvm_object_wrapper
Methods
create_componentCreates a component of type T having the provided name and parent.
get_type_nameReturns the value given by the string parameter, Tname.
getReturns the singleton instance of this type.
createReturns an instance of the component type, T, represented by this proxy, subject to any factory overrides based on the context provided by the parent’s full name.
set_type_overrideConfigures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type, T, represented by this proxy, provided no instance override applies.
set_inst_overrideConfigures the factory to create a component of the type represented by override_type whenever a request is made to create an object of the type, T, represented by this proxy, with matching instance paths.

create_component

virtual function uvm_component create_component ( string  name,
uvm_component  parent )

Creates a component of type T having the provided name and parent.  This is an override of the method in uvm_object_wrapper.  It is called by the factory after determining the type of object to create.  You should not call this method directly.  Call create instead.

get_type_name

virtual function string get_type_name()

Returns the value given by the string parameter, Tname.  This method overrides the method in uvm_object_wrapper.

get

static function this_type get()

Returns the singleton instance of this type.  Type-based factory operation depends on there being a single proxy instance for each registered type.

create

static function T create( string  name,   
uvm_component  parent,   
string  contxt  =  "" )

Returns an instance of the component type, T, represented by this proxy, subject to any factory overrides based on the context provided by the parent’s full name.  The contxt argument, if supplied, supercedes the parent’s context.  The new instance will have the given leaf name and parent.

set_type_override

static function void set_type_override ( uvm_object_wrapper  override_type,   
bit  replace  =  1 )

Configures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type, T, represented by this proxy, provided no instance override applies.  The original type, T, is typically a super class of the override type.

set_inst_override

static function void set_inst_override( uvm_object_wrapper  override_type,   
string  inst_path,   
uvm_component  parent  =  null )

Configures the factory to create a component of the type represented by override_type whenever a request is made to create an object of the type, T, represented by this proxy, with matching instance paths.  The original type, T, is typically a super class of the override type.

If parent is not specified, inst_path is interpreted as an absolute instance path, which enables instance overrides to be set from outside component classes.  If parent is specified, inst_path is interpreted as being relative to the parent’s hierarchical instance path, i.e.  {parent.get_full_name(),”.”,inst_path} is the instance path that is registered with the override.  The inst_path may contain wildcards for matching against multiple contexts.

uvm_object_registry #(T,Tname)

The uvm_object_registry serves as a lightweight proxy for an uvm_object of type T and type name Tname, a string.  The proxy enables efficient registration with the uvm_factory.  Without it, registration would require an instance of the object itself.

See Usage section below for information on using uvm_component_registry.

Summary
uvm_object_registry #(T,Tname)
The uvm_object_registry serves as a lightweight proxy for an uvm_object of type T and type name Tname, a string.
Class Hierarchy
uvm_object_registry#(T,Tname)
Class Declaration
class uvm_object_registry #(
    type  T  =  uvm_object,
    string  Tname  =  "<unknown>"
) extends uvm_object_wrapper
create_objectCreates an object of type T and returns it as a handle to an uvm_object.
get_type_nameReturns the value given by the string parameter, Tname.
getReturns the singleton instance of this type.
createReturns an instance of the object type, T, represented by this proxy, subject to any factory overrides based on the context provided by the parent’s full name.
set_type_overrideConfigures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type represented by this proxy, provided no instance override applies.
set_inst_overrideConfigures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type represented by this proxy, with matching instance paths.
UsageThis section describes usage for the uvm_*_registry classes.

create_object

virtual function uvm_object create_object( string  name  =  "" )

Creates an object of type T and returns it as a handle to an uvm_object.  This is an override of the method in uvm_object_wrapper.  It is called by the factory after determining the type of object to create.  You should not call this method directly.  Call create instead.

get_type_name

virtual function string get_type_name()

Returns the value given by the string parameter, Tname.  This method overrides the method in uvm_object_wrapper.

get

static function this_type get()

Returns the singleton instance of this type.  Type-based factory operation depends on there being a single proxy instance for each registered type.

create

static function T create ( string  name  =  "",
uvm_component  parent  =  null,
string  contxt  =  "" )

Returns an instance of the object type, T, represented by this proxy, subject to any factory overrides based on the context provided by the parent’s full name.  The contxt argument, if supplied, supercedes the parent’s context.  The new instance will have the given leaf name, if provided.

set_type_override

static function void set_type_override ( uvm_object_wrapper  override_type,   
bit  replace  =  1 )

Configures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type represented by this proxy, provided no instance override applies.  The original type, T, is typically a super class of the override type.

set_inst_override

static function void set_inst_override( uvm_object_wrapper  override_type,   
string  inst_path,   
uvm_component  parent  =  null )

Configures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type represented by this proxy, with matching instance paths.  The original type, T, is typically a super class of the override type.

If parent is not specified, inst_path is interpreted as an absolute instance path, which enables instance overrides to be set from outside component classes.  If parent is specified, inst_path is interpreted as being relative to the parent’s hierarchical instance path, i.e.  {parent.get_full_name(),”.”,inst_path} is the instance path that is registered with the override.  The inst_path may contain wildcards for matching against multiple contexts.

Usage

This section describes usage for the uvm_*_registry classes.

The wrapper classes are used to register lightweight proxies of objects and components.

To register a particular component type, you need only typedef a specialization of its proxy class, which is typically done inside the class.

For example, to register an UVM component of type mycomp

class mycomp extends uvm_component;
  typedef uvm_component_registry #(mycomp,"mycomp") type_id;
endclass

However, because of differences between simulators, it is necessary to use a macro to ensure vendor interoperability with factory registration.  To register an UVM component of type mycomp in a vendor-independent way, you would write instead:

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

The `uvm_component_utils macro is for non-parameterized classes.  In this example, the typedef underlying the macro specifies the Tname parameter as “mycomp”, and mycomp’s get_type_name() is defined to return the same.  With Tname defined, you can use the factory’s name-based methods to set overrides and create objects and components of non-parameterized types.

For parameterized types, the type name changes with each specialization, so you can not specify a Tname inside a parameterized class and get the behavior you want; the same type name string would be registered for all specializations of the class!  (The factory would produce warnings for each specialization beyond the first.)  To avoid the warnings and simulator interoperability issues with parameterized classes, you must register parameterized classes with a different macro.

For example, to register an UVM component of type driver #(T), you would write:

class driver #(type T=int) extends uvm_component;
  `uvm_component_param_utils(driver #(T));
  ...
endclass

The `uvm_component_param_utils and `uvm_object_param_utils macros are used to register parameterized classes with the factory.  Unlike the the non-param versions, these macros do not specify the Tname parameter in the underlying uvm_component_registry typedef, and they do not define the get_type_name method for the user class.  Consequently, you will not be able to use the factory’s name-based methods for parameterized classes.

The primary purpose for adding the factory’s type-based methods was to accommodate registration of parameterized types and eliminate the many sources of errors associated with string-based factory usage.  Thus, use of name-based lookup in uvm_factory is no longer recommended.

class uvm_component_registry #(
    type  T  =  uvm_component,
    string  Tname  =  "<unknown>"
) extends uvm_object_wrapper
The uvm_component_registry serves as a lightweight proxy for a component of type T and type name Tname, a string.
class uvm_object_registry #(
    type  T  =  uvm_object,
    string  Tname  =  "<unknown>"
) extends uvm_object_wrapper
The uvm_object_registry serves as a lightweight proxy for an uvm_object of type T and type name Tname, a string.
virtual class uvm_object extends uvm_void
The uvm_object class is the base class for all UVM data and hierarchical classes.
virtual class uvm_object_wrapper
The uvm_object_wrapper provides an abstract interface for creating object and component proxies.
virtual function uvm_component create_component ( string  name,
uvm_component  parent )
Creates a component of type T having the provided name and parent.
virtual function string get_type_name()
Returns the value given by the string parameter, Tname.
static function this_type get()
Returns the singleton instance of this type.
static function T create( string  name,   
uvm_component  parent,   
string  contxt  =  "" )
Returns an instance of the component type, T, represented by this proxy, subject to any factory overrides based on the context provided by the parent’s full name.
static function void set_type_override ( uvm_object_wrapper  override_type,   
bit  replace  =  1 )
Configures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type, T, represented by this proxy, provided no instance override applies.
static function void set_inst_override( uvm_object_wrapper  override_type,   
string  inst_path,   
uvm_component  parent  =  null )
Configures the factory to create a component of the type represented by override_type whenever a request is made to create an object of the type, T, represented by this proxy, with matching instance paths.
class uvm_factory
As the name implies, uvm_factory is used to manufacture (create) UVM objects and components.
This example illustrates basic TLM connectivity using the blocking put inteface.
virtual function uvm_object create_object( string  name  =  "" )
Creates an object of type T and returns it as a handle to an uvm_object.
virtual function string get_type_name()
Returns the value given by the string parameter, Tname.
static function this_type get()
Returns the singleton instance of this type.
static function T create ( string  name  =  "",
uvm_component  parent  =  null,
string  contxt  =  "" )
Returns an instance of the object type, T, represented by this proxy, subject to any factory overrides based on the context provided by the parent’s full name.
static function void set_type_override ( uvm_object_wrapper  override_type,   
bit  replace  =  1 )
Configures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type represented by this proxy, provided no instance override applies.
static function void set_inst_override( uvm_object_wrapper  override_type,   
string  inst_path,   
uvm_component  parent  =  null )
Configures the factory to create an object of the type represented by override_type whenever a request is made to create an object of the type represented by this proxy, with matching instance paths.
This section describes usage for the uvm_*_registry classes.