Vetoes, Early Exit and an Error-Injection Library
Let a callback refuse a beat with uvm_do_callbacks_exit_on. Then build a small injection library that drops, corrupts and delays beats, with a ledger that matches the pins.
You Will Be Able To
- Write a veto hook with
uvm_do_callbacks_exit_onand predict its return value. - Choose the registration order so the right callback may veto.
- Build stackable injectors that read a plan and write a ledger.
- Check that every injection the ledger records reached the pins.
- Lesson
- U18.4
- Time
- 30 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
A VIP release added a hook that lets a test drop a beat. The first test that used it lost every beat on the lane, not just the planned one. The driver asked its callbacks with uvm_do_callbacks, which ignores their answers, so its veto function always returned 0.
| Facade line in may_send | Beats the plan drops | Beats on the pins |
|---|---|---|
uvm_do_callbacks(...) | 1 of 5 | 0 of 5 |
uvm_do_callbacks_exit_on(..., 0) (the example) | 1 of 5 | 4 of 5 |
Measured with the lesson's lane VIP: five items, the plan drops item 2.
A Hook That Can Say No
Some hooks must return an answer: may this beat go out? The VIP's second release adds allow_send, a function hook that returns bit. The driver asks it through may_send before it builds the pins, and drops the beat on 0.
uvm_do_callbacks
while (cb != null) begin
cb.allow_send(this, it, beat);
cb = iter.next();
end
Every callback is asked and every answer is thrown away.
uvm_do_callbacks_exit_on(..., 0)
while (cb != null) begin
if (cb.allow_send(this, it, beat) == 0)
return 0;
cb = iter.next();
end
return 1;
The first callback that answers 0 ends the walk; with none, the result is 1.
The fourth argument is the value that stops the walk; the function returns its opposite when nobody gives it. With 0, every callback must agree and any one may veto. With 1, the first callback that says yes decides, and the rest are not asked.
Because the expansion contains return, it must be the last statement of a function that returns bit. A task cannot hold it, and code after it never runs. uvm_do_obj_callbacks_exit_on is the same with an object argument instead of this.
Order Decides Who May Veto
lane0.drv asks its callbacks in queue order: drop, asked, corrupt, delay. Arrows are calls.- Driver
- Step
- I/O
- Control
- Data
- Ask the first callback
may_sendexpandsuvm_do_callbacks_exit_onwith value 0. It asksdropfirst, becausedropwas added first.Follow the calls, values and waits
- call allow_send(item 2): lane0.drv → drop
- The veto
dropfinds item 2 in the plan, records it and returns 0. The macro runsreturn 0at once, soaskedis never asked.Follow the calls, values and waits
- data dropped: 2: drop → ledger
- return returns 0: drop → lane0.drv
- Nothing else runs
The driver calls
item_donefor item 2 and asks for item 3. Nopre_sendruns for item 2, socorruptcannot touch the dropped beat although item 2 is in its plan.
Read the diagram as text
- lane0.drv: may_send(item 2, beat)
- drop: item 2 is planned: returns 0
- asked: an observer: never asked about item 2
- corrupt: pre_send never runs for item 2
- ledger: dropped: 2
- lane_if pins: nothing for item 2
- lane0.drv → drop: allow_send
- drop → asked: next: skipped
- drop → ledger: dropped 2
- lane0.drv → corrupt: pre_send: skipped
- lane0.drv → lane_if pins: drives
Order decides who may veto and who is asked. An observer that must see every beat goes before the vetoing callback.
The example adds four callbacks in this order: drop, asked, corrupt, delay. asked is an observer that counts the beats it was asked about. It reports 4, not 5, because item 2 stopped at drop.
The UVM 1.1 guide shows another style: a ref bit drop argument that every callback may set. Every callback then runs, and a later one may even clear an earlier drop. Pick one style per hook and write it in the hook's comment.
Three Patterns for an Answering Hook
| Pattern | Macro value | Result with no callbacks | Example |
|---|---|---|---|
| Ask permission: anyone may veto | 0 | 1: send | allow_send: drop a planned beat |
| First handler wins | 1 | 0: not handled | A response hook: the first callback that claims an address answers it |
| Everyone votes, the driver decides | none: ref argument | whatever the driver set | UVM 1.1 trans_received(..., ref bit drop) |
The value in the macro is the answer that stops the walk.
A Stackable Injection Library
Each injector does one thing at the hook that fits it. drop_cb vetoes at allow_send. corrupt_cb flips parity at pre_send. delay_cb waits at post_send. They share two objects: a plan, which items each one acts on, and a ledger, what each one really did.
Because each injector has one job, a test stacks only the ones it needs, and two tests combine without a new class. The plan can come from the configuration database or plusargs, so a regression varies it without editing code.
Item 2 never reaches the pins, so its planned corruption never happens. The ledger says the same.
The ledger is what makes the library trustworthy. check_phase compares it with the monitor: one bad beat per recorded corruption, and one missing beat per recorded drop. A mismatch means an injector claims work the pins never showed, as in the hook. U12.1's CBIDLE check is the same idea for one injector.
Try It
Four beats reach the sink. Item 2 is missing, item 4 has bad parity, and item 4 waits two extra clocks after item 3. The ledger agrees with the pins, so check_phase reports nothing.
Swap the first two add lines so asked comes first: it counts 5. Then add corrupt before drop and change corrupt_cb to act in allow_send instead of pre_send: the ledger lists 2 as corrupted, and check_phase reports LEDGER.
15 ns lane0 took 10, parity good 35 ns lane0 took 30, parity good 65 ns lane0 took 40, parity BAD 85 ns lane0 took 50, parity good ledger: dropped 2; corrupted 4; delayed 3; asked 4 times; pins: 4 beats, 1 bad UVM_ERROR : 0Check Yourself
Common Mistakes
Wrong Put a veto hook point behind uvm_do_callbacks in a function that returns bit.
The plain macro throws every answer away, and the function returns its default, 0.
Fix Use uvm_do_callbacks_exit_on, which returns the first veto or the other value.
function bit may_send(lane_item it, lane_beat beat);
`uvm_do_callbacks(lane_driver, lane_cb, allow_send(this, it, beat))
endfunctionfunction bit may_send(lane_item it, lane_beat beat);
`uvm_do_callbacks_exit_on(lane_driver, lane_cb, allow_send(this, it, beat), 0)
endfunctionWrong Write code after the ` _exit_on ` macro in the same function.
The macro ends in return statements, so the code after it never runs.
Fix Give the macro a function of its own, and act on its result in the caller.
Wrong Register an observer after the vetoing callback and trust its count of every beat.
The walk stops at the veto, so callbacks later in the queue are never asked about that beat.
Fix Put callbacks that must see every beat before the one that may veto, or count from the monitor.
Remember
uvm_do_callbacks_exit_on(T, CB, METHOD, VAL)returns VAL at the first callback that returns VAL, and 1-VAL if none does.- The macro contains
return, so it must be the last statement of a function that returns bit. - Callbacks after a veto are not asked. Put observers before the vetoing callback, or count from the monitor.
- Give each injector one job at the hook that fits it. Share a plan and a ledger, and check the ledger against the pins.