UVM Recorders

The uvm_recorder class serves two purposes

  • Firstly, it is an abstract representation of a record within a uvm_tr_stream.
  • Secondly, it is a policy object for recording fields into that record within the stream.
Contents
UVM Recorders
uvm_recorderAbstract class which defines the recorder API.
uvm_text_recorderThe uvm_text_recorder is the default recorder implementation for the uvm_text_tr_database.

uvm_recorder

Abstract class which defines the recorder API.

Summary
uvm_recorder
Abstract class which defines the recorder API.
Class Hierarchy
uvm_void
uvm_object
uvm_recorder
Class Declaration
virtual class uvm_recorder extends uvm_object
default_radixThis is the default radix setting if record_field is called without a radix.
physicalThis bit provides a filtering mechanism for fields.
abstractThis bit provides a filtering mechanism for fields.
identifierThis bit is used to specify whether or not an object’s reference should be recorded when the object is recorded.
recursion_policySets the recursion policy for recording objects.
Configuration API
get_streamReturns a reference to the stream which created this record.
Transaction Recorder APIOnce a recorder has been opened via uvm_tr_stream::open_recorder, the user can close the recorder.
closeCloses this recorder.
freeFrees this recorder
is_openReturns true if this uvm_recorder was opened on its stream, but has not yet been closed.
get_open_timeReturns the open_time
is_closedReturns true if this uvm_recorder was closed on its stream, but has not yet been freed.
get_close_timeReturns the close_time
Handles
get_handleReturns a unique ID for this recorder.
get_recorder_from_handleStatic accessor, returns a recorder reference for a given unique id.
Attribute Recording
record_fieldRecords an integral field (less than or equal to 4096 bits).
record_field_intRecords an integral field (less than or equal to 64 bits).
record_field_realRecords a real field.
record_objectRecords an object field.
record_stringRecords a string field.
record_timeRecords a time field.
record_genericRecords a name/value pair, where value has been converted to a string.
use_record_attributeIndicates that this recorder does (or does not) support usage of the `uvm_record_attribute macro.
get_record_attribute_handleProvides a tool-specific handle which is compatible with `uvm_record_attribute.
Implementation Agnostic API
do_openCallback triggered via uvm_tr_stream::open_recorder.
do_closeCallback triggered via close.
do_freeCallback triggered via free.
do_record_fieldRecords an integral field (less than or equal to 4096 bits).
do_record_field_intRecords an integral field (less than or equal to 64 bits).
do_record_field_realRecords a real field.
do_record_objectRecords an object field.
do_record_stringRecords a string field.
do_record_timeRecords a time field.
do_record_genericRecords a name/value pair, where value has been converted to a string.

default_radix

uvm_radix_enum default_radix = UVM_HEX

This is the default radix setting if record_field is called without a radix.

physical

bit physical = 1

This bit provides a filtering mechanism for fields.

The abstract and physical settings allow an object to distinguish between two different classes of fields.

It is up to you, in the uvm_object::do_record method, to test the setting of this field if you want to use the physical trait as a filter.

abstract

bit abstract = 1

This bit provides a filtering mechanism for fields.

The abstract and physical settings allow an object to distinguish between two different classes of fields.

It is up to you, in the uvm_object::do_record method, to test the setting of this field if you want to use the abstract trait as a filter.

identifier

bit identifier = 1

This bit is used to specify whether or not an object’s reference should be recorded when the object is recorded.

recursion_policy

uvm_recursion_policy_enum policy = UVM_DEFAULT_POLICY

Sets the recursion policy for recording objects.

The default policy is deep (which means to recurse an object).

Configuration API

get_stream

function uvm_tr_stream get_stream()

Returns a reference to the stream which created this record.

A warning will be asserted if get_stream is called prior to the record being initialized via do_open.

Transaction Recorder API

Once a recorder has been opened via uvm_tr_stream::open_recorder, the user can close the recorder.

Due to the fact that many database implementations will require crossing a language boundary, an additional step of freeing the recorder is required.

A link can be established within the database any time between open and free, however it is illegal to establish a link after freeing the recorder.

close

function void close(
    time  close_time  =  0
)

Closes this recorder.

Closing a recorder marks the end of the transaction in the stream.

Parameters

close_timeOptional time to record as the closing time of this transaction.

This method will trigger a do_close call.

free

function void free(
    time  close_time  =  0
)

Frees this recorder

Freeing a recorder indicates that the stream and database can release any references to the recorder.

Parameters

close_timeOptional time to record as the closing time of this transaction.

If a recorder has not yet been closed (via a call to close), then close will automatically be called, and passed the close_time.  If the recorder has already been closed, then the close_time will be ignored.

This method will trigger a do_free call.

is_open

function bit is_open()

Returns true if this uvm_recorder was opened on its stream, but has not yet been closed.

get_open_time

function time get_open_time()

Returns the open_time

is_closed

function bit is_closed()

Returns true if this uvm_recorder was closed on its stream, but has not yet been freed.

get_close_time

function time get_close_time()

Returns the close_time

Handles

get_handle

function integer get_handle()

Returns a unique ID for this recorder.

A value of 0 indicates that the recorder has been freed, and no longer has a valid ID.

get_recorder_from_handle

static function uvm_recorder get_recorder_from_handle(
    integer  id
)

Static accessor, returns a recorder reference for a given unique id.

If no recorder exists with the given id, or if the recorder with that id has been freed, then null is returned.

This method can be used to access the recorder associated with a call to uvm_transaction::begin_tr or uvm_component::begin_tr.

integer handle = tr.begin_tr();
uvm_recorder recorder = uvm_recorder::get_recorder_from_handle(handle);
if (recorder != null) begin
  recorder.record_string("begin_msg", "Started recording transaction!");
end

Attribute Recording

record_field

function void record_field(
    string  name,   
    uvm_bitstream_t  value,   
    int  size,   
    uvm_radix_enum  radix  =  UVM_NORADIX
)

Records an integral field (less than or equal to 4096 bits).

Parameters

nameName of the field
valueValue of the field to record.
sizeNumber of bits of the field which apply (Usually obtained via $bits).
radixThe uvm_radix_enum to use.

This method will trigger a do_record_field call.

record_field_int

function void record_field_int(
    string  name,   
    uvm_integral_t  value,   
    int  size,   
    uvm_radix_enum  radix  =  UVM_NORADIX
)

Records an integral field (less than or equal to 64 bits).

This optimized version of record_field is useful for sizes up to 64 bits.

Parameters

nameName of the field
valueValue of the field to record
sizeNumber of bits of the wfield which apply (Usually obtained via $bits).
radixThe uvm_radix_enum to use.

This method will trigger a do_record_field_int call.

record_field_real

function void record_field_real(
    string  name,
    real  value
)

Records a real field.

Parameters

nameName of the field
valueValue of the field to record

This method will trigger a do_record_field_real call.

record_object

function void record_object(
    string  name,
    uvm_object  value
)

Records an object field.

Parameters

nameName of the field
valueObject to record

The implementation must use the recursion_policy and identifier to determine exactly what should be recorded.

record_string

function void record_string(
    string  name,
    string  value
)

Records a string field.

Parameters

nameName of the field
valueValue of the field

record_time

function void record_time(
    string  name,
    time  value
)

Records a time field.

Parameters

nameName of the field
valueValue of the field

record_generic

function void record_generic(
    string  name,   
    string  value,   
    string  type_name  =  ""
)

Records a name/value pair, where value has been converted to a string.

For example

recorder.record_generic("myvar","var_type", $sformatf("%0d",myvar), 32);

Parameters

nameName of the field
valueValue of the field
type_nameoptional Type name of the field

use_record_attribute

virtual function bit use_record_attribute()

Indicates that this recorder does (or does not) support usage of the `uvm_record_attribute macro.

The default return value is 0 (not supported), developers can optionally extend uvm_recorder and set the value to 1 if they support the `uvm_record_attribute macro.

get_record_attribute_handle

virtual function integer get_record_attribute_handle()

Provides a tool-specific handle which is compatible with `uvm_record_attribute.

By default, this method will return the same value as get_handle, however tool vendors can override this method to provide tool-specific handles which will be passed to the `uvm_record_attribute macro.

Implementation Agnostic API

do_open

protected virtual function void do_open(
    uvm_tr_stream  stream,
    time  open_time,
    string  type_name
)

Callback triggered via uvm_tr_stream::open_recorder.

The do_open callback can be used to initialize any internal state within the recorder, as well as providing a location to record any initial information.

do_close

protected virtual function void do_close(
    time  close_time
)

Callback triggered via close.

The do_close callback can be used to set internal state within the recorder, as well as providing a location to record any closing information.

do_free

protected virtual function void do_free()

Callback triggered via free.

The do_free callback can be used to release the internal state within the recorder, as well as providing a location to record any “freeing” information.

do_record_field

pure virtual protected function void do_record_field(
    string  name,
    uvm_bitstream_t  value,
    int  size,
    uvm_radix_enum  radix
)

Records an integral field (less than or equal to 4096 bits).

Mandatory Backend implementation of record_field

do_record_field_int

pure virtual protected function void do_record_field_int(
    string  name,
    uvm_integral_t  value,
    int  size,
    uvm_radix_enum  radix
)

Records an integral field (less than or equal to 64 bits).

Mandatory Backend implementation of record_field_int

do_record_field_real

pure virtual protected function void do_record_field_real(
    string  name,
    real  value
)

Records a real field.

Mandatory Backend implementation of record_field_real

do_record_object

pure virtual protected function void do_record_object(
    string  name,
    uvm_object  value
)

Records an object field.

Mandatory Backend implementation of record_object

do_record_string

pure virtual protected function void do_record_string(
    string  name,
    string  value
)

Records a string field.

Mandatory Backend implementation of record_string

do_record_time

pure virtual protected function void do_record_time(
    string  name,
    time  value
)

Records a time field.

Mandatory Backend implementation of record_time

do_record_generic

pure virtual protected function void do_record_generic(
    string  name,
    string  value,
    string  type_name
)

Records a name/value pair, where value has been converted to a string.

Mandatory Backend implementation of record_generic

uvm_text_recorder

The uvm_text_recorder is the default recorder implementation for the uvm_text_tr_database.

Summary
uvm_text_recorder
The uvm_text_recorder is the default recorder implementation for the uvm_text_tr_database.
Class Hierarchy
uvm_void
uvm_object
uvm_recorder
uvm_text_recorder
Class Declaration
class uvm_text_recorder extends uvm_recorder
newConstructor
Implementation Agnostic API
do_openCallback triggered via uvm_tr_stream::open_recorder.
do_closeCallback triggered via uvm_recorder::close.
do_freeCallback triggered via uvm_recorder::free.
do_record_fieldRecords an integral field (less than or equal to 4096 bits).
do_record_field_intRecords an integral field (less than or equal to 64 bits).
do_record_field_realRecord a real field.
do_record_objectRecord an object field.
do_record_stringRecords a string field.
do_record_timeRecords a time field.
do_record_genericRecords a name/value pair, where value has been converted to a string.
Implementation Specific API
write_attributeOutputs an integral attribute to the textual log
write_attribute_intOutputs an integral attribute to the textual log

new

function new(
    string  name  =  "unnamed-uvm_text_recorder"
)

Constructor

Parameters

nameInstance name

Implementation Agnostic API

do_open

protected virtual function void do_open(
    uvm_tr_stream  stream,
    time  open_time,
    string  type_name
)

Callback triggered via uvm_tr_stream::open_recorder.

Text-backend specific implementation.

do_close

protected virtual function void do_close(
    time  close_time
)

Callback triggered via uvm_recorder::close.

Text-backend specific implementation.

do_free

protected virtual function void do_free()

Callback triggered via uvm_recorder::free.

Text-backend specific implementation.

do_record_field

protected virtual function void do_record_field(
    string  name,
    uvm_bitstream_t  value,
    int  size,
    uvm_radix_enum  radix
)

Records an integral field (less than or equal to 4096 bits).

Text-backend specific implementation.

do_record_field_int

protected virtual function void do_record_field_int(
    string  name,
    uvm_integral_t  value,
    int  size,
    uvm_radix_enum  radix
)

Records an integral field (less than or equal to 64 bits).

Text-backend specific implementation.

do_record_field_real

protected virtual function void do_record_field_real(
    string  name,
    real  value
)

Record a real field.

Text-backened specific implementation.

do_record_object

protected virtual function void do_record_object(
    string  name,
    uvm_object  value
)

Record an object field.

Text-backend specific implementation.

The method uses identifier to determine whether or not to record the object instance id, and recursion_policy to determine whether or not to recurse into the object.

do_record_string

protected virtual function void do_record_string(
    string  name,
    string  value
)

Records a string field.

Text-backend specific implementation.

do_record_time

protected virtual function void do_record_time(
    string  name,
    time  value
)

Records a time field.

Text-backend specific implementation.

do_record_generic

protected virtual function void do_record_generic(
    string  name,
    string  value,
    string  type_name
)

Records a name/value pair, where value has been converted to a string.

Text-backend specific implementation.

Implementation Specific API

write_attribute

function void write_attribute(
    string  nm,   
    uvm_bitstream_t  value,   
    uvm_radix_enum  radix,   
    integer  numbits  =  $bits(uvm_bitstream_t)
)

Outputs an integral attribute to the textual log

Parameters

nmName of the attribute
valueValue
radixRadix of the output
numbitsnumber of valid bits

write_attribute_int

function void write_attribute_int(
    string  nm,   
    uvm_integral_t  value,   
    uvm_radix_enum  radix,   
    integer  numbits  =  $bits(uvm_bitstream_t)
)

Outputs an integral attribute to the textual log

Parameters

nmName of the attribute
valueValue
radixRadix of the output
numbitsnumber of valid bits
virtual class uvm_recorder extends uvm_object
Abstract class which defines the recorder API.
class uvm_text_recorder extends uvm_recorder
The uvm_text_recorder is the default recorder implementation for the uvm_text_tr_database.
class uvm_text_tr_database extends uvm_tr_database
The uvm_text_tr_database is the default implementation for the uvm_tr_database.
virtual class uvm_tr_stream extends uvm_object
The uvm_tr_stream base class is a representation of a stream of records within a uvm_tr_database.
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.
uvm_radix_enum default_radix = UVM_HEX
This is the default radix setting if record_field is called without a radix.
function void record_field(
    string  name,   
    uvm_bitstream_t  value,   
    int  size,   
    uvm_radix_enum  radix  =  UVM_NORADIX
)
Records an integral field (less than or equal to 4096 bits).
bit physical = 1
This bit provides a filtering mechanism for fields.
bit abstract = 1
This bit provides a filtering mechanism for fields.
bit identifier = 1
This bit is used to specify whether or not an object’s reference should be recorded when the object is recorded.
uvm_recursion_policy_enum policy = UVM_DEFAULT_POLICY
Sets the recursion policy for recording objects.
function uvm_tr_stream get_stream()
Returns a reference to the stream which created this record.
function uvm_recorder open_recorder(
    string  name,   
    time  open_time  =  0,
    string  type_name  =  ""
)
Marks the opening of a new transaction recorder on the stream.
function void close(
    time  close_time  =  0
)
Closes this recorder.
function void free(
    time  close_time  =  0
)
Frees this recorder
function bit is_open()
Returns true if this uvm_recorder was opened on its stream, but has not yet been closed.
function time get_open_time()
Returns the open_time
function bit is_closed()
Returns true if this uvm_recorder was closed on its stream, but has not yet been freed.
function time get_close_time()
Returns the close_time
function integer get_handle()
Returns a unique ID for this recorder.
static function uvm_recorder get_recorder_from_handle(
    integer  id
)
Static accessor, returns a recorder reference for a given unique id.
function void record_field_int(
    string  name,   
    uvm_integral_t  value,   
    int  size,   
    uvm_radix_enum  radix  =  UVM_NORADIX
)
Records an integral field (less than or equal to 64 bits).
function void record_field_real(
    string  name,
    real  value
)
Records a real field.
function void record_object(
    string  name,
    uvm_object  value
)
Records an object field.
function void record_string(
    string  name,
    string  value
)
Records a string field.
function void record_time(
    string  name,
    time  value
)
Records a time field.
function void record_generic(
    string  name,   
    string  value,   
    string  type_name  =  ""
)
Records a name/value pair, where value has been converted to a string.
virtual function bit use_record_attribute()
Indicates that this recorder does (or does not) support usage of the `uvm_record_attribute macro.
Vendor-independent macro to hide tool-specific interface for recording attributes (fields) to a transaction database.
virtual function integer get_record_attribute_handle()
Provides a tool-specific handle which is compatible with `uvm_record_attribute.
protected virtual function void do_open(
    uvm_tr_stream  stream,
    time  open_time,
    string  type_name
)
Callback triggered via uvm_tr_stream::open_recorder.
protected virtual function void do_close(
    time  close_time
)
Callback triggered via close.
protected virtual function void do_free()
Callback triggered via free.
pure virtual protected function void do_record_field(
    string  name,
    uvm_bitstream_t  value,
    int  size,
    uvm_radix_enum  radix
)
Records an integral field (less than or equal to 4096 bits).
pure virtual protected function void do_record_field_int(
    string  name,
    uvm_integral_t  value,
    int  size,
    uvm_radix_enum  radix
)
Records an integral field (less than or equal to 64 bits).
pure virtual protected function void do_record_field_real(
    string  name,
    real  value
)
Records a real field.
pure virtual protected function void do_record_object(
    string  name,
    uvm_object  value
)
Records an object field.
pure virtual protected function void do_record_string(
    string  name,
    string  value
)
Records a string field.
pure virtual protected function void do_record_time(
    string  name,
    time  value
)
Records a time field.
pure virtual protected function void do_record_generic(
    string  name,
    string  value,
    string  type_name
)
Records a name/value pair, where value has been converted to a string.
virtual function void do_record (
    uvm_recorder  recorder
)
The do_record method is the user-definable hook called by the record method.
function integer begin_tr (
    time  begin_time  =  0
)
This function indicates that the transaction has been started and is not the child of another transaction.
function integer begin_tr (
    uvm_transaction  tr,   
    string  stream_name  =  "main",
    string  label  =  "",
    string  desc  =  "",
    time  begin_time  =  0,
    integer  parent_handle  =  0
)
This function marks the start of a transaction, tr, by this component.
Specifies the radix to print or record in.
function new(
    string  name  =  "unnamed-uvm_text_recorder"
)
Constructor
protected virtual function void do_open(
    uvm_tr_stream  stream,
    time  open_time,
    string  type_name
)
Callback triggered via uvm_tr_stream::open_recorder.
protected virtual function void do_close(
    time  close_time
)
Callback triggered via uvm_recorder::close.
protected virtual function void do_free()
Callback triggered via uvm_recorder::free.
protected virtual function void do_record_field(
    string  name,
    uvm_bitstream_t  value,
    int  size,
    uvm_radix_enum  radix
)
Records an integral field (less than or equal to 4096 bits).
protected virtual function void do_record_field_int(
    string  name,
    uvm_integral_t  value,
    int  size,
    uvm_radix_enum  radix
)
Records an integral field (less than or equal to 64 bits).
protected virtual function void do_record_field_real(
    string  name,
    real  value
)
Record a real field.
protected virtual function void do_record_object(
    string  name,
    uvm_object  value
)
Record an object field.
protected virtual function void do_record_string(
    string  name,
    string  value
)
Records a string field.
protected virtual function void do_record_time(
    string  name,
    time  value
)
Records a time field.
protected virtual function void do_record_generic(
    string  name,
    string  value,
    string  type_name
)
Records a name/value pair, where value has been converted to a string.
function void write_attribute(
    string  nm,   
    uvm_bitstream_t  value,   
    uvm_radix_enum  radix,   
    integer  numbits  =  $bits(uvm_bitstream_t)
)
Outputs an integral attribute to the textual log
function void write_attribute_int(
    string  nm,   
    uvm_integral_t  value,   
    uvm_radix_enum  radix,   
    integer  numbits  =  $bits(uvm_bitstream_t)
)
Outputs an integral attribute to the textual log