Callback, Override, Knob or Delegate: A Decision Lab

Build one requirement four ways, combine two teams' changes, and choose the extension point that survives the combination. Then write the VIP author's checklist for hooks.

You Will Be Able To

  • Build one change as a knob, an override, a callback and a delegate.
  • Predict what happens when two teams combine overrides or callbacks on one driver.
  • Choose an extension point from who must foresee the change and whether changes stack.
  • List what a VIP author promises with each hook.
Lesson
U18.5
Time
30 min
Runs on
Verilator with UVM
Check
4 questions

Two teams each needed one change on the same lane driver: bad parity on item 2, and inverted data on item 3. Each delivered a factory override, and each test passed alone. Combined on one lane, the parity change vanished without a message.

Lane 4 setupBad parity onChanged data on
Two instance overrides, parity team first2-
Two callbacks (lane 5)23

Measured in the example: with two overrides on one path, only the first one set is built.

One Requirement, Four Ways

The example's VIP offers four extension points around the beat. They are a knob cfg.bad_par_on, a delegate policy.parity(), a virtual method shape() and the pre_send callbacks. Each of lanes 0 to 3 sends item 2 with bad parity through one of them.

KnobOverrideCallbackDelegate
Code the test writesone field seta subclass and an overridea subclass and an adda subclass and a config set
Must the VIP author foresee it?the exact valuea virtual methoda hook pointthe delegate role
Two teams at onceonly if both knobs existone class winsstack in queue orderone object per role
Change during the runif the VIP rereads itnoadd, delete, switch offswap the handle
Work per beata field reada virtual callone iterator per hook point runa virtual call
Silent failurewrong path or read too earlypath matches nothing, or another override winswrong instance or typeset after the VIP read it

Lanes 0-3 of the example all send item 2 with bad parity; the differences show only when changes combine.

Combining Two Teams

Lanes 4 and 5 carry both requirements. Lane 4 gets two instance overrides for the same driver path; lane 5 gets two callbacks. Lane 5 shows both changes. Lane 4 shows only the parity change: the factory found the first override for that path and built par2_driver. That is the standard's rule (IEEE 1800.2-2020 §8.3.1.4.1). Instance overrides are searched in the order they were set, and the first match wins.

Choosing an Extension PointQuestions a VIP author and a test writer ask, in order. Arrows are answers.
  • Control / FSM
  • Result
  • Control
Choosing an extension pointQuestions a VIP author and a test writer ask, in order. Arrows are answers. control A value the VIPauthor foresaw? a delay, an idle value,an error rate result Config knob a field the VIP reads control Several changesmust stack orswitch during therun? two teams on onedriver result Callback at a hook point theVIP offers control One algorithmreplaced as awhole? timing, arbitration, achecksum result Delegate object a handle the VIP calls result Factory override a subclass built in itsplace yesnoyesnoyes, the VIP offers ahandleno: change the class
  1. control A value the VIP author foresaw?a delay, an idle value, an error rate
    • yes → Config knob
    • no → Several changes must stack or switch during the run?
  2. result Config knoba field the VIP reads
  3. control Several changes must stack or switch during the run?two teams on one driver
    • yes → Callback
    • no → One algorithm replaced as a whole?
  4. result Callbackat a hook point the VIP offers
  5. control One algorithm replaced as a whole?timing, arbitration, a checksum
    • yes, the VIP offers a handle → Delegate object
    • no: change the class → Factory override
  6. result Delegate objecta handle the VIP calls
  7. result Factory overridea subclass built in its place
  1. Foreseen values

    If the author can name the variation, a knob is the cheapest: one field, set per instance.

  2. Stacking

    Only callbacks stack: two teams add two objects to one driver. lane5 in the example.

  3. Replacing

    One replaced algorithm fits a delegate if the VIP offers one, else an override of the class.

Read the diagram as text
  • A value the VIP author foresaw?: a delay, an idle value, an error rate
  • Config knob: a field the VIP reads
  • Several changes must stack or switch during the run?: two teams on one driver
  • Callback: at a hook point the VIP offers
  • One algorithm replaced as a whole?: timing, arbitration, a checksum
  • Delegate object: a handle the VIP calls
  • Factory override: a subclass built in its place
  • A value the VIP author foresaw? → Config knob: yes
  • A value the VIP author foresaw? → Several changes must stack or switch during the run?: no
  • Several changes must stack or switch during the run? → Callback: yes
  • Several changes must stack or switch during the run? → One algorithm replaced as a whole?: no
  • One algorithm replaced as a whole? → Delegate object: yes, the VIP offers a handle
  • One algorithm replaced as a whole? → Factory override: no: change the class

The Cookbook prefers overrides and delegates to callbacks; callbacks earn their place when changes must stack.

The VIP Author's Checklist

  1. Offer knobs for foreseen values

    Put them in a config object, read them where they are used, and document when they are read.

  2. Offer a delegate for each replaceable algorithm

    Timing, arbitration, a checksum: a small base class with a default, set before build.

  3. Offer few hooks, per item

    Pass the objects a callback may change, such as the beat, and keep their prototypes stable.

  4. Document the order

    Say when each hook runs, whether it is a task, and what a veto does.

  5. Keep methods virtual and creation in the factory

    So an override stays possible for the cases nobody foresaw.

The Cookbook's guideline is to avoid callbacks and use overrides or a delegate instead. That fits changes that replace behaviour. Callbacks remain the one point where independent additions stack and can be switched during the run. That is why vendor VIP offers them.

Try It

Lanes 0-3 are the four ways to the same result. Lane 4 built only par2_driver, so team B's change is missing; lane 5 runs both callbacks.

Change lane 0's knob to item 3 and lane 3's policy to flip every item, and compare the edits each needs.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: lane0 knob lane_driver bad parity on 2, changed data on - lane1 override par2_driver bad parity on 2, changed data on - lane2 callback lane_driver bad parity on 2, changed data on - lane3 delegate lane_driver bad parity on 2, changed data on - lane4 2 overrides par2_driver bad parity on 2, changed data on - lane5 2 callbacks lane_driver bad parity on 2, changed data on 3

Check Yourself

Predict the outputSame bench, but lane 4's two instance overrides are set in the other order: inv3_driver first, then par2_driver. What line does the $display print for lane 4?
`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 knobs the VIP author foresaw. 0 means off.
class lane_cfg extends uvm_object;
  `uvm_object_utils(lane_cfg)
  int bad_par_on;                      // send this item with bad parity
  function new(string name = "lane_cfg"); super.new(name); endfunction
endclass

// The delegate: one object the driver asks for the parity bit. Swap it for another policy.
class lane_policy extends uvm_object;
  `uvm_object_utils(lane_policy)
  function new(string name = "lane_policy"); super.new(name); endfunction
  virtual function bit parity(lane_item it, bit computed); return computed; endfunction
endclass

// ---- 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
  lane_cfg     cfg;                                // knobs the VIP author foresaw
  lane_policy  policy;                             // the delegate that decides the parity bit
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    if (!uvm_config_db #(lane_cfg)::get(this, "", "cfg", cfg)) cfg = lane_cfg::type_id::create("cfg");
    if (!uvm_config_db #(lane_policy)::get(this, "", "policy", policy)) policy = lane_policy::type_id::create("policy");
  endfunction
  // A subclass may override this to change the beat. The base leaves it alone.
  virtual function void shape(lane_item it, lane_beat beat); 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
      if (cfg.bad_par_on == req.n) beat.par = !beat.par;   // 1: the knob
      beat.par = policy.parity(req, beat.par);            // 2: the delegate
      shape(req, beat);                                   // 3: the virtual method
      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

// ---- One requirement, four ways: send item 2 with bad parity ----
class par2_driver extends lane_driver;               // a factory override
  `uvm_component_utils(par2_driver)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void shape(lane_item it, lane_beat beat); if (it.n == 2) beat.par = !beat.par; endfunction
endclass
class par2_cb extends lane_cb;                       // a callback
  `uvm_object_utils(par2_cb)
  function new(string name = "par2_cb"); super.new(name); endfunction
  function void pre_send(lane_driver drv, lane_item it, lane_beat beat); if (it.n == 2) beat.par = !beat.par; endfunction
endclass
class par2_policy extends lane_policy;               // a delegate
  `uvm_object_utils(par2_policy)
  function new(string name = "par2_policy"); super.new(name); endfunction
  function bit parity(lane_item it, bit computed); return it.n == 2 ? !computed : computed; endfunction
endclass

// ---- A second team's requirement: invert the data of item 3 ----
class inv3_driver extends lane_driver;
  `uvm_component_utils(inv3_driver)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void shape(lane_item it, lane_beat beat); if (it.n == 3) beat.data = ~beat.data; endfunction
endclass
class inv3_cb extends lane_cb;
  `uvm_object_utils(inv3_cb)
  function new(string name = "inv3_cb"); super.new(name); endfunction
  function void pre_send(lane_driver drv, lane_item it, lane_beat beat); if (it.n == 3) beat.data = ~beat.data; endfunction
endclass

// Records, by beat number, which beats had bad parity or data the sequence did not send.
class audit_monitor extends lane_monitor;
  `uvm_component_utils(audit_monitor)
  int bad_on[$], changed_on[$];
  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_on.push_back(beats);
        if (vif.data != 8'(16 * beats)) changed_on.push_back(beats);
      end
    end
  endtask
  static function string show(int q[$]);
    string s = "";
    foreach (q[i]) begin
      if (s != "") s = {s, ","};
      s = {s, $sformatf("%0d", q[i])};
    end
    return s == "" ? "-" : s;
  endfunction
endclass

class choose_test extends uvm_test;
  `uvm_component_utils(choose_test)
  string     how[6] = '{"knob", "override", "callback", "delegate", "2 overrides", "2 callbacks"};
  lane_agent lane[6];
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    lane_cfg    knob   = lane_cfg::type_id::create("knob");
    par2_policy policy = par2_policy::type_id::create("policy");
    lane_monitor::type_id::set_type_override(audit_monitor::get_type());
    knob.bad_par_on = 2;
    uvm_config_db #(lane_cfg)::set(this, "lane0.drv", "cfg", knob);                       // lane 0
    lane_driver::type_id::set_inst_override(par2_driver::get_type(), "lane1.drv", this);   // lane 1
    uvm_config_db #(lane_policy)::set(this, "lane3.drv", "policy", policy);               // lane 3
    lane_driver::type_id::set_inst_override(inv3_driver::get_type(), "lane4.drv", this);   // lane 4:
    lane_driver::type_id::set_inst_override(par2_driver::get_type(), "lane4.drv", this);   //  both teams
    foreach (lane[i]) lane[i] = lane_agent::type_id::create($sformatf("lane%0d", i), this);
  endfunction
  function void connect_phase(uvm_phase phase);
    par2_cb p2 = par2_cb::type_id::create("p2");
    inv3_cb i3 = inv3_cb::type_id::create("i3");
    uvm_callbacks #(lane_driver, lane_cb)::add(lane[2].drv, p2);                         // lane 2
    uvm_callbacks #(lane_driver, lane_cb)::add(lane[5].drv, p2);                         // lane 5:
    uvm_callbacks #(lane_driver, lane_cb)::add(lane[5].drv, i3);                         //  both teams
  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;
    #20;
    phase.drop_objection(this);
  endtask
  function void report_phase(uvm_phase phase);
    foreach (lane[i]) if (i == 4) begin
      audit_monitor m;
      $cast(m, lane[i].mon);
      $display("%s %-11s %-11s bad parity on %s, changed data on %s", lane[i].get_name(), how[i],
               lane[i].drv.get_type_name(), audit_monitor::show(m.bad_on), audit_monitor::show(m.changed_on));
    end
  endfunction
endclass

module tb;
  bit clk;
  always #5 clk = ~clk;
  lane_if   bus0 (clk), bus1 (clk), bus2 (clk), bus3 (clk), bus4 (clk), bus5 (clk);
  lane_sink sink0 (bus0), sink1 (bus1), sink2 (bus2), sink3 (bus3), sink4 (bus4), sink5 (bus5);
  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);
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane3", "vif", bus3);
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane4", "vif", bus4);
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane5", "vif", bus5);
    run_test("choose_test");
  end
endmodule
ConceptA VIP author expects users to choose between three idle values on the bus. Which extension point fits?
ConceptThe lane driver reads its pacing delegate from the configuration database in build_phase. A test sets a new pacer in connect_phase. What happens?
ConceptWhich change is the best fit for a callback?

Common Mistakes

Wrong Give two teams' changes as two factory overrides for the same driver.

Only one class is built per instance; with two instance overrides on one path, the first one set wins.

Fix Make additions callbacks, or write one subclass that does both.

Wrong Set a delegate in the configuration database after the driver's build_phase.

The driver reads the handle once in build_phase and keeps the default.

Fix Set it before the driver is built, from the test's build_phase.

Wrong Use a callback to replace the driver's timing.

A callback runs only at the points the VIP offers; it cannot change how the driver waits between them.

Fix Replace an algorithm with a delegate or an override.

Remember

  • Knobs for foreseen values, delegates or overrides for replaced algorithms, callbacks for additions that must stack or switch.
  • One instance gets one class: two overrides for one path do not combine, and the first one set wins.
  • A delegate or knob is read when the VIP reads it, usually in build_phase; set it before.
  • A VIP author offers few per-item hooks with stable arguments and documents their order.

Practice

Report a problem with this page