Barriers: A Rendezvous That Survives Change

A barrier holds every party until the last one arrives. Learn how it counts and what a new threshold does to the parties already waiting. Then keep it right when one of them leaves for good.

You Will Be Able To

  • Predict when wait_for releases, with auto-reset on and off.
  • Predict what set_threshold, reset and cancel do to processes already waiting.
  • Remove a lane from a running rendezvous without an early release or a hang.
  • Use named barriers and a timeout without leaving the count wrong.
Lesson
U17.3
Time
35 min
Runs on
Verilator with UVM
Check
4 questions

Four lanes must start each burst in the same clock, so they meet at a barrier with a threshold of 4. A test stops lane C halfway through. One fix lowers the threshold to 3, and lanes A, B and D drift a round apart without a single error. Doing nothing instead hangs the test in round 3.

Burst Start Times (Ns) per Round When Lane C Is Killed at 24 Ns
012round123all four lanesall at 9all at 25all at 41nothing doneall at 9A B D at 25hangsthreshold loweredall at 9B D at 24, A at 40B D at 40, A hangscancel, then lowerall at 9A B D at 25A B D at 41C dies while it waits
Scroll horizontally ↔
  1. Cycle 0

    Round 1: the last lane, D, arrives at 9 ns and all four start together.

  2. Cycle 1

    C arrives first in round 2 and is killed at 24 ns while it waits. The barrier still counts it.

  3. Cycle 2

    Only cancel and then a lower threshold keep A, B and D together. The other two responses hang or split the lanes.

Measured by the example below. "Hangs" means the scenario gave up 100 ns after the kill.

How wait_for Counts

A uvm_barrier keeps a threshold, a count of waiting processes, an auto-reset flag and one internal uvm_event. wait_for() adds one to the count. If the count is still below the threshold, the caller waits on the internal event. The arrival that reaches the threshold triggers that event, sets the count back to 0 and returns.

Every waiter is released in the same time step. The last arrival waits one #0 before it returns, so that the others resume first. That is why the last lane's line is never printed first in the example.

One Round of Four Lanes at a Barrier with Threshold 4Arrows point from each lane to the barrier. wait_for() travels along them; the release comes back.
  • Step
  • Control / FSM
  • Control
CallValueReturnWaiting
One round of four lanes at a barrier with threshold 4Arrows point from each lane to the barrier. `wait_for()` travels along them; the release comes back. step Lane A arrives at 4 ns step Lane B arrives at 7 ns step Lane C arrives at 5 ns step Lane D arrives at 9 ns control burst barrier threshold 4, a count,an event wait_for()wait_for()wait_for()wait_for()
  1. step Lane Aarrives at 4 ns
    • wait_for() → burst barrier
  2. step Lane Barrives at 7 ns
    • wait_for() → burst barrier
  3. step Lane Carrives at 5 ns
    • wait_for() → burst barrier
  4. control burst barrierthreshold 4, a count, an event
  5. step Lane Darrives at 9 ns
    • wait_for() → burst barrier
  1. Three arrive4-7 ns (illustrative)

    A, C and B arrive. The count goes 1, 2, 3, and each waits on the internal event.

    Follow the calls, values and waits
    1. call count 1: Lane A → burst barrier
    2. call count 2: Lane C → burst barrier
    3. call count 3: Lane B → burst barrier
    4. Waiting: Lane A — waiting
    5. Waiting: Lane B — waiting
    6. Waiting: Lane C — waiting
  2. The fourth arrives9 ns (illustrative)

    D makes the count 4. It triggers the event and sets the count to 0.

    Follow the calls, values and waits
    1. call count 4: trigger: Lane D → burst barrier
  3. All four start9 ns (illustrative)

    A, B and C resume. D waits one #0, then returns too. With auto-reset on, the next arrival starts round 2.

    Follow the calls, values and waits
    1. return release: burst barrier → Lane A
    2. return release: burst barrier → Lane B
    3. return release: burst barrier → Lane C
    4. return return: burst barrier → Lane D
    5. Released: Lane A
    6. Released: Lane B
    7. Released: Lane C
Read the diagram as text
  • Lane A: arrives at 4 ns
  • Lane B: arrives at 7 ns
  • Lane C: arrives at 5 ns
  • Lane D: arrives at 9 ns
  • burst barrier: threshold 4, a count, an event
  • Lane A → burst barrier: wait_for()
  • Lane B → burst barrier: wait_for()
  • Lane C → burst barrier: wait_for()
  • Lane D → burst barrier: wait_for()

The count lives in the barrier, not in the lanes. Anything that changes who will arrive must change the count or the threshold too.

With auto-reset on, the default, the barrier is ready for the next round at once. set_auto_reset(0) makes it a one-shot gate. After the first release it stays open, and every later wait_for returns at once until reset.

Changing the Threshold While Lanes Wait

set_threshold(n) takes effect at once. Raising it while lanes wait makes them wait for more arrivals. Lowering it to the count or below calls reset(1), which triggers the internal event and releases every waiter.

In uvm-core 2020.3.1 the release happens when the new threshold is equal to the count or below it. The standard covers both cases (1800.2 §10.3.2.6). Once the threshold is reached every waiter is released, and a threshold below the count also resets the barrier. The predict question below measures the case where the two are equal. So lowering a threshold is a release, not a setting, and is safe only when you know who is waiting.

A Lane That Leaves

Lanes leave for real reasons. A test disables one, a lane hits an error and stops, or a reset kills its thread. The barrier knows none of this. If the lane was waiting, it is still in the count. If it was not, it will simply never arrive. Either way the threshold is now one too high.

The example kills lane C at 24 ns, while C waits in round 2, and compares three responses.

What the test doesRound 2Round 3Why
NothingA, B and D at 25 nsHangs with 3 waitingDead C still counts in round 2, so the 3 live lanes make 4. In round 3 they can never make 4.
set_threshold(3)B and D at 24 ns, A at 40 nsB and D at 40 ns, then A hangsB, C and D already make 3, so lowering releases them at once. A becomes the first arrival of a new round.
cancel(), then set_threshold(3)A, B and D at 25 nsA, B and D at 41 nsThe count drops to 2, so A's arrival makes 3.

Measured by the example. Neither of the first two responses reports an error: one hangs and one quietly splits the lanes.

cancel() takes one waiter out of the count. It is only bookkeeping: it wakes nobody, and it cannot tell which process left. So the rule has two parts. If the leaving lane was inside wait_for, cancel once. In every case, lower the threshold by one. Cancelling for a lane that was not waiting is just as wrong, because it removes a live waiter.

Reset and the One-Shot Gate

reset(wakeup) sets the count to 0 and leaves the threshold alone. With wakeup = 1, the barrier's default, it triggers the internal event, so every waiter is released. Use it when a round is abandoned, for example at a design reset.

With wakeup = 0, it resets the internal event instead. That is the event reset from U17.1, with the same problem: what happens to the waiters depends on the simulator. They are no longer counted, though, so the barrier has lost track of them. Never use reset(0) on a barrier with waiters.

CallCountThresholdWaiting processes
set_threshold(n), n above the countunchangednkeep waiting
set_threshold(n), n at or below the count0nreleased
reset(1)0unchangedreleased
reset(0)0unchangedno longer counted; release depends on the simulator
cancel()minus 1unchangedunchanged
set_auto_reset(0)unchangedunchangedlater callers pass once it has released

uvm-core 2020.3.1, base/uvm_barrier.svh.

Who Owns the Threshold

A barrier works only if its threshold always equals the number of parties that will still arrive. That number changes whenever a lane is added, disabled or killed. So give the threshold one owner: usually the virtual sequence or the environment that starts and stops the lanes. Lanes themselves never touch it.

The owner also decides what a lane that leaves means for the others. Sometimes the round should go on without it, as in the example. Sometimes the whole round is now invalid, and reset(1) is the honest answer: release everyone, then let each lane decide what to do. Write that decision down next to the barrier, because the barrier itself will never report it.

Barriers are also the wrong tool in some places. When one party announces and the others listen, use an event. When the end of the test must wait for every lane to drain, an objection per lane is simpler. A barrier is for the case where everyone must arrive before anyone continues.

Named Barriers and Timeouts

uvm_barrier_pool::get_global("burst") returns the barrier with that name and creates it on first use, like the event pool in U17.2. A new barrier has threshold 0, and a threshold of 0 lets every caller through at once. So one component must own each named barrier. It sets the threshold in a build or connect phase, before any lane can call wait_for.

A rendezvous that can hang needs a timeout. Wrap wait_for in a fork with a timer. If the timer wins, disable the waiting branch and call cancel(), because that waiter is gone. Then report an error, so that a hang becomes a message with a name and a time.

A rendezvous that cannot hang silently
task automatic meet(uvm_barrier bar, time limit, string who);
  bit arrived = 0;
  fork begin
    fork
      begin bar.wait_for(); arrived = 1; end
      #(limit);
    join_any
    disable fork;
  end join
  if (!arrived) begin
    bar.cancel();                          // our wait_for was cut off
    `uvm_error("RENDEZVOUS", $sformatf("%s waited %0t at %s", who, limit, bar.get_name()))
  end
endtask

UVM books say little about barriers; the Cookbook only names them as a tool for advanced synchronisation. Everything here comes from the uvm-core source and the standard, checked by the runs.

Try It

Four scenarios, each on a new barrier. In the last three, lane C is killed at 24 ns while it waits in round 2. The test then does nothing, lowers the threshold, or cancels and then lowers it. A scenario gives up 100 ns after the kill. Lines within one time step can come in any order.

Try two edits. Change the third scenario's response to "cancel", and its rounds line up. Then move the kill to 18 ns, while C is still bursting, and decide which response is right. C has not arrived, so there is nothing to cancel.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: --- all four lanes 9 ns round 1 D starts its burst 41 ns round 3 D starts its burst --- C killed, nothing done 24 ns C killed, barrier holds 3 waiter(s) 24 ns fix 'none': threshold 4, waiters 3 25 ns round 2 A starts its burst 124 ns gave up: 3 lane(s) still waiting --- C killed, threshold lowered 24 ns C killed, barrier holds 3 waiter(s) 24 ns fix 'lower': threshold 3, waiters 0 24 ns round 2 B starts its burst 24 ns round 2 D starts its burst 40 ns round 2 A starts its burst 40 ns round 3 B starts its burst 40 ns round 3 D starts its burst 124 ns gave up: 1 lane(s) still waiting --- C killed, cancel then lower 24 ns fix 'cancel': threshold 3, waiters 2 25 ns round 2 A starts its burst 41 ns round 3 D starts its burst

Check Yourself

Predict the outputThe barrier comes from the global pool. 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_barrier go = uvm_barrier_pool::get_global("go");
    int a, b, c;
    phase.raise_objection(this);
    fork
      begin #5;  go.wait_for(); a = $time; end
      begin #6;  go.set_threshold(3); end
      begin #10; go.wait_for(); b = $time; end
      begin #12; go.wait_for(); c = $time; end
      begin #15; go.set_threshold(2); end
    join
    $display("A %0d, B %0d, C %0d", a, b, c);
    phase.drop_objection(this);
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule
ConceptA test stops lane B while B is still working, before it reaches the barrier. Three other lanes still meet there. What must the test do?
ConceptA barrier with threshold 2 has set_auto_reset(0). Lanes arrive at 5, 8, 20 and 30 ns. When does each return?
ConceptWhy does the timeout wrapper call cancel() after disable fork?

Common Mistakes

Wrong Kill a waiting lane and only lower the threshold.

The dead lane is still counted. With the lower threshold the barrier releases one arrival early.

Fix Take the dead waiter out of the count before you lower the threshold.

Wrong Call cancel() for a lane that was not waiting.

It removes a live waiter from the count, so the round releases one arrival early.

Fix Cancel only when the lane was inside wait_for. Always lower the threshold.

Wrong Use a barrier from uvm_barrier_pool before anyone sets its threshold.

The pool creates the barrier with threshold 0, so every wait_for returns at once.

Fix Let one owner set the threshold before any party can arrive.

Remember

  • A barrier counts arrivals and releases them all when the count reaches the threshold. Auto-reset re-arms it; set_auto_reset(0) latches it open.
  • Lowering the threshold to the count or below is a release, not just a setting.
  • When a lane leaves for good, cancel only if it was waiting, and always lower the threshold.
  • A pool barrier starts at threshold 0, so one owner sets it before any lane arrives.
  • Put a timeout and a cancel around every rendezvous that can hang.

Practice

Report a problem with this page