# Phasing Definition classes

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

Contents

Phasing Definition classes | The following class are used to specify a phase and its implied functionality.
uvm_phase | This base class defines everything about a phase: behavior, state, and context.
uvm_phase_state_change | Phase state transition descriptor.
uvm_phase_cb | This class defines a callback method that is invoked by the phaser during the execution of a specific node in the phase graph or all phase nodes.
uvm_phase_cb_pool | Convenience type for the uvm_callbacks#(uvm_phase, uvm_phase_cb) class.

## uvm_phase

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.

Summary

uvm_phase
This base class defines everything about a phase: behavior, state, and context.
Class Hierarchy
uvm_void
uvm_object
uvm_phase
Class Declaration
> class uvm_phase extends uvm_object
Construction |
new | Create a new phase node, with a name and a note of its type name - name of this phase type - a value in uvm_phase_type
get_phase_type | Returns the phase type as defined by uvm_phase_type
State |
get_state | Accessor to return current state of this phase
get_run_count | Accessor to return the integer number of times this phase has executed
find_by_name | Locate a phase node with the specified name and return its handle.
find | Locate the phase node with the specified phase IMP and return its handle.
is | returns 1 if the containing uvm_phase refers to the same phase as the phase argument, 0 otherwise
is_before | Returns 1 if the containing uvm_phase refers to a phase that is earlier than the phase argument, 0 otherwise
is_after | returns 1 if the containing uvm_phase refers to a phase that is later than the phase argument, 0 otherwise
Callbacks |
exec_func | Implements the functor/delegate functionality for a function phase type comp - the component to execute the functionality upon phase - the phase schedule that originated this phase call
exec_task | Implements the functor/delegate functionality for a task phase type comp - the component to execute the functionality upon phase - the phase schedule that originated this phase call
Schedule |
add | Build up a schedule structure inserting phase by phase, specifying linkage
get_parent | Returns the parent schedule node, if any, for hierarchical graph traversal
get_full_name | Returns the full path from the enclosing domain down to this node.
get_schedule | Returns the topmost parent schedule node, if any, for hierarchical graph traversal
get_schedule_name | Returns the schedule name associated with this phase node
get_domain | Returns the enclosing domain
get_imp | Returns the phase implementation for this this node.
get_domain_name | Returns the domain name associated with this phase node
get_adjacent_predecessor_nodes | Provides an array of nodes which are predecessors to this phase node.
get_adjacent_successor_nodes | Provides an array of nodes which are successors to this phase node.
Phase Done Objection | Task-based phase nodes within the phasing graph provide a uvm_objection based interface for prolonging the execution of the phase.
get_objection | Return the uvm_objection that gates the termination of the phase.
raise_objection | Raise an objection to ending this phase Provides components with greater control over the phase flow for processes which are not implicit objectors to the phase.
drop_objection | Drop an objection to ending this phase
get_objection_count | Returns the current number of objections to ending this phase raised by the given object.
Synchronization | The functions ‘sync’ and ‘unsync’ add soft sync relationships between nodes
sync | Synchronize two domains, fully or partially
unsync | Remove synchronization between two domains, fully or partially
wait_for_state | Wait until this phase compares with the given state and op operand.
Jumping |
jump | Jump to a specified phase.
set_jump_phase | Specify a phase to transition to when phase is complete.
end_prematurely | Set a flag to cause the phase to end prematurely.
get_jump_target | Return handle to the target phase of the current jump, or null if no jump is in progress.

### Construction

### new

> function new(
> | string | name | = | "uvm_phase",
> | uvm_phase_type | phase_type | = | UVM_PHASE_SCHEDULE,
> | uvm_phase | parent | = | null
> )

Create a new phase node, with a name and a note of its type name - name of this phase type - a value in uvm_phase_type

### get_phase_type

> function uvm_phase_type get_phase_type()

Returns the phase type as defined by uvm_phase_type

### State

### get_state

> function uvm_phase_state get_state()

Accessor to return current state of this phase

### get_run_count

> function int get_run_count()

Accessor to return the integer number of times this phase has executed

### find_by_name

> function uvm_phase find_by_name(
> | string | name, |  |
> | bit | stay_in_scope | = | 1
> )

Locate a phase node with the specified name and return its handle. With stay_in_scope set, searches only within this phase’s schedule or domain.

### find

> function uvm_phase find(
> | uvm_phase | phase, |  |
> | bit | stay_in_scope | = | 1
> )

Locate the phase node with the specified phase IMP and return its handle. With stay_in_scope set, searches only within this phase’s schedule or domain.

### is

> function bit is(
> | uvm_phase | phase
> )

returns 1 if the containing uvm_phase refers to the same phase as the phase argument, 0 otherwise

### is_before

> function bit is_before(
> | uvm_phase | phase
> )

Returns 1 if the containing uvm_phase refers to a phase that is earlier than the phase argument, 0 otherwise

### is_after

> function bit is_after(
> | uvm_phase | phase
> )

returns 1 if the containing uvm_phase refers to a phase that is later than the phase argument, 0 otherwise

### Callbacks

### exec_func

> virtual function void exec_func(
> | uvm_component | comp,
> | uvm_phase | phase
> )

Implements the functor/delegate functionality for a function phase type comp - the component to execute the functionality upon phase - the phase schedule that originated this phase call

### exec_task

> virtual task exec_task(
> | uvm_component | comp,
> | uvm_phase | phase
> )

Implements the functor/delegate functionality for a task phase type comp - the component to execute the functionality upon phase - the phase schedule that originated this phase call

### Schedule

### add

> function void add(
> | uvm_phase | phase, |  |
> | uvm_phase | with_phase | = | null,
> | uvm_phase | after_phase | = | null,
> | uvm_phase | before_phase | = | null
> )

Build up a schedule structure inserting phase by phase, specifying linkage

Phases can be added anywhere, in series or parallel with existing nodes

phase | handle of singleton derived imp containing actual functor. by default the new phase is appended to the schedule
with_phase | specify to add the new phase in parallel with this one
after_phase | specify to add the new phase as successor to this one
before_phase | specify to add the new phase as predecessor to this one

### get_parent

> function uvm_phase get_parent()

Returns the parent schedule node, if any, for hierarchical graph traversal

### get_full_name

> virtual function string get_full_name()

Returns the full path from the enclosing domain down to this node. The singleton IMP phases have no hierarchy.

### get_schedule

> function uvm_phase get_schedule(
> | bit | hier | = | 0
> )

Returns the topmost parent schedule node, if any, for hierarchical graph traversal

### get_schedule_name

> function string get_schedule_name(
> | bit | hier | = | 0
> )

Returns the schedule name associated with this phase node

### get_domain

> function uvm_domain get_domain()

Returns the enclosing domain

### get_imp

> function uvm_phase get_imp()

Returns the phase implementation for this this node. Returns null if this phase type is not a UVM_PHASE_LEAF_NODE.

### get_domain_name

> function string get_domain_name()

Returns the domain name associated with this phase node

### get_adjacent_predecessor_nodes

> function void get_adjacent_predecessor_nodes(
> | ref | uvm_phase | pred[]
> )

Provides an array of nodes which are predecessors to this phase node. A ‘predecessor node’ is defined as any phase node which lies prior to this node in the phase graph, with no nodes between this node and the predecessor node.

### get_adjacent_successor_nodes

> function void get_adjacent_successor_nodes(
> | ref | uvm_phase | succ[]
> )

Provides an array of nodes which are successors to this phase node. A ‘successor’s node’ is defined as any phase node which comes after this node in the phase graph, with no nodes between this node and the successor node.

### Phase Done Objection

Task-based phase nodes within the phasing graph provide a uvm_objection based interface for prolonging the execution of the phase. All other phase types do not contain an objection, and will report a fatal error if the user attempts to raise, drop, or get_objection_count.

### get_objection

> function uvm_objection get_objection()

Return the uvm_objection that gates the termination of the phase.

### raise_objection

> virtual function void raise_objection (
> | uvm_object | obj, |  |
> | string | description | = | "",
> | int | count | = | 1
> )

Raise an objection to ending this phase Provides components with greater control over the phase flow for processes which are not implicit objectors to the phase.

>     while(1) begin
>       some_phase.raise_objection(this);
>       ...
>       some_phase.drop_objection(this);
>     end
>     ...

### drop_objection

> virtual function void drop_objection (
> | uvm_object | obj, |  |
> | string | description | = | "",
> | int | count | = | 1
> )

Drop an objection to ending this phase

The drop is expected to be matched with an earlier raise.

### get_objection_count

> virtual function int get_objection_count(
> | uvm_object | obj | = | null
> )

Returns the current number of objections to ending this phase raised by the given object.

### Synchronization

The functions ‘sync’ and ‘unsync’ add soft sync relationships between nodes

#### Summary of usage

>     my_phase.sync(.target(domain)
>                  [,.phase(phase)[,.with_phase(phase)]]);
>     my_phase.unsync(.target(domain)
>                    [,.phase(phase)[,.with_phase(phase)]]);

Components in different schedule domains can be phased independently or in sync with each other. An API is provided to specify synchronization rules between any two domains. Synchronization can be done at any of three levels:

- the domain’s whole phase schedule can be synchronized
- a phase can be specified, to sync that phase with a matching counterpart
- or a more detailed arbitrary synchronization between any two phases

Each kind of synchronization causes the same underlying data structures to be managed. Like other APIs, we use the parameter dot-notation to set optional parameters.

When a domain is synced with another domain, all of the matching phases in the two domains get a ‘with’ relationship between them. Likewise, if a domain is unsynched, all of the matching phases that have a ‘with’ relationship have the dependency removed. It is possible to sync two domains and then just remove a single phase from the dependency relationship by unsyncing just the one phase.

### sync

> function void sync(
> | uvm_domain | target, |  |
> | uvm_phase | phase | = | null,
> | uvm_phase | with_phase | = | null
> )

Synchronize two domains, fully or partially

target | handle of target domain to synchronize this one to
phase | optional single phase in this domain to synchronize, otherwise sync all
with_phase | optional different target-domain phase to synchronize with, otherwise use phase in the target domain

### unsync

> function void unsync(
> | uvm_domain | target, |  |
> | uvm_phase | phase | = | null,
> | uvm_phase | with_phase | = | null
> )

Remove synchronization between two domains, fully or partially

target | handle of target domain to remove synchronization from
phase | optional single phase in this domain to un-synchronize, otherwise unsync all
with_phase | optional different target-domain phase to un-synchronize with, otherwise use phase in the target domain

### wait_for_state

> task wait_for_state(
> | uvm_phase_state | state, |  |
> | uvm_wait_op | op | = | UVM_EQ
> )

Wait until this phase compares with the given state and op operand. For UVM_EQ and UVM_NE operands, several uvm_phase_states can be supplied by ORing their enum constants, in which case the caller will wait until the phase state is any of (UVM_EQ) or none of (UVM_NE) the provided states.

To wait for the phase to be at the started state or after

>     wait_for_state(UVM_PHASE_STARTED, UVM_GTE);

To wait for the phase to be either started or executing

>     wait_for_state(UVM_PHASE_STARTED | UVM_PHASE_EXECUTING, UVM_EQ);

### Jumping

### jump

> function void jump(
> | uvm_phase | phase
> )

Jump to a specified phase. If the destination phase is within the current phase schedule, a simple local jump takes place. If the jump-to phase is outside of the current schedule then the jump affects other schedules which share the phase.

### set_jump_phase

> function void set_jump_phase(
> | uvm_phase | phase
> )

Specify a phase to transition to when phase is complete. Note that this function is part of what jump() does; unlike jump() it does not set the flag to terminate the phase prematurely.

### end_prematurely

> function void end_prematurely()

Set a flag to cause the phase to end prematurely. Note that this function is part of what jump() does; unlike jump() it does not set a jump_phase to go to after the phase ends.

### get_jump_target

> function uvm_phase get_jump_target()

Return handle to the target phase of the current jump, or null if no jump is in progress. Valid for use during the phase_ended() callback

## uvm_phase_state_change

Phase state transition descriptor. Used to describe the phase transition that caused a <uvm_phase_cb::phase_state_changed()> callback to be invoked.

Summary

uvm_phase_state_change
Phase state transition descriptor.
Class Hierarchy
uvm_void
uvm_object
uvm_phase_state_change
Class Declaration
> class uvm_phase_state_change extends uvm_object
Methods |
get_state() | Returns the state the phase just transitioned to.
get_prev_state() | Returns the state the phase just transitioned from.
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.

### Methods

### get_state()

> virtual function uvm_phase_state get_state()

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

### get_prev_state()

> virtual function uvm_phase_state get_prev_state()

Returns the state the phase just transitioned from.

### jump_to()

> function uvm_phase 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 null otherwise.

## uvm_phase_cb

This class defines a callback method that is invoked by the phaser during the execution of a specific node in the phase graph or all phase nodes. User-defined callback extensions can be used to integrate data types that are not natively phase-aware with the UVM phasing.

Summary

uvm_phase_cb
This class defines a callback method that is invoked by the phaser during the execution of a specific node in the phase graph or all phase nodes.
Class Hierarchy
uvm_void
uvm_object
uvm_callback
uvm_phase_cb
Class Declaration
> class uvm_phase_cb extends uvm_callback
Methods |
new | Constructor
phase_state_change | Called whenever a phase changes state.

### Methods

### new

> function new(
> | string | name | = | "unnamed-uvm_phase_cb"
> )

Constructor

### phase_state_change

> virtual function void phase_state_change(
> | uvm_phase | phase,
> | uvm_phase_state_change | 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.

## uvm_phase_cb_pool

Convenience type for the uvm_callbacks#(uvm_phase, uvm_phase_cb) class.

Summary

uvm_phase_cb_pool
Convenience type for the uvm_callbacks#(uvm_phase, uvm_phase_cb) class.
Class Declaration
> typedef uvm_callbacks#(
> | uvm_phase,
> | uvm_phase_cb
> ) uvm_phase_cb_pool

> class uvm_phase extends uvm_object

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

> class uvm_phase_state_change extends uvm_object

Phase state transition descriptor.

> class uvm_phase_cb extends uvm_callback

This class defines a callback method that is invoked by the phaser during the execution of a specific node in the phase graph or all phase nodes.

> typedef uvm_callbacks#(
> | uvm_phase,
> | uvm_phase_cb
> ) uvm_phase_cb_pool

Convenience type for the uvm_callbacks#(uvm_phase, uvm_phase_cb) 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 | = | "uvm_phase",
> | uvm_phase_type | phase_type | = | UVM_PHASE_SCHEDULE,
> | uvm_phase | parent | = | null
> )

Create a new phase node, with a name and a note of its type name - name of this phase type - a value in uvm_phase_type
This is an attribute of a uvm_phase object which defines the phase type.

> function uvm_phase_type get_phase_type()

Returns the phase type as defined by uvm_phase_type

> function uvm_phase_state get_state()

Accessor to return current state of this phase

> function int get_run_count()

Accessor to return the integer number of times this phase has executed

> function uvm_phase find_by_name(
> | string | name, |  |
> | bit | stay_in_scope | = | 1
> )

Locate a phase node with the specified name and return its handle.

> function uvm_phase find(
> | uvm_phase | phase, |  |
> | bit | stay_in_scope | = | 1
> )

Locate the phase node with the specified phase IMP and return its handle.

> function bit is(
> | uvm_phase | phase
> )

returns 1 if the containing uvm_phase refers to the same phase as the phase argument, 0 otherwise

> function bit is_before(
> | uvm_phase | phase
> )

Returns 1 if the containing uvm_phase refers to a phase that is earlier than the phase argument, 0 otherwise

> function bit is_after(
> | uvm_phase | phase
> )

returns 1 if the containing uvm_phase refers to a phase that is later than the phase argument, 0 otherwise

> virtual function void exec_func(
> | uvm_component | comp,
> | uvm_phase | phase
> )

Implements the functor/delegate functionality for a function phase type comp - the component to execute the functionality upon phase - the phase schedule that originated this phase call

> virtual task exec_task(
> | uvm_component | comp,
> | uvm_phase | phase
> )

Implements the functor/delegate functionality for a task phase type comp - the component to execute the functionality upon phase - the phase schedule that originated this phase call

> function void add(
> | uvm_phase | phase, |  |
> | uvm_phase | with_phase | = | null,
> | uvm_phase | after_phase | = | null,
> | uvm_phase | before_phase | = | null
> )

Build up a schedule structure inserting phase by phase, specifying linkage

> function uvm_phase get_parent()

Returns the parent schedule node, if any, for hierarchical graph traversal

> virtual function string get_full_name()

Returns the full path from the enclosing domain down to this node.

> function uvm_phase get_schedule(
> | bit | hier | = | 0
> )

Returns the topmost parent schedule node, if any, for hierarchical graph traversal

> function string get_schedule_name(
> | bit | hier | = | 0
> )

Returns the schedule name associated with this phase node

> function uvm_domain get_domain()

Returns the enclosing domain

> function uvm_phase get_imp()

Returns the phase implementation for this this node.

> function string get_domain_name()

Returns the domain name associated with this phase node

> function void get_adjacent_predecessor_nodes(
> | ref | uvm_phase | pred[]
> )

Provides an array of nodes which are predecessors to this phase node.

> function void get_adjacent_successor_nodes(
> | ref | uvm_phase | succ[]
> )

Provides an array of nodes which are successors to this phase node.

> class uvm_objection extends uvm_report_object

Objections provide a facility for coordinating status information between two or more participating components, objects, and even module-based IP.

> function uvm_objection get_objection()

Return the uvm_objection that gates the termination of the phase.

> virtual function void raise_objection (
> | uvm_object | obj, |  |
> | string | description | = | "",
> | int | count | = | 1
> )

Raise an objection to ending this phase Provides components with greater control over the phase flow for processes which are not implicit objectors to the phase.

> virtual function void drop_objection (
> | uvm_object | obj, |  |
> | string | description | = | "",
> | int | count | = | 1
> )

Drop an objection to ending this phase

> virtual function int get_objection_count(
> | uvm_object | obj | = | null
> )

Returns the current number of objections to ending this phase raised by the given object.

> function void sync(
> | uvm_domain | target, |  |
> | uvm_phase | phase | = | null,
> | uvm_phase | with_phase | = | null
> )

Synchronize two domains, fully or partially

> function void unsync(
> | uvm_domain | target, |  |
> | uvm_phase | phase | = | null,
> | uvm_phase | with_phase | = | null
> )

Remove synchronization between two domains, fully or partially

> task wait_for_state(
> | uvm_phase_state | state, |  |
> | uvm_wait_op | op | = | UVM_EQ
> )

Wait until this phase compares with the given state and op operand.

> function void jump(
> | uvm_phase | phase
> )

Jump to a specified phase.

> function void set_jump_phase(
> | uvm_phase | phase
> )

Specify a phase to transition to when phase is complete.

> function void end_prematurely()

Set a flag to cause the phase to end prematurely.

> function uvm_phase get_jump_target()

Return handle to the target phase of the current jump, or null if no jump is in progress.

> static function uvm_run_phase get()

Returns the singleton phase handle
equal
not equal
The set of possible states of a phase.

> virtual function uvm_phase_state get_state()

Returns the state the phase just transitioned to.

> virtual function uvm_phase_state get_prev_state()

Returns the state the phase just transitioned from.

> function uvm_phase 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.

> class uvm_callback extends uvm_object

The uvm_callback class is the base class for user-defined callback classes.

> function new(
> | string | name | = | "unnamed-uvm_phase_cb"
> )

Constructor

> virtual function void phase_state_change(
> | uvm_phase | phase,
> | uvm_phase_state_change | change
> )

Called whenever a phase changes state.