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_typeso 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 declares | Lane 1 (slow_driver) calls |
|---|---|
| Its own pair only | pace |
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.
- Test
- Storage
- Driver
- Data
- Typewide on the base
add(null, cov)throughuvm_callbacks #(lane_driver, lane_cb)fills the lane_driver typewide queue.slow_drivernamedlane_driveras its super type. So the add is copied to the slow_driver typewide queue too. - 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.
- Owning
The instance add of
perrthrough 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, thenperris 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.
| Registration | Base facade on a derived object | Derived facade, no super type | Derived facade, with super type |
|---|---|---|---|
| Typewide on the base | runs | does not run | runs |
| Typewide on the derived type | runs only with the super type | runs | runs |
| Instance add, either pool | runs | runs | runs |
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.
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
endclassAny 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.
lane0 lane_driver calls: cov lane1 slow_driver calls: cov pace lane2 slow_driver calls: cov pace perrCheck Yourself
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_callbacksruns the callbacks of another object, and anyuvm_objectcan offer callbacks.