[source]

Class uvm_pkg::uvm_phase

uvm_pkg::uvm_phase + m_imp : uvm_phase + m_num_procs_not_yet_returned : int + max_ready_to_end_iter : int unsigned + phase_done : uvm_objection + add(): void + clear(): void + clear_successors(): void + convert2string(): string + drop_objection(): void + end_prematurely(): void + exec_func(): void + exec_task() + execute(): void + find(): uvm_phase + find_by_name(): uvm_phase + get_adjacent_predecessor_nodes(): void + get_adjacent_successor_nodes(): void + get_begin_node(): uvm_phase + get_domain(): uvm_domain + get_domain_name(): string + get_end_node(): uvm_phase + get_full_name(): string + get_imp(): uvm_phase + get_jump_target(): uvm_phase + get_objection(): uvm_objection + get_objection_count(): int + get_parent(): uvm_phase + get_phase_type(): uvm_phase_type + get_ready_to_end_count(): int unsigned + get_run_count(): int + get_schedule(): uvm_phase + get_schedule_name(): string + get_state(): uvm_phase_state + is(): bit + is_after(): bit + is_before(): bit + is_domain(): bit + jump(): void + jump_all(): void + kill(): void + kill_successors(): void + m_find_predecessor(): uvm_phase + m_find_predecessor_by_name(): uvm_phase + m_find_successor(): uvm_phase + m_find_successor_by_name(): uvm_phase + m_get_transitive_children(): void + m_print_successors(): void + m_report_null_objection(): void + m_run_phases() + raise_objection(): void + set_jump_phase(): void + sync(): void + traverse(): void + unsync(): void + wait_for_state() uvm_pkg::uvm_domain uvm_pkg::uvm_task_phase uvm_pkg::uvm_bottomup_phase uvm_pkg::uvm_topdown_phase

Inheritance Diagram of uvm_phase

uvm_pkg::uvm_phase + m_imp : uvm_phase + m_num_procs_not_yet_returned : int + max_ready_to_end_iter : int unsigned + phase_done : uvm_objection + add(): void + clear(): void + clear_successors(): void + convert2string(): string + drop_objection(): void + end_prematurely(): void + exec_func(): void + exec_task() + execute(): void + find(): uvm_phase + find_by_name(): uvm_phase + get_adjacent_predecessor_nodes(): void + get_adjacent_successor_nodes(): void + get_begin_node(): uvm_phase + get_domain(): uvm_domain + get_domain_name(): string + get_end_node(): uvm_phase + get_full_name(): string + get_imp(): uvm_phase + get_jump_target(): uvm_phase + get_objection(): uvm_objection + get_objection_count(): int + get_parent(): uvm_phase + get_phase_type(): uvm_phase_type + get_ready_to_end_count(): int unsigned + get_run_count(): int + get_schedule(): uvm_phase + get_schedule_name(): string + get_state(): uvm_phase_state + is(): bit + is_after(): bit + is_before(): bit + is_domain(): bit + jump(): void + jump_all(): void + kill(): void + kill_successors(): void + m_find_predecessor(): uvm_phase + m_find_predecessor_by_name(): uvm_phase + m_find_successor(): uvm_phase + m_find_successor_by_name(): uvm_phase + m_get_transitive_children(): void + m_print_successors(): void + m_report_null_objection(): void + m_run_phases() + raise_objection(): void + set_jump_phase(): void + sync(): void + traverse(): void + unsync(): void + wait_for_state() uvm_pkg::uvm_objection m_imp phase_done

Collaboration Diagram of uvm_phase

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.

Variables

Name

Type

Description
max_ready_to_end_iter

int unsigned
phase_done

uvm_objection

phase done objection

Constructors

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

Function

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. New

Parameters:

Functions

get_phase_type()

Function

get_phase_type

Returns the phase type as defined by uvm_phase_type. Get_phase_type

Return type:

uvm_phase_type

get_state()

Function

get_state

Accessor to return current state of this phase. Get_state

Return type:

uvm_phase_state

get_run_count()

Function

get_run_count

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

find_by_name(string name, bit stay_in_scope = 1)

Function

find_by_name

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_by_name

Parameters:

  • name (string)

  • stay_in_scope (bit)

Return type:

uvm_phase

find(uvm_phase phase, bit stay_in_scope = 1)

Function

find

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. Find

Parameters:
Return type:

uvm_phase

is(uvm_phase phase)

Function

is

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

Parameters:

phase (uvm_phase)

is_before(uvm_phase phase)

Function

is_before

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

Parameters:

phase (uvm_phase)

is_after(uvm_phase phase)

Function

is_after

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

Parameters:

phase (uvm_phase)

exec_func(uvm_component comp, uvm_phase phase)

Function

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

Parameters:
add(uvm_phase phase, uvm_phase with_phase = null, uvm_phase after_phase = null, uvm_phase before_phase = null)

Function

add

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. Add

TBD error checks if param nodes are actually in this schedule or not

Parameters:
get_parent()

Function

get_parent

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

Return type:

uvm_phase

get_full_name()

Function

get_full_name

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

get_schedule(bit hier = 0)

Function

get_schedule

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

Parameters:

hier (bit)

Return type:

uvm_phase

get_schedule_name(bit hier = 0)

Function

get_schedule_name

Returns the schedule name associated with this phase node. Get_schedule_name

Parameters:

hier (bit)

get_domain()

Function

get_domain

Returns the enclosing domain. Get_domain

Return type:

uvm_domain

get_imp()

Function

get_imp

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

Return type:

uvm_phase

get_domain_name()

Function

get_domain_name

Returns the domain name associated with this phase node. Get_domain_name

get_adjacent_predecessor_nodes(uvm_phase pred)

Function

get_adjacent_predecessor_nodes

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.

Parameters:

pred (uvm_phase)

get_adjacent_successor_nodes(uvm_phase succ)

Function

get_adjacent_successor_nodes

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.

Parameters:

succ (uvm_phase)

get_objection()

Function

get_objection

Return the uvm_objection that gates the termination of the phase.

Return type:

uvm_objection

raise_objection(uvm_object obj, string description = "", int count = 1)

Function

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.

   while(1) begin
     some_phase.raise_objection(this);
     ...
     some_phase.drop_objection(this);
   end
   ... Raise_objection
Parameters:

  • obj (uvm_object)

  • description (string)

  • count (int)

drop_objection(uvm_object obj, string description = "", int count = 1)

Function

drop_objection

Drop an objection to ending this phase

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

Parameters:

  • obj (uvm_object)

  • description (string)

  • count (int)

get_objection_count(uvm_object obj = null)

Function

get_objection_count

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

Parameters:

obj (uvm_object)

sync(uvm_domain target, uvm_phase phase = null, uvm_phase with_phase = null)

Function

sync

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. Sync

Parameters:
unsync(uvm_domain target, uvm_phase phase = null, uvm_phase with_phase = null)

Function

unsync

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. Unsync

Parameters:
jump(uvm_phase phase)

Function

jump

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. Jump

Note that this function does not directly alter flow of control. That is, the new phase is not initiated in this function. Rather, flags are set which execute_phase() uses to determine that a jump has been requested and performs the jump.

Parameters:

phase (uvm_phase)

set_jump_phase(uvm_phase phase)

Function

set_jump_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. Set_jump_phase

Specify a phase to transition to when phase is complete.

Parameters:

phase (uvm_phase)

end_prematurely()

Function

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 jumpphase to go to after the phase ends. Endprematurely

Set a flag to cause the phase to end prematurely.

jump_all(uvm_phase phase)

Function- jump_all

Make all schedules jump to a specified phase , even if the jump target is local. The jump happens to all phase schedules that contain the jump-to phase , i.e. a global jump. Jump_all

Parameters:

phase (uvm_phase)

get_jump_target()

Function

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. Get_jump_target

Return type:

uvm_phase

traverse(uvm_component comp, uvm_phase phase, uvm_phase_state state)

Implementation

Callbacks

Provide the required component traversal behavior. Called by execute()

Parameters:
execute(uvm_component comp, uvm_phase phase)

Provide the required per-component execution flow. Called by traverse()

Parameters:
get_begin_node()
Return type:

uvm_phase

get_end_node()
Return type:

uvm_phase

get_ready_to_end_count()
clear(uvm_phase_state state = UVM_PHASE_DORMANT)

Clear

for internal graph maintenance after a forward jump

Parameters:

state (uvm_phase_state)

clear_successors(uvm_phase_state state = UVM_PHASE_DORMANT, uvm_phase end_state = null)

Clear_successors

for internal graph maintenance after a forward jump called only by execute_phase() depth-first traversal of the DAG, calliing clear() on each node do not clear the end phase or beyond

Parameters:
kill()

Kill

kill_successors()

Using a depth-first traversal, kill all the successor phases of the current phase.

convert2string()
is_domain()

Tasks

exec_task(uvm_component comp, uvm_phase phase)

Function

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

Parameters:
wait_for_state(uvm_phase_state state, uvm_wait_op op = UVM_EQ)

Function

wait_for_state

Wait until this phase compares with the given state and op operand. For and 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);. Wait_for_state
Parameters: