How to build UVM Environment Part – 2

In part one we understood the pipe design, wrote its interface, built the data_packet transaction, and set up the driver skeleton. Now we make stimulus flow. By the end of this part, a sequence will create packets and the driver will drive them onto the pins.

A simple way to picture it

Think of a coffee shop at the counter. The customer writing an order is the sequence. The person at the till who lines up the orders and hands them to the barista one at a time is the sequencer. The barista who reads one order and makes the drink is the driver. The barista does not start the next drink until the current one is done. That one at a time handoff is exactly the sequence to driver handshake we build here.

The sequencer

The sequencer controls the flow of sequences to the driver. What is striking is how little you write: the whole class is a few lines, because the library does the hard part. You parameterise uvm_sequencer with your transaction type and you are done.

class pipe_sequencer extends uvm_sequencer #(data_packet);
  `uvm_component_utils(pipe_sequencer)

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

Finishing the driver

In part one the driver fetched its interface. Now we fill in the run phase so it drives real activity. The pattern is a forever loop with three steps: ask for the next item, drive it onto the pins, then report that it is done. Those three calls are the heart of every UVM driver.

class pipe_driver extends uvm_driver #(data_packet);
  `uvm_component_utils(pipe_driver)

  virtual pipe_if vif;

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

  virtual function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    if (!uvm_config_db #(virtual pipe_if)::get(this, "", "vif", vif))
      `uvm_fatal("NOVIF", "virtual interface not set for pipe_driver")
  endfunction

  virtual task run_phase(uvm_phase phase);
    forever begin
      data_packet tr;
      seq_item_port.get_next_item(tr);  // 1. ask the sequencer
      drive_item(tr);                    // 2. drive the pins
      seq_item_port.item_done();         // 3. tell it we are done
    end
  endtask

  virtual task drive_item(data_packet tr);
    // wait for any requested delay between packets
    repeat (tr.delay) @(posedge vif.clk);
    @(posedge vif.clk);
    vif.cf       <= tr.cf;
    vif.enable   <= tr.enable;
    vif.data_in1 <= tr.data_in1;
    vif.data_in2 <= tr.data_in2;
    @(posedge vif.clk);
    vif.enable   <= 1'b0;   // drop enable after one cycle
  endtask
endclass

What the three handshake calls mean

The rule to remember: every get_next_item must be matched by an item_done. If you forget item_done, the driver will hang forever waiting, and the sequence will never send the next packet. This is one of the most common first-testbench bugs.

Sequences: the stimulus recipes

A sequence creates transactions and sends them to the driver through the sequencer. We will write three, from simplest to most useful, so you can see how they grow.

Example 1: a single random packet

The simplest sequence sends one randomised packet. It creates the item, starts the handshake, randomises, and finishes.

class random_sequence extends uvm_sequence #(data_packet);
  `uvm_object_utils(random_sequence)

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

  virtual task body();
    data_packet tr = data_packet::type_id::create("tr");
    start_item(tr);
    if (!tr.randomize())
      `uvm_error("SEQ", "randomize failed")
    finish_item(tr);
  endtask
endclass

Example 2: many packets in a loop

Real tests send many packets. This sequence repeats the handshake a random number of times, so each run has a different length. Notice the count itself is randomised with a constraint, which is a small but real example of controlling test size.

class multiple_random_sequence extends uvm_sequence #(data_packet);
  `uvm_object_utils(multiple_random_sequence)

  rand int loop;
  constraint loop_c { loop inside {[5:10]}; }

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

  virtual task body();
    repeat (loop) begin
      data_packet tr = data_packet::type_id::create("tr");
      start_item(tr);
      if (!tr.randomize())
        `uvm_error("SEQ", "randomize failed")
      finish_item(tr);
    end
  endtask
endclass

Example 3: a directed sequence

Sometimes you need an exact case, not a random one. A directed sequence sets the fields by hand. This is how you reproduce a specific scenario, for example both channels enabled with a fixed control value, which is useful when chasing a known bug.

class directed_sequence extends uvm_sequence #(data_packet);
  `uvm_object_utils(directed_sequence)

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

  virtual task body();
    data_packet tr = data_packet::type_id::create("tr");
    start_item(tr);
    // Fixed, repeatable values instead of random ones
    tr.cf       = 2'b01;
    tr.enable   = 1'b1;
    tr.data_in1 = 16'h00FF;
    tr.data_in2 = 16'hFF00;
    tr.delay    = 0;
    finish_item(tr);
  endtask
endclass

Which sequence should I use?

A healthy test plan uses all three: random for breadth, directed for the exact cases you care about, and multi-count to control how long a run lasts.

Connecting the driver to the sequencer

The driver and sequencer talk through a port and an export. The connection is made in the agent, which we build in part three, but here is the single line that links them so you know what is coming.

// Inside the agent connect_phase (built in Part 3)
driver.seq_item_port.connect(sequencer.seq_item_export);

Without this line the driver has nobody to ask for items, so get_next_item would block forever. It is the wire that carries every packet.

How the interface handle reaches the driver

The driver fetched its interface with a config DB get. Something must have put it there first. That is done at the top level with a set, usually in the test, passing the real interface down to every component that needs it. We explain this fully in our guide on passing the virtual interface through uvm_config_db, and we wire it up in part four.

Common mistakes at this stage

• Missing item_done. The driver hangs waiting and no more packets flow. Always pair it with get_next_item.
• Not checking randomize. If randomize returns zero and you ignore it, you drive stale values. Always test the return and report an error.
• Driving without a clock edge. Assigning pins outside a clocking event causes races. Drive on the clock, as shown in drive_item.
• Leaving enable high. If you never drop enable, the design keeps acting on old data. Drop it after the packet, as in the example.

Where we are now

You now have a working driver, a sequencer, and three kinds of sequence. Stimulus can flow into the design. In part three we add the monitor to observe the pins, wrap everything in an agent, and build a scoreboard to check the results.

Keep learning

For the ideas behind this part, browse the UVM guides for sequences, the sequencer, and driver communication, the SystemVerilog guides for constraints and randomisation, and the Verification Fundamentals for the wider flow. Preparing for an interview? See the interview questions.

Frequently asked questions

Share this post: on Twitter on Facebook