Order, Scope and Lifetime

Predict the calling order on every driver after typewide, instance, prepended and by-name adds and deletes. Check it with the iterator API and display.

You Will Be Able To

  • Predict a driver's calling order from the sequence of add and delete calls.
  • Register by name with a pattern that matches full names, after the components exist.
  • Switch a callback off, delete it, or delete it everywhere, and know which to use.
  • Walk a queue with the iterator API, and avoid changing it during a walk.
Lesson
U18.2
Time
30 min
Runs on
Verilator with UVM
Check
4 questions

Two teams added callbacks to the same lane drivers, one typewide in build_phase and one on a single lane in connect_phase. The coverage callback that was meant to run last ran in the middle on that one lane. Nobody had printed the queues, so the difference showed up as odd coverage weeks later.

After calllane0 callslane1 callslane2 calls
2 add(lane1, perr)covcov perrcov
5 add(null, first, UVM_PREPEND)first cov monfirst cov perr monfirst dly cov mon
7 delete(null, cov)first mon tagfirst perr monfirst dly mon tag

Three of the example's seven measured lines. Each lane may end up with a different order.

Own a Queue or Borrow One

The pool keeps one queue per object and one typewide queue per type. A driver with no queue of its own borrows the typewide queue. The first instance add gives it a queue: a copy of the typewide queue, then the new callback. After that, every typewide add or delete changes the typewide queue and every queue that exists.

Seven Calls, Three LanesThe example's registrations in connect_phase. A lane with no queue of its own borrows the typewide queue. Arrows are adds and copies.
  • Test
  • Storage
  • Data
Seven calls, three lanesThe example's registrations in `connect_phase`. A lane with no queue of its own borrows the typewide queue. Arrows are adds and copies. test Test seven add and deletecalls storage Typewide queue after call 7: firstmon storage lane0 queue own from call 6: firstmon tag storage lane1 queue own from call 2: firstperr mon storage lane2 queue own from call 4: firstdly mon tag add(null, ...)copied at call 2copied at call 4copied at call 6add(lane1, perr)
  1. test Testseven add and delete calls
    • add(null, ...) → Typewide queue
    • add(lane1, perr) → lane1 queue
  2. storage Typewide queueafter call 7: first mon
    • copied at call 2 → lane1 queue
    • copied at call 4 → lane2 queue
    • copied at call 6 → lane0 queue
  3. storage lane1 queueown from call 2: first perr mon
  4. storage lane2 queueown from call 4: first dly mon tag
  5. storage lane0 queueown from call 6: first mon tag
  1. Calls 1-2

    add(null, cov) fills the typewide queue; every lane borrows it. add(lane1, perr) gives lane1 its own queue: a copy of the typewide queue, then perr.

  2. Calls 3-5

    Later typewide adds reach every queue that exists: mon is appended everywhere, first is prepended everywhere. add(lane2, dly, UVM_PREPEND) copies the typewide queue and puts dly in front of it.

  3. Calls 6-7

    add_by_name gives lane0 and lane2 their own queues. delete(null, cov) removes cov from the typewide queue and from every lane's own queue.

Read the diagram as text
  • Test: seven add and delete calls
  • Typewide queue: after call 7: first mon
  • lane0 queue: own from call 6: first mon tag
  • lane1 queue: own from call 2: first perr mon
  • lane2 queue: own from call 4: first dly mon tag
  • Test → Typewide queue: add(null, ...)
  • Typewide queue → lane1 queue: copied at call 2
  • Typewide queue → lane2 queue: copied at call 4
  • Typewide queue → lane0 queue: copied at call 6
  • Test → lane1 queue: add(lane1, perr)

One rule explains every line. A lane copies the typewide queue when it gets its own; every later typewide change reaches every queue.

UVM_PREPEND puts the callback at the front of each queue it reaches. On an instance add that is in front of the copied typewide callbacks too: lane2 calls dly before cov.

In uvm-core 2020.3.1 that per-object queue is shared by every callback type, report catchers included. A first add of another type can give a driver its own queue and drop earlier typewide lane callbacks. U18.6 measures it next to the standard's rule.

Adding by Name

add_by_name(pattern, cb, root, ordering) finds every component under root whose full name matches pattern, and makes an instance add on each one of the right type. The match happens once, at the call. A component built later is not added, and a call that matches nothing prints CBNOMTC.

The pattern is a glob: * matches any characters, + one or more, ? exactly one. Square brackets are literal characters in a glob, so *.lane[02].drv matches nothing. A pattern between slashes is a regular expression instead: the example uses /lane[02]\.drv$/ to reach lane0 and lane2. delete_by_name takes the same arguments.

Off, Deleted, or Deleted Everywhere

CallEffectUse it for
cb.callback_mode(0)Stays in every queue; hook points skip itA window, such as no injection during reset
delete(drv, cb)Leaves that driver's own queueA job done on one driver
delete(null, cb)Leaves the typewide queue and every queueA job done everywhere
delete_by_name(pattern, cb, root)delete on every matchUndoing an add_by_name

A disabled callback keeps its place, so it runs in the same position when switched on again.

Reading a Queue

uvm_callback_iter #(T, CB) walks a driver's queue the way a hook point does: first, next, last, prev, each skipping disabled callbacks. The static get_first(itr, obj) and its relatives do the same with an int cursor you keep. get_all(q, obj) collects every callback of the type, enabled or not.

display(obj) prints the typewide callbacks, marked (*), and then the driver's own queue. A driver with its own queue calls only that queue, so the (*) lines repeat callbacks it already holds. The example's display of lane2 shows this.

Changing the Queue During a Walk

The iterator keeps a position and asks the pool for the queue again at every step. Changing the queue while a walk is in progress shifts what the position points at.

An append during a walk runs in the same walk, because the queue just grew at the end. A delete during a walk skips the callback after the deleted one. Make queue changes between walks: in a phase, or from the test after a sequence, not from inside a hook.

Try It

Each line lists the callbacks each lane's hook point would call after one more registration call. The display of lane2 at the end lists the typewide queue, marked (*), and then lane2's own queue.

Move call 2 after call 5 and run again: lane1's copy now starts with first cov mon, and perr comes last.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: 1 add(null, cov) lane0: cov | lane1: cov | lane2: cov 2 add(lane1, perr) lane0: cov | lane1: cov perr | lane2: cov 3 add(null, mon) lane0: cov mon | lane1: cov perr mon | lane2: cov mon 4 add(lane2, dly, UVM_PREPEND) lane0: cov mon | lane1: cov perr mon | lane2: dly cov mon 5 add(null, first, UVM_PREPEND) lane0: first cov mon | lane1: first cov perr mon | lane2: first dly cov mon 6 add_by_name(regex lane0, lane2) lane0: first cov mon tag | lane1: first cov perr mon | lane2: first dly cov mon tag 7 delete(null, cov) lane0: first mon tag | lane1: first perr mon | lane2: first dly mon tag first (*) on ON mon (*) on ON first uvm_test_top.lane2.drv on ON dly uvm_test_top.lane2.drv on ON mon uvm_test_top.lane2.drv on ON tag uvm_test_top.lane2.drv on ON

Check Yourself

Predict the outputlane1's own queue is cov x sd y. sd deletes itself from lane1's queue the first time it is called. The test walks the queue twice, the way a hook point does, and prints who was called. What line does the $display print?
`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;

// One lane of the chip's link. The sink takes a beat at a rising edge where valid and
// ready are both 1, then is busy for one edge.
interface lane_if (input logic clk);
  logic       valid = 0;
  logic [7:0] data = 0;
  logic       par = 0;
  logic       ready;
endinterface

module lane_sink (lane_if bus);
  logic busy = 0;
  assign bus.ready = !busy;
  always @(posedge bus.clk) busy <= bus.valid && !busy;
endmodule

class lane_item extends uvm_sequence_item;
  `uvm_object_utils(lane_item)
  bit [7:0] data;
  int       n;                         // 1, 2, 3, ...: position in the sequence
  function new(string name = "lane_item"); super.new(name); endfunction
endclass

// The pin values of one transfer. Callbacks may edit this; the item stays as the sequence sent it.
class lane_beat extends uvm_object;
  `uvm_object_utils(lane_beat)
  bit [7:0] data;
  bit       par;
  function new(string name = "lane_beat"); super.new(name); endfunction
endclass

typedef class lane_driver;

// ---- The VIP author's hook class: two hooks, all empty until a callback overrides them ----
class lane_cb extends uvm_callback;
  `uvm_object_utils(lane_cb)
  function new(string name = "lane_cb"); super.new(name); endfunction
  // After the driver builds the beat, before any pin moves. Edit the beat here.
  virtual function void pre_send(lane_driver drv, lane_item it, lane_beat beat); endfunction
  // After the sink took the beat, before item_done. A task: the driver waits until it returns.
  virtual task post_send(lane_driver drv, lane_item it, lane_beat beat); endtask
endclass

class lane_driver extends uvm_driver #(lane_item);
  `uvm_component_utils(lane_driver)
  `uvm_register_cb(lane_driver, lane_cb)          // lane_driver offers lane_cb hooks
  virtual lane_if vif;
  int unsigned hook_runs;                          // how many times a hook point ran
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    forever begin
      lane_beat beat;
      seq_item_port.get_next_item(req);
      beat = lane_beat::type_id::create("beat");
      beat.data = req.data;
      beat.par  = ^req.data;                       // even parity over data and par
      hook_runs++;
      `uvm_do_callbacks(lane_driver, lane_cb, pre_send(this, req, beat))
      @(negedge vif.clk);
      vif.valid <= 1;
      vif.data  <= beat.data;
      vif.par   <= beat.par;
      do @(posedge vif.clk); while (!vif.ready);   // the sink takes the beat at this edge
      vif.valid <= 0;
      hook_runs++;
      `uvm_do_callbacks(lane_driver, lane_cb, post_send(this, req, beat))
      seq_item_port.item_done();
    end
  endtask
endclass

// Counts, and prints, every beat the sink takes.
class lane_monitor extends uvm_monitor;
  `uvm_component_utils(lane_monitor)
  virtual lane_if vif;
  int unsigned beats, bad;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    forever begin
      @(posedge vif.clk);
      if (vif.valid && vif.ready) begin
        beats++;
        if (vif.par != ^vif.data) bad++;
      end
    end
  endtask
endclass

class lane_agent extends uvm_agent;
  `uvm_component_utils(lane_agent)
  uvm_sequencer #(lane_item) sqr;
  lane_driver  drv;
  lane_monitor mon;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    virtual lane_if vif;
    if (!uvm_config_db #(virtual lane_if)::get(this, "", "vif", vif)) `uvm_fatal("NOVIF", "no lane_if")
    sqr = uvm_sequencer #(lane_item)::type_id::create("sqr", this);
    drv = lane_driver::type_id::create("drv", this);
    mon = lane_monitor::type_id::create("mon", this);
    drv.vif = vif;
    mon.vif = vif;
  endfunction
  function void connect_phase(uvm_phase phase); drv.seq_item_port.connect(sqr.seq_item_export); endfunction
endclass

// Items 1, 2, 3, ... with data 10, 20, 30, ... (hex).
class lane_seq extends uvm_sequence #(lane_item);
  `uvm_object_utils(lane_seq)
  int count = 3;
  function new(string name = "lane_seq"); super.new(name); endfunction
  task body();
    for (int i = 1; i <= count; i++) begin
      lane_item it = lane_item::type_id::create("it");
      start_item(it);
      it.data = 8'(16 * i);
      it.n    = i;
      finish_item(it);
    end
  endtask
endclass

// Records each lane whose driver called it, and how often.
class tally_cb extends lane_cb;
  `uvm_object_utils(tally_cb)
  int calls[string];
  function new(string name = "tally_cb"); super.new(name); endfunction
  function void pre_send(lane_driver drv, lane_item it, lane_beat beat);
    string lane = drv.get_parent().get_name();
    if (!calls.exists(lane)) calls[lane] = 0;
    calls[lane]++;
  endfunction
endclass

function automatic string roster(lane_driver d);
  uvm_callback_iter #(lane_driver, lane_cb) it = new(d);
  string s = "";
  for (lane_cb cb = it.first(); cb != null; cb = it.next()) s = {s, " ", cb.get_name()};
  return s == "" ? " -" : s;
endfunction

// Deletes itself from the driver's queue the first time it is called.
class once_cb extends tally_cb;
  `uvm_object_utils(once_cb)
  function new(string name = "once_cb"); super.new(name); endfunction
  function void pre_send(lane_driver drv, lane_item it, lane_beat beat);
    super.pre_send(drv, it, beat);
    uvm_callbacks #(lane_driver, lane_cb)::delete(drv, this);
  endfunction
endclass
// Adds extra to the driver's queue the first time it is called.
class adder_cb extends tally_cb;
  `uvm_object_utils(adder_cb)
  lane_cb       extra;
  uvm_apprepend how;
  function new(string name = "adder_cb"); super.new(name); endfunction
  function void pre_send(lane_driver drv, lane_item it, lane_beat beat);
    super.pre_send(drv, it, beat);
    if (extra != null) uvm_callbacks #(lane_driver, lane_cb)::add(drv, extra, how);
    extra = null;
  endfunction
endclass

class order_test extends uvm_test;
  `uvm_component_utils(order_test)
  lane_agent lane[3];
  tally_cb   cov, perr, mon, dly, first, tag;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    foreach (lane[i]) lane[i] = lane_agent::type_id::create($sformatf("lane%0d", i), this);
    cov   = tally_cb::type_id::create("cov");
    perr  = tally_cb::type_id::create("perr");
    mon   = tally_cb::type_id::create("mon");
    dly   = tally_cb::type_id::create("dly");
    first = tally_cb::type_id::create("first");
    tag   = tally_cb::type_id::create("tag");
  endfunction
  function void show(string call);
    $display("%-36s lane0:%s | lane1:%s | lane2:%s", call, roster(lane[0].drv), roster(lane[1].drv), roster(lane[2].drv));
  endfunction
  function void connect_phase(uvm_phase phase);
    uvm_callbacks #(lane_driver, lane_cb)::add(null, cov);
  endfunction
  task run_phase(uvm_phase phase);
    lane_driver d = lane[1].drv;
    lane_item   it = new("it");
    lane_beat   bt = new("bt");
    tally_cb    x = new("x"), y = new("y");
    once_cb     sd = new("sd");
    string      w1, w2;
    uvm_callbacks #(lane_driver, lane_cb)::add(d, x);
    uvm_callbacks #(lane_driver, lane_cb)::add(d, sd);
    uvm_callbacks #(lane_driver, lane_cb)::add(d, y);
    w1 = walk(d, it, bt);
    w2 = walk(d, it, bt);
    $display("walk 1:%s | walk 2:%s", w1, w2);
  endtask
  // Runs the hook point the way the driver does and returns who was called.
  function string walk(lane_driver d, lane_item it, lane_beat bt);
    uvm_callback_iter #(lane_driver, lane_cb) iter = new(d);
    string s = "";
    for (lane_cb cb = iter.first(); cb != null; cb = iter.next()) begin
      s = {s, " ", cb.get_name()};
      cb.pre_send(d, it, bt);
    end
    return s;
  endfunction
endclass

module tb;
  bit clk;
  always #5 clk = ~clk;
  lane_if   bus0 (clk), bus1 (clk), bus2 (clk);
  lane_sink sink0 (bus0), sink1 (bus1), sink2 (bus2);
  initial begin
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane0", "vif", bus0);
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane1", "vif", bus1);
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane2", "vif", bus2);
    run_test("order_test");
  end
endmodule
ConceptThe test calls add(null, a), then add(drv1, b), then add(null, c, UVM_PREPEND). In what order does drv1 call them?
ConceptWhich call adds cb to the drivers of lanes 0 and 2 in an environment under the test?
ConceptAn error injector must stay quiet during a reset in the middle of the test and then resume in the same position. Which call fits?

Common Mistakes

Wrong Call add_by_name in the test's build_phase, before the environment builds its lanes.

The pattern is matched once, at the call; nothing matches yet, so the callback is never added (CBNOMTC).

Fix Call it in connect_phase or later, when the components exist.

Wrong Write the pattern relative to the root: add_by_name("env.lane*.drv", cb, this).

The pattern is matched against full names; the root only limits where the search looks.

Fix Start the pattern with *. or write the full name.

Before
add_by_name("env.lane*.drv", cb, this);
After
add_by_name("*.lane*.drv", cb, this);

Wrong Delete a callback from a driver that has never had a callback of its own.

uvm-core 2020.3.1 then reads a null queue and the simulation stops with a null-pointer error.

Fix Delete typewide with delete(null, cb), or switch the callback off with callback_mode(0).

Remember

  • A driver borrows the typewide queue until its first instance add, which copies the typewide queue and appends.
  • Every later typewide add or delete changes the typewide queue and every queue that exists; UVM_PREPEND puts the callback at the front.
  • add_by_name matches full names, once, at the call; globs use only * and ?, and /.../ is a regular expression.
  • Switch a callback off with callback_mode(0); delete it typewide with delete(null, cb); never change a queue from inside a hook.

Practice

Report a problem with this page