# Transaction Recording Streams

Contents

Transaction Recording Streams |
uvm_tr_stream | The uvm_tr_stream base class is a representation of a stream of records within a uvm_tr_database.
uvm_text_tr_stream | The uvm_text_tr_stream is the default stream implementation for the uvm_text_tr_database.

## uvm_tr_stream

The uvm_tr_stream base class is a representation of a stream of records within a uvm_tr_database.

The record stream is intended to hide the underlying database implementation from the end user, as these details are often vendor or tool-specific.

The uvm_tr_stream class is pure virtual, and must be extended with an implementation. A default text-based implementation is provided via the uvm_text_tr_stream class.

Summary

uvm_tr_stream
The uvm_tr_stream base class is a representation of a stream of records within a uvm_tr_database.
Class Hierarchy
uvm_void
uvm_object
uvm_tr_stream
Class Declaration
> virtual class uvm_tr_stream extends uvm_object
new | Constructor
Configuration API |
get_db | Returns a reference to the database which contains this stream.
get_scope | Returns the scope supplied when opening this stream.
get_stream_type_name | Returns a reference to the database which contains this stream.
Stream API | Once a stream has been opened via uvm_tr_database::open_stream, the user can close the stream.
close | Closes this stream.
free | Frees this stream.
is_open | Returns true if this uvm_tr_stream was opened on the database, but has not yet been closed.
is_closed | Returns true if this uvm_tr_stream was closed on the database, but has not yet been freed.
Transaction Recorder API | New recorders can be opened prior to the stream being closed.
open_recorder | Marks the opening of a new transaction recorder on the stream.
get_recorders | Provides a queue of all transactions within the stream.
Handles |
get_handle | Returns a unique ID for this stream.
get_stream_from_handle | Static accessor, returns a stream reference for a given unique id.
Implementation Agnostic API |
do_open | Callback triggered via uvm_tr_database::open_stream.
do_close | Callback triggered via close.
do_free | Callback triggered via free.
do_open_recorder | Marks the beginning of a new record in the stream.

### new

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

Constructor

#### Parameters

name | Stream instance name

### Configuration API

### get_db

> function uvm_tr_database get_db()

Returns a reference to the database which contains this stream.

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

### get_scope

> function string get_scope()

Returns the scope supplied when opening this stream.

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

### get_stream_type_name

> function string get_stream_type_name()

Returns a reference to the database which contains this stream.

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

### Stream API

Once a stream has been opened via uvm_tr_database::open_stream, the user can close the stream.

Due to the fact that many database implementations will require crossing a language boundary, an additional step of freeing the stream 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 stream.

### close

> function void close()

Closes this stream.

Closing a stream closes all open recorders in the stream.

This method will trigger a do_close call, followed by uvm_recorder::close on all open recorders within the stream.

### free

> function void free()

Frees this stream.

Freeing a stream indicates that the database can free any references to the stream (including references to records within the stream).

This method will trigger a do_free call, followed by uvm_recorder::free on all recorders within the stream.

### is_open

> function bit is_open()

Returns true if this uvm_tr_stream was opened on the database, but has not yet been closed.

### is_closed

> function bit is_closed()

Returns true if this uvm_tr_stream was closed on the database, but has not yet been freed.

### Transaction Recorder API

New recorders can be opened prior to the stream being closed.

Once a stream has been closed, requests to open a new recorder will be ignored (open_recorder will return null).

### open_recorder

> 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.

#### Parameters

name | A name for the new transaction
open_time | Optional time to record as the opening of this transaction
type_name | Optional type name for the transaction

If open_time is omitted (or set to 0), then the stream will use the current time.

This method will trigger a do_open_recorder call. If do_open_recorder returns a non-null value, then the uvm_recorder::do_open method will be called in the recorder.

Transaction recorders can only be opened if the stream is open on the database (per is_open). Otherwise the request will be ignored, and null will be returned.

### get_recorders

> function unsigned get_recorders(
> | ref | uvm_recorder | q[$]
> )

Provides a queue of all transactions within the stream.

#### Parameters

q | A reference to the queue of uvm_recorders

The get_recorders method returns the size of the queue, such that the user can conditionally process the elements.

>     uvm_recorder tr_q[$];
>     if (my_stream.get_recorders(tr_q)) begin
>       // Process the queue...
>     end

### Handles

### get_handle

> function integer get_handle()

Returns a unique ID for this stream.

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

### get_stream_from_handle

> static function uvm_tr_stream get_stream_from_handle(
> | integer | id
> )

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

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

### Implementation Agnostic API

### do_open

> protected virtual function void do_open(
> | uvm_tr_database | db,
> | string | scope,
> | string | stream_type_name
> )

Callback triggered via uvm_tr_database::open_stream.

#### Parameters

db | Database which the stream belongs to
scope | Optional scope
stream_type_name | Optional type name for the stream

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

### do_close

> protected virtual function void do_close()

Callback triggered via close.

The do_close callback can be used to set internal state within the stream, 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 stream, as well as providing a location to record any “freeing” information.

### do_open_recorder

> protected virtual function uvm_recorder do_open_recorder(
> | string | name,
> | time | open_time,
> | string | type_name
> )

Marks the beginning of a new record in the stream.

Backend implementation of open_recorder

## uvm_text_tr_stream

The uvm_text_tr_stream is the default stream implementation for the uvm_text_tr_database.

Summary

uvm_text_tr_stream
The uvm_text_tr_stream is the default stream implementation for the uvm_text_tr_database.
Class Hierarchy
uvm_void
uvm_object
uvm_tr_stream
uvm_text_tr_stream
Class Declaration
> class uvm_text_tr_stream extends uvm_tr_stream
new | Constructor
Implementation Agnostic API |
do_open | Callback triggered via uvm_tr_database::open_stream.
do_close | Callback triggered via uvm_tr_stream::close.
do_free | Callback triggered via uvm_tr_stream::free.
do_open_recorder | Marks the beginning of a new record in the stream

### new

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

Constructor

#### Parameters

name | Instance name

### Implementation Agnostic API

### do_open

> protected virtual function void do_open(
> | uvm_tr_database | db,
> | string | scope,
> | string | stream_type_name
> )

Callback triggered via uvm_tr_database::open_stream.

### do_close

> protected virtual function void do_close()

Callback triggered via uvm_tr_stream::close.

### do_free

> protected virtual function void do_free()

Callback triggered via uvm_tr_stream::free.

### do_open_recorder

> protected virtual function uvm_recorder do_open_recorder(
> | string | name,
> | time | open_time,
> | string | type_name
> )

Marks the beginning of a new record in the stream

Text-backend specific implementation.

> 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_tr_database extends uvm_object

The uvm_tr_database class is intended to hide the underlying database implementation from the end user, as these details are often vendor or tool-specific.

> class uvm_text_tr_stream extends uvm_tr_stream

The uvm_text_tr_stream is the default stream 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_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.

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

Constructor

> function uvm_tr_database get_db()

Returns a reference to the database which contains this stream.

> function string get_scope()

Returns the scope supplied when opening this stream.

> function string get_stream_type_name()

Returns a reference to the database which contains this stream.

> function uvm_tr_stream open_stream(
> | string | name, |  |
> | string | scope | = | "",
> | string | type_name | = | ""
> )

Provides a reference to a stream within the database.

> function void close()

Closes this stream.

> function void free()

Frees this stream.

> function bit is_open()

Returns true if this uvm_tr_stream was opened on the database, but has not yet been closed.

> function bit is_closed()

Returns true if this uvm_tr_stream was closed on the database, but has not yet been freed.

> 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 unsigned get_recorders(
> | ref | uvm_recorder | q[$]
> )

Provides a queue of all transactions within the stream.

> function integer get_handle()

Returns a unique ID for this stream.

> static function uvm_tr_stream get_stream_from_handle(
> | integer | id
> )

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

> protected virtual function void do_open(
> | uvm_tr_database | db,
> | string | scope,
> | string | stream_type_name
> )

Callback triggered via uvm_tr_database::open_stream.

> protected virtual function void do_close()

Callback triggered via close.

> protected virtual function void do_free()

Callback triggered via free.

> protected virtual function uvm_recorder do_open_recorder(
> | string | name,
> | time | open_time,
> | string | type_name
> )

Marks the beginning of a new record in the stream.

> function void close(
> | time | close_time | = | 0
> )

Closes this recorder.

> function void free(
> | time | close_time | = | 0
> )

Frees this recorder

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

Callback triggered via uvm_tr_stream::open_recorder.

> virtual class uvm_recorder extends uvm_object

Abstract class which defines the recorder API.

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

Constructor

> protected virtual function void do_open(
> | uvm_tr_database | db,
> | string | scope,
> | string | stream_type_name
> )

Callback triggered via uvm_tr_database::open_stream.

> protected virtual function void do_close()

Callback triggered via uvm_tr_stream::close.

> protected virtual function void do_free()

Callback triggered via uvm_tr_stream::free.

> protected virtual function uvm_recorder do_open_recorder(
> | string | name,
> | time | open_time,
> | string | type_name
> )

Marks the beginning of a new record in the stream