uvm_resource

Title: Resources

Topic: Intro

A resource is a parameterized container that holds arbitrary data. Resources can be used to configure components, supply data to sequences, or enable sharing of information across disparate parts of a testbench. They are stored using scoping information so their visibility can be constrained to certain parts of the testbench. Resource containers can hold any type of data, constrained only by the data types available in SystemVerilog. Resources can contain scalar objects, class handles, queues, lists, or even virtual interfaces.

Resources are stored in a resource database so that each resource can be retrieved by name or by type. The database has both a name table and a type table and each resource is entered into both. The database is globally accessible.

Each resource has a set of scopes over which it is visible. The set of scopes is represented as a regular expression. When a resource is looked up the scope of the entity doing the looking up is supplied to the lookup function. This is called the ~current scope~. If the current scope is in the set of scopes over which a resource is visible then the resource can be retuned in the lookup.

Resources can be looked up by name or by type. To support type lookup each resource has a static type handle that uniquely identifies the type of each specialized resource container.

Multiple resources that have the same name are stored in a queue. Each resource is pushed into a queue with the first one at the front of the queue and each subsequent one behind it. The same happens for multiple resources that have the same type. The resource queues are searched front to back, so those placed earlier in the queue have precedence over those placed later.

The precedence of resources with the same name or same type can be altered. One way is to set the ~precedence~ member of the resource container to any arbitrary value. The search algorithm will return the resource with the highest precedence. In the case where there are multiple resources that match the search criteria and have the same (highest) precedence, the earliest one located in the queue will be one returned. Another way to change the precedence is to use the set_priority function to move a resource to either the front or back of the queue.

The classes defined here form the low level layer of the resource database. The classes include the resource container and the database that holds the containers. The following set of classes are defined here:

<uvm_resource_types>: A class without methods or members, only typedefs and enums. These types and enums are used throughout the resources facility. Putting the types in a class keeps them confined to a specific name space.

<uvm_resource_options>: policy class for setting options, such as auditing, which effect resources.

<uvm_resource_base>: the base (untyped) resource class living in the resource database. This class includes the interface for setting a resource as read-only, notification, scope management, altering search priority, and managing auditing.

<uvm_resource#(T)>: parameterized resource container. This class includes the interfaces for reading and writing each resource. Because the class is parameterized, all the access functions are type safe.

<uvm_resource_pool>: the resource database. This is a singleton class object.

class uvm.base.uvm_resource.Access_t

Bases: object

class uvm.base.uvm_resource.UVMResourceOptions

Bases: object

Provides a namespace for managing options for the resources facility. The only thing allowed in this class is static local data members and static functions for manipulating and retrieving the value of the data members. The static local data members represent options and settings that control the behavior of the resources facility.

Options include:

• auditing: on/off

  The default for auditing is on. You may wish to turn it off to for performance reasons. With auditing off memory is not consumed for storage of auditing information and time is not spent collecting and storing auditing information. Of course, during the period when auditing is off no audit trail information is available

auditing = True

classmethod turn_on_auditing()

classmethod turn_off_auditing()

classmethod is_auditing()

class uvm.base.uvm_resource.get_t

Bases: object

class uvm.base.uvm_resource.UVMResourceBase(name='', s='*')

Bases: UVMObject

default_precedence = 1000

get_type_handle()

Function: get_type_handle

Pure virtual function that returns the type handle of the resource container. Raises:

set_read_only()

set_read_write()

is_read_only()

Function: is_read_only

Returns one if this resource has been set to read-only, zero otherwise Returns:

async wait_modified()

set_scope(s)

Function: set_scope

Set the value of the regular expression that identifies the set of scopes over which this resource is visible. If the supplied argument is a glob it will be converted to a regular expression before it is stored.

Parameters

s –

get_scope()

Function: get_scope

Retrieve the regular expression string that identifies the set of scopes over which this resource is visible.

Returns:

match_scope(s)

Function: match_scope

Using the regular expression facility, determine if this resource is visible in a scope. Return one if it is, zero otherwise.

Parameters

s –

Returns:

record_read_access(accessor=None)

#——————- Group: Audit Trail #——————-

To find out what is happening as the simulation proceeds, an audit trail of each read and write is kept. The <uvm_resource#(T)::read> and <uvm_resource#(T)::write> methods each take an accessor argument. This is a handle to the object that performed that resource access.

function T read(uvm_object accessor = None)
function void write(T t, uvm_object accessor = None)

The accessor can by anything as long as it is derived from uvm_object. The accessor object can be a component or a sequence or whatever object from which a read or write was invoked. Typically the this handle is used as the accessor. For example:

uvm_resource#(int) rint
int i
...
rint.write(7, this)
i = rint.read(this)

The accessor’s ~get_full_name()~ is stored as part of the audit trail. This way you can find out what object performed each resource access. Each audit record also includes the time of the access (simulation time) and the particular operation performed (read or write).

Auditing is controlled through the uvm_resource_options class. function: record_read_access #function void record_read_access(uvm_object accessor = None) :param accessor:

record_write_access(accessor=None)

function: record_write_access

Parameters

accessor –

init_access_record(access_record)

Function: init_access_record

Initialize a new access record

Parameters

access_record –

class uvm.base.uvm_resource.UVMResource(name='', scope='')

Bases: UVMResourceBase

my_type = None

convert2string()

This virtual function is a user-definable hook, called directly by the user, that allows users to provide object information in the form of a string. Unlike sprint, there is no requirement to use a uvm_printer policy object. As such, the format and content of the output is fully customizable, which may be suitable for applications not requiring the consistent formatting offered by the print/sprint/do_print API.

Fields declared in <Utility Macros> macros (`uvm_field_*), if used, will not automatically appear in calls to convert2string.

An example implementation of convert2string follows.

 class Base(UVMObject):
   field = "foo"
   def convert2string(self):
     return "base_field=" + self.field

 class Obj2(UVMObject):
   field = "bar"
   def convert2string()
     convert2string = "child_field=" + self.field

 class Obj(Base):
   addr = 0x123
   data = 0x456
   write = 1
   child = Obj2()
   def convert2string(self):
      convert2string = super().convert2string() +
        sv.sformatf(" write=%0d addr=%8h data=%8h ",write,addr,data) +
        child.convert2string()

Then, to display an object, you could write:

.. code-block:: python

  o = Obj()
  uvm_report_info("BusMaster", "Sending:

” + o.convert2string())

The output will look similar to:

UVM_INFO @ 0: reporter [BusMaster] Sending:
  base_field=foo write=1 addr=00000123 data=00000456 child_field=bar

Returns:

str: Object converted into string.

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_handle()

Function: get_type_handle

Returns the static type handle of this resource in a polymorphic fashion. The return type of get_type_handle() is uvm_resource_base. This function is not static and therefore can only be used by instances of a parameterized resource. Returns:

set()

Function: set

Simply put this resource into the global resource pool

set_override(override=2)

Function: set_override

Put a resource into the global resource pool as an override. This means it gets put at the head of the list and is searched before other existing resources that occupy the same position in the name map or the type map. The default is to override both the name and type maps. However, using the override argument you can specify that either the name map or type map is overridden. :param override: :param NAME_OVERRIDE:

classmethod get_by_name(scope, name, rpterr=True)

Function: get_by_name

looks up a resource by name in the name map. The first resource with the specified name, whose type is the current type, and is visible in the specified scope is returned, if one exists. The rpterr flag indicates whether or not an error should be reported if the search fails. If rpterr is set to one then a failure message is issued, including suggested spelling alternatives, based on resource names that exist in the database, gathered by the spell checker. :param cls: :param scope: :param name: :param rpterr:

Returns:

read(accessor=None)

Return the object stored in the resource container

write(t, accessor=None)

Function: write Modify the object stored in this resource container. If the resource is read-only then issue an error message and return without modifying the object in the container. If the resource is not read-only and an accessor object has been supplied then also update the accessor record. Lastly, replace the object value in the container with the value supplied as the argument, t, and release any processes blocked on <uvm_resource_base::wait_modified>. If the value to be written is the same as the value already present in the resource then the write is not done. That also means that the accessor record is not updated and the modified bit is not set. :param t: :param accessor:

classmethod get_highest_precedence(q, T=None)

Function: get_highest_precedence

In a queue of resources, locate the first one with the highest precedence whose type is T. This function is static so that it can be called from anywhere. #static function this_type get_highest_precedence(ref uvm_resource_types::rsrc_q_t q) :param q: :param T:

Returns:

class uvm.base.uvm_resource.UVMResourcePool

Bases: object

rp = None

classmethod get()

Function: get

Returns the singleton handle to the resource pool Returns:

spell_check(s)

Function: spell_check

Invokes the spell checker for a string s. The universe of correctly spelled strings – i.e. the dictionary – is the name map. :param s:

Returns:

set(rsrc, override=False)

Function: set

Add a new resource to the resource pool. The resource is inserted into both the name map and type map so it can be located by either.

An object creates a resources and sets it into the resource pool. Later, other objects that want to access the resource must get it from the pool

Overrides can be specified using this interface. Either a name override, a type override or both can be specified. If an override is specified then the resource is entered at the front of the queue instead of at the back. It is not recommended that users specify the override parameter directly, rather they use the set_override, set_name_override, or set_type_override functions.

Parameters

• rsrc –

• override –

push_get_record(name, scope, rsrc)

function - push_get_record

Insert a new record into the get history list. #function void push_get_record(string name, string scope,

uvm_resource_base rsrc)

Parameters

• name –

• scope –

• rsrc –

lookup_name(scope, name, type_handle=None, rpterr=True)

Function: lookup_name

Lookup resources by name. Returns a queue of resources that match the name, scope, and type_handle. If no resources match the queue is returned empty. If rpterr is set then a warning is issued if no matches are found, and the spell checker is invoked on name. If type_handle is None then a type check is not made and resources are returned that match only name and scope. :param scope: :param name: :param type_handle: :param rpterr:

Returns:

get_highest_precedence(q)

Function: get_highest_precedence

Traverse a queue, q, of resources and return the one with the highest precedence. In the case where there exists more than one resource with the highest precedence value, the first one that has that precedence will be the one that is returned.

#function uvm_resource_base get_highest_precedence(ref uvm_resource_types::rsrc_q_t q) :param q:

Returns:

classmethod sort_by_precedence(q)

Function: sort_by_precedence

Given a list of resources, obtained for example from lookup_scope, sort the resources in precedence order. The highest precedence resource will be first in the list and the lowest precedence will be last. Resources that have the same precedence and the same name will be ordered by most recently set first. #static function queue sort_by_precedence(ref uvm_resource_types::rsrc_q_t q) :param cls: :param q:

Returns:

get_by_name(scope, name, type_handle, rpterr=True)

Function: get_by_name

Lookup a resource by name, scope, and type_handle. Whether the get succeeds or fails, save a record of the get attempt. The rpterr flag indicates whether to report errors or not. Essentially, it serves as a verbose flag. If set then the spell checker will be invoked and warnings about multiple resources will be produced.

#function uvm_resource_base get_by_name(string scope = “”,

string name, uvm_resource_base type_handle, bit rpterr = 1)

Parameters

• scope –

• name –

• type_handle –

• rpterr –

Returns:

lookup_regex_names(scope, name, type_handle=None)

Function: lookup_regex_names

This utility function answers the question, for a given name, scope, and type_handle, what are all of the resources with requested name, a matching scope (where the resource scope may be a regular expression), and a matching type? name and scope are explicit values. #function uvm_resource_types::rsrc_q_t lookup_regex_names(string scope,

string name, uvm_resource_base type_handle = None)

Parameters

• scope –

• name –

• type_handle –

Returns:

lookup_scope(scope)

Function: lookup_scope

This is a utility function that answers the question: For a given scope, what resources are visible to it? Locate all the resources that are visible to a particular scope. This operation could be quite expensive, as it has to traverse all of the resources in the database. #function uvm_resource_types::rsrc_q_t lookup_scope(string scope) :param scope:

Returns:

set_priority_queue(rsrc, q, pri)

#local function void set_priority_queue(uvm_resource_base rsrc,

ref uvm_resource_types::rsrc_q_t q, uvm_resource_types::priority_e pri)

Parameters

• rsrc –

• q –

• pri –

set_priority_name(rsrc, pri)

#function void set_priority_name(uvm_resource_base rsrc,

uvm_resource_types::priority_e pri)

Parameters

• rsrc –

• pri –

print_resources(rq, audit=False)

Print the resources that are in a single queue, rq. This is a utility function that can be used to print any collection of resources stored in a queue. The audit flag determines whether or not the audit trail is printed for each resource along with the name, value, and scope regular expression. #function void print_resources(uvm_resource_types::rsrc_q_t rq, bit audit = 0) :param rq: :param audit:

dump(audit=False)