Virtual Registers

A virtual register is a collection of fields, overlaid on top of a memory, usually in an array.  The semantics and layout of virtual registers comes from an agreement between the software and the hardware, not any physical structures in the DUT.

Contents
Virtual RegistersA virtual register is a collection of fields, overlaid on top of a memory, usually in an array.
uvm_vregVirtual register abstraction base class
uvm_vreg_cbsPre/post read/write callback facade class

uvm_vreg

Virtual register abstraction base class

A virtual register represents a set of fields that are logically implemented in consecutive memory locations.

All virtual register accesses eventually turn into memory accesses.

A virtual register array may be implemented on top of any memory abstraction class and possibly dynamically resized and/or relocated.

Summary
uvm_vreg
Virtual register abstraction base class
Class Hierarchy
uvm_vreg
Class Declaration
class uvm_vreg extends uvm_object
Initialization
newCreate a new instance and type-specific configuration
configureInstance-specific configuration
implementDynamically implement, resize or relocate a virtual register array
allocateRandomly implement, resize or relocate a virtual register array
get_regionGet the region where the virtual register array is implemented
release_regionDynamically un-implement a virtual register array
Introspection
get_nameGet the simple name
get_full_nameGet the hierarchical name
get_parentGet the parent block
get_memoryGet the memory where the virtual register array is implemented
get_n_mapsReturns the number of address maps this virtual register array is mapped in
is_in_mapReturn TRUE if this virtual register array is in the specified address map
get_mapsReturns all of the address maps where this virtual register array is mapped
get_rightsReturns the access rights of this virtual register array
get_accessReturns the access policy of the virtual register array when written and read via an address map.
get_sizeReturns the size of the virtual register array.
get_n_bytesReturns the width, in bytes, of a virtual register.
get_n_memlocsReturns the number of memory locations used by a single virtual register.
get_incrReturns the number of memory locations between two individual virtual registers in the same array.
get_fieldsReturn the virtual fields in this virtual register
get_field_by_nameReturn the named virtual field in this virtual register
get_offset_in_memoryReturns the offset of a virtual register
get_addressReturns the base external physical address of a virtual register
HDL Access
writeWrite the specified value in a virtual register
readRead the current value from a virtual register
pokeDeposit the specified value in a virtual register
peekSample the current value in a virtual register
resetReset the access semaphore
Callbacks
pre_writeCalled before virtual register write.
post_writeCalled after virtual register write.
pre_readCalled before virtual register read.
post_readCalled after virtual register read.

new

function new(
    string  name,
    int  unsigned  n_bits
)

Create a new instance and type-specific configuration

Creates an instance of a virtual register abstraction class with the specified name.

n_bits specifies the total number of bits in a virtual register.  Not all bits need to be mapped to a virtual field.  This value is usually a multiple of 8.

configure

function void configure(
    uvm_reg_block  parent,   
    uvm_mem  mem  =  null,
    longint  unsigned  size  =  0,
    uvm_reg_addr_t  offset  =  0,
    int  unsigned  incr  =  0
)

Instance-specific configuration

Specify the parent block of this virtual register array.  If one of the other parameters are specified, the virtual register is assumed to be dynamic and can be later (re-)implemented using the uvm_vreg::implement() method.

If mem is specified, then the virtual register array is assumed to be statically implemented in the memory corresponding to the specified memory abstraction class and size, offset and incr must also be specified.  Static virtual register arrays cannot be re-implemented.

implement

virtual function bit implement(
    longint  unsigned  n,   
    uvm_mem  mem  =  null,
    uvm_reg_addr_t  offset  =  0,
    int  unsigned  incr  =  0
)

Dynamically implement, resize or relocate a virtual register array

Implement an array of virtual registers of the specified size, in the specified memory and offset.  If an offset increment is specified, each virtual register is implemented at the specified offset increment from the previous one.  If an offset increment of 0 is specified, virtual registers are packed as closely as possible in the memory.

If no memory is specified, the virtual register array is in the same memory, at the same base offset using the same offset increment as originally implemented.  Only the number of virtual registers in the virtual register array is modified.

The initial value of the newly-implemented or relocated set of virtual registers is whatever values are currently stored in the memory now implementing them.

Returns TRUE if the memory can implement the number of virtual registers at the specified base offset and offset increment.  Returns FALSE otherwise.

The memory region used to implement a virtual register array is reserved in the memory allocation manager associated with the memory to prevent it from being allocated for another purpose.

allocate

virtual function uvm_mem_region allocate(
    longint  unsigned  n,   
    uvm_mem_mam  mam,   
    uvm_mem_mam_policy  alloc  =  null
)

Randomly implement, resize or relocate a virtual register array

Implement a virtual register array of the specified size in a randomly allocated region of the appropriate size in the address space managed by the specified memory allocation manager.  If a memory allocation policy is specified, it is passed to the uvm_mem_mam::request_region() method.

The initial value of the newly-implemented or relocated set of virtual registers is whatever values are currently stored in the memory region now implementing them.

Returns a reference to a uvm_mem_region memory region descriptor if the memory allocation manager was able to allocate a region that can implement the virtual register array with the specified allocation policy.  Returns null otherwise.

A region implementing a virtual register array must not be released using the uvm_mem_mam::release_region() method.  It must be released using the uvm_vreg::release_region() method.

get_region

virtual function uvm_mem_region get_region()

Get the region where the virtual register array is implemented

Returns a reference to the uvm_mem_region memory region descriptor that implements the virtual register array.

Returns null if the virtual registers array is not currently implemented.  A region implementing a virtual register array must not be released using the uvm_mem_mam::release_region() method.  It must be released using the uvm_vreg::release_region() method.

release_region

virtual function void release_region()

Dynamically un-implement a virtual register array

Release the memory region used to implement a virtual register array and return it to the pool of available memory that can be allocated by the memory’s default allocation manager.  The virtual register array is subsequently considered as unimplemented and can no longer be accessed.

Statically-implemented virtual registers cannot be released.

get_name

Get the simple name

Return the simple object name of this register.

get_full_name

virtual function string get_full_name()

Get the hierarchical name

Return the hierarchal name of this register.  The base of the hierarchical name is the root block.

get_parent

virtual function uvm_reg_block get_parent()

Get the parent block

get_memory

virtual function uvm_mem get_memory()

Get the memory where the virtual register array is implemented

get_n_maps

virtual function int get_n_maps ()

Returns the number of address maps this virtual register array is mapped in

is_in_map

function bit is_in_map (
    uvm_reg_map  map
)

Return TRUE if this virtual register array is in the specified address map

get_maps

virtual function void get_maps (
    ref  uvm_reg_map  maps[$]
)

Returns all of the address maps where this virtual register array is mapped

get_rights

virtual function string get_rights(
    uvm_reg_map  map  =  null
)

Returns the access rights of this virtual register array

Returns “RW”, “RO” or “WO”.  The access rights of a virtual register array is always “RW”, unless it is implemented in a shared memory with access restriction in a particular address map.

If no address map is specified and the memory is mapped in only one address map, that address map is used.  If the memory is mapped in more than one address map, the default address map of the parent block is used.

If an address map is specified and the memory is not mapped in the specified address map, an error message is issued and “RW” is returned.

get_access

virtual function string get_access(
    uvm_reg_map  map  =  null
)

Returns the access policy of the virtual register array when written and read via an address map.

If the memory implementing the virtual register array is mapped in more than one address map, an address map must be specified.  If access restrictions are present when accessing a memory through the specified address map, the access mode returned takes the access restrictions into account.  For example, a read-write memory accessed through an address map with read-only restrictions would return “RO”.

get_size

virtual function int unsigned get_size()

Returns the size of the virtual register array.

get_n_bytes

virtual function int unsigned get_n_bytes()

Returns the width, in bytes, of a virtual register.

The width of a virtual register is always a multiple of the width of the memory locations used to implement it.  For example, a virtual register containing two 1-byte fields implemented in a memory with 4-bytes memory locations is 4-byte wide.

get_n_memlocs

virtual function int unsigned get_n_memlocs()

Returns the number of memory locations used by a single virtual register.

get_incr

virtual function int unsigned get_incr()

Returns the number of memory locations between two individual virtual registers in the same array.

get_fields

virtual function void get_fields(
    ref  uvm_vreg_field  fields[$]
)

Return the virtual fields in this virtual register

Fills the specified array with the abstraction class for all of the virtual fields contained in this virtual register.  Fields are ordered from least-significant position to most-significant position within the register.

get_field_by_name

virtual function uvm_vreg_field get_field_by_name(
    string  name
)

Return the named virtual field in this virtual register

Finds a virtual field with the specified name in this virtual register and returns its abstraction class.  If no fields are found, returns null.

get_offset_in_memory

virtual function uvm_reg_addr_t get_offset_in_memory(
    longint  unsigned  idx
)

Returns the offset of a virtual register

Returns the base offset of the specified virtual register, in the overall address space of the memory that implements the virtual register array.

get_address

virtual function uvm_reg_addr_t get_address(
    longint  unsigned  idx,   
    uvm_reg_map  map  =  null
)

Returns the base external physical address of a virtual register

Returns the base external physical address of the specified virtual register if accessed through the specified address map.

If no address map is specified and the memory implementing the virtual register array is mapped in only one address map, that address map is used.  If the memory is mapped in more than one address map, the default address map of the parent block is used.

If an address map is specified and the memory is not mapped in the specified address map, an error message is issued.

write

virtual task write(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    input  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Write the specified value in a virtual register

Write value in the DUT memory location(s) that implements the virtual register array that corresponds to this abstraction class instance using the specified access path.

If the memory implementing the virtual register array is mapped in more than one address map, an address map must be specified if a physical access is used (front-door access).

The operation is eventually mapped into set of memory-write operations at the location where the virtual register specified by idx in the virtual register array is implemented.

read

virtual task read(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    output  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Read the current value from a virtual register

Read from the DUT memory location(s) that implements the virtual register array that corresponds to this abstraction class instance using the specified access path and return the readback value.

If the memory implementing the virtual register array is mapped in more than one address map, an address map must be specified if a physical access is used (front-door access).

The operation is eventually mapped into set of memory-read operations at the location where the virtual register specified by idx in the virtual register array is implemented.

poke

virtual task poke(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    input  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Deposit the specified value in a virtual register

Deposit value in the DUT memory location(s) that implements the virtual register array that corresponds to this abstraction class instance using the memory backdoor access.

The operation is eventually mapped into set of memory-poke operations at the location where the virtual register specified by idx in the virtual register array is implemented.

peek

virtual task peek(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    output  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)

Sample the current value in a virtual register

Sample the DUT memory location(s) that implements the virtual register array that corresponds to this abstraction class instance using the memory backdoor access, and return the sampled value.

The operation is eventually mapped into set of memory-peek operations at the location where the virtual register specified by idx in the virtual register array is implemented.

reset

function void reset(
    string  kind  =  "HARD"
)

Reset the access semaphore

Reset the semaphore that prevents concurrent access to the virtual register.  This semaphore must be explicitly reset if a thread accessing this virtual register array was killed in before the access was completed

pre_write

virtual task pre_write(
    longint  unsigned  idx,
    ref  uvm_reg_data_t  wdat,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)

Called before virtual register write.

If the specified data value, access path or address map are modified, the updated data value, access path or address map will be used to perform the virtual register operation.

The registered callback methods are invoked after the invocation of this method.  All register callbacks are executed after the corresponding field callbacks The pre-write virtual register and field callbacks are executed before the corresponding pre-write memory callbacks

post_write

virtual task post_write(
    longint  unsigned  idx,
    uvm_reg_data_t  wdat,
    uvm_path_e  path,
    uvm_reg_map  map,
    ref  uvm_status_e  status
)

Called after virtual register write.

If the specified status is modified, the updated status will be returned by the virtual register operation.

The registered callback methods are invoked before the invocation of this method.  All register callbacks are executed before the corresponding field callbacks The post-write virtual register and field callbacks are executed after the corresponding post-write memory callbacks

pre_read

virtual task pre_read(
    longint  unsigned  idx,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)

Called before virtual register read.

If the specified access path or address map are modified, the updated access path or address map will be used to perform the register operation.

The registered callback methods are invoked after the invocation of this method.  All register callbacks are executed after the corresponding field callbacks The pre-read virtual register and field callbacks are executed before the corresponding pre-read memory callbacks

post_read

virtual task post_read(
    longint  unsigned  idx,
    ref  uvm_reg_data_t  rdat,
    input  uvm_path_e  path,
    input  uvm_reg_map  map,
    ref  uvm_status_e  status
)

Called after virtual register read.

If the specified readback data or status is modified, the updated readback data or status will be returned by the register operation.

The registered callback methods are invoked before the invocation of this method.  All register callbacks are executed before the corresponding field callbacks The post-read virtual register and field callbacks are executed after the corresponding post-read memory callbacks

uvm_vreg_cbs

Pre/post read/write callback facade class

Summary
uvm_vreg_cbs
Pre/post read/write callback facade class
Class Hierarchy
Class Declaration
class uvm_vreg_cbs extends uvm_callback
Methods
pre_writeCallback called before a write operation.
post_writeCalled after register write.
pre_readCalled before register read.
post_readCalled after register read.
Types
uvm_vreg_cbConvenience callback type declaration
uvm_vreg_cb_iterConvenience callback iterator type declaration

pre_write

virtual task pre_write(
    uvm_vreg  rg,
    longint  unsigned  idx,
    ref  uvm_reg_data_t  wdat,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)

Callback called before a write operation.

The registered callback methods are invoked after the invocation of the uvm_vreg::pre_write() method.  All virtual register callbacks are executed after the corresponding virtual field callbacks The pre-write virtual register and field callbacks are executed before the corresponding pre-write memory callbacks

The written value wdat, access path and address map, if modified, modifies the actual value, access path or address map used in the virtual register operation.

post_write

virtual task post_write(
    uvm_vreg  rg,
    longint  unsigned  idx,
    uvm_reg_data_t  wdat,
    uvm_path_e  path,
    uvm_reg_map  map,
    ref  uvm_status_e  status
)

Called after register write.

The registered callback methods are invoked before the invocation of the uvm_reg::post_write() method.  All register callbacks are executed before the corresponding virtual field callbacks The post-write virtual register and field callbacks are executed after the corresponding post-write memory callbacks

The status of the operation, if modified, modifies the actual returned status.

pre_read

virtual task pre_read(
    uvm_vreg  rg,
    longint  unsigned  idx,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)

Called before register read.

The registered callback methods are invoked after the invocation of the uvm_reg::pre_read() method.  All register callbacks are executed after the corresponding virtual field callbacks The pre-read virtual register and field callbacks are executed before the corresponding pre-read memory callbacks

The access path and address map, if modified, modifies the actual access path or address map used in the register operation.

post_read

virtual task post_read(
    uvm_vreg  rg,
    longint  unsigned  idx,
    ref  uvm_reg_data_t  rdat,
    input  uvm_path_e  path,
    input  uvm_reg_map  map,
    ref  uvm_status_e  status
)

Called after register read.

The registered callback methods are invoked before the invocation of the uvm_reg::post_read() method.  All register callbacks are executed before the corresponding virtual field callbacks The post-read virtual register and field callbacks are executed after the corresponding post-read memory callbacks

The readback value rdat and the status of the operation, if modified, modifies the actual returned readback value and status.

uvm_vreg_cb

Convenience callback type declaration

Use this declaration to register virtual register callbacks rather than the more verbose parameterized class

uvm_vreg_cb_iter

Convenience callback iterator type declaration

Use this declaration to iterate over registered virtual register callbacks rather than the more verbose parameterized class

class uvm_vreg extends uvm_object
Virtual register abstraction base class
class uvm_vreg_cbs extends uvm_callback
Pre/post read/write callback facade 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.
function new(
    string  name,
    int  unsigned  n_bits
)
Create a new instance and type-specific configuration
function void configure(
    uvm_reg_block  parent,   
    uvm_mem  mem  =  null,
    longint  unsigned  size  =  0,
    uvm_reg_addr_t  offset  =  0,
    int  unsigned  incr  =  0
)
Instance-specific configuration
virtual function bit implement(
    longint  unsigned  n,   
    uvm_mem  mem  =  null,
    uvm_reg_addr_t  offset  =  0,
    int  unsigned  incr  =  0
)
Dynamically implement, resize or relocate a virtual register array
virtual function uvm_mem_region allocate(
    longint  unsigned  n,   
    uvm_mem_mam  mam,   
    uvm_mem_mam_policy  alloc  =  null
)
Randomly implement, resize or relocate a virtual register array
virtual function uvm_mem_region get_region()
Get the region where the virtual register array is implemented
virtual function void release_region()
Dynamically un-implement a virtual register array
virtual function string get_full_name()
Get the hierarchical name
virtual function uvm_reg_block get_parent()
Get the parent block
virtual function uvm_mem get_memory()
Get the memory where the virtual register array is implemented
virtual function int get_n_maps ()
Returns the number of address maps this virtual register array is mapped in
function bit is_in_map (
    uvm_reg_map  map
)
Return TRUE if this virtual register array is in the specified address map
virtual function void get_maps (
    ref  uvm_reg_map  maps[$]
)
Returns all of the address maps where this virtual register array is mapped
virtual function string get_rights(
    uvm_reg_map  map  =  null
)
Returns the access rights of this virtual register array
virtual function string get_access(
    uvm_reg_map  map  =  null
)
Returns the access policy of the virtual register array when written and read via an address map.
virtual function int unsigned get_size()
Returns the size of the virtual register array.
virtual function int unsigned get_n_bytes()
Returns the width, in bytes, of a virtual register.
virtual function int unsigned get_n_memlocs()
Returns the number of memory locations used by a single virtual register.
virtual function int unsigned get_incr()
Returns the number of memory locations between two individual virtual registers in the same array.
virtual function void get_fields(
    ref  uvm_vreg_field  fields[$]
)
Return the virtual fields in this virtual register
virtual function uvm_vreg_field get_field_by_name(
    string  name
)
Return the named virtual field in this virtual register
virtual function uvm_reg_addr_t get_offset_in_memory(
    longint  unsigned  idx
)
Returns the offset of a virtual register
virtual function uvm_reg_addr_t get_address(
    longint  unsigned  idx,   
    uvm_reg_map  map  =  null
)
Returns the base external physical address of a virtual register
virtual task write(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    input  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Write the specified value in a virtual register
virtual task read(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    output  uvm_reg_data_t  value,   
    input  uvm_path_e  path  =  UVM_DEFAULT_PATH,
    input  uvm_reg_map  map  =  null,
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Read the current value from a virtual register
virtual task poke(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    input  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Deposit the specified value in a virtual register
virtual task peek(
    input longint  unsigned  idx,   
    output  uvm_status_e  status,   
    output  uvm_reg_data_t  value,   
    input  uvm_sequence_base  parent  =  null,
    input  uvm_object  extension  =  null,
    input  string  fname  =  "",
    input  int  lineno  =  0
)
Sample the current value in a virtual register
function void reset(
    string  kind  =  "HARD"
)
Reset the access semaphore
virtual task pre_write(
    longint  unsigned  idx,
    ref  uvm_reg_data_t  wdat,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)
Called before virtual register write.
virtual task post_write(
    longint  unsigned  idx,
    uvm_reg_data_t  wdat,
    uvm_path_e  path,
    uvm_reg_map  map,
    ref  uvm_status_e  status
)
Called after virtual register write.
virtual task pre_read(
    longint  unsigned  idx,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)
Called before virtual register read.
virtual task post_read(
    longint  unsigned  idx,
    ref  uvm_reg_data_t  rdat,
    input  uvm_path_e  path,
    input  uvm_reg_map  map,
    ref  uvm_status_e  status
)
Called after virtual register read.
class uvm_mem_region
Allocated memory region descriptor
function void release_region(
    uvm_mem_region  region
)
Release the specified region
class uvm_callback extends uvm_object
The uvm_callback class is the base class for user-defined callback classes.
virtual task pre_write(
    uvm_vreg  rg,
    longint  unsigned  idx,
    ref  uvm_reg_data_t  wdat,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)
Callback called before a write operation.
virtual task post_write(
    uvm_vreg  rg,
    longint  unsigned  idx,
    uvm_reg_data_t  wdat,
    uvm_path_e  path,
    uvm_reg_map  map,
    ref  uvm_status_e  status
)
Called after register write.
virtual task pre_read(
    uvm_vreg  rg,
    longint  unsigned  idx,
    ref  uvm_path_e  path,
    ref  uvm_reg_map  map
)
Called before register read.
virtual task post_read(
    uvm_vreg  rg,
    longint  unsigned  idx,
    ref  uvm_reg_data_t  rdat,
    input  uvm_path_e  path,
    input  uvm_reg_map  map,
    ref  uvm_status_e  status
)
Called after register read.
virtual task post_write(
    uvm_reg_item  rw
)
Called after register write.
virtual task pre_read(
    uvm_reg_item  rw
)
Called before register read.
virtual task post_read(
    uvm_reg_item  rw
)
Called after register read.