The uvm_object class is the base class for all UVM data and hierarchical classes. Its primary role is to define a set of methods for such common operations as create, copy, compare, print, and record. Classes deriving from uvm_object must implement the pure virtual methods such as create and get_type_name.
uvm_object | |||
The uvm_object class is the base class for all UVM data and hierarchical classes. | |||
Class Hierarchy | |||
| |||
Class Declaration | |||
| |||
new | Creates a new uvm_object with the given instance name. | ||
Seeding | |||
use_uvm_seeding | This bit enables or disables the UVM seeding mechanism. | ||
reseed | Calls srandom on the object to reseed the object using the UVM seeding mechanism, which sets the seed based on type name and instance name instead of based on instance position in a thread. | ||
Identification | |||
set_name | Sets the instance name of this object, overwriting any previously given name. | ||
get_name | Returns the name of the object, as provided by the name argument in the new constructor or set_name method. | ||
get_full_name | Returns the full hierarchical name of this object. | ||
get_inst_id | Returns the object’s unique, numeric instance identifier. | ||
get_inst_count | Returns the current value of the instance counter, which represents the total number of uvm_object-based objects that have been allocated in simulation. | ||
get_type | Returns the type-proxy (wrapper) for this object. | ||
get_object_type | Returns the type-proxy (wrapper) for this object. | ||
get_type_name | This function returns the type name of the object, which is typically the type identifier enclosed in quotes. | ||
Creation | |||
create | The create method allocates a new object of the same type as this object and returns it via a base uvm_object handle. | ||
clone | The clone method creates and returns an exact copy of this object. | ||
Printing | |||
The print method deep-prints this object’s properties in a format and manner governed by the given printer argument; if the printer argument is not provided, the global uvm_default_printer is used. | |||
sprint | The sprint method works just like the print method, except the output is returned in a string rather than displayed. | ||
do_print | The do_print method is the user-definable hook called by print and sprint that allows users to customize what gets printed or sprinted beyond the field information provided by the `uvm_field_* macros, Utility and Field Macros for Components and Objects. | ||
convert2string | This virtual function is a user-definable hook, called directly by the user, that allows users to provide object information in the form of a string. | ||
Recording | |||
record | The record method deep-records this object’s properties according to an optional recorder policy. | ||
do_record | The do_record method is the user-definable hook called by the record method. | ||
Copying | |||
copy | The copy method returns a deep copy of this object. | ||
do_copy | The do_copy method is the user-definable hook called by the copy method. | ||
Comparing | |||
compare | Deep compares members of this data object with those of the object provided in the rhs (right-hand side) argument, returning 1 on a match, 0 othewise. | ||
do_compare | The do_compare method is the user-definable hook called by the compare method. | ||
Packing | |||
pack | |||
pack_bytes | |||
pack_ints | The pack methods bitwise-concatenate this object’s properties into an array of bits, bytes, or ints. | ||
do_pack | The do_pack method is the user-definable hook called by the pack methods. | ||
Unpacking | |||
unpack | |||
unpack_bytes | |||
unpack_ints | The unpack methods extract property values from an array of bits, bytes, or ints. | ||
do_unpack | The do_unpack method is the user-definable hook called by the unpack method. | ||
Configuration | |||
set_int_local | |||
set_string_local | |||
set_object_local | These methods provide write access to integral, string, and uvm_object-based properties indexed by a field_name string. |
function new ( string name = "" )
Creates a new uvm_object with the given instance name. If name is not supplied, the object is unnamed.
static bit use_uvm_seeding = 1
This bit enables or disables the UVM seeding mechanism. It globally affects the operation of the reseed method.
When enabled, UVM-based objects are seeded based on their type and full hierarchical name rather than allocation order. This improves random stability for objects whose instance names are unique across each type. The uvm_component class is an example of a type that has a unique instance name.
function void reseed ()
Calls srandom on the object to reseed the object using the UVM seeding mechanism, which sets the seed based on type name and instance name instead of based on instance position in a thread.
If the use_uvm_seeding static variable is set to 0, then reseed() does not perform any function.
virtual function void set_name ( string name )
Sets the instance name of this object, overwriting any previously given name.
virtual function string get_full_name ()
Returns the full hierarchical name of this object. The default implementation is the same as get_name, as uvm_objects do not inherently possess hierarchy.
Objects possessing hierarchy, such as uvm_components, override the default implementation. Other objects might be associated with component hierarchy but are not themselves components. For example, uvm_sequence #(REQ,RSP) classes are typically associated with a uvm_sequencer #(REQ,RSP). In this case, it is useful to override get_full_name to return the sequencer’s full name concatenated with the sequence’s name. This provides the sequence a full context, which is useful when debugging.
virtual function int get_inst_id ()
Returns the object’s unique, numeric instance identifier.
static function int get_inst_count()
Returns the current value of the instance counter, which represents the total number of uvm_object-based objects that have been allocated in simulation. The instance counter is used to form a unique numeric instance identifier.
static function uvm_object_wrapper get_type ()
Returns the type-proxy (wrapper) for this object. The uvm_factory’s type-based override and creation methods take arguments of uvm_object_wrapper. This method, if implemented, can be used as convenient means of supplying those arguments.
The default implementation of this method produces an error and returns null. To enable use of this method, a user’s subtype must implement a version that returns the subtype’s wrapper.
class cmd extends uvm_object; typedef uvm_object_registry #(cmd) type_id; static function type_id get_type(); return type_id::get(); endfunction endclass
factory.set_type_override(cmd::get_type(),subcmd::get_type());
This function is implemented by the `uvm_*_utils macros, if employed.
virtual function uvm_object_wrapper get_object_type ()
Returns the type-proxy (wrapper) for this object. The uvm_factory’s type-based override and creation methods take arguments of uvm_object_wrapper. This method, if implemented, can be used as convenient means of supplying those arguments. This method is the same as the static get_type method, but uses an already allocated object to determine the type-proxy to access (instead of using the static object).
The default implementation of this method does a factory lookup of the proxy using the return value from get_type_name. If the type returned by get_type_name is not registered with the factory, then a null handle is returned.
class cmd extends uvm_object; typedef uvm_object_registry #(cmd) type_id; static function type_id get_type(); return type_id::get(); endfunction virtual function type_id get_object_type(); return type_id::get(); endfunction endclass
This function is implemented by the `uvm_*_utils macros, if employed.
virtual function string get_type_name ()
This function returns the type name of the object, which is typically the type identifier enclosed in quotes. It is used for various debugging functions in the library, and it is used by the factory for creating objects.
This function must be defined in every derived class.
class mytype extends uvm_object; ... const static string type_name = "mytype"; virtual function string get_type_name(); return type_name; endfunction
We define the type_name static variable to enable access to the type name without need of an object of the class, i.e., to enable access via the scope operator, mytype::type_name.
virtual function uvm_object create ( string name = "" )
The create method allocates a new object of the same type as this object and returns it via a base uvm_object handle. Every class deriving from uvm_object, directly or indirectly, must implement the create method.
class mytype extends uvm_object; ... virtual function uvm_object create(string name=""); mytype t = new(name); return t; endfunction
function void print ( uvm_printer printer = null )
The print method deep-prints this object’s properties in a format and manner governed by the given printer argument; if the printer argument is not provided, the global uvm_default_printer is used. See uvm_printer for more information on printer output formatting. See also uvm_line_printer, uvm_tree_printer, and uvm_table_printer for details on the pre-defined printer “policies,” or formatters, provided by the UVM.
The print method is not virtual and must not be overloaded. To include custom information in the print and sprint operations, derived classes must override the do_print method and use the provided printer policy class to format the output.
function string sprint ( uvm_printer printer = null )
The sprint method works just like the print method, except the output is returned in a string rather than displayed.
The sprint method is not virtual and must not be overloaded. To include additional fields in the print and sprint operation, derived classes must override the do_print method and use the provided printer policy class to format the output. The printer policy will manage all string concatenations and provide the string to sprint to return to the caller.
virtual function void do_print ( uvm_printer printer )
The do_print method is the user-definable hook called by print and sprint that allows users to customize what gets printed or sprinted beyond the field information provided by the `uvm_field_* macros, Utility and Field Macros for Components and Objects.
The printer argument is the policy object that governs the format and content of the output. To ensure correct print and sprint operation, and to ensure a consistent output format, the printer must be used by all do_print implementations. That is, instead of using $display or string concatenations directly, a do_print implementation must call through the printer’s API to add information to be printed or sprinted.
class mytype extends uvm_object; data_obj data; int f1; virtual function void do_print (uvm_printer printer); super.do_print(printer); printer.print_int("f1", f1, $bits(f1), DEC); printer.print_object("data", data); endfunction
mytype t = new; t.print(); uvm_report_info("Received",t.sprint());
See uvm_printer for information about the printer API.
virtual function string convert2string()
This virtual function is a user-definable hook, called directly by the user, that allows users to provide object information in the form of a string. Unlike sprint, there is no requirement to use an uvm_printer policy object. As such, the format and content of the output is fully customizable, which may be suitable for applications not requiring the consistent formatting offered by the print/sprint/do_print API.
Fields declared in Utility Macros macros (`uvm_field_*), if used, will not automatically appear in calls to convert2string.
An example implementation of convert2string follows.
class base extends uvm_object; string field = "foo"; virtual function string convert2string(); convert2string = {"base_field=",field}; endfunction endclass class obj2 extends uvm_object; string field = "bar"; virtual function string convert2string(); convert2string = {"child_field=",field}; endfunction endclass class obj extends base; int addr = 'h123; int data = 'h456; bit write = 1; obj2 child = new; virtual function string convert2string(); convert2string = {super.convert2string(), $psprintf(" write=%0d addr=%8h data=%8h ",write,addr,data), child.convert2string()}; endfunction endclass
obj o = new; uvm_report_info("BusMaster",{"Sending:\n ",o.convert2string()});
UVM_INFO @ 0: reporter [BusMaster] Sending: base_field=foo write=1 addr=00000123 data=00000456 child_field=bar
function void record ( uvm_recorder recorder = null )
The record method deep-records this object’s properties according to an optional recorder policy. The method is not virtual and must not be overloaded. To include additional fields in the record operation, derived classes should override the do_record method.
The optional recorder argument specifies the recording policy, which governs how recording takes place. If a recorder policy is not provided explicitly, then the global uvm_default_recorder policy is used. See uvm_recorder for information.
A simulator’s recording mechanism is vendor-specific. By providing access via a common interface, the uvm_recorder policy provides vendor-independent access to a simulator’s recording capabilities.
virtual function void do_record ( uvm_recorder recorder )
The do_record method is the user-definable hook called by the record method. A derived class should override this method to include its fields in a record operation.
The recorder argument is policy object for recording this object. A do_record implementation should call the appropriate recorder methods for each of its fields. Vendor-specific recording implementations are encapsulated in the recorder policy, thereby insulating user-code from vendor-specific behavior. See uvm_recorder for more information.
class mytype extends uvm_object; data_obj data; int f1; function void do_record (uvm_recorder recorder); recorder.record_field_int("f1", f1, $bits(f1), DEC); recorder.record_object("data", data); endfunction
virtual function void do_copy ( uvm_object rhs )
The do_copy method is the user-definable hook called by the copy method. A derived class should override this method to include its fields in a copy operation.
class mytype extends uvm_object; ... int f1; function void do_copy (uvm_object rhs); mytype rhs_; super.do_copy(rhs); $cast(rhs_,rhs); field_1 = rhs_.field_1; endfunction
The implementation must call super.do_copy, and it must $cast the rhs argument to the derived type before copying.
function bit compare ( uvm_object rhs, uvm_comparer comparer = null )
Deep compares members of this data object with those of the object provided in the rhs (right-hand side) argument, returning 1 on a match, 0 othewise.
The compare method is not virtual and should not be overloaded in derived classes. To compare the fields of a derived class, that class should override the do_compare method.
The optional comparer argument specifies the comparison policy. It allows you to control some aspects of the comparison operation. It also stores the results of the comparison, such as field-by-field miscompare information and the total number of miscompares. If a compare policy is not provided, then the global uvm_default_comparer policy is used. See uvm_comparer for more information.
virtual function bit do_compare ( uvm_object rhs, uvm_comparer comparer )
The do_compare method is the user-definable hook called by the compare method. A derived class should override this method to include its fields in a compare operation. It should return 1 if the comparison succeeds, 0 otherwise.
class mytype extends uvm_object; ... int f1; virtual function bit do_compare (uvm_object rhs,uvm_comparer comparer); mytype rhs_; do_compare = super.do_compare(rhs,comparer); $cast(rhs_,rhs); do_compare &= comparer.compare_field_int("f1", f1, rhs_.f1); endfunction
A derived class implementation must call super.do_compare() to ensure its base class’ properties, if any, are included in the comparison. Also, the rhs argument is provided as a generic uvm_object. Thus, you must $cast it to the type of this object before comparing.
The actual comparison should be implemented using the uvm_comparer object rather than direct field-by-field comparison. This enables users of your class to customize how comparisons are performed and how much miscompare information is collected. See uvm_comparer for more details.
function int pack ( ref bit bitstream[], input uvm_packer packer = null )
function int pack_bytes ( ref byte unsigned bytestream[], input uvm_packer packer = null )
function int pack_ints ( ref int unsigned intstream[], input uvm_packer packer = null )
The pack methods bitwise-concatenate this object’s properties into an array of bits, bytes, or ints. The methods are not virtual and must not be overloaded. To include additional fields in the pack operation, derived classes should override the do_pack method.
The optional packer argument specifies the packing policy, which governs the packing operation. If a packer policy is not provided, the global uvm_default_packer policy is used. See uvm_packer for more information.
The return value is the total number of bits packed into the given array. Use the array’s built-in size method to get the number of bytes or ints consumed during the packing process.
virtual function void do_pack ( uvm_packer packer )
The do_pack method is the user-definable hook called by the pack methods. A derived class should override this method to include its fields in a pack operation.
The packer argument is the policy object for packing. The policy object should be used to pack objects.
A typical example of an object packing itself is as follows
class mysubtype extends mysupertype; ... shortint myshort; obj_type myobj; byte myarray[]; ... function void do_pack (uvm_packer packer); super.do_pack(packer); // pack mysupertype properties packer.pack_field_int(myarray.size(), 32); foreach (myarray) packer.pack_field_int(myarray[index], 8); packer.pack_field_int(myshort, $bits(myshort)); packer.pack_object(myobj); endfunction
The implementation must call super.do_pack so that base class properties are packed as well.
If your object contains dynamic data (object, string, queue, dynamic array, or associative array), and you intend to unpack into an equivalent data structure when unpacking, you must include meta-information about the dynamic data when packing as follows.
When the `uvm_field_* macros are used, Utility and Field Macros for Components and Objects, the above meta information is included provided the uvm_packer::use_metadata variable is set for the packer.
Packing order does not need to match declaration order. However, unpacking order must match packing order.
function int unpack ( ref bit bitstream[], input uvm_packer packer = null )
function int unpack_bytes ( ref byte unsigned bytestream[], input uvm_packer packer = null )
function int unpack_ints ( ref int unsigned intstream[], input uvm_packer packer = null )
The unpack methods extract property values from an array of bits, bytes, or ints. The method of unpacking must exactly correspond to the method of packing. This is assured if (a) the same packer policy is used to pack and unpack, and (b) the order of unpacking is the same as the order of packing used to create the input array.
The unpack methods are fixed (non-virtual) entry points that are directly callable by the user. To include additional fields in the unpack operation, derived classes should override the do_unpack method.
The optional packer argument specifies the packing policy, which governs both the pack and unpack operation. If a packer policy is not provided, then the global uvm_default_packer policy is used. See uvm_packer for more information.
The return value is the actual number of bits unpacked from the given array.
virtual function void do_unpack ( uvm_packer packer )
The do_unpack method is the user-definable hook called by the unpack method. A derived class should override this method to include its fields in an unpack operation.
The packer argument is the policy object for both packing and unpacking. It must be the same packer used to pack the object into bits. Also, do_unpack must unpack fields in the same order in which they were packed. See uvm_packer for more information.
The following implementation corresponds to the example given in do_pack.
function void do_unpack (uvm_packer packer); int sz; super.do_unpack(packer); // unpack super's properties sz = packer.unpack_field_int(myarray.size(), 32); myarray.delete(); for(int index=0; index<sz; index++) myarray[index] = packer.unpack_field_int(8); myshort = packer.unpack_field_int($bits(myshort)); packer.unpack_object(myobj); endfunction
If your object contains dynamic data (object, string, queue, dynamic array, or associative array), and you intend to unpack into an equivalent data structure, you must have included meta-information about the dynamic data when it was packed.
virtual function void set_int_local ( string field_name, uvm_bitstream_t value, bit recurse = 1 )
virtual function void set_string_local ( string field_name, string value, bit recurse = 1 )
virtual function void set_object_local ( string field_name, uvm_object value, bit clone = 1, bit recurse = 1 )
These methods provide write access to integral, string, and uvm_object-based properties indexed by a field_name string. The object designer choose which, if any, properties will be accessible, and overrides the appropriate methods depending on the properties’ types. For objects, the optional clone argument specifies whether to clone the value argument before assignment.
The global uvm_is_match function is used to match the field names, so field_name may contain wildcards.
An example implementation of all three methods is as follows.
class mytype extends uvm_object; local int myint; local byte mybyte; local shortint myshort; // no access local string mystring; local obj_type myobj; // provide access to integral properties function void set_int_local(string field_name, uvm_bitstream_t value); if (uvm_is_match (field_name, "myint")) myint = value; else if (uvm_is_match (field_name, "mybyte")) mybyte = value; endfunction // provide access to string properties function void set_string_local(string field_name, string value); if (uvm_is_match (field_name, "mystring")) mystring = value; endfunction // provide access to sub-objects function void set_object_local(string field_name, uvm_object value, bit clone=1); if (uvm_is_match (field_name, "myobj")) begin if (value != null) begin obj_type tmp; // if provided value is not correct type, produce error if (!$cast(tmp, value) ) /* error */ else begin if(clone) $cast(myobj, tmp.clone()); else myobj = tmp; end end else myobj = null; // value is null, so simply assign null to myobj end endfunction ...
Although the object designer implements these methods to provide outside access to one or more properties, they are intended for internal use (e.g., for command-line debugging and auto-configuration) and should not be called directly by the user.
The uvm_object class is the base class for all UVM data and hierarchical classes.
virtual class uvm_object extends uvm_void
Creates a new uvm_object with the given instance name.
function new ( string name = "" )
This bit enables or disables the UVM seeding mechanism.
static bit use_uvm_seeding = 1
Calls srandom on the object to reseed the object using the UVM seeding mechanism, which sets the seed based on type name and instance name instead of based on instance position in a thread.
function void reseed ()
Sets the instance name of this object, overwriting any previously given name.
virtual function void set_name ( string name )
Returns the name of the object, as provided by the name argument in the new constructor or set_name method.
virtual function string get_name ()
Returns the full hierarchical name of this object.
virtual function string get_full_name ()
Returns the object’s unique, numeric instance identifier.
virtual function int get_inst_id ()
Returns the current value of the instance counter, which represents the total number of uvm_object-based objects that have been allocated in simulation.
static function int get_inst_count()
Returns the type-proxy (wrapper) for this object.
static function uvm_object_wrapper get_type ()
Returns the type-proxy (wrapper) for this object.
virtual function uvm_object_wrapper get_object_type ()
This function returns the type name of the object, which is typically the type identifier enclosed in quotes.
virtual function string get_type_name ()
The create method allocates a new object of the same type as this object and returns it via a base uvm_object handle.
virtual function uvm_object create ( string name = "" )
The clone method creates and returns an exact copy of this object.
virtual function uvm_object clone ()
The print method deep-prints this object’s properties in a format and manner governed by the given printer argument; if the printer argument is not provided, the global uvm_default_printer is used.
function void print ( uvm_printer printer = null )
The default printer policy.
uvm_printer uvm_default_printer = uvm_default_table_printer
The sprint method works just like the print method, except the output is returned in a string rather than displayed.
function string sprint ( uvm_printer printer = null )
The do_print method is the user-definable hook called by print and sprint that allows users to customize what gets printed or sprinted beyond the field information provided by the `uvm_field_* macros, Utility and Field Macros for Components and Objects.
virtual function void do_print ( uvm_printer printer )
This virtual function is a user-definable hook, called directly by the user, that allows users to provide object information in the form of a string.
virtual function string convert2string()
The record method deep-records this object’s properties according to an optional recorder policy.
function void record ( uvm_recorder recorder = null )
The do_record method is the user-definable hook called by the record method.
virtual function void do_record ( uvm_recorder recorder )
The copy method returns a deep copy of this object.
function void copy ( uvm_object rhs )
The do_copy method is the user-definable hook called by the copy method.
virtual function void do_copy ( uvm_object rhs )
Deep compares members of this data object with those of the object provided in the rhs (right-hand side) argument, returning 1 on a match, 0 othewise.
function bit compare ( uvm_object rhs, uvm_comparer comparer = null )
The do_compare method is the user-definable hook called by the compare method.
virtual function bit do_compare ( uvm_object rhs, uvm_comparer comparer )
function int pack ( ref bit bitstream[], input uvm_packer packer = null )
function int pack_bytes ( ref byte unsigned bytestream[], input uvm_packer packer = null )
The pack methods bitwise-concatenate this object’s properties into an array of bits, bytes, or ints.
function int pack_ints ( ref int unsigned intstream[], input uvm_packer packer = null )
The do_pack method is the user-definable hook called by the pack methods.
virtual function void do_pack ( uvm_packer packer )
function int unpack ( ref bit bitstream[], input uvm_packer packer = null )
function int unpack_bytes ( ref byte unsigned bytestream[], input uvm_packer packer = null )
The unpack methods extract property values from an array of bits, bytes, or ints.
function int unpack_ints ( ref int unsigned intstream[], input uvm_packer packer = null )
The do_unpack method is the user-definable hook called by the unpack method.
virtual function void do_unpack ( uvm_packer packer )
virtual function void set_int_local ( string field_name, uvm_bitstream_t value, bit recurse = 1 )
virtual function void set_string_local ( string field_name, string value, bit recurse = 1 )
These methods provide write access to integral, string, and uvm_object-based properties indexed by a field_name string.
virtual function void set_object_local ( string field_name, uvm_object value, bit clone = 1, bit recurse = 1 )
The uvm_component class is the root base class for UVM components.
virtual class uvm_component extends uvm_report_object
The uvm_sequence class provides the interfaces necessary in order to create streams of sequence items and/or other sequences.
virtual class uvm_sequence #( type REQ = uvm_sequence_item, type RSP = REQ ) extends uvm_sequence_base
class uvm_sequencer #( type REQ = uvm_sequence_item, RSP = REQ ) extends uvm_sequencer_param_base #(REQ, RSP)
As the name implies, uvm_factory is used to manufacture (create) UVM objects and components.
class uvm_factory
The uvm_object_wrapper provides an abstract interface for creating object and component proxies.
virtual class uvm_object_wrapper
The uvm_printer class provides an interface for printing uvm_objects in various formats.
virtual class uvm_printer
The line printer prints output in a line format.
class uvm_line_printer extends uvm_tree_printer
By overriding various methods of the uvm_printer super class, the tree printer prints output in a tree format.
class uvm_tree_printer extends uvm_printer
The table printer prints output in a tabular format.
class uvm_table_printer extends uvm_printer
The default recording policy.
uvm_recorder uvm_default_recorder = new()
The uvm_recorder class provides a policy object for recording uvm_objects.
class uvm_recorder extends uvm_object
The uvm_comparer class provides a policy object for doing comparisons.
class uvm_comparer
The default packer policy.
uvm_packer uvm_default_packer = new()
This flag indicates whether to encode metadata when packing dynamic data, or to decode metadata when unpacking.
bit use_metadata = 0
Returns 1 if the two strings match, 0 otherwise.
function bit uvm_is_match ( string expr, string str )