Objections in Depth
An objection is a count per component that travels up the tree. Learn how raises and drops propagate, where drain time sits and which hooks see what. Then find out who kept a test alive.
You Will Be Able To
- Predict the count and total of every component as raises and drops propagate.
- Place a drain time on the right component and predict when the drop reaches the top.
- Choose between component hooks, objection callbacks and
phase_ready_to_end. - Find who holds a phase open with
get_objectors,display_objectionsand a callback.
- Lesson
- U17.5
- Time
- 35 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
A regression run lasts two hours after its traffic ends, and the log only says that the run phase timed out. Somebody still holds an objection. To find who, you need to read objections as counts that travel up the tree, through drain times and hooks.
- Cycle 2
b drops at 15 ns. Its total is 0, so its 10 ns drain starts: the drop would leave b at 25 ns.
- Cycle 4
b raises again at 22 ns, during the drain. The pending drop and the new raise cancel, so the top never sees either.
- Cycle 6
The second drop leaves b at 38 ns and takes the top to 0. The scoreboard raises in
phase_ready_to_end, so the run goes on. - Cycle 7
The scoreboard drops at 70 ns; the run phase ends, and the callback names sb as the last objector.
Measured by the example below.
Count, Total and Propagation
A uvm_objection keeps two numbers for every object that took part. The count is the object's own raises minus its own drops. The total adds the totals of everything below it. raise_objection(obj, description, count) adds count to the object's count and total, then to the total of each parent, up to the top, uvm_root.
| Object at 12 ns | get_objection_count | get_objection_total |
|---|---|---|
| uvm_test_top.env.a | 1 | 1 |
| uvm_test_top.env.b | 1 | 1 |
| uvm_test_top.env | 0 | 2 |
| top (uvm_root) | 0 | 2 |
Measured by the example: the environment holds nothing itself, but its total is 2. get_objectors returns the two agents.
A raise can carry a count above 1, and a drop may give back part of it. The description string travels with each change and shows up in trace messages, so name the reason for each raise. Every change is reported to the hooks of every object on the path.
A drop works the same way down to zero. While an object's total stays above 0, the drop goes on up at once. When the total reaches 0, the drop is held at that object first, for its drain time, and only then moves up. That pause is where drain time lives.
Propagation can be turned off. With set_propagate_mode(0) a raise goes straight from its source to the top, and the components in between see nothing. uvm-core refuses the change while the objection is raised or draining. The example tries it at 12 ns and gets UVM/BASE/OBJTN/PROP_MODE as an error.
Drain Time Belongs to an Object
set_drain_time(obj, t) attaches a drain to one object. When that object's total falls to 0, the objection waits t before it passes the drop to the parent. It calls the object's all_dropped hook after the wait. Most benches set it on the test or the top. Setting it on an agent delays only that agent's drops on their way up.
A raise at the same object during the drain cancels the pending drop. The raise and the pending drop are netted against each other, and nothing reaches the parent. In the example, agent b drops at 15 ns with a 10 ns drain, and raises again at 22 ns. The top never sees the first drop. Only the second one, at 28 ns, leaves b at 38 ns.
Hooks: Who Sees What
Three kinds of hooks watch an objection, and they see different things.
| Hook | Called | Measured in the example |
|---|---|---|
Component raised / dropped | On each component the change passes through, with the source | env sees every agent's raise |
Component all_dropped (a task) | When the component's total reaches 0, after its drain | env at 38 ns (last from b) and 70 ns (last from sb) |
uvm_objection_callback on one objection | At every level, with obj and source_obj | holder_log filters on the top and logs each change |
| The same callback added typewide | For every objection of the run | Spike S12: 46 phase-hopper raises in a 25 ns run |
all_dropped is a task: the objection waits for it before the drop moves on.
In a callback, obj is the object being updated and source_obj the component that raised or dropped. One raise from a leaf therefore calls the callback once per level. Filter on obj to pick a level, and use source_obj to name who caused the change.
Add callbacks with uvm_objection_cbs_t::add(objection, cb). Passing null adds it typewide. Then it also sees the objection of every phase, and the phase hopper's own objection, raised for every scheduled phase. A short test produced dozens of those calls, so a typewide logger mostly logs noise.
Ending the Test
Objections decide when a phase ends, so every end-of-test pattern is an objection pattern. They differ in who holds the phase and how long.
| Pattern | Who holds the phase | Risk |
|---|---|---|
| Test raises around its sequences | The test, until its last sequence returns | Ends before the design finishes the last items |
| Automatic objection on the root sequence | The sequence, for its body | Same, and it needs a starting phase |
| Drain time on the test | Nobody: a fixed wait after the last drop | A guess; deeper pipelines outgrow it |
phase_ready_to_end in the scoreboard | The scoreboard, while results are owed | Hangs if a result never comes: add a timeout |
all_dropped hook | Whoever raises in it | Runs at every zero, not only the last |
In the example the agents end at 38 ns; the scoreboard's raise in phase_ready_to_end moves the end to 70 ns.
The scoreboard pattern is the most honest, because it holds the phase exactly as long as results are owed. The library calls phase_ready_to_end every time the phase's total reaches 0, up to 20 times. U1.3 shows the basic form.
Objections of Your Own
A phase objection is only one use of the class. uvm_objection is an ordinary object, so a bench can create its own for any "someone is still busy" question. The heartbeats of U17.4 watch one. The predict question below uses one named "work", with a drain on the test, and no phase ends when it drops.
A process can wait on such an objection directly, but mind which waits are edges. wait_for(UVM_ALL_DROPPED, obj) waits for the next time the total at obj drops to 0, after the hooks have run. If the total is already 0, it hangs. UVM_RAISED and UVM_DROPPED also wait for the next change. wait_for_total_count(obj, n) is a level wait: it returns at once if the total at obj already equals n.
This gives a clean way to wait until every lane is idle, without a barrier. Each lane raises a "busy" objection while it works, and the coordinator calls busy.wait_for_total_count(null, 0). With wait_for(UVM_ALL_DROPPED) instead, a coordinator that arrives after the lanes went idle waits for ever. Unlike a barrier, an objection needs no threshold, so lanes can come and go freely.
Who Kept the Test Alive?
When a run will not end, ask the objection. get_objectors(list) returns every object whose own count is above 0. get_objection_count(obj) and get_objection_total(obj) read one object. display_objections() prints the tree with both numbers. Spike S12 printed it with the test holding one and an agent holding two.
trace_mode(1) logs every raise, drop and drain as a UVM_INFO message. That helps in a short run and drowns you in a long one. A callback on the run phase's objection is quieter. The example's holder_log keeps the source of the last drop at the top, and the report phase prints it.
clear(obj) throws all counts away and ends the phase at once, with a warning OBJTN_CLEAR if anything was still raised. Use it only to abandon a phase on purpose, never to hide a leak.
Try It
Agent a works from 0 to 20 ns. Agent b has a 10 ns drain and works from 5 to 15 ns and from 22 to 28 ns. Its first drop is cancelled during the drain. The scoreboard keeps the phase open in phase_ready_to_end until 70 ns. The one UVM_ERROR is the refused propagation change at 12 ns.
Delete the set_drain_time line, and b's first drop reaches the top at 15 ns and its second at 28 ns. Delete the scoreboard's raise, and the run phase ends at 38 ns.
0 ns top: +1 from a, total 1 5 ns top: +1 from b, total 2 12 ns objectors: 2; count(env)=0 total(env)=2 total(top)=2 uvm_test_top.env.a count 1 uvm_test_top.env.b count 1 UVM_ERROR uvm/base/uvm_objection.svh(318) @ 12: run_objection [UVM/BASE/OBJTN/PROP_MODE] The propagation mode of 'run_objection' cannot be changed while the objection is raised or draining! 20 ns top: -1 from a, total 1 38 ns env: all_dropped (last from b) 38 ns top: -1 from b, total 0 38 ns sb: phase_ready_to_end, results still owed: raise 38 ns top: +1 from sb, total 1 70 ns env: all_dropped (last from sb) 70 ns top: -1 from sb, total 0 run phase ended at 70 ns; last drop at the top came from sb UVM_ERROR : 1Check Yourself
Common Mistakes
Wrong Read obj in an objection callback as the component that raised.
The hook runs once per level as the change travels up. obj is the level being updated; source_obj is the component that raised.
Fix Use source_obj to name the raiser, and filter on obj to pick one level.
Wrong Register an objection callback typewide to watch the run phase.
A typewide callback sees every objection of the run, including the phase hopper's and every phase's. Its log fills with noise.
Fix Add it to the one objection you care about: uvm_objection_cbs_t::add(phase.get_objection(), cb).
Wrong Change the propagation mode while the objection is raised.
uvm-core refuses with UVM/BASE/OBJTN/PROP_MODE and keeps the old mode.
Fix Set it before the first raise, or not at all.
Wrong Expect a drain time on an agent to delay its own drops.
A drain starts when the component's total reaches zero, and it delays the drop on its way to the parent.
Fix Put the drain on the component whose zero total should wait.
Remember
- Each object has a count of its own raises and a total that includes everything below it. A change updates its source, then each parent.
- A drain time belongs to one object. When its total reaches zero, the drop waits there before moving up, and a raise meanwhile cancels it.
- Component hooks see changes below them. An objection callback on one objection sees every level; added typewide it sees every objection.
get_objectors,get_objection_count,get_objection_totalanddisplay_objectionssay who holds a phase open right now.