uvm_event in Depth: States, Waits and Data

Read an event as four pieces of state. Pick the wait that answers your question, and know what a second trigger, reset and cancel do to the processes that wait.

You Will Be Able To

  • Name the four pieces of state a uvm_event keeps and predict how each call changes them.
  • Choose the waiting call that answers your question, with or without a deadline.
  • Predict what a second trigger, reset and cancel do to the data and to waiting processes.
  • Decide when an event is the wrong tool and a FIFO is the right one.
Lesson
U17.1
Time
35 min
Runs on
Verilator with UVM
Check
5 questions

A FIFO overflows at 2 ns, before the service sequence starts, and the sequence then calls wait_trigger() at 10 ns. It waits for an overflow that already happened, and the test hangs until its timeout. The fix is one word, wait_on(), and to see why you have to read the event as state.

One uvm_event over 45 Ns: Its Four Pieces of State
01234567time (ns)510202530354045calltwo waitingtrigger(1)trigger(2,3)reset(0)trigger(4)reset(1)trigger(5)kill, cancelondatanullnote1note3nullnote4nullnote5trigger time01020030040waiters20note2 is lostthe parked waiter is no longer counted
Scroll horizontally ↔
  1. Cycle 0

    Two processes wait from time 0. The event is off, has no data and counts two waiters.

  2. Cycle 1

    trigger(note1) turns the event on, stores the note and the time, and releases both waiters. The count goes back to 0.

  3. Cycle 2

    Two triggers in one time step. The event keeps one data handle, so the waiter reads note3. Nobody ever sees note2.

  4. Cycle 3

    reset(0) with one process parked since 22 ns. The count drops to 0, but the process still waits. On this simulator it returns at the next trigger, 30 ns.

  5. Cycle 5

    The standard says reset(1) releases the parked process at once. On this simulator it waits for the trigger at 40 ns.

  6. Cycle 7

    A waiting process is killed. Only cancel() takes it out of the count.

Values printed by the example below at each step. The waiter column is what get_num_waiters() returns, not how many processes really wait.

Four Pieces of State

A uvm_event #(T) wraps one SystemVerilog event and adds state around it. There is an on flag, one data handle of type T, the time of the last trigger and a count of waiting processes. Every call reads or changes some of these four, and once you can say which, every wait in this lesson is predictable.

Callondatatrigger timewaiter count
trigger(d)set to 1set to dset to nowset to 0
reset(wakeup)set to 0set to the default dataset to 0set to 0
cancel()unchangedunchangedunchangedminus 1
a wait that blocksunchangedunchangedunchangedplus 1

uvm-core 2020.3.1, base/uvm_event.svh. The default data is null until set_default_data sets one.

Two facts follow at once. The data is a single handle, so the latest trigger always wins. And the waiter count is bookkeeping, not a list of processes, so it can disagree with reality.

Notice also what the event does not keep: a history. It cannot tell you how many times it fired, or what the data of an earlier trigger was. A consumer that needs that must get it from somewhere else, such as a queue or a counter.

The two families of waits also listen to different things. wait_trigger and wait_ptrigger wait on the SystemVerilog event inside. wait_on and wait_off wait for the on flag to change. That difference decides what a reset does to each of them.

Which Wait Answers Your Question

Pick the call by the question you are asking, not by its name. Most event bugs come from asking "has it happened?" with a call that answers "wake me at the next one".

QuestionCallMeasured in the example
Has it happened since the last reset?wait_on()Called at 15 ns, after the trigger at 10: returns at once
Wait for the next one, and only thatwait_trigger()Waiting since 0 ns: returns at 10
The next one, but forgive a trigger earlier in this time stepwait_ptrigger()Called at 10 ns, after the trigger: returns at once
Wait, then take the datawait_trigger_data(d)Waiting since 0 ns: returns note1 at 10
Wait until somebody consumes itwait_off()Returns when reset turns the event off

wait_ptrigger_data is wait_ptrigger followed by get_trigger_data.

wait_ptrigger checks the triggered property of the inner event. IEEE 1800-2017 §15.5.3 keeps that property true only for the rest of the trigger's time step. So it removes a race inside one time step and nothing more: a call one nanosecond later waits for the next trigger.

wait_on(1) and wait_off(1) add a #0 before they return when the state is already right. That lets processes that were already waiting run first. Use it when the order of processes in one time step matters to you.

One Data Handle: The Last Trigger Wins

trigger(d) stores d in the event's single data slot, and a second trigger before anyone reads the slot replaces it. At 20 ns the example triggers note2 and then note3 in one time step. The process waiting in wait_trigger_data since 15 ns receives note3, and nobody ever sees note2.

wait_trigger_data(d) does not protect against this. The standard defines it as wait_trigger followed by get_trigger_data (1800.2 §10.1.2.2.2). Between the release and the read, every other process in the time step may run, including a second trigger.

So an event carries one outstanding announcement. Either the producer holds the next one back with wait_off() until the consumer resets the event, or the announcements belong in a queue. The right-hand pattern below is the first choice. It matches hardware with a sticky status flag that stays set until software clears it.

Announcements can pile up

// monitor, on every overflow:
ovf.trigger(note);
// service:
ovf.wait_trigger_data(n);
serve(n);

Two overflows in one step merge into one, and one that arrives during serve() is missed.

One outstanding announcement

// monitor, on every overflow:
if (ovf.is_on()) ovf.wait_off();  // last one not consumed yet
ovf.trigger(note);
// consumer: takes what it needs from the
// event, then turns it off with reset()

The monitor waits for the consumer to consume the last one. Nothing is overwritten before it is read.

One Outstanding Announcement: Who Waits for Whom
01234time (ns)10122028monitortrigger(n1)overflow 2: wait_off-trigger(n2)-onconsumerbusyreads n1, reset()handles n1reads n2, reset()
Scroll horizontally ↔
  1. Cycle 0

    The monitor announces overflow 1. The event holds n1 and stays on.

  2. Cycle 1

    Overflow 2 happens while n1 is unread. The monitor holds it back with wait_off().

  3. Cycle 2

    The consumer is free, so it reads n1 and resets the event, and on falls.

  4. Cycle 3

    The monitor's wait_off() returns, and it announces n2 in the same step.

  5. Cycle 4

    The consumer finishes n1 and takes n2. Every note is read before anything replaces it.

A sketch of the handshake. The consumer's loop is yours to write in U17.1.1.

Reset and the Processes That Wait

reset(wakeup) turns the event off, puts the default data back, and sets the time and the waiter count to 0. It does this by giving the event a fresh inner SystemVerilog event. With wakeup = 1 it first triggers the old one.

The standard and Verilator 5.052 disagree about what happens to processes parked in wait_trigger. The example parks one before each reset and then triggers 5 ns later.

Call with a process parked in wait_triggerStandard behaviourVerilator 5.052, measured
reset(1) at 35 nsReleased at the reset (1800.2 §10.1.1.2.8)Not released; returns at the next trigger, 40 ns
reset(0) at 25 nsNever released: a process waiting on a replaced event does not unblock (IEEE 1800-2023 §15.5.5.1)Returns at the next trigger, 30 ns
EitherThe waiter count drops to 0The waiter count drops to 0

Both rows come from the example below. The count no longer knows about the parked process in either case.

Processes in wait_on and wait_off wait for the on flag instead. A reset turns on off, so it releases wait_off waiters. It never releases a wait_on waiter: that process waits because the event is already off.

The portable rule is simple. Do not reset an event while get_num_waiters() is above 0. To release waiting processes, trigger the event. Reset it afterwards, once the consumers have seen it. Code that follows this rule behaves the same on every simulator, so the table above never matters to it.

A new waiter starts in the trigger's time step, after the triggerStandard behaviourVerilator 5.052, measured
Processes that were already waitingReleased by the trigger (IEEE 1800-2023 §15.5.1)Miss it and wake at the next trigger, when the event is a class property, as inside uvm_event
The same with #0 before the new waitReleased by the triggerReleased by the trigger
A plain module-level event waited with @eReleased by the triggerReleased by the trigger

Separate probes on Verilator 5.052. The example starts each new waiter 2 ns after a trigger, so its output is the same on every simulator.

Cancel: The Count Is Bookkeeping

get_num_waiters() returns a counter. Each blocking wait adds one, every trigger and every reset sets it to 0, and cancel() takes one away. No call removes a process that has died. At 45 ns the example kills a waiting process, and the count still says 1 until cancel() brings it to 0.

The rule from the standard is short: call cancel() once for every waiting process you disable or kill (1800.2 §10.1.1.2.9). The barrier in U17.3 is built on exactly this count, and there a wrong count really hurts.

Waiting with a Deadline

Real waits have a limit, because a reply that never comes must not hang the whole test. So the wait races a delay, and whichever branch loses is stopped. When the delay wins, the process you stop is a waiter the event still counts, so cancel() it.

A deadline wait often starts right after a request, so a fast responder may trigger before the wait begins. wait_trigger_data misses such a trigger. wait_ptrigger_data is wait_ptrigger then get_trigger_data (1800.2 §10.1.2.2.3), so it takes a trigger from earlier in the same step. A trigger from an earlier step still does not count, even while on stays set.

Trigger camewait_trigger_datawait_ptrigger_datawait_on, then get_trigger_data
LaterReturns itReturns itReturns it
Earlier in this time stepWaits for the next oneReturns it at onceReturns it at once
In an earlier time step, never resetWaits for the next oneWaits for the next oneReturns the old data at once

uvm-core 2020.3.1, base/uvm_event.svh. Pick the column that matches which triggers belong to your wait.

get_trigger_time() tells you when the data now in the event was triggered. A late consumer that logs $time instead records when it noticed the announcement, not when it happened.

Event, Flag or FIFO

An event fits when one side announces and the other side either waits for the next announcement or checks a state. It fits badly when announcements can pile up, because it holds one data handle and one on flag.

You needUseWhy
Wake whoever waits now; late arrivals do not mattertrigger with wait_triggerA pulse: nothing is stored
A late consumer must still see it, oncetrigger with wait_on, then resetA level: the on flag holds it
Every announcement, in order, with its datauvm_tlm_fifo or an analysis FIFOA queue: nothing is overwritten
Several consumers each see each announcementOne FIFO per consumerA FIFO's get removes the entry for everyone

Pick by what must survive between the producer and the consumer.

No UVM book covers uvm_event beyond the event pool in a pipelined sequence. This lesson rests on the uvm-core source, IEEE 1800.2-2020 §10.1 and the runs shown.

Try It

Each show line prints the four pieces of state after the call it names. The other lines come from waiting processes as they return. The two parked waiters return at the trigger after their reset, 30 and 40 ns. A simulator that follows the standard prints the second one at 35 ns and never prints the first.

Try two edits. Change the #0 before wait_ptrigger to #1, and that process waits until the trigger at 20 ns. Move the last ovf.reset() to just after #3. The killed waiter then leaves the count at once, but so would any live waiter.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: 5 ns two processes parked on=0 data=null time=0 waiters=2 10 ns trigger(note1) on=1 data=note1 time=10 waiters=0 10 ns wait_trigger (since 0) returns 10 ns wait_trigger_data (since 0) returns note1 10 ns wait_ptrigger (called after the trigger) returns 15 ns wait_on (called at 15) returns at once 20 ns trigger(note2), trigger(note3) on=1 data=note3 time=20 waiters=0 20 ns wait_trigger_data (since 15) returns note3 25 ns one parked at 22 on=1 data=note3 time=20 waiters=1 25 ns reset(0) on=0 data=null time=0 waiters=0 30 ns trigger(note4) on=1 data=note4 time=30 waiters=0 30 ns waiter parked at 22 returns 35 ns reset(1) on=0 data=null time=0 waiters=0 40 ns trigger(note5) on=1 data=note5 time=40 waiters=0 40 ns waiter parked at 32 returns 45 ns waiter killed on=1 data=note5 time=40 waiters=1 45 ns cancel() on=1 data=note5 time=40 waiters=0 45 ns reset() on=0 data=null time=0 waiters=0

Check Yourself

Predict the outputTwo triggers come in one time step, and a late consumer reads and resets. What line does the $display print?
`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class note_c extends uvm_object;
  `uvm_object_utils(note_c)
  int x;
  function new(string name = "note_c"); super.new(name); endfunction
endclass
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 #(note_c) ev = new("ev");
    note_c a = new("a"), b = new("b"), got, late;
    a.x = 1;
    b.x = 2;
    phase.raise_objection(this);
    fork
      begin ev.wait_trigger_data(got); end
      begin #10; ev.trigger(a); ev.trigger(b); end
      begin #12; ev.wait_on(); late = ev.get_trigger_data(); ev.reset(); end
    join
    $display("got x=%0d, late x=%0d, on=%0d, data null=%0d", got.x, late.x, ev.is_on(), ev.get_trigger_data() == null);
    phase.drop_objection(this);
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule
ConceptA process waits in wait_on() while the event is off. Another process calls reset(1). What happens to the waiting process?
ConceptA sequence killed while it waited on an event leaves get_num_waiters() at 1. What does the standard say to do?
ConceptA monitor can announce several errors per clock, and the checker must see every one with its data. What should carry them?
ConceptWhy does the example's wait_ptrigger call, made after the trigger, still return?

Common Mistakes

Wrong Call reset() before reading the data.

reset puts the default data back, which is null unless you set one. The note is gone.

Fix Read the data, and the trigger time if you need it, before you reset.

Wrong Trust wait_trigger_data to keep the data of the trigger that woke you.

It is wait_trigger followed by get_trigger_data. A second trigger in the same time step replaces the data before the waiter runs.

Fix Keep one announcement outstanding: the producer waits for the event to be off. Use a FIFO when announcements can pile up.

Wrong Reset an event while processes wait on it in wait_trigger.

The standard and the simulator disagree about what happens to them. On Verilator 5.052 neither reset(0) nor reset(1) releases them.

Fix Reset only when get_num_waiters() is 0. To release waiters, trigger the event.

Wrong Kill a waiting process and keep trusting get_num_waiters().

The count is bookkeeping. A killed waiter stays in it.

Fix Call cancel() once for every waiting process you kill.

Remember

  • A uvm_event is four pieces of state: the on flag, one data handle, the trigger time and a waiter count.
  • wait_on asks whether it happened since the last reset. wait_trigger waits for the next one, and wait_ptrigger also accepts one earlier in the same time step.
  • The data is one handle: read it before reset, and never let two announcements be outstanding.
  • Do not reset an event while processes wait on it; what happens to them depends on the simulator.
  • The waiter count is bookkeeping: call cancel() for every waiting process you kill, including a wait that lost a race against a deadline.

Practice

Report a problem with this page