TLM Generic Payload & Extensions

The Generic Payload transaction represents a generic bus read/write access.  It is used as the default transaction in TLM2 blocking and nonblocking transport interfaces.

Contents
TLM Generic Payload & ExtensionsThe Generic Payload transaction represents a generic bus read/write access.
GlobalsDefines, Constants, enums.
uvm_tlm_command_eCommand attribute type definition
uvm_tlm_response_status_eResponse status attribute type definition
Generic Payload
uvm_tlm_generic_payloadThis class provides a transaction definition commonly used in memory-mapped bus-based systems.
uvm_tlm_gpThis typedef provides a short, more convenient name for the uvm_tlm_generic_payload type.
uvm_tlm_extension_baseThe class uvm_tlm_extension_base is the non-parameterized base class for all generic payload extensions.
uvm_tlm_extensionTLM extension class.

Globals

Defines, Constants, enums.

uvm_tlm_command_e

Command attribute type definition

UVM_TLM_READ_COMMANDBus read operation
UVM_TLM_WRITE_COMMANDBus write operation
UVM_TLM_IGNORE_COMMANDNo bus operation.

uvm_tlm_response_status_e

Response status attribute type definition

UVM_TLM_OK_RESPONSEBus operation completed successfully
UVM_TLM_INCOMPLETE_RESPONSETransaction was not delivered to target
UVM_TLM_GENERIC_ERROR_RESPONSEBus operation had an error
UVM_TLM_ADDRESS_ERROR_RESPONSEInvalid address specified
UVM_TLM_COMMAND_ERROR_RESPONSEInvalid command specified
UVM_TLM_BURST_ERROR_RESPONSEInvalid burst specified
UVM_TLM_BYTE_ENABLE_ERROR_RESPONSEInvalid byte enabling specified

uvm_tlm_generic_payload

This class provides a transaction definition commonly used in memory-mapped bus-based systems.  It’s intended to be a general purpose transaction class that lends itself to many applications.  The class is derived from uvm_sequence_item which enables it to be generated in sequences and transported to drivers through sequencers.

Summary
uvm_tlm_generic_payload
This class provides a transaction definition commonly used in memory-mapped bus-based systems.
Class Hierarchy
Class Declaration
class uvm_tlm_generic_payload extends uvm_sequence_item
m_addressAddress for the bus operation.
m_commandBus operation type.
m_dataData read or to be written.
m_lengthThe number of bytes to be copied to or from the m_data array, inclusive of any bytes disabled by the m_byte_enable attribute.
m_response_statusStatus of the bus operation.
m_dmiDMI mode is not yet supported in the UVM TLM2 subset.
m_byte_enableIndicates valid m_data array elements.
m_byte_enable_lengthThe number of elements in the m_byte_enable array.
m_streaming_widthNumber of bytes transferred on each beat.
newCreate a new instance of the generic payload.
AccessorsThe accessor functions let you set and get each of the members of the generic payload.
get_commandGet the value of the m_command variable
set_commandSet the value of the m_command variable
is_readReturns true if the current value of the m_command variable is UVM_TLM_READ_COMMAND.
set_readSet the current value of the m_command variable to UVM_TLM_READ_COMMAND.
is_writeReturns true if the current value of the m_command variable is UVM_TLM_WRITE_COMMAND.
set_writeSet the current value of the m_command variable to UVM_TLM_WRITE_COMMAND.
set_addressSet the value of the m_address variable
get_addressGet the value of the m_address variable
get_dataReturn the value of the m_data array
set_dataSet the value of the m_data array
get_data_lengthReturn the current size of the m_data array
set_data_lengthSet the value of the m_length
get_streaming_widthGet the value of the m_streaming_width array
set_streaming_widthSet the value of the m_streaming_width array
get_byte_enableReturn the value of the m_byte_enable array
set_byte_enableSet the value of the m_byte_enable array
get_byte_enable_lengthReturn the current size of the m_byte_enable array
set_byte_enable_lengthSet the size m_byte_enable_length of the m_byte_enable array i.e.
set_dmi_allowedDMI hint.
is_dmi_allowedDMI hint.
get_response_statusReturn the current value of the m_response_status variable
set_response_statusSet the current value of the m_response_status variable
is_response_okReturn TRUE if the current value of the m_response_status variable is UVM_TLM_OK_RESPONSE
is_response_errorReturn TRUE if the current value of the m_response_status variable is not UVM_TLM_OK_RESPONSE
get_response_stringReturn the current value of the m_response_status variable as a string
Extensions Mechanism
set_extensionAdd an instance-specific extension.
get_num_extensionsReturn the current number of instance specific extensions.
get_extensionReturn the instance specific extension bound under the specified key.
clear_extensionRemove the instance-specific extension bound under the specified key.
clear_extensionsRemove all instance-specific extensions
pre_randomize()Prepare this class instance for randomization
post_randomize()Clean-up this class instance after randomization

m_address

rand bit [63:0] m_address

Address for the bus operation.  Should be set or read using the set_address and get_address methods.  The variable should be used only when constraining.

For a read command or a write command, the target shall interpret the current value of the address attribute as the start address in the system memory map of the contiguous block of data being read or written.  The address associated with any given byte in the data array is dependent upon the address attribute, the array index, the streaming width attribute, the endianness and the width of the physical bus.

If the target is unable to execute the transaction with the given address attribute (because the address is out-of-range, for example) it shall generate a standard error response.  The recommended response status is UVM_TLM_ADDRESS_ERROR_RESPONSE.

m_command

rand uvm_tlm_command_e m_command

Bus operation type.  Should be set using the set_command, set_read or set_write methods and read using the get_command, is_read or is_write methods.  The variable should be used only when constraining.

If the target is unable to execute a read or write command, it shall generate a standard error response.  The recommended response status is UVM_TLM_COMMAND_ERROR_RESPONSE.

On receipt of a generic payload transaction with the command attribute equal to UVM_TLM_IGNORE_COMMAND, the target shall not execute a write command or a read command not modify any data.  The target may, however, use the value of any attribute in the generic payload, including any extensions.

The command attribute shall be set by the initiator, and shall not be overwritten by any interconnect

m_data

rand byte unsigned m_data[]

Data read or to be written.  Should be set and read using the set_data or get_data methods The variable should be used only when constraining.

For a read command or a write command, the target shall copy data to or from the data array, respectively, honoring the semantics of the remaining attributes of the generic payload.

For a write command or UVM_TLM_IGNORE_COMMAND, the contents of the data array shall be set by the initiator, and shall not be overwritten by any interconnect component or target.  For a read command, the contents of the data array shall be overwritten by the target (honoring the semantics of the byte enable) but by no other component.

Unlike the OSCI TLM-2.0 LRM, there is no requirement on the endiannes of multi-byte data in the generic payload to match the host endianness.  Unlike C++, it is not possible in SystemVerilog to cast an arbitrary data type as an array of bytes.  Therefore, matching the host endianness is not necessary.  In contrast, arbitrary data types may be converted to and from a byte array using the streaming operator and uvm_object objects may be further converted using the uvm_object::pack_bytes() and uvm_object::unpack_bytes() methods.  All that is required is that a consistent mechanism is used to fill the payload data array and later extract data from it.

Should a generic payload be transferred to/from a SystemC model, it will be necessary for any multi-byte data in that generic payload to use/be interpreted using the host endianness.  However, this process is currently outside the scope of this standard.

m_length

rand int unsigned m_length

The number of bytes to be copied to or from the m_data array, inclusive of any bytes disabled by the m_byte_enable attribute.

The data length attribute shall be set by the initiator, and shall not be overwritten by any interconnect component or target.

The data length attribute shall not be set to 0.  In order to transfer zero bytes, the m_command attribute should be set to UVM_TLM_IGNORE_COMMAND.

m_response_status

rand uvm_tlm_response_status_e m_response_status

Status of the bus operation.  Should be set using the set_response_status method and read using the get_response_status, get_response_string, is_response_ok or is_response_error methods.  The variable should be used only when constraining.

The response status attribute shall be set to UVM_TLM_INCOMPLETE_RESPONSE by the initiator, and may be overwritten by the target.  The response status attribute should not be overwritten by any interconnect component, because the default value UVM_TLM_INCOMPLETE_RESPONSE indicates that the transaction was not delivered to the target.

The target may set the response status attribute to UVM_TLM_OK_RESPONSE to indicate that it was able to execute the command successfully, or to one of the five error responses to indicate an error.  The target should choose the appropriate error response depending on the cause of the error.  If a target detects an error but is unable to select a specific error response, it may set the response status to UVM_TLM_GENERIC_ERROR_RESPONSE.

The target shall be responsible for setting the response status attribute at the appropriate point in the lifetime of the transaction.  In the case of the blocking transport interface, this means before returning control from b_transport.  In the case of the non-blocking transport interface and the base protocol, this means before sending the BEGIN_RESP phase or returning a value of UVM_TLM_COMPLETED.

It is recommended that the initiator should always check the response status attribute on receiving a transition to the BEGIN_RESP phase or after the completion of the transaction.  An initiator may choose to ignore the response status if it is known in advance that the value will be UVM_TLM_OK_RESPONSE, perhaps because it is known in advance that the initiator is only connected to targets that always return UVM_TLM_OK_RESPONSE, but in general this will not be the case.  In other words, the initiator ignores the response status at its own risk.

m_dmi

bit m_dmi

DMI mode is not yet supported in the UVM TLM2 subset.  This variable is provided for completeness and interoperability with SystemC.

m_byte_enable

rand byte unsigned m_byte_enable[]

Indicates valid m_data array elements.  Should be set and read using the set_byte_enable or get_byte_enable methods The variable should be used only when constraining.

The elements in the byte enable array shall be interpreted as follows.  A value of 8’h00 shall indicate that that corresponding byte is disabled, and a value of 8’hFF shall indicate that the corresponding byte is enabled.

Byte enables may be used to create burst transfers where the address increment between each beat is greater than the number of significant bytes transferred on each beat, or to place words in selected byte lanes of a bus.  At a more abstract level, byte enables may be used to create “lacy bursts” where the data array of the generic payload has an arbitrary pattern of holes punched in it.

The byte enable mask may be defined by a small pattern applied repeatedly or by a large pattern covering the whole data array.  The byte enable array may be empty, in which case byte enables shall not be used for the current transaction.

The byte enable array shall be set by the initiator and shall not be overwritten by any interconnect component or target.

If the byte enable pointer is not empty, the target shall either implement the semantics of the byte enable as defined below or shall generate a standard error response.  The recommended response status is UVM_TLM_BYTE_ENABLE_ERROR_RESPONSE.

In the case of a write command, any interconnect component or target should ignore the values of any disabled bytes in the m_data array.  In the case of a read command, any interconnect component or target should not modify the values of disabled bytes in the m_data array.

m_byte_enable_length

rand int unsigned m_byte_enable_length

The number of elements in the m_byte_enable array.

It shall be set by the initiator, and shall not be overwritten by any interconnect component or target.

m_streaming_width

rand int unsigned m_streaming_width

Number of bytes transferred on each beat.  Should be set and read using the set_streaming_width or get_streaming_width methods The variable should be used only when constraining.

Streaming affects the way a component should interpret the data array.  A stream consists of a sequence of data transfers occurring on successive notional beats, each beat having the same start address as given by the generic payload address attribute.  The streaming width attribute shall determine the width of the stream, that is, the number of bytes transferred on each beat.  In other words, streaming affects the local address associated with each byte in the data array.  In all other respects, the organization of the data array is unaffected by streaming.

The bytes within the data array have a corresponding sequence of local addresses within the component accessing the generic payload transaction.  The lowest address is given by the value of the address attribute.  The highest address is given by the formula address_attribute + streaming_width - 1.  The address to or from which each byte is being copied in the target shall be set to the value of the address attribute at the start of each beat.

With respect to the interpretation of the data array, a single transaction with a streaming width shall be functionally equivalent to a sequence of transactions each having the same address as the original transaction, each having a data length attribute equal to the streaming width of the original, and each with a data array that is a different subset of the original data array on each beat.  This subset effectively steps down the original data array maintaining the sequence of bytes.

A streaming width of 0 indicates that a streaming transfer is not required. it is equivalent to a streaming width value greater than or equal to the size of the m_data array.

Streaming may be used in conjunction with byte enables, in which case the streaming width would typically be equal to the byte enable length.  It would also make sense to have the streaming width a multiple of the byte enable length.  Having the byte enable length a multiple of the streaming width would imply that different bytes were enabled on each beat.

If the target is unable to execute the transaction with the given streaming width, it shall generate a standard error response.  The recommended response status is TLM_BURST_ERROR_RESPONSE.

new

function new(
    string  name  =  ""
)

Create a new instance of the generic payload.  Initialize all the members to their default values.

Accessors

The accessor functions let you set and get each of the members of the generic payload.  All of the accessor methods are virtual.  This implies a slightly different use model for the generic payload than in SystemC.  The way the generic payload is defined in SystemC does not encourage you to create new transaction types derived from uvm_tlm_generic_payload.  Instead, you would use the extensions mechanism.  Thus in SystemC none of the accessors are virtual.

get_command

virtual function uvm_tlm_command_e get_command()

Get the value of the m_command variable

set_command

virtual function void set_command(
    uvm_tlm_command_e  command
)

Set the value of the m_command variable

is_read

virtual function bit is_read()

Returns true if the current value of the m_command variable is UVM_TLM_READ_COMMAND.

set_read

virtual function void set_read()

Set the current value of the m_command variable to UVM_TLM_READ_COMMAND.

is_write

virtual function bit is_write()

Returns true if the current value of the m_command variable is UVM_TLM_WRITE_COMMAND.

set_write

virtual function void set_write()

Set the current value of the m_command variable to UVM_TLM_WRITE_COMMAND.

set_address

virtual function void set_address(
    bit  [63:0]  addr
)

Set the value of the m_address variable

get_address

virtual function bit [63:0] get_address()

Get the value of the m_address variable

get_data

virtual function void get_data (
    output byte unsigned  []
)

Return the value of the m_data array

set_data

virtual function void set_data(
    ref byte unsigned  []
)

Set the value of the m_data array

get_data_length

virtual function int unsigned get_data_length()

Return the current size of the m_data array

set_data_length

virtual function void set_data_length(
    int  unsigned  length
)

Set the value of the m_length

get_streaming_width

virtual function int unsigned get_streaming_width()

Get the value of the m_streaming_width array

set_streaming_width

virtual function void set_streaming_width(
    int  unsigned  width
)

Set the value of the m_streaming_width array

get_byte_enable

virtual function void get_byte_enable(
    output byte  unsigned  p[]
)

Return the value of the m_byte_enable array

set_byte_enable

virtual function void set_byte_enable(
    ref byte  unsigned  p[]
)

Set the value of the m_byte_enable array

get_byte_enable_length

virtual function int unsigned get_byte_enable_length()

Return the current size of the m_byte_enable array

set_byte_enable_length

virtual function void set_byte_enable_length(
    int  unsigned  length
)

Set the size m_byte_enable_length of the m_byte_enable array i.e.  m_byte_enable.size()

set_dmi_allowed

virtual function void set_dmi_allowed(
    bit  dmi
)

DMI hint.  Set the internal flag m_dmi to allow dmi access

is_dmi_allowed

virtual function bit is_dmi_allowed()

DMI hint.  Query the internal flag m_dmi if allowed dmi access

get_response_status

virtual function uvm_tlm_response_status_e get_response_status()

Return the current value of the m_response_status variable

set_response_status

virtual function void set_response_status(
    uvm_tlm_response_status_e  status
)

Set the current value of the m_response_status variable

is_response_ok

virtual function bit is_response_ok()

Return TRUE if the current value of the m_response_status variable is UVM_TLM_OK_RESPONSE

is_response_error

virtual function bit is_response_error()

Return TRUE if the current value of the m_response_status variable is not UVM_TLM_OK_RESPONSE

get_response_string

virtual function string get_response_string()

Return the current value of the m_response_status variable as a string

set_extension

function uvm_tlm_extension_base set_extension(
    uvm_tlm_extension_base  ext
)

Add an instance-specific extension.  Only one instance of any given extension type is allowed.  If there is an existing extension instance of the type of ext, ext replaces it and its handle is returned.  Otherwise, null is returned.

get_num_extensions

function int get_num_extensions()

Return the current number of instance specific extensions.

get_extension

function uvm_tlm_extension_base get_extension(
    uvm_tlm_extension_base  ext_handle
)

Return the instance specific extension bound under the specified key.  If no extension is bound under that key, null is returned.

clear_extension

function void clear_extension(
    uvm_tlm_extension_base  ext_handle
)

Remove the instance-specific extension bound under the specified key.

clear_extensions

function void clear_extensions()

Remove all instance-specific extensions

pre_randomize()

function void pre_randomize()

Prepare this class instance for randomization

post_randomize()

function void post_randomize()

Clean-up this class instance after randomization

uvm_tlm_gp

This typedef provides a short, more convenient name for the uvm_tlm_generic_payload type.

Summary
uvm_tlm_gp
This typedef provides a short, more convenient name for the uvm_tlm_generic_payload type.
Class Declaration
typedef uvm_tlm_generic_payload uvm_tlm_gp

uvm_tlm_extension_base

The class uvm_tlm_extension_base is the non-parameterized base class for all generic payload extensions.  It includes the utility do_copy() and create().  The pure virtual function get_type_handle() allows you to get a unique handle that represents the derived type.  This is implemented in derived classes.

This class is never used directly by users.  The uvm_tlm_extension class is used instead.

Summary
uvm_tlm_extension_base
The class uvm_tlm_extension_base is the non-parameterized base class for all generic payload extensions.
Class Hierarchy
uvm_tlm_extension_base
Class Declaration
virtual class uvm_tlm_extension_base extends uvm_object
Methods
new
get_type_handleAn interface to polymorphically retrieve a handle that uniquely identifies the type of the sub-class
get_type_handle_nameAn interface to polymorphically retrieve the name that uniquely identifies the type of the sub-class
create

new

function new(
    string  name  =  ""
)

get_type_handle

pure virtual function uvm_tlm_extension_base get_type_handle()

An interface to polymorphically retrieve a handle that uniquely identifies the type of the sub-class

get_type_handle_name

pure virtual function string get_type_handle_name()

An interface to polymorphically retrieve the name that uniquely identifies the type of the sub-class

create

virtual function uvm_object create (
    string  name  =  ""
)

uvm_tlm_extension

TLM extension class.  The class is parameterized with arbitrary type which represents the type of the extension.  An instance of the generic payload can contain one extension object of each type; it cannot contain two instances of the same extension type.

The extension type can be identified using the ID() method.

To implement a generic payload extension, simply derive a new class from this class and specify the name of the derived class as the extension parameter.

class my_ID extends uvm_tlm_extension#(my_ID);
  int ID;

  `uvm_object_utils_begin(my_ID)
     `uvm_field_int(ID, UVM_ALL_ON)
  `uvm_object_utils_end

  function new(string name = "my_ID");
     super.new(name);
  endfunction
endclass
Summary
uvm_tlm_extension
TLM extension class.
Class Hierarchy
Class Declaration
class uvm_tlm_extension #(
    type  T  =  int
) extends uvm_tlm_extension_base
Methods
newcreates a new extension object.
ID()Return the unique ID of this TLM extension type.

new

function new(
    string  name  =  ""
)

creates a new extension object.

ID()

static function this_type ID()

Return the unique ID of this TLM extension type.  This method is used to identify the type of the extension to retrieve from a uvm_tlm_generic_payload instance, using the uvm_tlm_generic_payload::get_extension() method.

class uvm_tlm_generic_payload extends uvm_sequence_item
This class provides a transaction definition commonly used in memory-mapped bus-based systems.
typedef uvm_tlm_generic_payload uvm_tlm_gp
This typedef provides a short, more convenient name for the uvm_tlm_generic_payload type.
virtual class uvm_tlm_extension_base extends uvm_object
The class uvm_tlm_extension_base is the non-parameterized base class for all generic payload extensions.
class uvm_tlm_extension #(
    type  T  =  int
) extends uvm_tlm_extension_base
TLM extension class.
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.
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.
rand bit [63:0] m_address
Address for the bus operation.
rand uvm_tlm_command_e m_command
Bus operation type.
rand byte unsigned m_data[]
Data read or to be written.
rand int unsigned m_length
The number of bytes to be copied to or from the m_data array, inclusive of any bytes disabled by the m_byte_enable attribute.
rand byte unsigned m_byte_enable[]
Indicates valid m_data array elements.
rand uvm_tlm_response_status_e m_response_status
Status of the bus operation.
bit m_dmi
DMI mode is not yet supported in the UVM TLM2 subset.
rand int unsigned m_byte_enable_length
The number of elements in the m_byte_enable array.
rand int unsigned m_streaming_width
Number of bytes transferred on each beat.
function new(
    string  name  =  ""
)
Create a new instance of the generic payload.
virtual function uvm_tlm_command_e get_command()
Get the value of the m_command variable
virtual function void set_command(
    uvm_tlm_command_e  command
)
Set the value of the m_command variable
virtual function bit is_read()
Returns true if the current value of the m_command variable is UVM_TLM_READ_COMMAND.
virtual function void set_read()
Set the current value of the m_command variable to UVM_TLM_READ_COMMAND.
virtual function bit is_write()
Returns true if the current value of the m_command variable is UVM_TLM_WRITE_COMMAND.
virtual function void set_write()
Set the current value of the m_command variable to UVM_TLM_WRITE_COMMAND.
virtual function void set_address(
    bit  [63:0]  addr
)
Set the value of the m_address variable
virtual function bit [63:0] get_address()
Get the value of the m_address variable
virtual function void get_data (
    output byte unsigned  []
)
Return the value of the m_data array
virtual function void set_data(
    ref byte unsigned  []
)
Set the value of the m_data array
virtual function int unsigned get_data_length()
Return the current size of the m_data array
virtual function void set_data_length(
    int  unsigned  length
)
Set the value of the m_length
virtual function int unsigned get_streaming_width()
Get the value of the m_streaming_width array
virtual function void set_streaming_width(
    int  unsigned  width
)
Set the value of the m_streaming_width array
virtual function void get_byte_enable(
    output byte  unsigned  p[]
)
Return the value of the m_byte_enable array
virtual function void set_byte_enable(
    ref byte  unsigned  p[]
)
Set the value of the m_byte_enable array
virtual function int unsigned get_byte_enable_length()
Return the current size of the m_byte_enable array
virtual function void set_byte_enable_length(
    int  unsigned  length
)
Set the size m_byte_enable_length of the m_byte_enable array i.e.
virtual function void set_dmi_allowed(
    bit  dmi
)
DMI hint.
virtual function bit is_dmi_allowed()
DMI hint.
virtual function uvm_tlm_response_status_e get_response_status()
Return the current value of the m_response_status variable
virtual function void set_response_status(
    uvm_tlm_response_status_e  status
)
Set the current value of the m_response_status variable
virtual function bit is_response_ok()
Return TRUE if the current value of the m_response_status variable is UVM_TLM_OK_RESPONSE
virtual function bit is_response_error()
Return TRUE if the current value of the m_response_status variable is not UVM_TLM_OK_RESPONSE
virtual function string get_response_string()
Return the current value of the m_response_status variable as a string
function uvm_tlm_extension_base set_extension(
    uvm_tlm_extension_base  ext
)
Add an instance-specific extension.
function int get_num_extensions()
Return the current number of instance specific extensions.
function uvm_tlm_extension_base get_extension(
    uvm_tlm_extension_base  ext_handle
)
Return the instance specific extension bound under the specified key.
function void clear_extension(
    uvm_tlm_extension_base  ext_handle
)
Remove the instance-specific extension bound under the specified key.
function void clear_extensions()
Remove all instance-specific extensions
function void pre_randomize()
Prepare this class instance for randomization
function void post_randomize()
Clean-up this class instance after randomization
function int pack_bytes (
    ref byte  unsigned  bytestream[],   
    input  uvm_packer  packer  =  null
)
function int unpack_bytes (
    ref byte  unsigned  bytestream[],   
    input  uvm_packer  packer  =  null
)
No bus operation.
function new(
    string  name  =  ""
)
pure virtual function uvm_tlm_extension_base get_type_handle()
An interface to polymorphically retrieve a handle that uniquely identifies the type of the sub-class
pure virtual function string get_type_handle_name()
An interface to polymorphically retrieve the name that uniquely identifies the type of the sub-class
virtual function uvm_object create (
    string  name  =  ""
)
function new(
    string  name  =  ""
)
creates a new extension object.
static function this_type ID()
Return the unique ID of this TLM extension type.