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_eventkeeps 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,
resetandcanceldo 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.
- Cycle 0
Two processes wait from time 0. The event is off, has no data and counts two waiters.
- Cycle 1
trigger(note1)turns the event on, stores the note and the time, and releases both waiters. The count goes back to 0. - Cycle 2
Two triggers in one time step. The event keeps one data handle, so the waiter reads note3. Nobody ever sees note2.
- 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. - Cycle 5
The standard says
reset(1)releases the parked process at once. On this simulator it waits for the trigger at 40 ns. - 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.
| Call | on | data | trigger time | waiter count |
|---|---|---|---|---|
trigger(d) | set to 1 | set to d | set to now | set to 0 |
reset(wakeup) | set to 0 | set to the default data | set to 0 | set to 0 |
cancel() | unchanged | unchanged | unchanged | minus 1 |
| a wait that blocks | unchanged | unchanged | unchanged | plus 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".
| Question | Call | Measured 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 that | wait_trigger() | Waiting since 0 ns: returns at 10 |
| The next one, but forgive a trigger earlier in this time step | wait_ptrigger() | Called at 10 ns, after the trigger: returns at once |
| Wait, then take the data | wait_trigger_data(d) | Waiting since 0 ns: returns note1 at 10 |
| Wait until somebody consumes it | wait_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.
- Cycle 0
The monitor announces overflow 1. The event holds n1 and stays on.
- Cycle 1
Overflow 2 happens while n1 is unread. The monitor holds it back with
wait_off(). - Cycle 2
The consumer is free, so it reads n1 and resets the event, and
onfalls. - Cycle 3
The monitor's
wait_off()returns, and it announces n2 in the same step. - 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_trigger | Standard behaviour | Verilator 5.052, measured |
|---|---|---|
reset(1) at 35 ns | Released at the reset (1800.2 §10.1.1.2.8) | Not released; returns at the next trigger, 40 ns |
reset(0) at 25 ns | Never 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 |
| Either | The waiter count drops to 0 | The 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 trigger | Standard behaviour | Verilator 5.052, measured |
|---|---|---|
| Processes that were already waiting | Released 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 wait | Released by the trigger | Released by the trigger |
A plain module-level event waited with @e | Released by the trigger | Released 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 came | wait_trigger_data | wait_ptrigger_data | wait_on, then get_trigger_data |
|---|---|---|---|
| Later | Returns it | Returns it | Returns it |
| Earlier in this time step | Waits for the next one | Returns it at once | Returns it at once |
| In an earlier time step, never reset | Waits for the next one | Waits for the next one | Returns 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 need | Use | Why |
|---|---|---|
| Wake whoever waits now; late arrivals do not matter | trigger with wait_trigger | A pulse: nothing is stored |
| A late consumer must still see it, once | trigger with wait_on, then reset | A level: the on flag holds it |
| Every announcement, in order, with its data | uvm_tlm_fifo or an analysis FIFO | A queue: nothing is overwritten |
| Several consumers each see each announcement | One FIFO per consumer | A 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.
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=0Check Yourself
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_eventis four pieces of state: theonflag, one data handle, the trigger time and a waiter count. wait_onasks whether it happened since the last reset.wait_triggerwaits for the next one, andwait_ptriggeralso 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.