uvm_phase

Section: Phasing Definition classes

The following class are used to specify a phase and its implied functionality.

uvm.base.uvm_phase.UVM_PH_TRACE(ID, MSG, PH, VERB)

uvm.base.uvm_phase.ph2str(state) → str

class uvm.base.uvm_phase.UVMPhaseStateChange(name='uvm_phase_state_change')

Bases: UVMObject

Class: UVMPhaseStateChange

Phase state transition descriptor. Used to describe the phase transition that caused a UVMPhaseCb.phase_state_changed() callback to be invoked.

get_state()

Returns the state the phase just transitioned to. Functionally equivalent to <uvm_phase::get_state()>.

Returns:

get_prev_state()

Returns the state the phase just transitioned from.

Returns:

jump_to()

If the current state is UVM_PHASE_ENDED or UVM_PHASE_JUMPING because of a phase jump, returns the phase that is the target of jump. Returns None otherwise.

Returns:

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 = 'UVMPhaseStateChange'

class uvm.base.uvm_phase.UVMPhase(name='uvm_phase', phase_type=3, parent=None)

Bases: UVMObject

Class: UVMPhase

This base class defines everything about a phase: behavior, state, and context.

To define behavior, it is extended by UVM or the user to create singleton objects which capture the definition of what the phase does and how it does it. These are then cloned to produce multiple nodes which are hooked up in a graph structure to provide context: which phases follow which, and to hold the state of the phase throughout its lifetime. UVM provides default extensions of this class for the standard runtime phases. VIP Providers can likewise extend this class to define the phase functor for a particular component context as required.

This base class defines everything about a phase: behavior, state, and context.

To define behavior, it is extended by UVM or the user to create singleton objects which capture the definition of what the phase does and how it does it. These are then cloned to produce multiple nodes which are hooked up in a graph structure to provide context: which phases follow which, and to hold the state of the phase throughout its lifetime. UVM provides default extensions of this class for the standard runtime phases. VIP Providers can likewise extend this class to define the phase functor for a particular component context as required.

Phase Definition

Singleton instances of those extensions are provided as package variables. These instances define the attributes of the phase (not what state it is in) They are then cloned into schedule nodes which point back to one of these implementations, and calls its virtual task or function methods on each participating component. It is the base class for phase functors, for both predefined and user-defined phases. Per-component overrides can use a customized imp.

To create custom phases, do not extend uvm_phase directly: see the three predefined extended classes below which encapsulate behavior for different phase types: task, bottom-up function and top-down function.

Extend the appropriate one of these to create a uvm_YOURNAME_phase class (or YOURPREFIX_NAME_phase class) for each phase, containing the default implementation of the new phase, which must be a uvm_component-compatible delegate, and which may be a ~null~ implementation. Instantiate a singleton instance of that class for your code to use when a phase handle is required. If your custom phase depends on methods that are not in uvm_component, but are within an extended class, then extend the base YOURPREFIX_NAME_phase class with parameterized component class context as required, to create a specialized functor which calls your extended component class methods. This scheme ensures compile-safety for your extended component classes while providing homogeneous base types for APIs and underlying data structures.

Phase Context

A schedule is a coherent group of one or mode phase/state nodes linked together by a graph structure, allowing arbitrary linear/parallel relationships to be specified, and executed by stepping through them in the graph order. Each schedule node points to a phase and holds the execution state of that phase, and has optional links to other nodes for synchronization.

The main operations are: construct, add phases, and instantiate hierarchically within another schedule.

Structure is a DAG (Directed Acyclic Graph). Each instance is a node connected to others to form the graph. Hierarchy is overlaid with m_parent. Each node in the graph has zero or more successors, and zero or more predecessors. No nodes are completely isolated from others. Exactly one node has zero predecessors. This is the root node. Also the graph is acyclic, meaning for all nodes in the graph, by following the forward arrows you will never end up back where you started but you will eventually reach a node that has no successors.

Phase State

A given phase may appear multiple times in the complete phase graph, due to the multiple independent domain feature, and the ability for different VIP to customize their own phase schedules perhaps reusing existing phases. Each node instance in the graph maintains its own state of execution.

Phase Handle

Handles of this type uvm_phase are used frequently in the API, both by the user, to access phasing-specific API, and also as a parameter to some APIs. In many cases, the singleton phase handles can be used (eg. <uvm_run_phase::get()>) in APIs. For those APIs that need to look up that phase in the graph, this is done automatically.

m_phase_trace = 0

m_use_ovm_run_semantic = 0

m_phase_hopper = <uvm.base.uvm_mailbox.UVMMailbox object>

m_executing_phases: Dict[UVMPhase, bool] = {}

is_task_phase()

Returns True if the given phase is task (async) phase.

get_phase_type()

get_phase_done_event()

get_phase_synced_event()

set_state(state)

get_state()

get_run_count()

find_by_name(name: str, stay_in_scope=1)

find(phase, stay_in_scope=True)

is_before(phase)

is_after(phase)

exec_func(comp, phase)

add(phase, with_phase=None, after_phase=None, before_phase=None)

get_parent()

get_full_name()

Objects possessing hierarchy, such as <uvm_components>, override the default implementation. Other objects might be associated with component hierarchy but are not themselves components. For example, <uvm_sequence #(REQ,RSP)> classes are typically associated with a <uvm_sequencer #(REQ,RSP)>. In this case, it is useful to override get_full_name to return the sequencer’s full name concatenated with the sequence’s name. This provides the sequence a full context, which is useful when debugging.

Returns

The full hierarchical name of this object. The default implementation is the same as <get_name>, as uvm_objects do not inherently possess hierarchy.

Return type

str

get_schedule(hier=False)

get_schedule_name(hier=False)

get_domain()

get_domain_name()

get_adjacent_successor_nodes()

m_report_null_objection(obj, description, count, action)

get_objection()

raise_objection(obj, description='', count=1)

drop_objection(obj, description='', count=1)

async wait_for_state(state, op=3)

end_prematurely()

get_jump_target()

m_find_predecessor(phase: UVMPhase, stay_in_scope=True, orig_phase=None)

m_find_successor(phase: UVMPhase, stay_in_scope=True, orig_phase=None)

m_find_predecessor_by_name(name, stay_in_scope=1, orig_phase=None)

m_find_successor_by_name(name, stay_in_scope=1, orig_phase=None)

execute(comp, phase)

get_ready_to_end_count()

get_predecessors_for_successors(pred_of_succ)

async m_wait_for_pred()

clear(state=1)

clear_successors(state=1, end_state=None)

async classmethod m_run_phases()

async execute_phase()

has_predecessors()

async wait_for_self_and_siblings_to_drop()

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.

async wait_for_criterion_for_end_phase(state_chg)

class uvm.base.uvm_phase.UVMPhaseCb(name='unnamed-uvm_phase_cb')

Bases: UVMCallback

phase_state_change(phase, change)

Function: phase_state_change

Called whenever a phase changes state. The change descriptor describes the transition that was just completed. The callback method is invoked immediately after the phase state has changed, but before the phase implementation is executed.

An extension may interact with the phase, such as raising the phase objection to prolong the phase, in a manner that is consistent with the current phase state.

By default, the callback method does nothing. Unless otherwise specified, modifying the phase transition descriptor has no effect on the phasing schedule or execution.

Parameters

• phase –

• change –