UVM Test [uvm_test]

reg_env is fully built, but nothing has ever actually instantiated it. This article writes the component that finally does: a test that builds reg_env, starts reg_sequence against it, and gives this entire tutorial's testbench its first real run.

9 min read | Intermediate Level

What You'll Learn

• What a test does, and why the same environment gets reused across many of them
• How to build reg_test and start reg_sequence inside run_phase
• How to write a derivative test that reuses reg_test but runs a different sequence
• How to set a real default sequence, now that every name it depends on actually exists

What Is a Test?

A test verifies a specific feature or behavior of a design. Real verification plans typically need many tests - one for basic writes and reads, one for boundary addresses, one for back-to-back operations with no idle cycles, and so on. Rewriting the entire environment for each one would be wasteful, so instead, the same reg_env gets reused across all of them, with each test only changing what it actually needs to: which sequence runs, and which knobs are tweaked beforehand.

Building reg_test

1. Declare the Class

class reg_test extends uvm_test;

  `uvm_component_utils(reg_test)

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  // Code for rest of the steps come here
endclass

2. Declare and Build the Environment

reg_env m_top_env;

virtual function void build_phase(uvm_phase phase);
  super.build_phase(phase);
  m_top_env = reg_env::type_id::create("m_top_env", this);
endfunction

The source this article is built on also shows a configuration object built and passed down here, useful once an environment has knobs worth bundling into one object - the pattern covered in this chapter's deep dive on multi-agent environments. reg_env doesn't need one: it always builds the same agent and the same scoreboard, so there's nothing for reg_test to configure before building it.

3. Print the Topology

virtual function void end_of_elaboration_phase(uvm_phase phase);
  uvm_top.print_topology();
endfunction

By end_of_elaboration_phase, every component this tutorial has built is guaranteed to already exist - reg_test, reg_env, reg_agent and everything inside it, reg_scoreboard. print_topology() prints the entire hierarchy as built, which is a quick way to confirm nothing was left out or built in the wrong place before the simulation actually starts running anything.

4. Start a Sequence in run_phase

virtual task run_phase(uvm_phase phase);
  reg_sequence m_seq = reg_sequence::type_id::create("m_seq");

  phase.raise_objection(this);
  m_seq.start(m_top_env.m_agent.m_sequencer);
  phase.drop_objection(this);
endtask

Every piece of this line was established and explained from its own side, in its own article: the objection-raising pattern from How to Create and Use a Sequence, reg_sequence itself, and the path m_top_env.m_agent.m_sequencer, which only resolves to something real because reg_env owns m_agent and reg_agent owns m_sequencer. Nothing about any of those three classes needed to change to make this call work.

Setting a Real Default Sequence

How to Create and Use a Sequence introduced default sequences with a placeholder path, since reg_sequencer didn't have a fixed position in any hierarchy yet. It does now:

function void start_of_simulation_phase(uvm_phase phase);
  super.start_of_simulation_phase(phase);

  uvm_config_db #(uvm_object_wrapper)::set(this, "m_top_env.m_agent.m_sequencer.run_phase",
                                            "default_sequence", reg_sequence::type_id::get());
endfunction

"m_top_env.m_agent.m_sequencer.run_phase" is no longer a stand-in for a path that doesn't exist - it's the actual, resolvable location of reg_sequencer inside reg_test's own hierarchy. Setting this means reg_sequencer starts reg_sequence automatically once its run phase begins, with no explicit start() call needed anywhere - an alternative to the run_phase code shown in the previous step, not something used alongside it.

A Derivative Test

reg_test only ever starts reg_sequence - the same five-transaction, random read/write sequence every time. A second test that needs different stimulus doesn't have to rebuild reg_env from scratch. The cleanest way to give it different stimulus is a derivative sequence, extending reg_sequence with one extra constraint inside body(), the same inline with pattern already used in that article's own practice exercise:

class reg_write_only_sequence extends reg_sequence;

  `uvm_object_utils(reg_write_only_sequence)

  function new(string name = "reg_write_only_sequence");
    super.new(name);
  endfunction

  virtual task body();
    repeat (5) begin
      req = reg_transaction::type_id::create("req");
      start_item(req);
      assert(req.randomize() with { wr_en == 1; });
      finish_item(req);
    end
  endtask

endclass

With that sequence written, the derivative test itself only needs to override which sequence it starts:

class reg_write_only_test extends reg_test;

  `uvm_component_utils(reg_write_only_test)

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  virtual task run_phase(uvm_phase phase);
    reg_write_only_sequence m_seq = reg_write_only_sequence::type_id::create("m_seq");

    phase.raise_objection(this);
    m_seq.start(m_top_env.m_agent.m_sequencer);
    phase.drop_objection(this);
  endtask

endclass

Because reg_write_only_test doesn't define its own build_phase at all, it inherits reg_test's exactly as written - m_top_env still gets built the same way, with no duplicated code. Only the sequence being started changes, and that change lives entirely in run_phase.

Running a Test

Actually launching reg_test or reg_write_only_test happens through a global task, run_test(), typically called from the top-level module - covered in detail in UVM Testbench Top, along with how a test gets its virtual interface handle in the first place.

Common Mistakes

class reg_read_only_sequence extends reg_sequence;

  `uvm_object_utils(reg_read_only_sequence)

  function new(string name = "reg_read_only_sequence");
    super.new(name);
  endfunction

  virtual task body();
    repeat (5) begin
      req = reg_transaction::type_id::create("req");
      start_item(req);
      assert(req.randomize() with { rd_en == 1; });
      finish_item(req);
    end
  endtask

endclass

class reg_read_only_test extends reg_test;

  `uvm_component_utils(reg_read_only_test)

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  virtual task run_phase(uvm_phase phase);
    reg_read_only_sequence m_seq = reg_read_only_sequence::type_id::create("m_seq");

    phase.raise_objection(this);
    m_seq.start(m_top_env.m_agent.m_sequencer);
    phase.drop_objection(this);
  endtask

endclass