Callbacks, Inheritance and the Factory

Keep callbacks working when a factory override installs a derived driver. Know which pool a hook point reads, when uvm_set_super_type is needed, and which add order loses callbacks.

You Will Be Able To

  • Predict which typewide queue a driver borrows from its facade type.
  • Use uvm_set_super_type so base-type callbacks reach a derived driver.
  • Choose the pool for an instance add so no typewide callback is lost.
  • Run another object's callbacks with uvm_do_obj_callbacks.
Lesson
U18.3
Time
30 min
Runs on
Verilator with UVM
Check
4 questions

A coverage callback ran on every lane until another team's slow_driver was installed on some lanes by a factory override. On those lanes it silently stopped. slow_driver copied the base driver's loop and called its hooks through its own type. So it read a typewide queue that never received the callback.

slow_driver declaresLane 1 (slow_driver) calls
Its own pair onlypace
Its own pair and uvm_set_super_type(slow_driver, lane_driver) (the example)cov pace

Measured: cov is added typewide to lane_driver, pace typewide to slow_driver.

The Facade Type Picks the Queue

Every driver either owns a queue or borrows one. It owns a queue after the first instance add names it. Until then each hook point borrows a typewide queue, and the type in the facade line decides which. uvm_do_callbacks(lane_driver, ...) borrows lane_driver's queue, even when this is a slow_driver.

Whose Typewide Queue Does a Driver Borrow?The example's lanes. A driver with no queue of its own borrows a typewide queue; the facade type of its hook points decides which. Arrows are adds and look-ups.
  • Test
  • Storage
  • Driver
  • Data
Whose typewide queue does a driver borrow?The example's lanes. A driver with no queue of its own borrows a typewide queue; the facade type of its hook points decides which. Arrows are adds and look-ups. test Test add(null, cov) onlane_driver; add(null,pace) on slow_driver storage lane_drivertypewide cov storage slow_drivertypewide cov (copied: supertype), pace driver lane0.drv lane_driver: facadelane_driver driver lane1.drv slow_driver: facadeslow_driver storage lane2.drv's ownqueue copy of slow_drivertypewide, then perr driver lane2.drv slow_driver: facadeslow_driver add(null, cov)super type copiesborrowsborrowsfirst instance addcopiesowns
  1. test Testadd(null, cov) on lane_driver; add(null, pace) on slow_driver
    • add(null, cov) → lane_driver typewide
  2. storage lane_driver typewidecov
    • super type copies → slow_driver typewide
  3. storage slow_driver typewidecov (copied: super type), pace
    • first instance add copies → lane2.drv's own queue
  4. driver lane0.drvlane_driver: facade lane_driver
    • borrows → lane_driver typewide
  5. driver lane1.drvslow_driver: facade slow_driver
    • borrows → slow_driver typewide
  6. storage lane2.drv's own queuecopy of slow_driver typewide, then perr
  7. driver lane2.drvslow_driver: facade slow_driver
    • owns → lane2.drv's own queue
  1. Typewide on the base

    add(null, cov) through uvm_callbacks #(lane_driver, lane_cb) fills the lane_driver typewide queue. slow_driver named lane_driver as its super type. So the add is copied to the slow_driver typewide queue too.

  2. Borrowing

    The drivers of lane0 and lane1 have no queue of their own. lane0's hook points use the lane_driver facade, lane1's the slow_driver facade, so each borrows its own type's queue.

  3. Owning

    The instance add of perr through the slow_driver pool gives lane2 a queue of its own. It starts as a copy of the typewide queue of the pool named in that add, then perr is appended.

Read the diagram as text
  • Test: add(null, cov) on lane_driver; add(null, pace) on slow_driver
  • lane_driver typewide: cov
  • slow_driver typewide: cov (copied: super type), pace
  • lane0.drv: lane_driver: facade lane_driver
  • lane1.drv: slow_driver: facade slow_driver
  • lane2.drv's own queue: copy of slow_driver typewide, then perr
  • lane2.drv: slow_driver: facade slow_driver
  • Test → lane_driver typewide: add(null, cov)
  • lane_driver typewide → slow_driver typewide: super type copies
  • lane0.drv → lane_driver typewide: borrows
  • lane1.drv → slow_driver typewide: borrows
  • slow_driver typewide → lane2.drv's own queue: first instance add copies
  • lane2.drv → lane2.drv's own queue: owns

Without the super type, the copy arrow is missing and lane1 never calls cov.

So a derived driver that inherits the base run loop needs nothing: its hook points still use the lane_driver facade. The trouble starts when the derived class writes its own hook points with its own type, as slow_driver does.

uvm_set_super_type Connects the Two Queues

uvm_set_super_type(slow_driver, lane_driver) is a static declaration, like uvm_register_cb. It records lane_driver as the super type. From then on a typewide add on lane_driver is copied into the slow_driver typewide queue. The base facade also looks there for a slow_driver object.

RegistrationBase facade on a derived objectDerived facade, no super typeDerived facade, with super type
Typewide on the baserunsdoes not runruns
Typewide on the derived typeruns only with the super typerunsruns
Instance add, either poolrunsrunsruns

Measured in spike S4 (plan §4) on uvm-core 2020.3.1 with Verilator 5.052. It ran all four combinations of own pair and super type, six adds each. The example and the predicts on this page re-run three of its cells.

Keep the derived class's own uvm_register_cb. With the super type alone, the hook points still work, but every add through the derived pool warns CBUNREG.

The Pool Named in the First Instance Add

An instance add creates the object's own queue the first time. The new queue starts as a copy of one typewide queue: the one of the pool named in that add. Typewide adds made later reach the queue through any pool whose type the object is.

So adding to a slow_driver through uvm_callbacks #(lane_driver, lane_cb) copies the lane_driver typewide queue. Callbacks added typewide to slow_driver before that moment are lost here. The super type does not help.

Through the base pool

uvm_callbacks #(lane_driver, lane_cb)::add(lane[2].drv, perr);

lane2 calls cov perr: pace was added before and is lost.

Through the object's own pool

$cast(s2, lane[2].drv);
uvm_callbacks #(slow_driver, lane_cb)::add(s2, perr);

lane2 calls cov pace perr (the example).

The safest order avoids the question: make instance adds first, then typewide ones. Every typewide add then reaches every queue.

Running Another Object's Callbacks

uvm_do_callbacks is uvm_do_obj_callbacks with this as the object. Write the object form when the hook point lives in another object that works for the driver. That object runs the callbacks registered on the driver, not its own.

The facade type picks the queue here too: lane_driver's. A derived facade type would need the super type of the section above.
class idle_filler extends uvm_component;
  lane_driver drv;                 // the driver it fills idle cycles for
  function void fill(lane_item gap, lane_beat beat);
    `uvm_do_obj_callbacks(lane_driver, lane_cb, drv, pre_send(drv, gap, beat))
  endfunction
endclass

Any uvm_object can offer callbacks, not only components: a sequence, a transaction class, a register field. uvm_reg_field does exactly this for the register callbacks of U18.7.

Overrides and Handles

A factory override changes the type built, not the handles you hold. lane[1].drv is typed lane_driver and points to a slow_driver, so an instance add through it works. A handle read before build is still null, and add(null, cb) is typewide: the callback lands on every driver.

Register after the components exist, print each queue with display() at the end of elaboration, and compare it with what you meant.

Try It

Each line lists the callbacks the lane's own hook points call, in order. lane0 borrows the lane_driver queue, lane1 the slow_driver queue (with cov copied in), and lane2 owns a queue.

Delete the uvm_set_super_type line and run again: lane1 calls only pace. Then add perr through lane[2].drv and the lane_driver pool: lane2 loses pace.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: lane0 lane_driver calls: cov lane1 slow_driver calls: cov pace lane2 slow_driver calls: cov pace perr

Check Yourself

Predict the outputThe example's bench, with the super type. The test adds cov typewide to lane_driver and pace typewide to slow_driver, then adds perr to lane 2 with uvm_callbacks #(lane_driver, lane_cb)::add(lane[2].drv, perr). What line does the $display print for lane 2?
`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

// Team B's driver: lane_driver's loop, copied, with one idle cycle before each beat. It calls
// its hooks through its own type, so it registers its own pair.
class slow_driver extends lane_driver;
  `uvm_component_utils(slow_driver)
  `uvm_register_cb(slow_driver, lane_cb)
  `uvm_set_super_type(slow_driver, lane_driver)    // typewide lane_driver callbacks apply here too
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    forever begin
      lane_beat beat = lane_beat::type_id::create("beat");
      seq_item_port.get_next_item(req);
      beat.data = req.data;
      beat.par  = ^req.data;
      `uvm_do_callbacks(slow_driver, lane_cb, pre_send(this, req, beat))
      repeat (2) @(negedge vif.clk);               // the slow part: one idle cycle first
      vif.valid <= 1;
      vif.data  <= beat.data;
      vif.par   <= beat.par;
      do @(posedge vif.clk); while (!vif.ready);
      vif.valid <= 0;
      `uvm_do_callbacks(slow_driver, lane_cb, post_send(this, req, beat))
      seq_item_port.item_done();
    end
  endtask
endclass

class override_test extends uvm_test;
  `uvm_component_utils(override_test)
  lane_agent lane[3];
  tally_cb   cov, pace, perr;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    lane_driver::type_id::set_inst_override(slow_driver::get_type(), "lane1.drv", this);
    lane_driver::type_id::set_inst_override(slow_driver::get_type(), "lane2.drv", this);
    foreach (lane[i]) lane[i] = lane_agent::type_id::create($sformatf("lane%0d", i), this);
    cov  = tally_cb::type_id::create("cov");
    pace = tally_cb::type_id::create("pace");
    perr = tally_cb::type_id::create("perr");
  endfunction
  function void connect_phase(uvm_phase phase);
    uvm_callbacks #(lane_driver, lane_cb)::add(null, cov);
    uvm_callbacks #(slow_driver, lane_cb)::add(null, pace);
    uvm_callbacks #(lane_driver, lane_cb)::add(lane[2].drv, perr);    // through the lane_driver handle
  endfunction
  task run_phase(uvm_phase phase);
    phase.raise_objection(this);
    foreach (lane[i]) fork
      automatic int k = i;
      begin
        lane_seq seq = lane_seq::type_id::create("seq");
        seq.start(lane[k].sqr);
      end
    join_none
    wait fork;
    phase.drop_objection(this);
  endtask
  // The callbacks a lane's driver calls at pre_send, in calling order, through the facade
  // type its own hook points use: slow_driver for lanes 1 and 2, lane_driver for lane 0.
  function string calls(lane_driver d);
    slow_driver s;
    string r = "";
    if ($cast(s, d)) begin
      uvm_callback_iter #(slow_driver, lane_cb) it = new(s);
      for (lane_cb cb = it.first(); cb != null; cb = it.next()) r = {r, " ", cb.get_name()};
    end else begin
      uvm_callback_iter #(lane_driver, lane_cb) it = new(d);
      for (lane_cb cb = it.first(); cb != null; cb = it.next()) r = {r, " ", cb.get_name()};
    end
    return r == "" ? " none" : r;
  endfunction
  function void report_phase(uvm_phase phase);
    $display("%s %s calls:%s", lane[2].get_name(), lane[2].drv.get_type_name(), calls(lane[2].drv));
  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("override_test");
  end
endmodule
Concepterr_driver extends lane_driver overrides only shape() and inherits the base run loop. A test adds a callback typewide to lane_driver. Does an err_driver installed by a factory override call it?
ConceptA test stores lane[1].drv in a variable during its own build_phase, before the environment has built the lanes, and later calls add(saved, perr). What happens?
ConceptWhich line belongs in slow_driver so that callbacks added typewide to lane_driver reach it?

Common Mistakes

Wrong Give a derived driver its own hook points and registration, with no super type.

Its hook points borrow the derived typewide queue, which never receives callbacks added to the base type.

Fix Declare the base as the derived class's super type, next to its own registration (the example's slow_driver).

Wrong Make the first instance add on a derived driver through a lane_driver handle.

The new queue copies the lane_driver typewide queue, so callbacks added only to the derived type are lost.

Fix Add through the pool of the object's own type, or make instance adds before typewide ones.

Wrong Swap the arguments: uvm_set_super_type(lane_driver, slow_driver).

The first argument is the derived type; swapped, base-type callbacks never reach the derived driver.

Fix Write the derived type first, then its base.

Remember

  • A driver without instance callbacks borrows a typewide queue; the facade type of its hook points picks which.
  • uvm_set_super_type(derived, base) copies base typewide adds into the derived queue. Keep the derived class's own registration too.
  • The first instance add copies the typewide queue of the pool it names. Add through the object's own type, or make instance adds first.
  • uvm_do_obj_callbacks runs the callbacks of another object, and any uvm_object can offer callbacks.

Practice

Report a problem with this page