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_trigger and logs in post_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.

Two Environments Ask a Pool for "done"Arrows show which event each environment gets from its pool. With the global pool both land on one event; with local pools each has its own.
  • Environment
  • Control / FSM
  • Control
CallValueReturnWaiting
Two environments ask a pool for "done"Arrows show which event each environment gets from its pool. With the global pool both land on one event; with local pools each has its own. env env ga block done at 20 ns env env gb block done at 40 ns control global "done" one event for the run env env la block done at 20 ns env env lb block done at 40 ns control la_pool "done" only env la uses it control lb_pool "done" only env lb uses it get("done")get("done")get("done")get("done")
  1. env env gablock done at 20 ns
    • get("done") → global "done"
  2. env env gbblock done at 40 ns
    • get("done") → global "done"
  3. control global "done"one event for the run
  4. env env lablock done at 20 ns
    • get("done") → la_pool "done"
  5. env env lbblock done at 40 ns
    • get("done") → lb_pool "done"
  6. control la_pool "done"only env la uses it
  7. control lb_pool "done"only env lb uses it
  1. One name, one eventbuild (illustrative)

    Both global-pool environments get the same object.

  2. 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
    1. data trigger: env ga → global "done"
    2. return released: global "done" → env gb
  3. 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.

  1. 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.

  2. 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.

  3. Otherwise the event fires

    on is set, the data and time are stored, and the waiters are scheduled to resume.

  4. 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 behaviourVerilator 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 resetWakes

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.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: 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 on

Check Yourself

Predict the outputComponents ask pools for events by name. What line does the $display print?
`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    uvm_event_pool mine = new("mine");
    uvm_event #(uvm_object) a = uvm_event_pool::get_global("go");
    uvm_event #(uvm_object) b = uvm_event_pool::get_global_pool().get("go");
    uvm_event #(uvm_object) c = mine.get("go");
    uvm_event #(uvm_object) d = uvm_event_pool::get_global("Go");
    $display("same=%0d local_same=%0d global_count=%0d local_count=%0d", a == b, a == c,
             uvm_event_pool::get_global_pool().num(), mine.num());
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule
ConceptIn a bench with four copies of one environment, each consumer must wait for its own producer's "done". Where should the event come from?
ConceptA logger callback must record each announcement after it has really happened. Which hook should it use?
ConceptA scoreboard holds one request item and wants to wait until the driver has finished it. The sequencer records items. What can it wait on?

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_trigger returning 1 skips the whole trigger; post_trigger runs after the release and is for logging and counting.
  • Every transaction has its own pool with "begin", "accept" and "end" events.

Practice

Report a problem with this page