uvm_phase_hopper

The UVM phase hopper is responsible for the execution of the UVM phases during a test.

The UVM Library is responsible for calling run_phases on the phase hopper after transitioning the state of the UVM core to UVM_CORE_RUNNING.  The core shall stay in the RUNNING state until the run_phases task completes, at which point it shall transition to the UVM_CORE_POST_RUN state.

Phases are added to the hopper via the try_set method, and are retrieved using the try_get,~get~,~try_peek~, and peek methods.  After retrieving a new phase, the run_phases task is responsible for transitioning the phase’s state through the appropriate path (see <uvm_phase_state>).

@uvm-contrib For potential contribution to the 1800.2 standard

Summary
uvm_phase_hopper
The UVM phase hopper is responsible for the execution of the UVM phases during a test.
Class Hierarchy
uvm_object
uvm_phase_hopper
Class Declaration
class uvm_phase_hopper extends uvm_object
newCreates a new uvm_phase_hopper instance with name.
Singleton Accessors
get_global_hopperReturns the global phase hopper.
Queue API
try_putAttempts to add a new phase to the hopper.
getRetrieves the next phase from the hopper.
try_getAttempts to retrieve the next phase from the hopper.
peekCopies a phase from the hopper.
try_peekAttempts to copy a phase from the hopper.
Active Phase Objection
get_objectionRetrieves the Active Phase Objection.
raise_objectionThis is a pass through to <uvm_objection::raise_objection> on the objection returned by get_objection.
drop_objectionThis is a pass through to <uvm_objection::drop_objection> on the objection returned by get_objection.
get_objection_countThis is a pass through to <uvm_objection::get_objection_count> on the objection returned by get_objection.
get_objection_totalThis is a pass through to <uvm_objection::get_objection_total> on the objection returned by get_objection.
wait_for_objectionThis is a pass through to <uvm_objection::wait_for> on the objection returned by get_objection.
Phase Graph Execution
run_phasesRuns all phases associated with a test.
process_phaseProcesses a phase.
TransitionsPerforms actions associated with transitioning phase state to the UVM_PHASE_SYNCING state.
start_phasePerforms actions associated with transitioning phase state to the UVM_PHASE_STARTED state.
execute_phasePerforms actions associated with transitioning phase state to the UVM_PHASE_EXECUTING state.
end_phasePerforms actions associated with transitioning phase state to the UVM_PHASE_ENDED state.
cleanup_phasePerforms actions associated with transitioning phase state to the UVM_PHASE_CLEANUP or UVM_PHASE_JUMPING state.
finish_phasePerforms actions associated with transitioning phase state to the UVM_PHASE_DONE state.
wait_for_waitersDelays execution to allow waiters on phase state changes to react.
Phase Component Traversal
traverse_onCalls traverse on imp, passing in comp, node, and state.
execute_onCalls execute on imp, passing in comp, and node.

new

function new(
    string  name  =  "uvm_phase_hopper"
)

Creates a new uvm_phase_hopper instance with name.

get_global_hopper

static function uvm_phase_hopper get_global_hopper()

Returns the global phase hopper.

This method is provided as a wrapper function to conveniently retrieve the phase hopper via the uvm_coreservice_t::get_phase_hopper method.

try_put

virtual function bit try_put(
    uvm_phase  phase
)

Attempts to add a new phase to the hopper.

If the phase is successfully added to the internal queue, then raise_objection is called for phase, and ‘1’ is returned.  If the phase can not be added to the internal queue, then no objection is raised and ‘0’ is returned.

NOTEBy default the internal queue has no maximum depth, and as such this method shall always succeed.

get

protected virtual task get(
    output  uvm_phase  phase
)

Retrieves the next phase from the hopper.

The get method retrieves the next phase from the hopper, that is, removes one phase from the internal queue.  If the internal queue is empty, then the current process blocks until a phase is placed in the hopper.

try_get

protected virtual function bit try_get(
    inout  uvm_phase  phase
)

Attempts to retrieve the next phase from the hopper.

The try_get method attempts to retrieve the next phase from the hopper.  If no phases are available, then the method returns 0; otherwise returns 1.

peek

protected virtual task peek(
    output  uvm_phase  phase
)

Copies a phase from the hopper.

The peek method copies a phase from the internal queue without removing it.  If the internal queue is empty, then the current process blocks until a phase is placed in the hopper.

try_peek

protected virtual function bit try_peek(
    inout  uvm_phase  phase
)

Attempts to copy a phase from the hopper.

The try_peek method attempts to copy a phase from the internal queue without removing it.  If the internal queue is empty, then the method returns 0; otherwise return 1.

get_objection

protected virtual function uvm_objection get_objection()

Retrieves the Active Phase Objection.

The Active Phase Objection is used to track phases being processed by the hopper, ie. phases that have been added via a call to try_put, but have not yet completed processing via process_phase.

raise_objection

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

This is a pass through to <uvm_objection::raise_objection> on the objection returned by get_objection.

drop_objection

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

This is a pass through to <uvm_objection::drop_objection> on the objection returned by get_objection.

get_objection_count

virtual function int get_objection_count(
    uvm_object  obj  =  null
)

This is a pass through to <uvm_objection::get_objection_count> on the objection returned by get_objection.

get_objection_total

virtual function int get_objection_total(
    uvm_object  obj  =  null
)

This is a pass through to <uvm_objection::get_objection_total> on the objection returned by get_objection.

wait_for_objection

virtual task wait_for_objection(
    uvm_objection_event  objt_event,   
    uvm_object  obj  =  null
)

This is a pass through to <uvm_objection::wait_for> on the objection returned by get_objection.

run_phases

virtual task run_phases()

Runs all phases associated with a test.

The default implementation causes the following steps to occur in order:

  • try_put is passed <uvm_domain::get_common_domain>
  • A process is forked in a non-blocking fashion.  The forked process runs a forever loop that calls get.  When get returns, an additional process is forked in a non-blocking fashion that performs the following steps in order:
  • process_phase is called with the return value of get.
  • drop_objection is passed the return value of get.
  • The task is blocked, waiting on `wait_for_objection(UVM_ALL_DROPPED)`.

Note that the UVM core state shall transition to UVM_CORE_POST_RUN when run_phases returns.

process_phase

protected virtual task process_phase(
    uvm_phase  phase
)

Processes a phase.

The process_phase task transitions a phase from the SCHEDULED to the DONE state.

It calls the following tasks in order

  • sync_phase
  • start_phase
  • execute_phase
  • end_phase
  • cleanup_phase
  • finish_phase

Transitions

Performs actions associated with transitioning phase state to the UVM_PHASE_SYNCING state.

start_phase

protected virtual task start_phase(
    uvm_phase  phase
)

Performs actions associated with transitioning phase state to the UVM_PHASE_STARTED state.

execute_phase

protected virtual task execute_phase(
    uvm_phase  phase
)

Performs actions associated with transitioning phase state to the UVM_PHASE_EXECUTING state.

end_phase

protected virtual task end_phase(
    uvm_phase  phase
)

Performs actions associated with transitioning phase state to the UVM_PHASE_ENDED state.

cleanup_phase

protected virtual task cleanup_phase(
    uvm_phase  phase
)

Performs actions associated with transitioning phase state to the UVM_PHASE_CLEANUP or UVM_PHASE_JUMPING state.

finish_phase

protected virtual task finish_phase(
    uvm_phase  phase
)

Performs actions associated with transitioning phase state to the UVM_PHASE_DONE state.

wait_for_waiters

protected virtual task wait_for_waiters(
    uvm_phase  phase,
    uvm_phase_state  prev_state
)

Delays execution to allow waiters on phase state changes to react.

By default, wait_for_waiters shall pause for a single delta cycle.

traverse_on

virtual function void traverse_on(
    uvm_phase  imp,
    uvm_component  comp,
    uvm_phase  node,
    uvm_phase_state  state
)

Calls traverse on imp, passing in comp, node, and state.

The traverse_on function is a hook that allows the phase hopper to witness, and potentially change how a phase traverses the component hierarchy.

By default, the traverse_on method calls <uvm_phase::traverse> for imp on comp, which will then in turn call traverse_on for all of imp on all of comp’s children.

Depending on the traversal policy of imp, the phase may be executed on comp before or after traverse_on is called for comp’s children.

If comp is null, then the default implementation shall pass <uvm_root::get> to the traverse method.

execute_on

virtual function void execute_on(
    uvm_phase  imp,
    uvm_component  comp,
    uvm_phase  node
)

Calls execute on imp, passing in comp, and node.

Similar the traverse_on, the execute_on function is a hook that allows the phase hopper to witness, and potentially change how a phase executes on a component.

By default, the execute_on method calls <uvm_phase::execute> for imp on comp.

class uvm_phase_hopper extends uvm_object
The UVM phase hopper is responsible for the execution of the UVM phases during a test.
function new(
    string  name  =  "uvm_phase_hopper"
)
Creates a new uvm_phase_hopper instance with name.
static function uvm_phase_hopper get_global_hopper()
Returns the global phase hopper.
virtual function bit try_put(
    uvm_phase  phase
)
Attempts to add a new phase to the hopper.
protected virtual task get(
    output  uvm_phase  phase
)
Retrieves the next phase from the hopper.
protected virtual function bit try_get(
    inout  uvm_phase  phase
)
Attempts to retrieve the next phase from the hopper.
protected virtual task peek(
    output  uvm_phase  phase
)
Copies a phase from the hopper.
protected virtual function bit try_peek(
    inout  uvm_phase  phase
)
Attempts to copy a phase from the hopper.
protected virtual function uvm_objection get_objection()
Retrieves the Active Phase Objection.
protected virtual function void raise_objection(
    uvm_object  obj,   
    string  description  =  "",
    int  count  =  1
)
This is a pass through to uvm_objection::raise_objection on the objection returned by get_objection.
protected virtual function void drop_objection(
    uvm_object  obj,   
    string  description  =  "",
    int  count  =  1
)
This is a pass through to uvm_objection::drop_objection on the objection returned by get_objection.
virtual function int get_objection_count(
    uvm_object  obj  =  null
)
This is a pass through to uvm_objection::get_objection_count on the objection returned by get_objection.
virtual function int get_objection_total(
    uvm_object  obj  =  null
)
This is a pass through to uvm_objection::get_objection_total on the objection returned by get_objection.
virtual task wait_for_objection(
    uvm_objection_event  objt_event,   
    uvm_object  obj  =  null
)
This is a pass through to uvm_objection::wait_for on the objection returned by get_objection.
virtual task run_phases()
Runs all phases associated with a test.
protected virtual task process_phase(
    uvm_phase  phase
)
Processes a phase.
protected virtual task start_phase(
    uvm_phase  phase
)
Performs actions associated with transitioning phase state to the UVM_PHASE_STARTED state.
protected virtual task execute_phase(
    uvm_phase  phase
)
Performs actions associated with transitioning phase state to the UVM_PHASE_EXECUTING state.
protected virtual task end_phase(
    uvm_phase  phase
)
Performs actions associated with transitioning phase state to the UVM_PHASE_ENDED state.
protected virtual task cleanup_phase(
    uvm_phase  phase
)
Performs actions associated with transitioning phase state to the UVM_PHASE_CLEANUP or UVM_PHASE_JUMPING state.
protected virtual task finish_phase(
    uvm_phase  phase
)
Performs actions associated with transitioning phase state to the UVM_PHASE_DONE state.
protected virtual task wait_for_waiters(
    uvm_phase  phase,
    uvm_phase_state  prev_state
)
Delays execution to allow waiters on phase state changes to react.
virtual function void traverse_on(
    uvm_phase  imp,
    uvm_component  comp,
    uvm_phase  node,
    uvm_phase_state  state
)
Calls traverse on imp, passing in comp, node, and state.
virtual function void execute_on(
    uvm_phase  imp,
    uvm_component  comp,
    uvm_phase  node
)
Calls execute on imp, passing in comp, and node.
pure virtual function uvm_phase_hopper get_phase_hopper()
Returns the uvm_phase_hopper (singleton) instance for this environment