Sequences and the item handshake

A sequence is a recipe for items

In the layered bench, a generator made transactions and put them in a mailbox. UVM splits that job in two. A sequence is an object that decides which items to send. A sequencer is a component that passes them to the driver one at a time.

The item is a class derived from uvm_sequence_item. Its rand fields are the values a test may randomize, and its constraints keep them legal. The example item has one field, x, constrained to the range 16 to 31.

A sequence extends uvm_sequence, parameterized with the item type it sends. Its work lives in one task, body(). The test runs it with seq.start(sqr), which calls body() and returns when body() ends. So start blocks, and the test raises its objection around it.

A sequence can also start other sequences inside its own body(), so long tests are built from small, tested pieces. U10 uses this for virtual sequences, which coordinate several sequencers at once.

Four steps send one item

incr_item it = incr_item::type_id::create("it");  // 1. create
start_item(it);                                   // 2. wait for a grant
if (!it.randomize())                              // 3. fill in the values
  `uvm_error("RAND", "randomize failed")
finish_item(it);                                  // 4. send it, wait for item_done

Create the item through the factory, as U2 showed, so a test can override its type. Start with start_item(it), which asks the sequencer for permission to send. It returns when the sequencer grants this sequence the driver.

Fill in the item, usually with randomize(). Check the result: a failed randomization returns 0 and leaves the old values in place, and nothing else warns you. Finish with finish_item(it), which hands the item to the driver. It returns only when the driver says it has finished with that item.

Spend no simulation time between start_item and finish_item. The driver is already waiting for this item, so any delay there stalls the bus.

The handshake, call by call

The driver pulls items; the sequence never pushes them. The driver's loop calls seq_item_port.get_next_item(req), which blocks until an item arrives. Later it calls seq_item_port.item_done() to say it has finished. These two calls pair with the sequence's two calls.

Read the table as two waits on each side. The sequence waits in start_item until the driver asks for an item, and in finish_item until the driver says it is done. The driver waits in get_next_item until a sequence has an item ready. Nobody polls; each side blocks until the other side acts.

Step 4 matters in the next lesson. The driver receives the very object the sequence created, not a copy. Anything the driver writes into req is visible to the sequence once finish_item returns.

Reading the handshake in a log

The example prints one line at each of these calls. Its driver keeps the bus idle for two clock cycles after time 0, then serves three items, two cycles each.

Two details stand out. First, the sequence called start_item at 0 ns but was granted at 20 ns, the moment the driver first asked. A grant goes only to a driver that is asking.

Second, finish_item for item 1 returned at 40 ns, in the same time step as item_done. The sequence was granted item 2 at once, because the driver asked again immediately. In steady state the handshake costs no simulation time at all.

The same two waits tell you where to look when a test hangs. A sequence stuck in finish_item points at the driver: it took the item but never called item_done. A sequence stuck in start_item means no driver is asking, because the driver is blocked elsewhere, was never connected to this sequencer, or has not started its loop.

Randomize after the grant

You could randomize before start_item, and the item would go out unchanged. Randomizing after the grant is called late randomization, and it has a real advantage. The values are chosen at the moment the driver is ready for them, so constraints can use the current state of the test.

Picture a sequence that writes to a FIFO and reads a fill-level counter kept by the scoreboard. Randomized late, its next item can be constrained to a write only while there is room. Randomized early, the item would reflect a fill level that may be several cycles old.

Inline constraints narrow one call without changing the class, as in it.randomize() with { x < 20; }. The class constraints still apply, so here x falls between 16 and 19. Ask for x < 10 instead and the two constraints conflict: randomize() returns 0 and x keeps its old value, which is why the example checks the result.

Breaking the handshake

Every get_next_item needs exactly one item_done. Miss one, and the hook's hang follows. In uvm-core, a second get_next_item before item_done reports an error and hands back the same item again. The driver then repeats that item while the sequence waits forever.

Call item_done twice and the second call finds no item outstanding, which is a fatal error. A loop with several exits, such as one that skips some items with continue, is where a missing item_done usually hides.

seq_item_port.get_next_item(req);
if (req.x == 0) continue;   // leaves the item open
drive(req);
seq_item_port.item_done();

seq_item_port.get_next_item(req);
if (req.x != 0) drive(req);
seq_item_port.item_done();

Two other driver calls change the pairing. get(req) fetches the item and completes the request handshake; it does not wait for pin activity or a response. try_next_item(req) returns null if no item becomes available during its delta-cycle check. A null result needs no item_done; lesson U4.3 uses this to drive idle cycles.

Try it

The log has one line per handshake call. Match it against the trace above: the sequence waits for its first grant until 20 ns, and each finish_item returns in the same time step as the driver's item_done.

Delete the repeat (2) line in the driver and predict the new time of the first grant. Then move item_done to just after get_next_item and watch finish_item return before the item is driven.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class item_c extends uvm_sequence_item;
  `uvm_object_utils(item_c)
  function new(string name = "item_c"); super.new(name); endfunction
endclass
class drv_c extends uvm_driver #(item_c);
  `uvm_component_utils(drv_c)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    #5;
    forever begin
      seq_item_port.get_next_item(req);
      #10;
      seq_item_port.item_done();
      #2;
    end
  endtask
endclass
class seq_c extends uvm_sequence #(item_c);
  `uvm_object_utils(seq_c)
  function new(string name = "seq_c"); super.new(name); endfunction
  task body();
    int granted[2], done[2];
    for (int i = 0; i < 2; i++) begin
      item_c it = item_c::type_id::create("it");
      start_item(it);
      granted[i] = $time;
      finish_item(it);
      done[i] = $time;
    end
    $display("granted %0d %0d, done %0d %0d", granted[0], granted[1], done[0], done[1]);
  endtask
endclass
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  drv_c drv;
  uvm_sequencer #(item_c) sqr;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    drv = drv_c::type_id::create("drv", this);
    sqr = uvm_sequencer #(item_c)::type_id::create("sqr", this);
  endfunction
  function void connect_phase(uvm_phase phase);
    drv.seq_item_port.connect(sqr.seq_item_export);
  endfunction
  task run_phase(uvm_phase phase);
    seq_c seq = seq_c::type_id::create("seq");
    phase.raise_objection(this);
    seq.start(sqr);
    phase.drop_objection(this);
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule

seq_item_port.get(req);
@(negedge vif.clk);
vif.valid <= 1;
vif.x     <= req.x;
@(negedge vif.clk);
vif.valid <= 0;

seq_item_port.get_next_item(req);
@(negedge vif.clk);
if (req.x == 0) continue;
vif.valid <= 1;
vif.x     <= req.x;
@(negedge vif.clk);
vif.valid <= 0;
seq_item_port.item_done();

seq_item_port.get_next_item(req);
@(negedge vif.clk);
vif.valid <= 1;
vif.x     <= req.x;
@(negedge vif.clk);
vif.valid <= 0;
seq_item_port.item_done();

@(negedge vif.clk);
seq_item_port.try_next_item(req);
if (req == null) begin
  vif.valid <= 0;
  continue;
end
vif.valid <= 1;
vif.x     <= req.x;
seq_item_port.item_done();