# 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_recorder | Abstract class which defines the recorder API.
uvm_text_recorder | The 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_radix | This is the default radix setting if record_field is called without a radix.
physical | This bit provides a filtering mechanism for fields.
abstract | This bit provides a filtering mechanism for fields.
identifier | This bit is used to specify whether or not an object’s reference should be recorded when the object is recorded.
recursion_policy | Sets the recursion policy for recording objects.
Configuration API |
get_stream | Returns a reference to the stream which created this record.
Transaction Recorder API | Once a recorder has been opened via uvm_tr_stream::open_recorder, the user can close the recorder.
close | Closes this recorder.
free | Frees this recorder
is_open | Returns true if this uvm_recorder was opened on its stream, but has not yet been closed.
get_open_time | Returns the open_time
is_closed | Returns true if this uvm_recorder was closed on its stream, but has not yet been freed.
get_close_time | Returns the close_time
Handles |
get_handle | Returns a unique ID for this recorder.
get_recorder_from_handle | Static accessor, returns a recorder reference for a given unique id.
Attribute Recording |
record_field | Records an integral field (less than or equal to 4096 bits).
record_field_int | Records an integral field (less than or equal to 64 bits).
record_field_real | Records a real field.
record_object | Records an object field.
record_string | Records a string field.
record_time | Records a time field.
record_generic | Records a name/value pair, where value has been converted to a string.
use_record_attribute | Indicates that this recorder does (or does not) support usage of the `uvm_record_attribute macro.
get_record_attribute_handle | Provides a tool-specific handle which is compatible with `uvm_record_attribute.
Implementation Agnostic API |
do_open | Callback triggered via uvm_tr_stream::open_recorder.
do_close | Callback triggered via close.
do_free | Callback triggered via free.
do_record_field | Records an integral field (less than or equal to 4096 bits).
do_record_field_int | Records an integral field (less than or equal to 64 bits).
do_record_field_real | Records a real field.
do_record_object | Records an object field.
do_record_string | Records a string field.
do_record_time | Records a time field.
do_record_generic | Records 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_time | Optional 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_time | Optional 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

name | Name of the field
value | Value of the field to record.
size | Number of bits of the field which apply (Usually obtained via $bits).
radix | The 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

name | Name of the field
value | Value of the field to record
size | Number of bits of the wfield which apply (Usually obtained via $bits).
radix | The 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

name | Name of the field
value | Value 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

name | Name of the field
value | Object 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

name | Name of the field
value | Value of the field

### record_time

> function void record_time(
> | string | name,
> | time | value
> )

Records a time field.

#### Parameters

name | Name of the field
value | Value 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

name | Name of the field
value | Value of the field
type_name | optional 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
new | Constructor
Implementation Agnostic API |
do_open | Callback triggered via uvm_tr_stream::open_recorder.
do_close | Callback triggered via uvm_recorder::close.
do_free | Callback triggered via uvm_recorder::free.
do_record_field | Records an integral field (less than or equal to 4096 bits).
do_record_field_int | Records an integral field (less than or equal to 64 bits).
do_record_field_real | Record a real field.
do_record_object | Record an object field.
do_record_string | Records a string field.
do_record_time | Records a time field.
do_record_generic | Records a name/value pair, where value has been converted to a string.
Implementation Specific API |
write_attribute | Outputs an integral attribute to the textual log
write_attribute_int | Outputs an integral attribute to the textual log

### new

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

Constructor

#### Parameters

name | Instance 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

nm | Name of the attribute
value | Value
radix | Radix of the output
numbits | number 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

nm | Name of the attribute
value | Value
radix | Radix of the output
numbits | number 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