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_callbacksline into the loop it runs. - Choose a function hook or a task hook for a VIP extension point.
- Read the
CBUNREGandCBPREGwarnings 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_send | Times the injector ran | Bad beats on the pins |
|---|---|---|
After vif.par <= beat.par | 1 | 0 |
| Before the pins move (the example) | 1 | 1 |
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.
| Piece | In the example | Written by |
|---|---|---|
| Hook class | lane_cb extends uvm_callback, with empty virtual pre_send and post_send | VIP author |
| Registration | uvm_register_cb(lane_driver, lane_cb) inside lane_driver | VIP author |
| Hook points | Two uvm_do_callbacks lines in the run loop | VIP author |
| Pool and callbacks | uvm_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.
pre_send hook point on lane0.drv. Solid arrows are calls; the pool holds handles.- Driver
- Neutral
- Storage
- Step
- Control
- Data
- 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.addchecks that mark and only warns when it is missing. - The line runs0 ns (illustrative)
For item 2 the driver reaches its
pre_sendline. The macro builds auvm_callback_iterforthis, even if no callback is registered.Follow the calls, values and waits
- call iterator for lane0.drv: lane0.drv → uvm_callback_iter
- Find the queue
first()asks the pool for this object's queue and skips any callback whosecallback_modeis 0. lane0.drv has its own queue: perr, then gap.Follow the calls, values and waits
- return queue: perr, gap: uvm_callbacks #(lane_driver, lane_cb) → uvm_callback_iter
- Call each callback
The loop calls
pre_sendon perr, which flips the parity, then on gap, whosepre_sendis the empty one fromlane_cb.next()returns null and the loop ends.Follow the calls, values and waits
- call pre_send(item 2): uvm_callback_iter → perr
- 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.
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 class | Called by | Hooks | Taught in |
|---|---|---|---|
uvm_report_catcher | every report, before it prints | catch() (function) | U16.1, U18.6 |
uvm_reg_cbs | register, field and memory accesses | pre_write ... post_read (tasks), post_predict, encode, decode | U18.7, U18.8 |
uvm_objection_callback | objection raise, drop, all dropped | raised, dropped (functions), all_dropped (task) | U17.5 |
uvm_heartbeat_callback | the heartbeat's objection | extends uvm_objection_callback | U17.4 |
uvm_event_callback | uvm_event::trigger | pre_trigger (may veto), post_trigger | U17.2 |
uvm_phase_cb | every phase state change | phase_state_change | U19.1 (planned) |
uvm_vreg_cbs | virtual register accesses | pre_write ... post_read | U25.4 (planned) |
uvm_run_test_callback | run_test | pre_run_test, post_run_test, pre_abort | U20.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.
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 beatsCheck Yourself
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.
vif.par <= beat.par;
`uvm_do_callbacks(lane_driver, lane_cb, pre_send(this, req, beat))`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_cband 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,
addwarnsCBUNREGand the callback still runs. A second add of the same callback warnsCBPREGand 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.