randsequence: rand join, Early Exits and Arguments

Generate whole bus scenarios instead of single operations. Interleave two bursts with rand join, cut a scenario short with break or return, and pass values to productions.

You Will Be Able To

  • Interleave two ordered bursts with rand join and predict which orders are possible.
  • Choose between break and return to stop a scenario or one production.
  • Pass values into productions with arguments.
  • Explain when a scenario finds a bug that single random operations miss.
Lesson
10.10
Time
30 min
Runs on
Verilator
Check
5 questions

A memory controller passed 10,000 random operations and a directed burst test, yet in the lab it returned stale data. The failing pattern was a read that arrived in the middle of a three-write burst. The random test never built a burst, and the directed test never mixed two bursts.

Three Tests on One Bus
012345single random opsW7R2R5W1R7W4directed burstsW0W1W2R0R1R2the lab patternW0W1R0W2R1R2read inside the burst
Scroll horizontally ↔
  1. Cycle 0

    The random test picks every operation alone. Its addresses are unrelated, so no three writes form a burst.

  2. Cycle 2

    The lab traffic puts read R0 between writes W1 and W2 of one burst. Only the third row has this slot.

  3. Cycle 3

    The directed test sends the whole write burst first. Its reads start only here, after the burst has ended.

Six bus slots of each test. W0 to W2 are one write burst, R0 to R2 one read burst.

One Operation at a Time, or a Whole Scenario

Atomic stimulus randomizes one transaction at a time, and each call knows nothing about the calls before it. A scenario is a whole sequence built together, such as a burst, a retry, or two bursts sharing a bus.

Atomic stimulusScenario
Unitone transactionan ordered sequence of transactions
Built withrandomize() on one objectrandsequence, or an array of objects
Findsbad single values and cornersbugs that need a pattern over time
Missespatterns longer than one transactionvalues its productions never produce

Real tests use both: a scenario decides the order, and atomic randomization fills in each transaction.

A randsequence block describes a scenario as a small grammar in which each named rule is a production. A production lists other productions and code blocks in braces, and they run from left to right.

This lesson adds four tools to that grammar: rand join, break, return and arguments. Together they turn a fixed list of steps into traffic that mixes, stops early and takes parameters.

rand join Keeps Each Burst in Order

rand join takes two or more productions and interleaves them at random, while the order inside each production stays fixed. Only the way the productions mix changes from run to run.

Two bursts share the bus. Each burst is one joined production.
randsequence (bus)
  bus    : rand join writes reads;
  writes : wr(0) wr(1) wr(2);     // W0 W1 W2, always in this order
  reads  : rd(0) rd(1) rd(2);     // R0 R1 R2, always in this order
  ...
endsequence
Two Lanes, One Bus OrderOne measured run of the example (seed 15). Each burst has its own lane; the last row is the order on the bus.
012345writes laneW0waitW1W2waitreads lanewaitR0R1waitR2bus orderW0R0R1W1W2R2
Scroll horizontally ↔
  1. Cycle 0

    The join picks the writes lane first, and the next item of that lane is W0.

  2. Cycle 1

    Now it picks the reads lane twice, so R0 and R1 run in the order their production lists them.

  3. Cycle 3

    The join switches back to the writes lane, which continues with W1, the item after W0.

  4. Cycle 5

    The reads lane finishes with R2. Each lane ran left to right; only the switching was random.

Verilator 5.052, seed 15. Another seed switches lanes at other slots, but never reorders a lane.

SeedBus order
13W0 W1 R0 R1 R2 W2
14R0 R1 R2 W0 W1 W2
15W0 R0 R1 W1 W2 R2
16R0 R1 W0 R2 W1 W2

Four measured runs of the example on Verilator 5.052. W0, W1, W2 and R0, R1, R2 keep their order in every row.

The join works one level deep, which means it interleaves only the items written in the joined rule. If an item is itself a production with several steps, those steps stay together. A repeat (3) w is one item too, so its three beats never split.

Each run draws from the random generator of the current process, so two runs normally build different orders. Call process::self().srandom(seed) before the block when you need to replay one order.

Ending a Scenario or One Production

A code block can stop early in two ways, and they differ in how much they stop. break leaves the whole randsequence block, while return leaves only the production it is in. After a return, the scenario carries on with the next item of the calling production.

A packet scenario: header, body with a checksum, tail.
randsequence (pkt)
  pkt  : hdr body tail;
  hdr  : { log = {log, "H"}; };
  body : { if (stop == 1) return; log = {log, "B"}; } crc;
  crc  : { if (stop == 2) break;  log = {log, "C"}; };
  tail : { log = {log, "T"}; };
endsequence
  1. stop = 0: H B C T

    Nothing stops early, so every production runs from left to right and the log shows all four steps.

  2. stop = 1: H T

    return ends body before its first step. The rest of body, including crc, is skipped. pkt continues with tail.

  3. stop = 2: H B

    break inside crc leaves the whole block. tail never runs, and the code after endsequence runs next.

Use break when the scenario is no longer valid, for example when a FIFO fills up halfway through. Use return to drop one optional part and keep the rest. Inside a for or while loop in a code block, break ends only that loop, as in any procedural code.

Arguments Pass Values Down

A production can take arguments, which are declared like task arguments and may have default values. The caller passes values in parentheses, and every rule and code block of the production can read them.

One burst production serves both bursts. Measured on Verilator 5.052: beats=5 total=11.
randsequence (main)
  main : burst(2, 4) burst(3, 1);
  burst(int n, int step) : repeat (n) beat(step);
  beat(int step) : { beats++; total += step; };
endsequence
// beats = 5, total = 2*4 + 3*1 = 11

Arguments remove copies: one wr(int i) production replaces w0, w1 and w2, and the caller decides which write it is.

The standard also lets a production hand a value back to its caller. Declare a type before the production's name and use return with a value. The caller reads the value by the production's name, or by name[1] and name[2] if the production ran twice.

Standard behaviour (IEEE 1800-2023 18.17.7), derived by hand. Verilator 5.052 does not run it.
randsequence (frame)
  frame    : size size { total = size[1] + size[2]; };
  int size : { return 8; };
endsequence
// Standard behaviour: total = 16

Try It

Four seeds give four mixes, and each keeps W0 W1 W2 and R0 R1 R2 in order. The last two lines replay seed 15. With a budget of 4, break ends the scenario after four operations. With skip_r1, return drops only R1, and the other five still run.

These orders are measurements on Verilator 5.052. Another simulator may print other orders for the same seeds, but never W1 before W0.

Change writes to wr(0) wr(1) wr(2) wr(3) and predict how long the first four lines become. Then swap break and return in rd and predict the last two lines.

RUNVerilator · simulator service
Edit the code, then run it
Expected: seed 13 : W0 W1 R0 R1 R2 W2 seed 14 : R0 R1 R2 W0 W1 W2 seed 15 : W0 R0 R1 W1 W2 R2 seed 16 : R0 R1 W0 R2 W1 W2 budget 4: W0 R0 R1 W1 skip R1 : W0 R0 W1 W2 R2

Check Yourself

Predict the outputPredict the exact output.
module tb;
  int beats, total;
  initial begin
    randsequence (main)
      main : burst(2, 4) burst(3, 1);
      burst(int n, int step) : repeat (n) beat(step);
      beat(int step) : { beats++; total += step; };
    endsequence
    $display("beats=%0d total=%0d", beats, total);
  end
endmodule
Spot the bugEach option is the top rule of a bus scenario. The checker needs W0 W1 W2 in order and R0 R1 R2 in order, in all 200 scenarios. Which rule breaks it?
ConceptA bug needs a read between the second and third write of one burst. Which stimulus reaches it most directly?
ConceptA code block contains for (int i = 0; i < 8; i++) begin if (i == 3) break; send(i); end. What does this break end?
ConceptA nightly run fails in scenario 812. What makes that exact scenario appear again in a rerun?

Common Mistakes

Wrong Join single operations, as in rand join w0 w1 w2 reads.

Each joined production is its own sequence, so the three writes can swap places.

Fix Put the ordered steps in one production, then join the productions.

Before
bus : rand join w0 w1 w2 reads;
// W2 may come before W0
After
bus    : rand join writes reads;
writes : w0 w1 w2;   // always in this order

Wrong Expect repeat (3) w inside a joined production to interleave beat by beat.

The join interleaves the items written in the joined rule, and a repeat is one item.

Fix Write the steps as separate items: writes : w w w;.

Wrong Use break to skip one optional step of a scenario.

break leaves the whole randsequence, so every later production is lost as well.

Fix Use return: it ends the current production and the scenario carries on.

Before
body : { if (!has_body) break; } data crc;
// the tail never runs
After
body : { if (!has_body) return; } data crc;
// the tail still runs

Wrong Report a failing scenario without the seed that built it.

The block draws from the random generator of its process, so another run builds another order.

Fix Seed the process before the block and log the seed with the failure.

Remember

  • Atomic stimulus randomizes one transaction; a scenario builds an ordered sequence that can reach bugs over time.
  • rand join interleaves productions at random and keeps the order inside each one.
  • The join works one level deep: a nested production or a repeat is one item and stays together.
  • break leaves the whole randsequence; return leaves one production and the caller carries on.
  • Arguments pass values down to a production; seed the process to replay a scenario.

Practice

Report a problem with this page