Order, Scope and Lifetime
Predict the calling order on every driver after typewide, instance, prepended and by-name adds and deletes. Check it with the iterator API and display.
You Will Be Able To
- Predict a driver's calling order from the sequence of add and delete calls.
- Register by name with a pattern that matches full names, after the components exist.
- Switch a callback off, delete it, or delete it everywhere, and know which to use.
- Walk a queue with the iterator API, and avoid changing it during a walk.
- Lesson
- U18.2
- Time
- 30 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
Two teams added callbacks to the same lane drivers, one typewide in build_phase and one on a single lane in connect_phase. The coverage callback that was meant to run last ran in the middle on that one lane. Nobody had printed the queues, so the difference showed up as odd coverage weeks later.
| After call | lane0 calls | lane1 calls | lane2 calls |
|---|---|---|---|
| 2 add(lane1, perr) | cov | cov perr | cov |
| 5 add(null, first, UVM_PREPEND) | first cov mon | first cov perr mon | first dly cov mon |
| 7 delete(null, cov) | first mon tag | first perr mon | first dly mon tag |
Three of the example's seven measured lines. Each lane may end up with a different order.
Own a Queue or Borrow One
The pool keeps one queue per object and one typewide queue per type. A driver with no queue of its own borrows the typewide queue. The first instance add gives it a queue: a copy of the typewide queue, then the new callback. After that, every typewide add or delete changes the typewide queue and every queue that exists.
connect_phase. A lane with no queue of its own borrows the typewide queue. Arrows are adds and copies.- Test
- Storage
- Data
- Calls 1-2
add(null, cov)fills the typewide queue; every lane borrows it.add(lane1, perr)gives lane1 its own queue: a copy of the typewide queue, then perr. - Calls 3-5
Later typewide adds reach every queue that exists: mon is appended everywhere, first is prepended everywhere.
add(lane2, dly, UVM_PREPEND)copies the typewide queue and puts dly in front of it. - Calls 6-7
add_by_namegives lane0 and lane2 their own queues.delete(null, cov)removes cov from the typewide queue and from every lane's own queue.
Read the diagram as text
- Test: seven add and delete calls
- Typewide queue: after call 7: first mon
- lane0 queue: own from call 6: first mon tag
- lane1 queue: own from call 2: first perr mon
- lane2 queue: own from call 4: first dly mon tag
- Test → Typewide queue: add(null, ...)
- Typewide queue → lane1 queue: copied at call 2
- Typewide queue → lane2 queue: copied at call 4
- Typewide queue → lane0 queue: copied at call 6
- Test → lane1 queue: add(lane1, perr)
One rule explains every line. A lane copies the typewide queue when it gets its own; every later typewide change reaches every queue.
UVM_PREPEND puts the callback at the front of each queue it reaches. On an instance add that is in front of the copied typewide callbacks too: lane2 calls dly before cov.
In uvm-core 2020.3.1 that per-object queue is shared by every callback type, report catchers included. A first add of another type can give a driver its own queue and drop earlier typewide lane callbacks. U18.6 measures it next to the standard's rule.
Adding by Name
add_by_name(pattern, cb, root, ordering) finds every component under root whose full name matches pattern, and makes an instance add on each one of the right type. The match happens once, at the call. A component built later is not added, and a call that matches nothing prints CBNOMTC.
The pattern is a glob: * matches any characters, + one or more, ? exactly one. Square brackets are literal characters in a glob, so *.lane[02].drv matches nothing. A pattern between slashes is a regular expression instead: the example uses /lane[02]\.drv$/ to reach lane0 and lane2. delete_by_name takes the same arguments.
Off, Deleted, or Deleted Everywhere
| Call | Effect | Use it for |
|---|---|---|
cb.callback_mode(0) | Stays in every queue; hook points skip it | A window, such as no injection during reset |
delete(drv, cb) | Leaves that driver's own queue | A job done on one driver |
delete(null, cb) | Leaves the typewide queue and every queue | A job done everywhere |
delete_by_name(pattern, cb, root) | delete on every match | Undoing an add_by_name |
A disabled callback keeps its place, so it runs in the same position when switched on again.
Reading a Queue
uvm_callback_iter #(T, CB) walks a driver's queue the way a hook point does: first, next, last, prev, each skipping disabled callbacks. The static get_first(itr, obj) and its relatives do the same with an int cursor you keep. get_all(q, obj) collects every callback of the type, enabled or not.
display(obj) prints the typewide callbacks, marked (*), and then the driver's own queue. A driver with its own queue calls only that queue, so the (*) lines repeat callbacks it already holds. The example's display of lane2 shows this.
Changing the Queue During a Walk
The iterator keeps a position and asks the pool for the queue again at every step. Changing the queue while a walk is in progress shifts what the position points at.
An append during a walk runs in the same walk, because the queue just grew at the end. A delete during a walk skips the callback after the deleted one. Make queue changes between walks: in a phase, or from the test after a sequence, not from inside a hook.
Try It
Each line lists the callbacks each lane's hook point would call after one more registration call. The display of lane2 at the end lists the typewide queue, marked (*), and then lane2's own queue.
Move call 2 after call 5 and run again: lane1's copy now starts with first cov mon, and perr comes last.
1 add(null, cov) lane0: cov | lane1: cov | lane2: cov 2 add(lane1, perr) lane0: cov | lane1: cov perr | lane2: cov 3 add(null, mon) lane0: cov mon | lane1: cov perr mon | lane2: cov mon 4 add(lane2, dly, UVM_PREPEND) lane0: cov mon | lane1: cov perr mon | lane2: dly cov mon 5 add(null, first, UVM_PREPEND) lane0: first cov mon | lane1: first cov perr mon | lane2: first dly cov mon 6 add_by_name(regex lane0, lane2) lane0: first cov mon tag | lane1: first cov perr mon | lane2: first dly cov mon tag 7 delete(null, cov) lane0: first mon tag | lane1: first perr mon | lane2: first dly mon tag first (*) on ON mon (*) on ON first uvm_test_top.lane2.drv on ON dly uvm_test_top.lane2.drv on ON mon uvm_test_top.lane2.drv on ON tag uvm_test_top.lane2.drv on ONCheck Yourself
Common Mistakes
Wrong Call add_by_name in the test's build_phase, before the environment builds its lanes.
The pattern is matched once, at the call; nothing matches yet, so the callback is never added (CBNOMTC).
Fix Call it in connect_phase or later, when the components exist.
Wrong Write the pattern relative to the root: add_by_name("env.lane*.drv", cb, this).
The pattern is matched against full names; the root only limits where the search looks.
Fix Start the pattern with *. or write the full name.
add_by_name("env.lane*.drv", cb, this);add_by_name("*.lane*.drv", cb, this);Wrong Delete a callback from a driver that has never had a callback of its own.
uvm-core 2020.3.1 then reads a null queue and the simulation stops with a null-pointer error.
Fix Delete typewide with delete(null, cb), or switch the callback off with callback_mode(0).
Remember
- A driver borrows the typewide queue until its first instance add, which copies the typewide queue and appends.
- Every later typewide add or delete changes the typewide queue and every queue that exists;
UVM_PREPENDputs the callback at the front. add_by_namematches full names, once, at the call; globs use only*and?, and/.../is a regular expression.- Switch a callback off with
callback_mode(0); delete it typewide withdelete(null, cb); never change a queue from inside a hook.