Fields

class uvm.reg.uvm_reg_field.UVMRegField(name='uvm_reg_field')

Bases: UVMObject

Field abstraction class

A field represents a set of bits that behave consistently as a single entity.

A field is contained within a single register, but may have different access policies depending on the address map use the access the register (thus the field).

m_max_size = 0

m_policy_names = {}

m_predefined = False

configure(parent, size, lsb_pos, access, volatile, reset, has_reset, is_rand, individually_accessible)

Instance-specific configuration

Specify the parent register of this field, its size in bits, the position of its least-significant bit within the register relative to the least-significant bit of the register, its access policy, volatility, “HARD” reset value, whether the field value is actually reset (the reset value is ignored if FALSE), whether the field value may be randomized and whether the field is the only one to occupy a byte lane in the register.

See set_access for a specification of the pre-defined field access policies.

If the field access policy is a pre-defined policy and NOT one of “RW”, “WRC”, “WRS”, “WO”, “W1”, or “WO1”, the value of is_rand is ignored and the rand_mode() for the field instance is turned off since it cannot be written.

Parameters

• parent (UVMReg) – Parent register.

• size (int) – Size of the field in bits

• lsb_pos (int) – LSB position of the field.

• access (str) – Access of the fields (ie “RW” or “RO”)

• volatile (bool) –

• reset –

• has_reset (bool) –

• is_rand (bool) –

• individually_accessible (bool) –

get_full_name()

Get the hierarchical name

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

Returns

Full hier name (including parent’s name)

Return type

str

get_parent()

Get the parent register

Returns

Parent register of this field

Return type

UVMReg

get_register()

Get the parent register

Returns

Parent register of this field

Return type

UVMReg

get_lsb_pos()

Return the position of the field

Returns the index of the least significant bit of the field in the register that instantiates it. An offset of 0 indicates a field that is aligned with the least-significant bit of the register.

Returns

LSB position of this field

Return type

int

get_n_bits()

Returns the width, in number of bits, of the field.

Returns

Width of the field in bits

Return type

int

classmethod get_max_size()

Function: get_max_size Returns the width, in number of bits, of the largest field.

Returns

Width of largest field

Return type

int

set_access(mode)

Modify the access policy of the field

Modify the access policy of the field to the specified one and return the previous access policy.

The pre-defined access policies are as follows. The effect of a read operation are applied after the current value of the field is sampled. The read operation will return the current value, not the value affected by the read operation (if any):

"RO"       - W: no effect, R: no effect
"RW"       - W: as-is, R: no effect
"RC"       - W: no effect, R: clears all bits
"RS"       - W: no effect, R: sets all bits
"WRC"      - W: as-is, R: clears all bits
"WRS"      - W: as-is, R: sets all bits
"WC"       - W: clears all bits, R: no effect
"WS"       - W: sets all bits, R: no effect
"WSRC"     - W: sets all bits, R: clears all bits
"WCRS"     - W: clears all bits, R: sets all bits
"W1C"      - W: 1/0 clears/no effect on matching bit, R: no effect
"W1S"      - W: 1/0 sets/no effect on matching bit, R: no effect
"W1T"      - W: 1/0 toggles/no effect on matching bit, R: no effect
"W0C"      - W: 1/0 no effect on/clears matching bit, R: no effect
"W0S"      - W: 1/0 no effect on/sets matching bit, R: no effect
"W0T"      - W: 1/0 no effect on/toggles matching bit, R: no effect
"W1SRC"    - W: 1/0 sets/no effect on matching bit, R: clears all bits
"W1CRS"    - W: 1/0 clears/no effect on matching bit, R: sets all bits
"W0SRC"    - W: 1/0 no effect on/sets matching bit, R: clears all bits
"W0CRS"    - W: 1/0 no effect on/clears matching bit, R: sets all bits
"WO"       - W: as-is, R: error
"WOC"      - W: clears all bits, R: error
"WOS"      - W: sets all bits, R: error
"W1"       - W: 1st W after ``HARD`` reset is as-is, other W have no effects, R: no effect
"WO1"      - W: 1st W after ``HARD`` reset is as-is, other W have no effects, R: error
"NOACCESS" - W: no effect, R: no effect

It is important to remember that modifying the access of a field will make the register model diverge from the specification that was used to create it.

Parameters

mode (str) – Mode from the list above.

Returns:

classmethod define_access(name)

Define a new access policy value

Because field access policies are specified using string values, there is no way for SystemVerilog to verify if a specific access value is valid or not. To help catch typing errors, user-defined access values must be defined using this method to avoid begin reported as an invalid access policy.

The name of field access policies are always converted to all uppercase.

Returns TRUE if the new access policy was not previously defined. Returns FALSE otherwise but does not issue an error message.

Parameters

• cls –

• name –

Returns

False if name already exists, True on success.

Return type

bool

classmethod m_predefine_policies()

Internal function which creates the predefines policies.

get_access(reg_map=None)

Get the access policy of the field

Returns the current access policy of the field when written and read through the specified address map. If the register containing the field is mapped in multiple address map, an address map must be specified. The access policy of a field from a specific address map may be restricted by the register’s access policy in that address map. For example, a RW field may only be writable through one of the address maps and read-only through all of the other maps. If the field access contradicts the map’s access value (field access of WO, and map access value of RO, etc), the method’s return value is NOACCESS.

Parameters

reg_map –

Returns:

is_known_access(_map=None)

Check if access policy is a built-in one.

Returns TRUE if the current access policy of the field, when written and read through the specified address map, is a built-in access policy.

Parameters

_map –

Returns:

set_volatility(volatile)

Function: set_volatility Modify the volatility of the field to the specified one.

It is important to remember that modifying the volatility of a field will make the register model diverge from the specification that was used to create it.

Parameters

volatile –

is_volatile()

Function: is_volatile Indicates if the field value is volatile

UVM uses the IEEE 1685-2009 IP-XACT definition of “volatility”. If TRUE, the value of the register is not predictable because it may change between consecutive accesses. This typically indicates a field whose value is updated by the DUT. The nature or cause of the change is not specified. If FALSE, the value of the register is not modified between consecutive accesses.

Returns

True if field volatile (see the definition above)

Return type

bool

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

Group: Access

Set the desired value for this field

It sets the desired value of the field to the specified value modified by the field access policy. It does not actually set the value of the field in the design, only the desired value in the abstraction class. Use the UVMReg.update method to update the actual register with the desired value or the UVMRegField.write method to actually write the field and update its mirrored value.

The final desired value in the mirror is a function of the field access policy and the set value, just like a normal physical write operation to the corresponding bits in the hardware. As such, this method (when eventually followed by a call to UVMReg.update) is a zero-time functional replacement for the UVMRegField.write method. For example, the desired value of a read-only field is not modified by this method and the desired value of a write-once field can only be set if the field has not yet been written to using a physical (for example, front-door) write operation.

Use the UVMRegField.predict to modify the mirrored value of the field. Function: set

Parameters

• value –

• fname –

• lineno –

get(fname='', lineno=0)

Function: get

Return the desired value of the field

It does not actually read the value of the field in the design, only the desired value in the abstraction class. Unless set to a different value using the UVMRegField.set, the desired value and the mirrored value are identical.

Use the UVMRegField.read or UVMRegField.peek method to get the actual field value.

If the field is write-only, the desired/mirrored value is the value last written and assumed to reside in the bits implementing it. Although a physical read operation would something different, the returned value is the actual content.

Parameters

• fname –

• lineno –

Returns:

get_mirrored_value(fname='', lineno=0)

Function: get_mirrored_value

Return the mirrored value of the field

It does not actually read the value of the field in the design, only the mirrored value in the abstraction class.

If the field is write-only, the desired/mirrored value is the value last written and assumed to reside in the bits implementing it. Although a physical read operation would something different, the returned value is the actual content.

Parameters

• fname –

• lineno –

Returns:

reset(kind='HARD')

Function: reset

Reset the desired/mirrored value for this field.

It sets the desired and mirror value of the field to the reset event specified by kind. If the field does not have a reset value specified for the specified reset kind the field is unchanged.

It does not actually reset the value of the field in the design, only the value mirrored in the field abstraction class.

Write-once fields can be modified after a “HARD” reset operation.

Parameters

kind –

get_reset(kind='HARD')

Function: get_reset

Get the specified reset value for this field

Return the reset value for this field for the specified reset kind. Returns the current field value is no reset value has been specified for the specified reset event.

Parameters

kind –

Returns:

has_reset(kind='HARD', delete=False)

Function: has_reset

Check if the field has a reset value specified

Return TRUE if this field has a reset value specified for the specified reset kind. If delete is TRUE, removes the reset value, if any.

Parameters

• kind –

• delete –

Returns:

set_reset(value, kind='HARD')

Function: set_reset

Specify or modify the reset value for this field

Specify or modify the reset value for this field corresponding to the cause specified by kind.

Parameters

• value –

• kind –

needs_update()

Function: needs_update

Check if the abstract model contains different desired and mirrored values.

If a desired field value has been modified in the abstraction class without actually updating the field in the DUT, the state of the DUT (more specifically what the abstraction class thinks the state of the DUT is) is outdated. This method returns TRUE if the state of the field in the DUT needs to be updated to match the desired value. The mirror values or actual content of DUT field are not modified. Use the UVMReg.update to actually update the DUT field.

Returns:

set_compare(check=1)

Sets the compare policy during a mirror update. The field value is checked against its mirror only when both the check argument in UVMRegBlock.mirror, UVMReg.mirror, or UVMRegField.mirror and the compare policy for the field is UVMRegField.m_check.

Parameters

check –

get_compare()

Returns the compare policy for this field.

Returns:

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

Update the mirrored and desired value for this field.

Predict the mirror and desired value of the field based on the specified observed value on a bus using the specified address map.

If kind is specified as UVM_PREDICT_READ, the value was observed in a read transaction on the specified address map or backdoor (if path is UVM_BACKDOOR). If kind is specified as UVM_PREDICT_WRITE, the value was observed in a write transaction on the specified address map or backdoor (if path is UVM_BACKDOOR). If kind is specified as UVM_PREDICT_DIRECT, the value was computed and is updated as-is, without regard to any access policy. For example, the mirrored value of a read-only field is modified by this method if kind is specified as UVM_PREDICT_DIRECT.

This method does not allow an update of the mirror (or desired) when the register containing this field is busy executing a transaction because the results are unpredictable and indicative of a race condition in the testbench.

Returns TRUE if the prediction was successful.

#function bit uvm_reg_field::predict (uvm_reg_data_t value,

uvm_reg_byte_en_t be = -1, uvm_predict_e kind = UVM_PREDICT_DIRECT, uvm_path_e path = UVM_FRONTDOOR, uvm_reg_map map = null, string fname = “”, int lineno = 0)

Parameters

• value –

• be (int) – Byte-enable

• kind –

• path –

• _map (UVMRegMap) –

• fname (str) –

• lineno (int) –

Returns:

XpredictX(cur_val, wr_val, _map)

/local/ extern virtual function uvm_reg_data_t XpredictX (uvm_reg_data_t cur_val,

uvm_reg_data_t wr_val, uvm_reg_map map)

Parameters

• cur_val –

• wr_val –

• _map –

Returns:

XupdateX()

Returns:

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

Parameters

• rw (UVMRegItem) –

• kind –

• be (int) – Byte-enable

Raises:

pre_randomize()

Classes derived from sv_obj can implement this callback, which is called before the actual randomization in randomize or randomize_with.

post_randomize()

Classes derived from sv_obj can implement this callback, which is called after the actual randomization in randomize or randomize_with.

async pre_write(rw)

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

The field callback methods are invoked after the callback methods on the containing register. The registered callback methods are invoked after the invocation of this method.

Parameters

rw (UVMRegItem) – Reg item associated with write.

async post_write(rw)

Called after field write.

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

The field callback methods are invoked after the callback methods on the containing register. The registered callback methods are invoked before the invocation of this method.

Parameters

rw (UVMRegItem) – Reg item associated with write.

async pre_read(rw)

Called before field read.

If the access path or address map in the rw argument 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 field callback methods are invoked after the callback methods on the containing register. The registered callback methods are invoked after the invocation of this method.

Parameters

rw (UVMRegItem) – Reg item associated with read.

async post_read(rw)

Task: post_read

Called after field read.

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

The field callback methods are invoked after the callback methods on the containing register. The registered callback methods are invoked before the invocation of this method.

Parameters

rw (UVMRegItem) – Reg item associated with read.

convert2string()

Return type

str

create(name='')

Group: Creation

The create method allocates a new object of the same type as this object and returns it via a base uvm_object handle. Every class deriving from uvm_object, directly or indirectly, must implement the create method.

A typical implementation is as follows:

class mytype (UVMObject):
  ...
  def create(self, name=""):
    mytype t = mytype(name)
    return t

Parameters

name (str) – Name of the created object.

Returns

New object.

Return type

obj

get_object_type()

Function: get_object_type

Returns the type-proxy (wrapper) for this object. The uvm_factory’s type-based override and creation methods take arguments of uvm_object_wrapper. This method, if implemented, can be used as convenient means of supplying those arguments. This method is the same as the static get_type method, but uses an already allocated object to determine the type-proxy to access (instead of using the static object).

The default implementation of this method does a factory lookup of the proxy using the return value from get_type_name. If the type returned by get_type_name is not registered with the factory, then a None handle is returned.

For example:

class cmd (UVMObject):
  type_id = UVMObjectRegistry()
  @classmethod
  def type_id get_type(cls):
    return type_id.get()
  def get_object_type(self):
    return cmd.type_id.get()

This function is implemented by the `uvm_*_utils macros, if employed.

Returns:

classmethod get_type()

Returns the type-proxy (wrapper) for this object. The UVMFactory’s type-based override and creation methods take arguments of uvm_object_wrapper. This method, if implemented, can be used as convenient means of supplying those arguments.

The default implementation of this method produces an error and returns None. To enable use of this method, a user’s subtype must implement a version that returns the subtype’s wrapper.

For example:

class cmd(UVMObject):
  type_id = None

  @classmethod
  def get_type(cls):
    return cls.type_id.get()

Then, to use:

factory.set_type_override(cmd.get_type(), subcmd.get_type())

This function is implemented by the uvm_*_utils functions, if employed.

Returns:

get_type_name()

This function returns the type name of the object, which is typically the type identifier enclosed in quotes. It is used for various debugging functions in the library, and it is used by the factory for creating objects.

This function must be defined in every derived class.

A typical implementation is as follows:

class mytype (UVMObject):
  ...
  type_name = "mytype"

  def get_type_name(self):
    return my_type.type_name

We define the type_name static variable to enable access to the type name without need of an object of the class, i.e., to enable access via the scope operator, ~mytype::type_name~.

Returns

Type name of the object.

Return type

str

type_id = <uvm.base.uvm_registry.UVMObjectRegistry object>

type_name = 'UVMRegField'