Sequence libraries, macros and default sequences

What a uvm_do line does

Writing the calls out, as U4.1 did, keeps the blocking points visible; the macros save lines and hide them. Read one as its expansion and you can predict every hook; the first quiz question asks you to.

The example and the quiz use uvm_do_with(req, {...}), the older spelling you will meet most often in inherited code. In the 2020 form it is uvm_do(req, , , {...}): the constraints are the fourth argument.

Three layers of sequences

An agent often wraps each API sequence in a task such as write(value, sqr, parent), so its callers never see start_item. The example's three API sequences send a value below 16, one from 240 to 254, and 255, whose result wraps to 0. Workers and virtual sequences can then change without touching the agent.

Sequence libraries

uvm_sequence_library is a sequence that runs other sequences chosen from a registered list. Register types with uvm_add_to_seq_lib or add_typewide_sequence, and call init_sequence_library() in the constructor. Each pick is created through the factory, named <type>:<n>, and started with uvm_rand_send: a child with call_pre_post = 0.

Register each type once. uvm_add_to_seq_lib(write_lo, incr_lib) inside each API class adds it to the library type, and the instance method add_sequence adds it to one library object. The example calls the static add_typewide_sequence in the constructor, which is harmless here because it builds one library, but repeats the registration for every further instance.

The library reads its mode and counts with typed lookups, uvm_config_db #(uvm_sequence_lib_mode) and #(int unsigned), scoped to where it runs. A +uvm_set_config_int plusarg stores uvm_bitstream_t, which those lookups do not see; copy a command-line value into the typed setting yourself.

Default sequences, phase by phase

A default sequence is one the sequencer starts by itself when a runtime phase begins. The scope is the sequencer's path plus the phase, the field is default_sequence, and the value is a type or an instance:

uvm_config_db #(uvm_object_wrapper)::set(this, "sqr.main_phase", "default_sequence",
                                          incr_lib::get_type());
// to switch an inherited one off: the same scope and field, with null
uvm_config_db #(uvm_object_wrapper)::set(this, "sqr.main_phase", "default_sequence", null);

1. Phase starts

   The sequencer looks up the setting, creates and randomizes the sequence and starts it in its own process.

2. Phase must stay open

   Nothing keeps the phase alive except objections. A plain sequence raises none. Measured with nothing else in the test raising an objection, the phase ended at 0 ns and a five-item default sequence was killed before it completed an item. With set_automatic_phase_objection(1) in its constructor, all 5 ran, to 50 ns. A library raises its own objection.

3. Phase ends

   A default sequence still running when its phase ends is killed, with everything U5.3 says a kill leaves behind.

The example sets incr_lib as the default sequence of sqr.main_phase, in RANDC mode with six picks; the hand-driven part runs in pre_main_phase, so the two never share the driver.

Both features work, and the Cookbook recommends against both. It calls the library "not the preferred method" for starting sequences and automatic starting "almost always the wrong thing to do". A random pick from a list gives up the test's control of what runs and in what order. Stimulus that starts because a phase began is hard to coordinate with the rest of the test, as the hook shows. Prefer a virtual sequence started from the test's run_phase.

Try it

The worker's log reads the macros back into calls. For its own item, pre_do(is_item=1) comes at the grant and mid_do just before the driver takes it. For hi and wrap, each child's pre_start comes first, then the worker's pre_do(is_item=0) and mid_do; no child prints pre_body, because the macro starts children with call_pre_post = 0.

The library then runs by itself in main_phase, two RANDC cycles through the three API sequences. Change the mode to UVM_SEQ_LIB_RAND and a sequence may repeat within three picks. Move the worker into main_phase and its items interleave with the library's, as in the hook.

Transfer exercise: a base test you inherit sets a default sequence for sqr.reset_phase. Write the one line that turns it off in your derived test, and say what the driver would see if you forgot it.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
string trail = "";
function automatic void note(string s);
  if (trail != "") trail = {trail, " "};
  trail = {trail, s};
endfunction

class item_c extends uvm_sequence_item;
  `uvm_object_utils(item_c)
  rand bit [7:0] x;
  function new(string name = "item_c"); super.new(name); endfunction
  function void post_randomize(); note("item.randomize"); endfunction
endclass

class child_seq extends uvm_sequence #(item_c);
  `uvm_object_utils(child_seq)
  function new(string name = "child_seq"); super.new(name); endfunction
  function void pre_randomize(); note("C.randomize"); endfunction
  task pre_start();  note("C.pre_start");  endtask
  task pre_body();   note("C.pre_body");   endtask
  task post_body();  note("C.post_body");  endtask
  task post_start(); note("C.post_start"); endtask
  task body(); note("C.body"); `uvm_do_with(req, { x == 7; }) endtask
endclass

class worker extends uvm_sequence #(item_c);
  `uvm_object_utils(worker)
  child_seq c;
  function new(string name = "worker"); super.new(name); endfunction
  task pre_do(bit is_item); note($sformatf("W.pre_do(%0d)", is_item)); endtask
  function void mid_do(uvm_sequence_item this_item);  note("W.mid_do");  endfunction
  function void post_do(uvm_sequence_item this_item); note("W.post_do"); endfunction
  task body(); `uvm_do(c) endtask
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);
    forever begin
      seq_item_port.get_next_item(req);
      #10;
      seq_item_port.item_done();
    end
  endtask
endclass

class order_test extends uvm_test;
  `uvm_component_utils(order_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);
    worker w = worker::type_id::create("w");
    phase.raise_objection(this);
    w.start(sqr);
    $display("%s", trail);
    phase.drop_objection(this);
  endtask
endclass

module tb;
  initial run_test("order_test");
endmodule

uvm_config_db #(uvm_object_wrapper)::set(this, "sqr.main_phase", "default_sequence", null);

uvm_config_db #(uvm_object_wrapper)::set(this, "sqr", "main_phase.default_sequence", null);

auto_seq::type_id::set_type_override(empty_seq::get_type());

uvm_config_db #(uvm_object_wrapper)::set(null, "uvm_test_top.sqr.main_phase", "default_sequence", null);