UVM Sequencer and Driver Communication:

The link between the sequencer and the driver is where transaction-level stimulus becomes real pin activity. It is a small interface, just a port, an export, and a handful of methods, but the exact order you call those methods decides whether your testbench runs cleanly or hangs waiting forever. This guide covers the full handshake with runnable code, the difference between the two ways to pull items, how the return path for responses works, a method comparison table, and the mistakes that cause the classic sequence hang. We reuse one memory-bus example throughout.

A simple way to picture it

Picture a kitchen order rail, the metal bar where order slips get clipped. The sequence writes an order and clips it to the rail. The line cook (the driver) takes the next slip off the rail, cooks that dish (drives the pins), and only when the plate is finished does the cook mark the slip done so the next order can come forward. The cook handles one slip at a time and never grabs the next until the current dish is served. If the cook forgets to mark a slip done, the rail jams and no new orders move. The UVM handshake works exactly like that rail: get_next_item takes the slip, driving cooks it, and item_done clears it.

The two ends: port and export

The connection has two matching halves. The driver owns a seq_item_port, which is the requesting end. The built-in sequencer owns a seq_item_export, which is the providing end. In connect_phase you join them, and after that the driver can pull items that any sequence starts on that sequencer.

class bus_agent extends uvm_agent;
  `uvm_component_utils(bus_agent)
  bus_sequencer sqr;
  bus_driver    drv;
  function new(string n, uvm_component p); super.new(n,p); endfunction

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    sqr = bus_sequencer::type_id::create("sqr", this);
    drv = bus_driver   ::type_id::create("drv", this);
  endfunction

  function void connect_phase(uvm_phase phase);
    // join the driver port to the sequencer export
    drv.seq_item_port.connect(sqr.seq_item_export);
  endfunction
endclass

This one connect line is what makes everything else work. Forget it and the driver blocks on the very first get_next_item, because it is connected to nothing.

The handshake, step by step

The driver spends its whole life in a forever loop running three calls. Here is the canonical loop for our memory-bus driver, with a comment on each step.

task run_phase(uvm_phase phase);
  bus_item req;
  forever begin
    seq_item_port.get_next_item(req);   // 1) block until an item is ready
    drive(req);                         // 2) turn the item into pin activity
    seq_item_port.item_done();          // 3) release the sequence to send more
  end
endtask

task drive(bus_item req);
  @(posedge vif.clk);
  vif.addr  <= req.addr;
  vif.wdata <= req.data;
  vif.we    <= req.is_write;
  vif.valid <= 1'b1;
  @(posedge vif.clk);
  vif.valid <= 1'b0;
endtask

On the sequence side, start_item and finish_item are the matching pair. start_item asks the sequencer for permission to send (it blocks until the driver is ready for a new item), and finish_item hands the completed item across.

task body();
  bus_item req = bus_item::type_id::create("req");
  start_item(req);                 // wait for the sequencer/driver to be ready
  assert(req.randomize() with { addr==16'h100; is_write==1; });
  finish_item(req);                // send it; returns when driver calls item_done
endtask

The two sides interlock: the sequence blocks in finish_item until the driver calls item_done, and the driver blocks in get_next_item until the sequence calls finish_item. That mutual waiting is what keeps them in lockstep with no lost or duplicated items.

get_next_item versus try_next_item

There are two ways to pull an item, and the choice affects how the driver behaves when no stimulus is waiting.

Use try_next_item when the protocol needs the driver to keep toggling something, for example driving idle cycles or a heartbeat, rather than freezing the pins while it waits. Here is the idle-aware pattern:

task run_phase(uvm_phase phase);
  bus_item req;
  forever begin
    seq_item_port.try_next_item(req);
    if (req == null) begin
      drive_idle();                 // keep the bus alive
    end
    else begin
      drive(req);
      seq_item_port.item_done();    // only when we actually took an item
    end
  end
endtask

Note the important rule: you only call item_done when try_next_item actually returned an item. Calling it after a null return corrupts the handshake.

Returning a response to the sequence

Sometimes the sequence needs to know what happened, for example the read data that came back. There are two ways to send a response upstream. The lightweight way passes the same request object to item_done, since the driver can fill in fields on it. The formal way builds a separate response and uses put_response.

// lightweight: fill the request object and pass it back
task run_phase(uvm_phase phase);
  bus_item req;
  forever begin
    seq_item_port.get_next_item(req);
    drive(req);
    if (!req.is_write) req.data = vif.rdata;  // capture read data
    seq_item_port.item_done(req);             // return the updated item
  end
endtask

// on the sequence side, read the response back
task body();
  bus_item req = bus_item::type_id::create("req");
  start_item(req);
  assert(req.randomize() with { addr==16'h100; is_write==0; });
  finish_item(req);
  get_response(rsp);            // rsp.data now holds the read value
endtask

The full method map

These are all the calls involved, grouped by which side uses them, so you can see how a driver call pairs with a sequence call.

What actually flows on the timeline

Follow one write from sequence to pins and back:

1. The sequence calls start_item, which blocks until the driver is ready.
2. The sequence randomizes the item and calls finish_item, handing it across.
3. The driver, waiting in get_next_item, receives the item and returns from that call.
4. The driver drives addr, wdata, we, and valid onto the pins over one or more clocks.
5. The driver calls item_done, which unblocks the sequence finish_item call.
6. The sequence loops and builds the next item, and the driver loops back to get_next_item.

Common mistakes to avoid

• Forgetting item_done. The sequence blocks in finish_item forever and the whole test hangs. This is the number-one sequencer-driver bug.
• Forgetting the connect line in connect_phase, so the driver port is joined to nothing and get_next_item blocks on the first call.
• Calling item_done twice for one item, which desynchronizes the handshake and can drop the next item.
• Calling item_done after try_next_item returned null. Only signal done when you actually took an item.
• Doing a get_next_item then never driving, so time never advances and the item is never finished.
• Trying to use get_response without the driver returning a response through item_done(rsp) or put_response.

Keep learning

This handshake sits at the bottom of the whole stack. See how the driver and sequencer fit the bigger picture in the UVM testbench architecture guide, learn how items are scheduled when several sequences compete in UVM sequence arbitration, and see the difference between the two sequencer handles in m_sequencer vs p_sequencer. Build the whole flow from scratch in how to build a UVM environment part 2, and find more on the UVM category page.

Frequently asked questions

Once the single handshake is clear, see how a virtual sequence coordinates several sequencers at once, and how the m_sequencer and p_sequencer handles let a sequence reach its sequencer.

Share this post: on Twitter on Facebook