The Callback Machinery, Read from the Source

Build a VIP's callback hooks and read what each macro expands to. Then predict which callbacks run, when they run, and what each hook point costs.

You Will Be Able To

  • Name the four pieces of the callback machinery and who writes each one.
  • Expand a uvm_do_callbacks line into the loop it runs.
  • Choose a function hook or a task hook for a VIP extension point.
  • Read the CBUNREG and CBPREG warnings and say what still runs after each.
Lesson
U18.1
Time
30 min
Runs on
Verilator with UVM
Check
5 questions

A VIP's release notes said its pre_send hook lets a test corrupt a beat. A team's parity injector ran on every item and the error test still passed. The driver called the hook one line too late, after it had already assigned the pins.

Where the VIP calls pre_sendTimes the injector ranBad beats on the pins
After vif.par <= beat.par10
Before the pins move (the example)11

Measured with the lesson's lane VIP: three items, the injector flips the parity of item 2.

Four Pieces, Two Authors

A callback is an object a test hands to a component, so the component calls it at a fixed point. The machinery has four pieces. The VIP author writes three of them; the test writes the fourth.

PieceIn the exampleWritten by
Hook classlane_cb extends uvm_callback, with empty virtual pre_send and post_sendVIP author
Registrationuvm_register_cb(lane_driver, lane_cb) inside lane_driverVIP author
Hook pointsTwo uvm_do_callbacks lines in the run loopVIP author
Pool and callbacksuvm_callbacks #(lane_driver, lane_cb)::add(lane0.drv, perr)Test

The pool class, uvm_callbacks #(T, CB), comes from the library. Its state is static.

One Hook Point, ExpandedThe example's pre_send hook point on lane0.drv. Solid arrows are calls; the pool holds handles.
  • Driver
  • Neutral
  • Storage
  • Step
  • Control
  • Data
CallValueReturnWaiting
One hook point, expandedThe example's `pre_send` hook point on `lane0.drv`. Solid arrows are calls; the pool holds handles. driver lane0.drv `uvm_do_callbacks(lane_driver,lane_cb, pre_send(...)) neutral uvm_callback_iter A new object on every run ofthe line storage uvm_callbacks#(lane_driver, lane_cb) Static: one queue per object,one per type step perr pre_send: flips par on item 2 step gap No pre_send of its own: theempty one runs storage `uvm_register_cb A static bit: lane_driveraccepts lane_cb new(this)first(), next()call 1call 2checked by add
  1. storage `uvm_register_cbA static bit: lane_driver accepts lane_cb
    • checked by add → uvm_callbacks #(lane_driver, lane_cb)
  2. storage uvm_callbacks #(lane_driver, lane_cb)Static: one queue per object, one per type
  3. driver lane0.drv`uvm_do_callbacks(lane_driver, lane_cb, pre_send(...))
    • new(this) → uvm_callback_iter
  4. neutral uvm_callback_iterA new object on every run of the line
    • first(), next() → uvm_callbacks #(lane_driver, lane_cb)
    • call 1 → perr
    • call 2 → gap
  5. step perrpre_send: flips par on item 2
  6. step gapNo pre_send of its own: the empty one runs
  1. Registration

    uvm_register_cb(lane_driver, lane_cb) declares a static bit in the driver class. Its initialiser marks the pair registered before time 0. add checks that mark and only warns when it is missing.

  2. The line runs0 ns (illustrative)

    For item 2 the driver reaches its pre_send line. The macro builds a uvm_callback_iter for this, even if no callback is registered.

    Follow the calls, values and waits
    1. call iterator for lane0.drv: lane0.drv → uvm_callback_iter
  3. Find the queue

    first() asks the pool for this object's queue and skips any callback whose callback_mode is 0. lane0.drv has its own queue: perr, then gap.

    Follow the calls, values and waits
    1. return queue: perr, gap: uvm_callbacks #(lane_driver, lane_cb) → uvm_callback_iter
  4. Call each callback

    The loop calls pre_send on perr, which flips the parity, then on gap, whose pre_send is the empty one from lane_cb. next() returns null and the loop ends.

    Follow the calls, values and waits
    1. call pre_send(item 2): uvm_callback_iter → perr
    2. call pre_send(item 2): uvm_callback_iter → gap
Read the diagram as text
  • lane0.drv: `uvm_do_callbacks(lane_driver, lane_cb, pre_send(...))
  • uvm_callback_iter: A new object on every run of the line
  • uvm_callbacks #(lane_driver, lane_cb): Static: one queue per object, one per type
  • perr: pre_send: flips par on item 2
  • gap: No pre_send of its own: the empty one runs
  • `uvm_register_cb: A static bit: lane_driver accepts lane_cb
  • lane0.drv → uvm_callback_iter: new(this)
  • uvm_callback_iter → uvm_callbacks #(lane_driver, lane_cb): first(), next()
  • uvm_callback_iter → perr: call 1
  • uvm_callback_iter → gap: call 2
  • `uvm_register_cb → uvm_callbacks #(lane_driver, lane_cb): checked by add

The driver owns the line and the arguments; the pool owns the order; each callback owns only its own methods.

What a Hook Point Expands To

Each hook point is a macro. Written out, it is a short loop over an iterator object:

What the VIP author writes

`uvm_do_callbacks(lane_driver, lane_cb,
                  pre_send(this, req, beat))

One line in the run loop: the hook point.

What it becomes

begin
  uvm_callback_iter #(lane_driver, lane_cb) iter = new(this);
  lane_cb cb = iter.first();
  while (cb != null) begin
    cb.pre_send(this, req, beat);
    cb = iter.next();
  end
end

first and next skip a callback whose callback_mode is 0.

Three facts follow from the loop. The callbacks run in queue order, one after another, in the driver's own process. A callback sees exactly the arguments the driver passes, so beat is the only thing it can change on the pins. And uvm_do_callbacks is uvm_do_obj_callbacks with this as the object, a form U18.3 uses directly.

The registration is a static bit. uvm_register_cb(lane_driver, lane_cb) declares one in lane_driver, and its initialiser marks the pair registered before time 0. add reads that mark. Without it, add prints CBUNREG and stores the callback anyway.

The Two Warnings, Measured

The example adds gap to lane0.drv twice. The second add prints CBPREG and changes nothing: a callback is in a queue at most once. display(lane0.drv) then prints the queue, with ON for each enabled callback.

So a missing registration is not silent, but nothing stops either. Treat any CBUNREG as a bug. The same warning is the only sign of a callback stored on a type that never calls it (U12.1).

Function Hooks and Task Hooks

A hook can be a function or a task. pre_send is a function, because an edit to the beat takes no time. post_send is a task, called after the sink took the beat. The driver waits inside the hook point until every callback returns, so a callback that waits adds idle time to the lane.

Lane 0 in the example: when the sink took each beat
0123456edge (ns)15253545556575beat taken10-20-30paritygood-BAD-gooddriver is inpost_sendgap waitsgap endspost_send-post_sendgap holds the driver for 3 edgesperr flipped par
Scroll horizontally ↔

Without gap, beat 20 would go at 35 ns. The task hook moved it to 55 ns.

Choose the kind by the promise you make. A function hook promises the driver will not stop there. A callback then cannot stall the bus in the middle of a transfer. A task hook lets callbacks add delays or wait for events, so place it where waiting is safe. Here that is after the handshake, before item_done.

Callbacks the Library Already Uses

The same machinery runs inside UVM. Each row is a hook class you can extend and add like lane_cb.

Hook classCalled byHooksTaught in
uvm_report_catcherevery report, before it printscatch() (function)U16.1, U18.6
uvm_reg_cbsregister, field and memory accessespre_write ... post_read (tasks), post_predict, encode, decodeU18.7, U18.8
uvm_objection_callbackobjection raise, drop, all droppedraised, dropped (functions), all_dropped (task)U17.5
uvm_heartbeat_callbackthe heartbeat's objectionextends uvm_objection_callbackU17.4
uvm_event_callbackuvm_event::triggerpre_trigger (may veto), post_triggerU17.2
uvm_phase_cbevery phase state changephase_state_changeU19.1 (planned)
uvm_vreg_cbsvirtual register accessespre_write ... post_readU25.4 (planned)
uvm_run_test_callbackrun_testpre_run_test, post_run_test, pre_abortU20.3 (planned)

Read from uvm-core 2020.3.1. uvm_run_test_callback keeps its own list, with static add and delete, instead of a uvm_callbacks pool.

What a Hook Point Costs

Every run of a hook point creates one uvm_callback_iter object, even when no callback is registered. The example counts the runs: 6 for 3 beats, two per item. That price is small per item and large per clock.

So offer hooks once per item or per transfer, never in a per-cycle idle loop. U15.3's rule applies: count the events first, then decide whether the host time matters.

Try It

The warning comes from the second add of gap. The UVM/CB/DISPLAY report lists perr and gap, both ON. The three beats show both hooks at work: gap delays beat 20, and perr sends it with bad parity.

Move the pre_send line in lane_driver below vif.par <= beat.par; and run again: item 2 goes out with good parity. Then delete the uvm_register_cb line and look for CBUNREG in the log.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: UVM_WARNING @ 0: reporter [CBPREG] Callback object gap is already registered with object uvm_test_top.lane0.drv UVM_INFO uvm/base/uvm_callback.svh(511) @ 0: reporter [UVM/CB/DISPLAY] Registered callbacks for instance uvm_test_top.lane0.drv of lane_driver perr uvm_test_top.lane0.drv on ON gap uvm_test_top.lane0.drv on ON 15 ns lane0 took 10, parity good 55 ns lane0 took 20, parity BAD 75 ns lane0 took 30, parity good hook points ran 6 times for 3 beats

Check Yourself

Predict the outputIn this VIP the driver calls pre_send just after vif.par <= beat.par;, in the same time step. The test adds perr, which flips the parity of item 2, and sends three items. 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
      @(negedge vif.clk);
      vif.valid <= 1;
      vif.data  <= beat.data;
      vif.par   <= beat.par;
      hook_runs++;
      `uvm_do_callbacks(lane_driver, lane_cb, pre_send(this, req, beat))   // after the pins
      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

// ---- What the test writes ----
// A function hook: send item 2 with bad parity.
class bad_parity_cb extends lane_cb;
  `uvm_object_utils(bad_parity_cb)
  function new(string name = "bad_parity_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 late_test extends uvm_test;
  `uvm_component_utils(late_test)
  lane_agent    lane0;
  bad_parity_cb perr;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    lane0 = lane_agent::type_id::create("lane0", this);
    perr  = bad_parity_cb::type_id::create("perr");
  endfunction
  function void connect_phase(uvm_phase phase);
    uvm_callbacks #(lane_driver, lane_cb)::add(lane0.drv, perr);
  endfunction
  task run_phase(uvm_phase phase);
    lane_seq seq = lane_seq::type_id::create("seq");
    phase.raise_objection(this);
    seq.start(lane0.sqr);
    phase.drop_objection(this);
  endtask
  function void report_phase(uvm_phase phase);
    $display("bad beats the monitor saw: %0d of %0d", lane0.mon.bad, lane0.mon.beats);
  endfunction
endclass

module tb;
  bit clk;
  always #5 clk = ~clk;
  lane_if   bus0 (clk);
  lane_sink sink0 (bus0);
  initial begin
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane0", "vif", bus0);
    run_test("late_test");
  end
endmodule
ConceptA VIP author wants tests to be able to add idle cycles after a beat. Which hook fits?
ConceptA lane driver runs 2 million clock cycles with 20,000 items. Its author put one hook point in the per-cycle idle loop and two per item. No test registers a callback. Roughly how many iterator objects does the run create?
ConceptThe UVM 1.1 User's Guide says registering a callback on a component not designed for it will not compile. What does uvm-core 2020.3.1 do with uvm_callbacks #(lane_monitor, lane_cb)::add(mon, perr) when lane_monitor never registered lane_cb?
ConceptA test calls perr.callback_mode(0) at 40 ns and perr.callback_mode(1) at 90 ns. What happens to perr in between?

Common Mistakes

Wrong Call the edit hook after the driver has assigned the pins.

The pins were scheduled with the old values, so every edit a callback makes is lost.

Fix Call the edit hook after the beat is built and before the first pin assignment.

Before
vif.par <= beat.par;
`uvm_do_callbacks(lane_driver, lane_cb, pre_send(this, req, beat))
After
`uvm_do_callbacks(lane_driver, lane_cb, pre_send(this, req, beat))
vif.par <= beat.par;

Wrong Ship the driver without uvm_register_cb because the callbacks run anyway.

Every user's add then prints a CBUNREG warning, and real wrong-type mistakes hide among them.

Fix Register every pair the driver calls, and treat any CBUNREG in a log as a bug.

Wrong Copy the UVM 1.1 argument order, uvm_do_callbacks(CB, T, METHOD).

The current macro takes the component type first, so the old order fails to compile.

Fix Write uvm_do_callbacks(T, CB, METHOD), component type first.

Remember

  • The VIP author writes the hook class, uvm_register_cb and the hook points. The test writes callbacks and adds them to the pool.
  • A hook point is a loop: one new iterator, then each enabled callback in queue order, in the driver's process.
  • Without the registration, add warns CBUNREG and the callback still runs. A second add of the same callback warns CBPREG and is ignored.
  • Call an edit hook before the pins move. Use a task hook only where waiting cannot break a transfer.
  • Each hook point run creates an object, so offer hooks per item, not per clock.

Practice

Report a problem with this page