Registers

class uvm.reg.uvm_reg.UVMReg(name, n_bits, has_coverage=0)

Bases: UVMObject

Register abstraction base class

A register represents a set of fields that are accessible as a single entity.

A register may be mapped to one or more address maps, each with different access rights and policy.

m_max_size = 0

configure(blk_parent, regfile_parent=None, hdl_path='')

Instance-specific configuration

Specify the parent block of this register. May also set a parent register file for this register,

If the register is implemented in a single HDL variable, its name is specified as the hdl_path. Otherwise, if the register is implemented as a concatenation of variables (usually one per field), then the HDL path must be specified using the <add_hdl_path()> or add_hdl_path_slice method.

Parameters

• blk_parent (UVMRegBlock) – The parent block of this register

• regfile_parent (UVMRegFile, optional) – The parent register file for this register

• hdl_path (str, optional) – The HDL path of the register

set_offset(reg_map, offset, unmapped=0)

Modify the offset of the register

The offset of a register within an address map is set using the <uvm_reg_map::add_reg()> method. This method is used to modify that offset dynamically.

Modifying the offset of a register will make the register model diverge from the specification that was used to create it.

Parameters

• reg_map (UVMRegMap) – The register map in which the offset should be modified.

• offset (int) – The new offset of the specified register.

• unmapped (int, optional) – The number of unmapped address locations between the register and the next mapped register. Defaults to 0.

set_parent(blk_parent, regfile_parent)

Set parent(s) for this register.

Parameters

• blk_parent (UVMRegBlock) – Parent register block.

• regfile_parent (UVMRegFile) – Parent register file.

add_field(field: UVMRegField) → None

Add a field into this register. :param field: Reg field to add into this register. :type field: UVMRegField

add_map(reg_map) → None

Parameters

reg_map (UVMRegMap) – Add a register map for this register.

Xlock_modelX() → None

Lock the modelX instance so that it cannot be used.

get_full_name()

Get the hierarchical name

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

Returns

The hierarchical name of this register.

Return type

str

get_parent()

Get the parent block of this register.

Returns

Parent block of this register.

Return type

UVMRegBlock

get_block()

Get the parent block of this register. :returns: Parent block of this register. :rtype: UVMRegBlock

get_regfile()

Get the parent register file Returns None if this register is instantiated in a block.

Returns

Parent register file of this register.

Return type

UVMRegFile

get_n_maps() → int

Returns the number of address maps this register is mapped in

Returns

Number of address map this registers is mapped in

Return type

int

is_in_map(_map) → bool

Returns 1 if this register is in the specified address map

Parameters

_map (UVMRegMap) –

Returns

True if the register is in the given address map, False otherwise

Return type

bool

get_maps(maps)

Returns all of the address maps where this register is mapped

Parameters

maps (list) – Appends found maps into this list.

Returns:

get_local_map(reg_map, caller='')

Gets the local register map that contains the given register map.

Parameters

• reg_map (UVMRegMap) –

• caller (str, optional) – The caller name, by default “”

Returns

The local register map instance containing the given register map, or None if not found.

get_default_map(caller='')

Get the default map associated with a register.

This function searches all parent blocks associated with this register for a default map associated with it. If none is found, the first map associated with this register is returned.

Parameters

caller (str) – The name of the calling object.

Returns

The default map associated with this register.

Return type

UVMRegMap

get_rights(reg_map=None)

Returns the accessibility (“RW, “RO”, or “WO”) of this register in the given map.

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

Whether a register field can be read or written depends on both the field’s configured access policy (refer to <uvm_reg_field::configure>) and the register’s accessibility rights in the map being used to access the field.

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

Parameters

reg_map (UVMRegMap) –

Returns

Register access rights.

Return type

str

get_n_bits()

Get the width, in bits, of the given register.

Returns: int: The width of the register, in bits.

get_n_bytes()

Returns the width, in bytes, of this register. Rounds up to next whole byte if register is not a multiple of 8.

Returns:

classmethod get_max_size()

Returns the maximum width, in bits, of all registers.

Returns

The width of this register in bytes.

Return type

int

get_fields(fields)

Return the fields in this register

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

Parameters

fields (list) –

get_field_by_name(name)

Return the named field in this register

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

Parameters

name (str) – Name of the sought field.

Returns

Named field, or None if nothing found.

Return type

UVMRegField

Xget_fields_accessX(_map)

Returns “WO” if all of the fields in the registers are write-only Returns “RO” if all of the fields in the registers are read-only Returns “RW” otherwise. :param _map: :type _map: UVMRegMap

Returns:

get_offset(reg_map=None)

Returns the offset of this register

Returns the offset of this register in an address map.

If no address map is specified and the register is mapped in only one address map, that address map is used. If the register 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 register is not mapped in the specified address map, an error message is issued.

Parameters

reg_map (UVMRegMap) – Offset in this map.

Returns

Offset of this register.

Return type

int

get_address(reg_map=None)

Returns the base external physical address of this register

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

If no address map is specified and the register is mapped in only one address map, that address map is used. If the register 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 register is not mapped in the specified address map, a warning message is issued.

Parameters

reg_map –

Returns

Base external physical address of this register

Return type

int

get_addresses(reg_map, addr)

Identifies the external physical address(es) of this register

Computes all of the external physical addresses that must be accessed to completely read or write this register. The addressed are specified in little endian order. Returns the number of bytes transferred on each access.

If no address map is specified and the register is mapped in only one address map, that address map is used. If the register 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 register is not mapped in the specified address map, an error message is issued.

Parameters

• reg_map (UVMRegMap) –

• addr (int) –

Returns

Number of bytes transferred on each access.

Return type

int

set(value, fname='', lineno=0)

Set the desired value for this register

Sets the desired value of the fields in the register to the specified value. Does not actually set the value of the register in the design, only the desired value in its corresponding abstraction class in the RegModel model. Use the UVMReg.update method to update the actual register with the mirrored value or the UVMReg.write method to set the actual register and its mirrored value.

Unless this method is used, the desired value is equal to the mirrored value.

Refer <uvm_reg_field::set()> for more details on the effect of setting mirror values on fields with different access policies.

To modify the mirrored field values to a specific value, and thus use the mirrored as a scoreboard for the register values in the DUT, use the UVMReg.predict method.

Parameters

• value –

• fname –

• lineno –

get(fname='', lineno=0)

Function: get

Return the desired value of the fields in the register.

Does not actually read the value of the register in the design, only the desired value in the abstraction class. Unless set to a different value using the UVMReg.set, the desired value and the mirrored value are identical.

Use the UVMReg.read or UVMReg.peek method to get the actual register value.

If the register contains write-only fields, the desired/mirrored value for those fields are the value last written and assumed to reside in the bits implementing these fields. Although a physical read operation would something different for these fields, the returned value is the actual content.

Parameters

• fname –

• lineno –

Returns:

get_mirrored_value(fname='', lineno=0)

Return the mirrored value of the fields in the register.

Does not actually read the value of the register in the design

If the register contains write-only fields, the desired/mirrored value for those fields are the value last written and assumed to reside in the bits implementing these fields. Although a physical read operation would something different for these fields, the returned value is the actual content.

Parameters

• fname –

• lineno –

Returns

Mirrored value in the register

Return type

int

needs_update()

Function: needs_update

Returns 1 if any of the fields need updating

See <uvm_reg_field::needs_update()> for details. Use the UVMReg.update to actually update the DUT register.

Returns:

reset(kind='HARD')

Function: reset

Reset the desired/mirrored value for this register.

Sets the desired and mirror value of the fields in this register to the reset value for the specified reset kind. See <uvm_reg_field.reset()> for more details.

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

Parameters

kind –

set_reset(value, kind='HARD') → None

Specify or modify the reset value for this register

Specify or modify the reset value for all the fields in the register corresponding to the cause specified by ~kind~.

async write(status, value, path=3, _map=None, parent=None, prior=-1, extension=None, fname='', lineno=0) → int

Task: write

Write the specified value in this register

Write value in the DUT register that corresponds to this abstraction class instance using the specified access path. If the register is mapped in more than one address map, an address map must be specified if a physical access is used (front-door access). If a back-door access path is used, the effect of writing the register through a physical access is mimicked. For example, read-only bits in the registers will not be written.

The mirrored value will be updated using the UVMReg.predict method.

extern virtual task write(output uvm_status_e status,

input uvm_reg_data_t value, input uvm_path_e path = UVM_DEFAULT_PATH, input uvm_reg_map map = None, input uvm_sequence_base parent = None, input int prior = -1, input uvm_object extension = None, input string fname = “”, input int lineno = 0)

Parameters

• status –

• value –

• path –

• UVM_DEFAULT_PATH –

• _map –

• parent –

• prior –

• extension –

• fname –

• lineno –

async read(status, value, path=3, _map=None, parent=None, prior=-1, extension=None, fname='', lineno=0)

Task: read

Read the current value from this register

Read and return value from the DUT register that corresponds to this abstraction class instance using the specified access path. If the register is mapped in more than one address map, an address map must be specified if a physical access is used (front-door access). If a back-door access path is used, the effect of reading the register through a physical access is mimicked. For example, clear-on-read bits in the registers will be set to zero.

The mirrored value will be updated using the UVMReg.predict method.

extern virtual task read(output uvm_status_e status,

output uvm_reg_data_t value, input uvm_path_e path = UVM_DEFAULT_PATH, input uvm_reg_map map = None, input uvm_sequence_base parent = None, input int prior = -1, input uvm_object extension = None, input string fname = “”, input int lineno = 0)

Parameters

• status –

• value –

• path –

• UVM_DEFAULT_PATH –

• _map –

• parent –

• prior –

• extension –

• fname –

• lineno –

async update(status, path=3, _map=None, parent=None, prior=-1, extension=None, fname='', lineno=0)

Task: update

Updates the content of the register in the design to match the desired value

This method performs the reverse operation of UVMReg.mirror. Write this register if the DUT register is out-of-date with the desired/mirrored value in the abstraction class, as determined by the UVMReg.needs_update method.

The update can be performed using the using the physical interfaces (frontdoor) or UVMReg.poke (backdoor) access. If the register is mapped in multiple address maps and physical access is used (front-door), an address map must be specified.

extern virtual task update(output uvm_status_e status,

input uvm_path_e path = UVM_DEFAULT_PATH, input uvm_reg_map map = None, input uvm_sequence_base parent = None, input int prior = -1, input uvm_object extension = None, input string fname = “”, input int lineno = 0)

Parameters

• status –

• path –

• UVM_DEFAULT_PATH –

• _map –

• parent –

• prior –

• extension –

• fname –

• lineno –

async mirror(status, check=0, path=3, _map=None, parent=None, prior=-1, extension=None, fname='', lineno=0)

Read the register and update/check its mirror value

Read the register and optionally compared the readback value with the current mirrored value if check is UVM_CHECK. The mirrored value will be updated using the UVMReg.predict method based on the readback value.

The mirroring can be performed using the physical interfaces (frontdoor) or UVMReg.peek (backdoor).

If check is specified as UVM_CHECK, an error message is issued if the current mirrored value does not match the readback value. Any field whose check has been disabled with <uvm_reg_field::set_compare()> will not be considered in the comparison.

If the register is mapped in multiple address maps and physical access is used (front-door access), an address map must be specified. If the register contains write-only fields, their content is mirrored and optionally checked only if a UVM_BACKDOOR access path is used to read the register.

extern virtual task mirror(output uvm_status_e status,

input uvm_check_e check = UVM_NO_CHECK, input uvm_path_e path = UVM_DEFAULT_PATH, input uvm_reg_map map = None, input uvm_sequence_base parent = None, input int prior = -1, input uvm_object extension = None, input string fname = “”, input int lineno = 0)

Parameters

• status –

• check –

• path –

• _map –

• parent –

• prior –

• extension –

• fname –

• lineno –

predict(value, be=-1, kind=0, path=0, reg_map=None, fname='', lineno=0)

Function: predict

Update the mirrored and desired value for this register.

Predict the mirror (and desired) value of the fields in the register based on the specified observed value on a specified address map, or based on a calculated value. See <uvm_reg_field::predict()> for more details.

Returns TRUE if the prediction was successful for each field in the register.

Parameters

• value –

• be –

• kind –

• UVM_PREDICT_DIRECT –

• path –

• UVM_FRONTDOOR –

• reg_map –

• fname –

• lineno –

Returns:

is_busy()

Function: is_busy

Returns 1 if register is currently being read or written.

Returns:

Xset_busyX(busy)

/local/ extern function void Xset_busyX(bit busy)

Parameters

busy –

async XreadX(status, value, path, _map, parent=None, prior=-1, extension=None, fname='', lineno=0)

/local/ extern task XreadX (output uvm_status_e status,

output uvm_reg_data_t value, input uvm_path_e path, input uvm_reg_map map, input uvm_sequence_base parent = None, input int prior = -1, input uvm_object extension = None, input string fname = “”, input int lineno = 0)

Parameters

• status –

• value –

• path –

• _map –

• parent –

• prior –

• extension –

• fname –

• lineno –

async XatomicX(on, rw=None)

/local/ extern task XatomicX(bit on)

Parameters

• on –

• rw –

Raises:

Xcheck_accessX(rw, map_info, caller)

/local/ extern virtual function bit Xcheck_accessX

(input uvm_reg_item rw,

output uvm_reg_map_info map_info, input string caller)

Parameters

• rw –

• map_info –

• caller –

Returns:

do_check(expected, actual, _map)

extern virtual function bit do_check(uvm_reg_data_t expected,

uvm_reg_data_t actual, uvm_reg_map map)

Parameters

• expected –

• actual –

• _map –

Returns:

async do_write(rw)

extern virtual task do_write(uvm_reg_item rw)

Parameters

rw –

async do_read(rw)

extern virtual task do_read(uvm_reg_item rw)

Parameters

rw –

do_predict(rw, kind=0, be=-1)

get_backdoor(inherited=True)

Function: get_backdoor

Returns the user-defined backdoor for this register

If None, no user-defined backdoor has been defined. A user-defined backdoor is defined by using the UVMReg.set_backdoor method.

If inherited is TRUE, returns the backdoor of the parent block if none have been specified for this register.

Parameters

inherited –

Returns:

add_hdl_path(slices, kind='RTL')

Function: add_hdl_path

Add an HDL path

Add the specified HDL path to the register instance for the specified design abstraction. This method may be called more than once for the same design abstraction if the register is physically duplicated in the design abstraction

For example, the following register

|        1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
| Bits:  5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|       +-+---+-------------+---+-------+
|       |A|xxx|      B      |xxx|   C   |
|       +-+---+-------------+---+-------+

 would be specified using the following literal value:

| add_hdl_path([ ["A_reg", 15, 1],
|                 ["B_reg",  6, 7],
|                 ['C_reg",  0, 4] ] )

 If the register is implemented using a single HDL variable,
 The array should specify a single slice with its `offset` and `size`
 specified as -1. For example:

| r1.add_hdl_path('{ '{"r1", -1, -1} })

Parameters

• slices –

• kind –

add_hdl_path_slice(name, offset, size, first=0, kind='RTL')

Function: add_hdl_path_slice

Append the specified HDL slice to the HDL path of the register instance for the specified design abstraction. If first is TRUE, starts the specification of a duplicate HDL implementation of the register.

Parameters

• name –

• offset –

• size –

• first –

• kind –

has_hdl_path(kind='')

Function: has_hdl_path

Check if a HDL path is specified

Returns TRUE if the register instance has a HDL path defined for the specified design abstraction. If no design abstraction is specified, uses the default design abstraction specified for the parent block.

Parameters

kind –

Returns:

get_full_hdl_path(paths, kind='', separator='.')

Function: get_full_hdl_path

Get the full hierarchical HDL path(s)

Returns the full hierarchical HDL path(s) defined for the specified design abstraction in the register instance. There may be more than one path returned even if only one path was defined for the register instance, if any of the parent components have more than one path defined for the same design abstraction

If no design abstraction is specified, the default design abstraction for each ancestor block is used to get each incremental path.

Parameters

• paths –

• kind –

• separator –

backdoor_read(rw)

Function: backdoor_read

User-define backdoor read access

Override the default string-based DPI backdoor access read for this register type. By default calls UVMReg.backdoor_read_func.

Parameters

rw –

backdoor_write(rw)

Function: backdoor_write

User-defined backdoor read access

Override the default string-based DPI backdoor access write for this register type.

Parameters

rw –

backdoor_read_func(rw)

Function: backdoor_read_func

User-defined backdoor read access

Override the default string-based DPI backdoor access read for this register type.

Parameters

rw –

Returns:

classmethod include_coverage(scope, models, accessor=None)

Function: backdoor_watch

User-defined DUT register change monitor

Watch the DUT register corresponding to this abstraction class instance for any change in value and return when a value-change occurs. This may be implemented a string-based DPI access if the simulation tool provide a value-change callback facility. Such a facility does not exists in the standard SystemVerilog DPI and thus no default implementation for this method can be provided.

virtual task backdoor_watch(); endtask

Group: Coverage

Function: include_coverage

Specify which coverage model that must be included in various block, register or memory abstraction class instances.

The coverage models are specified by OR’ing or adding the uvm_coverage_model_e coverage model identifiers corresponding to the coverage model to be included.

The scope specifies a hierarchical name or pattern identifying a block, memory or register abstraction class instances. Any block, memory or register whose full hierarchical name matches the specified scope will have the specified functional coverage models included in them.

The scope can be specified as a POSIX regular expression or simple pattern. See <uvm_resource_base::Scope Interface> for more details.

| uvm_reg::include_coverage("*", UVM_CVR_ALL)

 The specification of which coverage model to include in
 which abstraction class is stored in a `uvm_reg_cvr_t` resource in the
 `uvm_resource_db` resource database,
 in the "uvm_reg::" scope namespace.

extern static function void include_coverage(string scope,
                                             uvm_reg_cvr_t models,
                                             uvm_object accessor = None)

Parameters

• cls –

• scope –

• models –

• accessor –

build_coverage(models)

Function: build_coverage

Check if all of the specified coverage models must be built.

Check which of the specified coverage model must be built in this instance of the register abstraction class, as specified by calls to UVMReg.include_coverage.

Models are specified by adding the symbolic value of individual coverage model as defined in uvm_coverage_model_e. Returns the sum of all coverage models to be built in the register model.

Parameters

models –

Returns:

add_coverage(models)

Function: add_coverage

Specify that additional coverage models are available.

Add the specified coverage model to the coverage models available in this class. Models are specified by adding the symbolic value of individual coverage model as defined in uvm_coverage_model_e.

This method shall be called only in the constructor of subsequently derived classes.

extern virtual protected function void add_coverage(uvm_reg_cvr_t models)

Parameters

models –

has_coverage(models)

Function: has_coverage

Check if register has coverage model(s)

Returns TRUE if the register abstraction class contains a coverage model for all of the models specified. Models are specified by adding the symbolic value of individual coverage model as defined in uvm_coverage_model_e.

extern virtual function bit has_coverage(uvm_reg_cvr_t models)

Parameters

models –

Returns:

set_coverage(is_on)

Function: set_coverage

Turns on coverage measurement.

Turns the collection of functional coverage measurements on or off for this register. The functional coverage measurement is turned on for every coverage model specified using uvm_coverage_model_e symbolic identifiers. Multiple functional coverage models can be specified by adding the functional coverage model identifiers. All other functional coverage models are turned off. Returns the sum of all functional coverage models whose measurements were previously on.

This method can only control the measurement of functional coverage models that are present in the register abstraction classes, then enabled during construction. See the UVMReg.has_coverage method to identify the available functional coverage models.

Parameters

is_on –

Returns:

get_coverage(is_on)

Function: get_coverage

Check if coverage measurement is on.

Returns TRUE if measurement for all of the specified functional coverage models are currently on. Multiple functional coverage models can be specified by adding the functional coverage model identifiers.

See UVMReg.set_coverage for more details.

Parameters

is_on –

Returns:

sample(data, byte_en, is_read, _map)

Function: sample

Functional coverage measurement method

This method is invoked by the register abstraction class whenever it is read or written with the specified data via the specified address map. It is invoked after the read or write operation has completed but before the mirror has been updated.

Empty by default, this method may be extended by the abstraction class generator to perform the required sampling in any provided functional coverage model.

protected virtual function void sample(uvm_reg_data_t data,

uvm_reg_data_t byte_en, bit is_read, uvm_reg_map map)

Parameters

• data –

• byte_en –

• is_read –

• _map –

sample_values()

Function: sample_values

Functional coverage measurement method for field values

This method is invoked by the user or by the <uvm_reg_block::sample_values()> method of the parent block to trigger the sampling of the current field values in the register-level functional coverage model.

This method may be extended by the abstraction class generator to perform the required sampling in any provided field-value functional coverage model.

XsampleX(data, byte_en, is_read, _map)

/local/ function void XsampleX(uvm_reg_data_t data,

uvm_reg_data_t byte_en, bit is_read, uvm_reg_map map)

Parameters

• data –

• byte_en –

• is_read –

• _map –

async pre_write(rw)

async post_write(rw)

Task: post_write

Called after register write.

If the specified status is modified, the updated 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

Parameters

rw –

async pre_read(rw)

Task: pre_read

Called before 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. If the status is modified to anything other than UVM_IS_OK, the operation is aborted.

The registered callback methods are invoked after the invocation of this method. All register callbacks are executed before the corresponding field callbacks

Parameters

rw –

async post_read(rw)

Called after 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

Parameters

rw –

convert2string()

Converts this register into string.

Returns

String representation of this register.

Return type

str