Coordinating Sequences, Reset and the End of the Test

Put the synchronisation objects of this module together. A virtual sequence aligns lanes with a barrier and pauses them through a reset event. The test ends only when every lane has drained.

You Will Be Able To

  • Give each synchronisation object one owner and hand it to the sequences that use it.
  • Pause every lane through a reset and restart the rendezvous cleanly afterwards.
  • End a test when every lane has drained, not when the first one finishes.
  • Find a deadlock by drawing who waits on whom, and put a timeout on every rendezvous.
Lesson
U17.7
Time
35 min
Runs on
Verilator with UVM
Check
4 questions

Three agents must start each burst in the same clock, and the design is reset in the middle of the run. One virtual sequence owns a barrier and a reset event, and every lane sequence uses both. The test ends when the last lane has drained, not when the first one finishes.

Who Owns What in the ExampleThe virtual sequence creates the barrier and the reset event and hands both to each lane sequence. Arrows show who calls whom.
  • Test
  • Sequence
  • Control / FSM
  • Agent
  • Control
  • Reset
Who owns what in the exampleThe virtual sequence creates the barrier and the reset event and hands both to each lane sequence. Arrows show who calls whom. test coord_test raises the objection,drives reset sequence coord_vseq virtual sequence,owns bar and rst control barrier "burst" threshold 3 control event "rst" on while in reset agent lane0..lane2 one lane_seq peragent start, then waitstart, wait forkwait_for()is_on, wait_offtrigger, reset
  1. sequence coord_vseqvirtual sequence, owns bar and rst
    • start, wait fork → lane0..lane2
  2. agent lane0..lane2one lane_seq per agent
    • wait_for() → barrier "burst"
    • is_on, wait_off → event "rst"
  3. control barrier "burst"threshold 3
  4. test coord_testraises the objection, drives reset
    • start, then wait → coord_vseq
    • trigger, reset → event "rst"
  5. control event "rst"on while in reset
  1. Rounds15, 55 ns (illustrative)

    Every lane prepares, then waits at the barrier; the last arrival releases all three.

  2. Reset90 ns (illustrative)

    The test turns the reset event on and resets the barrier. The two lanes waiting there are released, see the reset, and wait for it to end.

  3. Restart130 ns (illustrative)

    The reset ends. All three lanes meet again, and round 3 starts at 135 ns.

  4. Drain155 ns (illustrative)

    The virtual sequence returns only after every lane's last beat, and the test drops its objection.

Read the diagram as text
  • coord_test: raises the objection, drives reset
  • coord_vseq: virtual sequence, owns bar and rst
  • barrier "burst": threshold 3
  • event "rst": on while in reset
  • lane0..lane2: one lane_seq per agent
  • coord_test → coord_vseq: start, then wait
  • coord_vseq → lane0..lane2: start, wait fork
  • lane0..lane2 → barrier "burst": wait_for()
  • lane0..lane2 → event "rst": is_on, wait_off
  • coord_test → event "rst": trigger, reset

Measured by the example below.

One Owner for Each Object

Every synchronisation object needs exactly one owner, the component or sequence that creates it, sizes it and decides when it changes. Everyone else only uses it. When nobody clearly owns an object, two places set a threshold or reset an event. The bench then fails in ways no single file explains.

ObjectOwner in the exampleUsersHow it reaches them
Barrier "burst"The virtual sequenceThe three lane sequencesA handle set before each lane starts
Event "rst"The virtual sequence creates it; the test drives itThe lane sequencesA handle, like the barrier
Run-phase objectionThe testNobody elseRaised around the virtual sequence

Pass handles down; a global pool name would let a second copy of the bench share them.

The owner also decides how each object changes during the run. The virtual sequence knows how many lanes it started, so it sizes the barrier. It also resets the barrier when the reset starts, and it knows when every lane has drained. Lanes never change any of this themselves.

Handing the objects down as handles, rather than looking them up by name, keeps two copies of the bench apart. U17.2 showed this for event pools.

Reset as a Level

A reset lasts for a while, so model it as a level. Use an event that is on while the design is in reset. A pulse at the start of the reset would only reach the processes already waiting for it. A lane checks rst.is_on() before it meets the others, and if it is on, waits with wait_off(). A lane that arrives during the reset waits for it to end.

The barrier needs care too. Lanes already waiting there when the reset starts are still counted, so the owner calls bar.reset(1) as the reset begins. That releases them, and each sees the reset on and goes back to wait for it to end. In the example two lanes are waiting at 90 ns, and both are released. After the reset at 130 ns all three meet again, and round 3 starts at 135 ns.

ToolWhat it does to running stimulusWhen to use it
A reset event, read by the lanesLanes pause at their next check and resume afterThe lanes know where it is safe to stop
stop_sequences() on each sequencerKills the running sequences and clears pending itemsStimulus must restart from scratch (U10.2)
A phase jumpLeaves the run-time phases and re-enters an earlier oneThe whole bench must re-run reset and configuration

A reset event is the gentlest of the three; it only works if every lane checks it.

The End of the Test Is a Rendezvous Too

The test must end when the last lane has drained, which is a synchronisation question like any other. The virtual sequence forks one lane sequence per agent and then waits for all of them, with wait fork or join. Only then does it return, and only then does the test drop its objection. In the example the last beat finishes at 145 ns, and the test ends at 155 ns.

Other ways work when the lanes live in components instead of one virtual sequence. Each lane can hold an objection while it has work, as in U17.5. Or the lanes can meet the test at a final "drained" barrier. What fails is returning after the first lane finishes, or forking with join_none and returning at once. Both end the run with bursts still on the bus, and both pass silently unless a check counts the beats.

Waiting for a Sequence to Finish

A coordinator often needs to know when one particular sequence is done, not just when all of them are. Every sequence has a state: CREATED, PRE_START, BODY, ENDED, FINISHED, STOPPED and a few more. get_sequence_state() reads it, and wait_for_sequence_state(UVM_FINISHED) blocks until the sequence reaches one of the states in the mask.

That gives three ways to wait for work, and they suit different shapes. start blocks the caller until the sequence returns, which is the simplest. A fork of several start calls with wait fork waits for a group. wait_for_sequence_state lets one process wait for a sequence that another process started. That helps when a reactive sequence must outlive the traffic it answers.

Pick the one that matches who started the work. The process that starts a sequence should normally be the one that waits for it. A second waiter means the coordination is spread over too many places.

Finding a Deadlock

A coordinated bench hangs when processes wait on each other in a circle, and the log usually shows nothing at all. Draw who waits on whom. Each lane waits on the barrier, the barrier waits on every lane, and a lane may wait for the reset to end. A circle in that graph is a deadlock. A lane that will never arrive leaves an open end, which hangs the rest just as surely.

Here is a typical circle. The coordinator waits for every lane to finish before it ends the reset. Each lane waits for the reset to end before it meets the others. Nobody can move, and nothing reports it. The fix is a reset driver that does not depend on the lanes, like the test in the example.

Two habits make hangs visible. Put a timeout and a cancel around every rendezvous, as in U17.3. A hang then becomes an error with a name and a time. And give each object one owner who knows how many parties are expected. That owner takes a lane that leaves out of the count.

Try It

Three lanes each run three rounds of three beats behind one barrier. The test resets the design from 90 to 130 ns. At that moment lanes 0 and 1 wait for round 3, and lane 2 is still preparing. The first beat of every round is printed by the drivers.

Delete the v.bar.reset(1); line, and lanes 0 and 1 stay counted through the reset. Round 3 still starts together, because nothing here makes the lanes prepare again. Problem U17.7.1 adds that rule.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: 15 ns lane 1 round 1: first beat 55 ns lane 0 round 2: first beat 90 ns reset: 2 lane(s) waiting at the barrier, released 130 ns reset ends 135 ns lane 1 round 3: first beat 135 ns lane 0 round 3: first beat 135 ns lane 2 round 3: first beat 155 ns every lane has drained: the test ends UVM_ERROR : 0

Check Yourself

Predict the outputLanes arrive at 5, 8 and 20 ns. Reset is on from 10 to 30 ns, and the barrier is reset when it starts. 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)
  uvm_barrier bar = new("start", 3);
  uvm_event #(uvm_object) rst = new("rst");
  int start_at[3];
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task lane(int i, int arrive);
    #(arrive);
    do begin
      if (rst.is_on()) rst.wait_off();
      bar.wait_for();
    end while (rst.is_on());
    start_at[i] = $time;
  endtask
  task run_phase(uvm_phase phase);
    int released;
    phase.raise_objection(this);
    fork
      lane(0, 5);
      lane(1, 8);
      lane(2, 20);
      begin #10 rst.trigger(); released = bar.get_num_waiters(); bar.reset(1); #20 rst.reset(); end
    join
    $display("released at reset %0d; lanes start at %0d, %0d, %0d", released, start_at[0], start_at[1], start_at[2]);
    phase.drop_objection(this);
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule
ConceptA virtual sequence forks three lane sequences with join_none and returns. The test drops its objection when the virtual sequence returns. What happens?
ConceptWhy is the reset an event that stays on, rather than one triggered once when the reset starts?
ConceptLane 2 of three is disabled by a test before round 3. The coordinator owns the barrier. What must it do?

Common Mistakes

Wrong Let lanes meet on an event that the first lane triggers.

A lane that starts waiting after the trigger misses it and hangs.

Fix Use a barrier sized to the number of lanes.

Before
if (lane == 0) go.trigger();
else go.wait_trigger();
After
bar.wait_for();   // threshold = number of lanes

Wrong Leave lanes waiting at the barrier when reset starts.

They stay counted, and after reset they start as soon as the late lanes arrive, without preparing again.

Fix On reset, call bar.reset(1) and let each lane check the reset event when it is released.

Wrong Fork the lanes with join_none and return.

The virtual sequence ends at once, the test drops its objection, and the run ends with bursts still on the bus.

Fix Wait for every lane (wait fork or join), then stop helper processes.

Remember

  • The virtual sequence owns the barrier and the reset event, and hands them to the lane sequences.
  • A barrier aligns lanes; an event announces; a level such as reset is read with is_on, wait_on and wait_off.
  • At reset, release the barrier with reset(1) and let each lane wait out the reset before it meets again.
  • The test ends when every lane has drained: wait for all lane sequences, then stop helper processes.
  • Draw who waits on whom; every rendezvous gets a timeout and a cancel.

Practice

Report a problem with this page