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 joinand predict which orders are possible. - Choose between
breakandreturnto 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.
- Cycle 0
The random test picks every operation alone. Its addresses are unrelated, so no three writes form a burst.
- Cycle 2
The lab traffic puts read R0 between writes W1 and W2 of one burst. Only the third row has this slot.
- 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 stimulus | Scenario | |
|---|---|---|
| Unit | one transaction | an ordered sequence of transactions |
| Built with | randomize() on one object | randsequence, or an array of objects |
| Finds | bad single values and corners | bugs that need a pattern over time |
| Misses | patterns longer than one transaction | values 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.
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- Cycle 0
The join picks the writes lane first, and the next item of that lane is W0.
- Cycle 1
Now it picks the reads lane twice, so R0 and R1 run in the order their production lists them.
- Cycle 3
The join switches back to the writes lane, which continues with W1, the item after W0.
- 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.
| Seed | Bus order |
|---|---|
| 13 | W0 W1 R0 R1 R2 W2 |
| 14 | R0 R1 R2 W0 W1 W2 |
| 15 | W0 R0 R1 W1 W2 R2 |
| 16 | R0 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.
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"}; };
endsequencestop = 0: H B C T
Nothing stops early, so every production runs from left to right and the log shows all four steps.
stop = 1: H T
returnendsbodybefore its first step. The rest ofbody, includingcrc, is skipped.pktcontinues withtail.stop = 2: H B
breakinsidecrcleaves the whole block.tailnever runs, and the code afterendsequenceruns 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.
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 = 11Arguments 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.
randsequence (frame)
frame : size size { total = size[1] + size[2]; };
int size : { return 8; };
endsequence
// Standard behaviour: total = 16Try 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.
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 R2Check Yourself
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.
bus : rand join w0 w1 w2 reads;
// W2 may come before W0bus : rand join writes reads;
writes : w0 w1 w2; // always in this orderWrong 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.
body : { if (!has_body) break; } data crc;
// the tail never runsbody : { if (!has_body) return; } data crc;
// the tail still runsWrong 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 joininterleaves productions at random and keeps the order inside each one.- The join works one level deep: a nested production or a
repeatis one item and stays together. breakleaves the wholerandsequence;returnleaves one production and the caller carries on.- Arguments pass values down to a production; seed the process to replay a scenario.