# 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
new | Creates a new uvm_phase_hopper instance with name.
Singleton Accessors |
get_global_hopper | Returns the global phase hopper.
Queue API |
try_put | Attempts to add a new phase to the hopper.
get | Retrieves the next phase from the hopper.
try_get | Attempts to retrieve the next phase from the hopper.
peek | Copies a phase from the hopper.
try_peek | Attempts to copy a phase from the hopper.
Active Phase Objection |
get_objection | Retrieves the Active Phase Objection.
raise_objection | This is a pass through to <uvm_objection::raise_objection> on the objection returned by get_objection.
drop_objection | This is a pass through to <uvm_objection::drop_objection> on the objection returned by get_objection.
get_objection_count | This is a pass through to <uvm_objection::get_objection_count> on the objection returned by get_objection.
get_objection_total | This is a pass through to <uvm_objection::get_objection_total> on the objection returned by get_objection.
wait_for_objection | This is a pass through to <uvm_objection::wait_for> on the objection returned by get_objection.
Phase Graph Execution |
run_phases | Runs all phases associated with a test.
schedule_phase | Performs actions associated with transitioning phase state to the UVM_PHASE_SCHEDULED state.
process_phase | Processes a phase.
Transitions | Performs actions associated with transitioning phase state to the UVM_PHASE_SYNCING state.
start_phase | Performs actions associated with transitioning phase state to the UVM_PHASE_STARTED state.
execute_phase | Performs actions associated with transitioning phase state to the UVM_PHASE_EXECUTING state.
end_phase | Performs actions associated with transitioning phase state to the UVM_PHASE_ENDED state.
cleanup_phase | Performs actions associated with transitioning phase state to the UVM_PHASE_CLEANUP or UVM_PHASE_JUMPING state.
finish_phase | Performs actions associated with transitioning phase state to the UVM_PHASE_DONE state.
wait_for_waiters | Delays execution to allow waiters on phase state changes to react.
Phase Component Traversal |
traverse_on | Calls traverse on imp, passing in comp, node, and state.
execute_on | Calls 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.

### Singleton Accessors

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

### Queue API

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

NOTE | By 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.

### Active Phase Objection

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

### Phase Graph Execution

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

### schedule_phase

> protected virtual task schedule_phase(
> | uvm_phase | phase, |  |
> | uvm_phase | from_phase | = | null
> )

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

If from_phase is not null, then phase tracing messages will include the name of the phase that scheduled phase.

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

### Phase Component Traversal

### 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 schedule_phase(
> | uvm_phase | phase, |  |
> | uvm_phase | from_phase | = | null
> )

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

> 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