Build, connect and observe the phase order

A phase is a step every component takes

UVM splits a test into named steps called phases. Each phase is a method of uvm_component that you can override, such as build_phase or run_phase. The library calls that method on every component in the tree before it moves on to the next phase.

Most phases are functions, so they take no simulation time. Only the run-time phases, such as run_phase, are tasks that can wait for clocks. A #10 or @(posedge clk) inside build_phase does not compile at all, because a function cannot contain a timing control.

Each phase method receives a uvm_phase argument, conventionally named phase. It describes the phase being run, and in the run phase it is also the handle you use to raise and drop objections.

Because every component goes through the same steps, you never write the order by hand. You only decide which step each piece of work belongs to.

The order from start to finish

1. build_phase (top-down)

   Each component creates its children and reads its configuration. A parent builds before its children.

   kind	function
   time	0

2. connect_phase (bottom-up)

   Ports are connected to their exports and imps. Children connect before their parent.

   kind	function
   time	0

3. end_of_elaboration_phase (bottom-up)

   The tree is complete. A good place to print it or check the structure.

   kind	function
   time	0

4. start_of_simulation_phase (bottom-up)

   Last zero-time setup before anything consumes time.

   kind	function
   time	0

5. run_phase (all in parallel)

   Every component's run_phase starts in the same time step. The run-time phases reset, configure, main and shutdown, each with pre and post steps, run alongside it.

   kind	task
   time	passes

6. extract_phase, check_phase, report_phase (bottom-up)

   Collect results, decide pass or fail, print them.

   kind	function
   time	frozen at the end of run

7. final_phase (top-down)

   Close files and finish. The last phase before the simulation ends.

   kind	function
   time	frozen

The two short phases after connect are easy to skip, but they have distinct jobs. In end_of_elaboration_phase the tree and its connections are final, so it is the place to print the topology or check that a required component exists. In start_of_simulation_phase you can print the configuration a test is about to use, which makes a failing log easier to read later.

The run phase is the only stretch where simulation time moves. The phases after it all see the same time, the moment the run phase ended. [U1.3](U1-3-uvm-objection-lifetime.html) shows what decides that moment.

Why build goes down and connect goes up

Build runs top-down because a parent creates its children. The child objects do not exist until the parent's build_phase has run, so the parent must go first. Going first also lets a parent store configuration for a child before the child reads it.

Connect runs bottom-up, after the whole tree exists. By then every port and export has been created, so any connection is safe. Lower levels finish their own wiring first, so an agent can connect its internals before the environment uses them.

The opening failure mixed the two jobs. The fix is to move the connection into connect_phase, where agent.mon is guaranteed to exist.

function void build_phase(uvm_phase phase);
  agent = incr_agent::type_id::create("agent", this);
  sb    = incr_scoreboard::type_id::create("sb", this);
  agent.mon.ap.connect(sb.imp);   // agent.mon is null
endfunction

function void build_phase(uvm_phase phase);
  agent = incr_agent::type_id::create("agent", this);
  sb    = incr_scoreboard::type_id::create("sb", this);
endfunction

function void connect_phase(uvm_phase phase);
  agent.mon.ap.connect(sb.imp);
endfunction

Configuration flows down with the build

Top-down building has a useful side effect. A parent can store a setting for a child in uvm_config_db during its own build_phase, and the child reads it during its build_phase, which always runs later.

It does not even matter whether the parent stores the setting before or after it creates the child. Creating a child only allocates the object; the child's build_phase runs after the parent's has finished. By then every setting the parent made is in place.

The same reasoning tells you where a setting arrives too late. A value stored in the child's connect_phase or in the run phase is invisible to a get that already ran in build_phase. Store configuration for a component before or during its parent's build.

Run-phase tasks run side by side

When the run phase starts, UVM starts every component's run_phase task in the same time step. The driver loops forever, fetching items. The monitor loops forever, watching pins. The test starts a sequence and waits for it.

Nobody returns from a forever loop, so returning cannot be what ends the phase. Instead, the phase ends when no component objects any more, and UVM then kills any run_phase task still running. The next lesson covers those objections.

Twelve finer run-time phases run beside run_phase. The next section shows how they are scheduled.

The run-time schedule beside run_phase

The schedule is pre_reset, reset, post_reset, pre_configure, configure, post_configure, pre_main, main, post_main, pre_shutdown, shutdown and post_shutdown. Each is a task phase with its own objection. A phase with no objection ends in the time step it starts.

That is the trap. An objection raised in run_phase keeps run_phase open; it does not keep main_phase open. A test that raises in run_phase but sends its traffic from main_phase sees main end at 0 ns, with nothing sent yet.

task run_phase(uvm_phase phase);
  phase.raise_objection(this);
  #100;
  phase.drop_objection(this);
endtask
task main_phase(uvm_phase phase);
  repeat (5) #10 sent++;
endtask

task main_phase(uvm_phase phase);
  phase.raise_objection(this);
  repeat (5) #10 sent++;
  phase.drop_objection(this);
endtask

Use the finer phases when the order matters to the whole bench: every agent finishes reset before any agent starts traffic. Many benches keep everything in run_phase and order it inside one sequence, which is simpler; these lessons do that. Do not mix the two styles in one component without a reason.

What belongs in each phase

Call super.build_phase(phase) first when you override build_phase. The base version can apply configuration to fields registered with the UVM field macros. Skipping it silently loses those settings.

Try it

Every component class here extends traced, a small helper that appends the component's name to a per-phase list. When a phase has finished everywhere, the test's phase_ended callback prints that list with the current time.

Check the order against the steps above: build goes from the test down, connect and the cleanup phases come up from the leaves, and final goes down again. Move the #30 in the test to #50 and predict which lines change.

Check yourself

`include "uvm_macros.svh"
import uvm_pkg::*;
string log_s;
class agent_c extends uvm_agent;
  `uvm_component_utils(agent_c)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);   log_s = {log_s, " B:agent"}; endfunction
  function void connect_phase(uvm_phase phase); log_s = {log_s, " C:agent"}; endfunction
endclass
class env_c extends uvm_env;
  `uvm_component_utils(env_c)
  agent_c agent;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    log_s = {log_s, " B:env"};
    agent = agent_c::type_id::create("agent", this);
  endfunction
  function void connect_phase(uvm_phase phase); log_s = {log_s, " C:env"}; endfunction
endclass
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  env_c env;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    log_s = {log_s, "B:test"};
    env = env_c::type_id::create("env", this);
  endfunction
  function void connect_phase(uvm_phase phase); log_s = {log_s, " C:test"}; endfunction
  function void start_of_simulation_phase(uvm_phase phase);
    $display("%s", log_s);
  endfunction
endclass
module tb;
  initial run_test("my_test");
endmodule

function void build_phase(uvm_phase phase);
  agent = agent_c::type_id::create("agent", this);
  sb    = sb_c::type_id::create("sb", this);
endfunction
function void connect_phase(uvm_phase phase);
  agent.mon.ap.connect(sb.imp);
endfunction

function void build_phase(uvm_phase phase);
  sb    = sb_c::type_id::create("sb", this);
  agent = agent_c::type_id::create("agent", this);
endfunction
function void connect_phase(uvm_phase phase);
  agent.mon.ap.connect(sb.imp);
endfunction

function void build_phase(uvm_phase phase);
  agent = agent_c::type_id::create("agent", this);
  sb    = sb_c::type_id::create("sb", this);
  agent.mon.ap.connect(sb.imp);
endfunction

function void build_phase(uvm_phase phase);
  super.build_phase(phase);
  agent = agent_c::type_id::create("agent", this);
  sb    = sb_c::type_id::create("sb", this);
endfunction
function void connect_phase(uvm_phase phase);
  super.connect_phase(phase);
  agent.mon.ap.connect(sb.imp);
endfunction

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class main_test extends uvm_test;
  `uvm_component_utils(main_test)
  int  sent, sent_at_main_end;
  time main_end;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    phase.raise_objection(this);
    #100;
    phase.drop_objection(this);
  endtask
  task main_phase(uvm_phase phase);
    repeat (5) #10 sent++;
  endtask
  function void phase_ended(uvm_phase phase);
    if (phase.get_name() == "main") begin
      main_end = $time;
      sent_at_main_end = sent;
    end
  endfunction
  function void report_phase(uvm_phase phase);
    $display("main ended at %0t ns with sent=%0d", main_end, sent_at_main_end);
  endfunction
endclass
module tb;
  initial run_test("main_test");
endmodule