# uvm_transaction

The uvm_transaction class is the root base class for UVM transactions. Inheriting all the methods of uvm_object, uvm_transaction adds a timing and recording interface.

This class provides timestamp properties, notification events, and transaction recording support.

Use of this class as a base for user-defined transactions is deprecated. Its subtype, uvm_sequence_item, shall be used as the base class for all user-defined transaction types.

The intended use of this API is via a uvm_driver #(REQ,RSP) to call uvm_component::accept_tr, uvm_component::begin_tr, and uvm_component::end_tr during the course of sequence item execution. These methods in the component base class will call into the corresponding methods in this class to set the corresponding timestamps (accept_time, begin_time, and end_time), trigger the corresponding event (begin_event and end_event, and, if enabled, record the transaction contents to a vendor-specific transaction database.

Note that get_next_item/item_done when called on a uvm_seq_item_pull_port will automatically trigger the begin_event and end_events via calls to begin_tr and end_tr. While convenient, it is generally the responsibility of drivers to mark a transaction’s progress during execution. To allow the driver or layering sequence to control sequence item timestamps, events, and recording, you must call uvm_sqr_if_base#(REQ,RSP)::disable_auto_item_recording at the beginning of the driver’s run_phase task.

Users may also use the transaction’s event pool, events, to define custom events for the driver to trigger and the sequences to wait on. Any in-between events such as marking the beginning of the address and data phases of transaction execution could be implemented via the events pool.

In pipelined protocols, the driver may release a sequence (return from finish_item() or it’s `uvm_do macro) before the item has been completed. If the driver uses the begin_tr/end_tr API in uvm_component, the sequence can wait on the item’s end_event to block until the item was fully executed, as in the following example.

>     task uvm_execute(item, ...);
>         // can use the `uvm_do macros as well
>         start_item(item);
>         item.randomize();
>         finish_item(item);
>         item.end_event.wait_on();
>         // get_response(rsp, item.get_transaction_id()); //if needed
>     endtask

A simple two-stage pipeline driver that can execute address and data phases concurrently might be implemented as follows:

>     task run();
>         // this driver supports a two-deep pipeline
>         fork
>           do_item();
>           do_item();
>         join
>     endtask

>     task do_item();

>       forever begin
>         mbus_item req;

>         lock.get();

>         seq_item_port.get(req); // Completes the sequencer-driver handshake

>         accept_tr(req);

>           // request bus, wait for grant, etc.

>         begin_tr(req);

>           // execute address phase

>         // allows next transaction to begin address phase
>         lock.put();

>           // execute data phase
>           // (may trigger custom "data_phase" event here)

>         end_tr(req);

>       end

>     endtask: do_item

Summary

uvm_transaction
The uvm_transaction class is the root base class for UVM transactions.
Class Hierarchy
uvm_void
uvm_object
uvm_transaction
Class Declaration
> virtual class uvm_transaction extends uvm_object
Methods |
new | Creates a new transaction object.
accept_tr | Calling accept_tr indicates that the transaction item has been received by a consumer component.
do_accept_tr | This user-definable callback is called by accept_tr just before the accept event is triggered.
begin_tr | This function indicates that the transaction has been started and is not the child of another transaction.
begin_child_tr | This function indicates that the transaction has been started as a child of a parent transaction given by parent_handle.
do_begin_tr | This user-definable callback is called by begin_tr and begin_child_tr just before the begin event is triggered.
end_tr | This function indicates that the transaction execution has ended.
do_end_tr | This user-definable callback is called by end_tr just before the end event is triggered.
get_tr_handle | Returns the handle associated with the transaction, as set by a previous call to begin_child_tr or begin_tr with transaction recording enabled.
disable_recording | Turns off recording for the transaction stream.
enable_recording | Turns on recording to the stream specified.
is_recording_enabled | Returns 1 if recording is currently on, 0 otherwise.
is_active | Returns 1 if the transaction has been started but has not yet been ended.
get_event_pool | Returns the event pool associated with this transaction.
set_initiator | Sets initiator as the initiator of this transaction.
get_initiator | Returns the component that produced or started the transaction, as set by a previous call to set_initiator.
get_accept_time |
get_begin_time |
get_end_time | Returns the time at which this transaction was accepted, begun, or ended, as by a previous call to accept_tr, begin_tr, begin_child_tr, or end_tr.
set_transaction_id | Sets this transaction’s numeric identifier to id.
get_transaction_id | Returns this transaction’s numeric identifier, which is -1 if not set explicitly by set_transaction_id.
Variables |
events | The event pool instance for this transaction.
begin_event | A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on the bus begins, typically as a result of a driver calling uvm_component::begin_tr.
end_event | A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on the bus ends, typically as a result of a driver calling uvm_component::end_tr.

### Methods

### new

> function new (
> | string | name | = | "",
> | uvm_component | initiator | = | null
> )

Creates a new transaction object. The name is the instance name of the transaction. If not supplied, then the object is unnamed.

### accept_tr

> function void accept_tr (
> | time | accept_time | = | 0
> )

Calling accept_tr indicates that the transaction item has been received by a consumer component. Typically a uvm_driver #(REQ,RSP) would call uvm_component::accept_tr, which calls this method-- upon return from a get_next_item(), get(), or peek() call on its sequencer port, uvm_driver#(REQ,RSP)::seq_item_port.

With some protocols, the received item may not be started immediately after it is accepted. For example, a bus driver, having accepted a request transaction, may still have to wait for a bus grant before beginning to execute the request.

#### This function performs the following actions

- The transaction’s internal accept time is set to the current simulation time, or to accept_time if provided and non-zero. The accept_time may be any time, past or future.
- The transaction’s internal accept event is triggered. Any processes waiting on the this event will resume in the next delta cycle.
- The do_accept_tr method is called to allow for any post-accept action in derived classes.

### do_accept_tr

> virtual protected function void do_accept_tr ()

This user-definable callback is called by accept_tr just before the accept event is triggered. Implementations should call super.do_accept_tr to ensure correct operation.

### begin_tr

> 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. Generally, a consumer component begins execution of a transactions it receives.

Typically a uvm_driver #(REQ,RSP) would call uvm_component::begin_tr, which calls this method, before actual execution of a sequence item transaction. Sequence items received by a driver are always a child of a parent sequence. In this case, begin_tr obtains the parent handle and delegates to begin_child_tr.

See accept_tr for more information on how the begin-time might differ from when the transaction item was received.

#### This function performs the following actions

- The transaction’s internal start time is set to the current simulation time, or to begin_time if provided and non-zero. The begin_time may be any time, past or future, but should not be less than the accept time.
- If recording is enabled, then a new database-transaction is started with the same begin time as above.
- The do_begin_tr method is called to allow for any post-begin action in derived classes.
- The transaction’s internal begin event is triggered. Any processes waiting on this event will resume in the next delta cycle.

The return value is a transaction handle, which is valid (non-zero) only if recording is enabled. The meaning of the handle is implementation specific.

### begin_child_tr

> function integer begin_child_tr (
> | time | begin_time | = | 0,
> | integer | parent_handle | = | 0
> )

This function indicates that the transaction has been started as a child of a parent transaction given by parent_handle. Generally, a consumer component calls this method via uvm_component::begin_child_tr to indicate the actual start of execution of this transaction.

The parent handle is obtained by a previous call to begin_tr or begin_child_tr. If the parent_handle is invalid (=0), then this function behaves the same as begin_tr.

#### This function performs the following actions

- The transaction’s internal start time is set to the current simulation time, or to begin_time if provided and non-zero. The begin_time may be any time, past or future, but should not be less than the accept time.
- If recording is enabled, then a new database-transaction is started with the same begin time as above. The inherited uvm_object::record method is then called, which records the current property values to this new transaction. Finally, the newly started transaction is linked to the parent transaction given by parent_handle.
- The do_begin_tr method is called to allow for any post-begin action in derived classes.
- The transaction’s internal begin event is triggered. Any processes waiting on this event will resume in the next delta cycle.

The return value is a transaction handle, which is valid (non-zero) only if recording is enabled. The meaning of the handle is implementation specific.

### do_begin_tr

> virtual protected function void do_begin_tr ()

This user-definable callback is called by begin_tr and begin_child_tr just before the begin event is triggered. Implementations should call super.do_begin_tr to ensure correct operation.

### end_tr

> function void end_tr (
> | time | end_time | = | 0,
> | bit | free_handle | = | 1
> )

This function indicates that the transaction execution has ended. Generally, a consumer component ends execution of the transactions it receives.

You must have previously called begin_tr or begin_child_tr for this call to be successful.

Typically a uvm_driver #(REQ,RSP) would call uvm_component::end_tr, which calls this method, upon completion of a sequence item transaction. Sequence items received by a driver are always a child of a parent sequence. In this case, begin_tr obtain the parent handle and delegate to begin_child_tr.

#### This function performs the following actions

- The transaction’s internal end time is set to the current simulation time, or to end_time if provided and non-zero. The end_time may be any time, past or future, but should not be less than the begin time.
- If recording is enabled and a database-transaction is currently active, then the record method inherited from uvm_object is called, which records the final property values. The transaction is then ended. If free_handle is set, the transaction is released and can no longer be linked to (if supported by the implementation).
- The do_end_tr method is called to allow for any post-end action in derived classes.
- The transaction’s internal end event is triggered. Any processes waiting on this event will resume in the next delta cycle.

### do_end_tr

> virtual protected function void do_end_tr ()

This user-definable callback is called by end_tr just before the end event is triggered. Implementations should call super.do_end_tr to ensure correct operation.

### get_tr_handle

> function integer get_tr_handle ()

Returns the handle associated with the transaction, as set by a previous call to begin_child_tr or begin_tr with transaction recording enabled.

### disable_recording

> function void disable_recording ()

Turns off recording for the transaction stream. This method does not effect a uvm_component’s recording streams.

### enable_recording

> function void enable_recording (
> | uvm_tr_stream | stream
> )

Turns on recording to the stream specified.

If transaction recording is on, then a call to record is made when the transaction is ended.

### is_recording_enabled

> function bit is_recording_enabled()

Returns 1 if recording is currently on, 0 otherwise.

### is_active

> function bit is_active ()

Returns 1 if the transaction has been started but has not yet been ended. Returns 0 if the transaction has not been started.

### get_event_pool

> function uvm_event_pool get_event_pool ()

Returns the event pool associated with this transaction.

By default, the event pool contains the events: begin, accept, and end. Events can also be added by derivative objects. An event pool is a specialization of uvm_pool#(KEY,T), e.g. a uvm_pool#(uvm_event).

### set_initiator

> function void set_initiator (
> | uvm_component | initiator
> )

Sets initiator as the initiator of this transaction.

The initiator can be the component that produces the transaction. It can also be the component that started the transaction. This or any other usage is up to the transaction designer.

### get_initiator

> function uvm_component get_initiator ()

Returns the component that produced or started the transaction, as set by a previous call to set_initiator.

### get_accept_time

> function time get_accept_time ()

### get_begin_time

> function time get_begin_time ()

### get_end_time

> function time get_end_time ()

Returns the time at which this transaction was accepted, begun, or ended, as by a previous call to accept_tr, begin_tr, begin_child_tr, or end_tr.

### set_transaction_id

> function void set_transaction_id(
> | integer | id
> )

Sets this transaction’s numeric identifier to id. If not set via this method, the transaction ID defaults to -1.

When using sequences to generate stimulus, the transaction ID is used along with the sequence ID to route responses in sequencers and to correlate responses to requests.

### get_transaction_id

> function integer get_transaction_id()

Returns this transaction’s numeric identifier, which is -1 if not set explicitly by set_transaction_id.

When using a uvm_sequence #(REQ,RSP) to generate stimulus, the transaction ID is used along with the sequence ID to route responses in sequencers and to correlate responses to requests.

### Variables

### events

> const uvm_event_pool events = new

The event pool instance for this transaction. This pool is used to track various milestones: by default, begin, accept, and end

### begin_event

> uvm_event#(
> | uvm_object
> ) begin_event

A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on the bus begins, typically as a result of a driver calling uvm_component::begin_tr. Processes that wait on this event will block until the transaction has begun.

For more information, see the general discussion for uvm_transaction. See uvm_event#(T) for details on the event API.

### end_event

> uvm_event#(
> | uvm_object
> ) end_event

A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on the bus ends, typically as a result of a driver calling uvm_component::end_tr. Processes that wait on this event will block until the transaction has ended.

For more information, see the general discussion for uvm_transaction. See uvm_event#(T) for details on the event API.

>     virtual task my_sequence::body();
>      ...
>      start_item(item);    \
>      item.randomize();     } `uvm_do(item)
>      finish_item(item);   /
>      // return from finish item does not always mean item is completed
>      item.end_event.wait_on();
>      ...

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

> virtual class uvm_transaction extends uvm_object

The uvm_transaction class is the root base class for UVM transactions.

> function new (
> | string | name | = | "",
> | uvm_component | initiator | = | null
> )

Creates a new transaction object.

> function void accept_tr (
> | time | accept_time | = | 0
> )

Calling accept_tr indicates that the transaction item has been received by a consumer component.

> virtual protected function void do_accept_tr ()

This user-definable callback is called by accept_tr just before the accept event is triggered.

> 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_child_tr (
> | time | begin_time | = | 0,
> | integer | parent_handle | = | 0
> )

This function indicates that the transaction has been started as a child of a parent transaction given by parent_handle.

> virtual protected function void do_begin_tr ()

This user-definable callback is called by begin_tr and begin_child_tr just before the begin event is triggered.

> function void end_tr (
> | time | end_time | = | 0,
> | bit | free_handle | = | 1
> )

This function indicates that the transaction execution has ended.

> virtual protected function void do_end_tr ()

This user-definable callback is called by end_tr just before the end event is triggered.

> function integer get_tr_handle ()

Returns the handle associated with the transaction, as set by a previous call to begin_child_tr or begin_tr with transaction recording enabled.

> function void disable_recording ()

Turns off recording for the transaction stream.

> function void enable_recording (
> | uvm_tr_stream | stream
> )

Turns on recording to the stream specified.

> function bit is_recording_enabled()

Returns 1 if recording is currently on, 0 otherwise.

> function bit is_active ()

Returns 1 if the transaction has been started but has not yet been ended.

> function uvm_event_pool get_event_pool ()

Returns the event pool associated with this transaction.

> function void set_initiator (
> | uvm_component | initiator
> )

Sets initiator as the initiator of this transaction.

> function uvm_component get_initiator ()

Returns the component that produced or started the transaction, as set by a previous call to set_initiator.

> function time get_accept_time ()

> function time get_begin_time ()

> function time get_end_time ()

Returns the time at which this transaction was accepted, begun, or ended, as by a previous call to accept_tr, begin_tr, begin_child_tr, or end_tr.

> function void set_transaction_id(
> | integer | id
> )

Sets this transaction’s numeric identifier to id.

> function integer get_transaction_id()

Returns this transaction’s numeric identifier, which is -1 if not set explicitly by set_transaction_id.

> const uvm_event_pool events = new

The event pool instance for this transaction.

> uvm_event#(
> | uvm_object
> ) begin_event

A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on the bus begins, typically as a result of a driver calling uvm_component::begin_tr.

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

> uvm_event#(
> | uvm_object
> ) end_event

A uvm_event#(uvm_object) that is triggered when this transaction’s actual execution on the bus ends, typically as a result of a driver calling uvm_component::end_tr.

> function void end_tr (
> | uvm_transaction | tr, |  |
> | time | end_time | = | 0,
> | bit | free_handle | = | 1
> )

This function marks the end of a transaction, tr, by this component.

> class uvm_sequence_item extends uvm_transaction

The base class for user-defined sequence items and also the base class for the uvm_sequence class.

> class uvm_driver #(
> | type | REQ | = | uvm_sequence_item,
> | type | RSP | = | REQ
> ) extends uvm_component

The base class for drivers that initiate requests for new transactions via a uvm_seq_item_pull_port.

> function void accept_tr (
> | uvm_transaction | tr, |  |
> | time | accept_time | = | 0
> )

This function marks the acceptance of a transaction, tr, by this component.

> virtual function void disable_auto_item_recording()

By default, item recording is performed automatically when get_next_item() and item_done() are called.
Derived driver classes should use this port to request items from the sequencer.

> function integer begin_child_tr (
> | uvm_transaction | tr, |  |
> | integer | parent_handle | = | 0,
> | string | stream_name | = | "main",
> | string | label | = | "",
> | string | desc | = | "",
> | time | begin_time | = | 0
> )

This function marks the start of a child transaction, tr, by this component.

> function void record (
> | uvm_recorder | recorder | = | null
> )

The record method deep-records this object’s properties according to an optional recorder policy.

> virtual class uvm_component extends uvm_report_object

The uvm_component class is the root base class for UVM components.

> class uvm_pool #(
> | type | KEY | = | int,
> |  | T | = | uvm_void
> ) extends uvm_object

Implements a class-based dynamic associative array.

> virtual class uvm_sequence #(
> | type | REQ | = | uvm_sequence_item,
> | type | RSP | = | REQ
> ) extends uvm_sequence_base

The uvm_sequence class provides the interfaces necessary in order to create streams of sequence items and/or other sequences.

> class uvm_event#(
> | type | T | = | uvm_object
> ) extends uvm_event_base

The uvm_event class is an extension of the abstract uvm_event_base class.