Event Pools and Event Callbacks
A pool turns a name into an event. Learn how widely that name is shared and how to keep two copies of one environment apart. Then let an event callback log, count or veto a trigger.
You Will Be Able To
- Predict which components share an event when they ask a pool for the same name.
- Give each environment instance its own event pool and hand it down.
- Write an event callback that vetoes a trigger in
pre_triggerand logs inpost_trigger. - Wait for one transaction to end through the pool every transaction carries.
- Lesson
- U17.2
- Time
- 30 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
A chip has two copies of a DMA block, so the bench builds two copies of its environment. Each consumer waits for "done" from the global pool. Block A finishes at 20 ns, and block B's consumer starts its second stage at 20 ns too. Block B is still working, yet no check fails: the checks just run against the wrong state.
- Environment
- Control / FSM
- Control
- One name, one eventbuild (illustrative)
Both global-pool environments get the same object.
- The first done releases both20 ns (illustrative)
The producer of env ga triggers. The consumer of env gb waits on the same event, so it starts too.
Follow the calls, values and waits
- data trigger: env ga → global "done"
- return released: global "done" → env gb
- Local pools20 and 40 ns (illustrative)
Envs la and lb each own a pool, so each "done" releases only its own consumer.
Read the diagram as text
- env ga: block done at 20 ns
- env gb: block done at 40 ns
- global "done": one event for the run
- env la: block done at 20 ns
- env lb: block done at 40 ns
- la_pool "done": only env la uses it
- lb_pool "done": only env lb uses it
- env ga → global "done": get("done")
- env gb → global "done": get("done")
- env la → la_pool "done": get("done")
- env lb → lb_pool "done": get("done")
A name is only as private as the pool it lives in. Measured by the example below.
A Pool Turns a Name into an Event
uvm_event_pool is a typedef of uvm_object_string_pool #(uvm_event #(uvm_object)): a table from strings to events. get(name) returns the event stored under that name. If there is none, it creates one with that name, stores it and returns it. exists, num and delete read and edit the table.
uvm_event_pool::get_global_pool() returns one pool for the whole simulation, and uvm_event_pool::get_global(name) is short for get_global_pool().get(name). Every component that asks the global pool for "done" gets the same object. That is the point of a pool: two components meet by name, with no handle passed between them.
An event stays in its pool for the rest of the run, and everyone who asked for it holds the same object. So a reset by one consumer clears the state for every other consumer of that name too. delete(name) only removes the pool's entry. Components that already hold the handle keep the old event, and the next get creates a new one.
It is also the risk. Because get creates on a miss, a typo is never an error. At 70 ns the example asks the global pool for "Done" with a capital D. The pool simply grows from 1 event to 2. A consumer waiting on "Done" would wait for ever, and nothing would report it.
Local Pools Keep Copies Apart
A reusable environment is built more than once: two DMA engines, four lanes, or a block bench reused at chip level. If it uses the global pool, all its copies share every name. In the example, environments ga and gb both use the global "done". ga's producer finishes at 20 ns, and both consumers start at 20 ns.
The fix is to scope the name. The environment creates its own pool, new({get_name(), "_pool"}), and hands it down. The example sets it in the configuration database for "*" below the environment, and each component gets it in its own build_phase. A small bench can also assign the handle to each component directly. Environments la and lb own a pool, and their consumers start at 20 and 40 ns.
One name for the whole run
// each component's run_phase
done = uvm_event_pool::get_global("done");
Every copy of the environment shares "done". The first block to finish releases them all.
One name per environment
// the environment's build_phase
uvm_config_db #(uvm_event_pool)::set(this, "*",
"pool", new({get_name(), "_pool"}));
// each component's build_phase
if (!uvm_config_db #(uvm_event_pool)::get(this, "",
"pool", pool)) `uvm_fatal("NOPOOL", "no pool")
Each copy has its own "done". Create the pool once, hand it down, and fail loudly if it is missing.
Two mistakes undo the fix. A pool created by each component separately gives the producer and the consumer two different events, so the consumer hangs. A component that falls back to the global pool when it finds no local one brings the cross-talk back.
Not every event needs a pool. When the producer and the consumer can be given the same handle, pass the uvm_event #(T) itself. Then the compiler checks the type of the data, while pool events always carry a plain uvm_object.
Event Callbacks: Log, Count, Veto
An event callback is an object attached to one event. uvm_event_callback #(T) has two hooks. pre_trigger(e, data) runs first, for every callback, and returns a bit. If any of them returns 1, the whole trigger is skipped. The event does not turn on, the data and time are not stored, no process is released and no post_trigger runs. Otherwise the event triggers, and then post_trigger(e, data) runs for every callback.
Every pre_trigger runs
uvm-core asks all of them and adds up the results, so a later callback still runs after an earlier one vetoed.
Any 1 skips the trigger
The event stays as it was. In the example, the second "done" at 52 ns leaves the event as the first one left it at 50 ns.
Otherwise the event fires
onis set, the data and time are stored, and the waiters are scheduled to resume.Every post_trigger runs
The waiters have not run yet, but they are already released. Use this hook to log or count.
post_trigger calls e.reset() | Standard behaviour | Verilator 5.052, measured |
|---|---|---|
A process in wait_on() | Wakes: on went 0, 1, 0, and any value change wakes @on (IEEE 1800-2023 §9.4.2) | Keeps waiting: the zero-width pulse of on is missed |
A process in wait_trigger() | Wakes: the inner event fired before the reset | Wakes |
So a reset in post_trigger is not a veto, even where it seems to work. Only pre_trigger can stop a trigger. Verilator row: U17 review probes.
add_callback(cb, append) attaches a callback to one event, and append = 0 puts it first. delete_callback(cb) removes it. The callback class is itself a uvm_callback, kept per event by uvm_callbacks #(uvm_event #(T), uvm_event_callback #(T)). Module U18 teaches that machinery.
Typical uses are small. A veto rejects malformed triggers, such as a second "done" within a few nanoseconds of the first, from a bouncing status bit. A logger records every announcement with its time. A counter feeds synchronisation coverage, for example how many interrupts arrived during a service. Keep the hooks short, because they run inside the producer's trigger call.
Every Transaction Carries a Pool
Each uvm_transaction, and so each sequence item, owns a private event pool, get_event_pool(). uvm-core triggers its "begin" event in begin_tr, its "end" event in end_tr and "accept" in accept_tr. With automatic item recording on, which is the sequencer's default, start_item calls begin_tr and finish_item calls end_tr for you.
A process that holds the item can therefore wait for that one item to finish, with no shared name: item.get_event_pool().get("end").wait_on(). The example calls begin_tr and end_tr by hand, and the waiter prints at 75 ns. Use this when one component needs to know when one particular transaction is done. The item also keeps the times of both calls, so the waiter can read get_begin_time() and get_end_time() to see how long the transaction took.
Try It
Five block environments run together. ga and gb use the global pool; la, lb and lc each own a pool, handed down through the configuration database. lc's status bit bounces and sends a second "done" at 52 ns, which the veto rejects. At 70 ns the test shows how a typo grows the global pool, and then it ends one sequence item by hand.
Delete the add_callback line and the last line reports a trigger at 52 ns. Set local_pool = 1 for gb, and its consumer waits until 40 ns.
20 ns uvm_test_top.ga.c starts stage 2 (done from uvm_test_top.ga.p) 20 ns uvm_test_top.gb.c starts stage 2 (done from uvm_test_top.ga.p) 20 ns uvm_test_top.la.c starts stage 2 (done from uvm_test_top.la.p) 40 ns uvm_test_top.lb.c starts stage 2 (done from uvm_test_top.lb.p) 50 ns log: done triggered by p 50 ns uvm_test_top.lc.c starts stage 2 (done from uvm_test_top.lc.p) 52 ns veto: done again 2 ns after the last trigger 70 ns global pool: 1 event(s), exists("Done") = 0 70 ns after get("Done"): 2 event(s); vetoed 1 70 ns lc's done: last trigger at 50 ns 75 ns the item's own end event is onCheck Yourself
Common Mistakes
Wrong Ask the global pool for "done" inside a reusable environment.
The global pool has one event per name for the whole run. Two copies of the environment share it, and the first "done" releases both.
Fix Let the environment create a pool and hand it to its components.
Wrong Veto a trigger in post_trigger.
post_trigger runs after the event has turned on and released its waiters. It returns nothing and cannot stop anything.
Fix Return 1 from pre_trigger.
Wrong Spell an event name two ways.
get creates an event for any new name, with no warning. The two sides now use different events, and the waiter hangs.
Fix Keep each name in one constant, or pass the event handle itself.
Remember
- A pool maps names to events and creates one on a miss: a typo makes a second, silent event.
- The global pool shares a name across the whole run. Give each environment instance its own pool and hand it down.
pre_triggerreturning 1 skips the whole trigger;post_triggerruns after the release and is for logging and counting.- Every transaction has its own pool with "begin", "accept" and "end" events.