Mailboxes and backpressure

A channel that makes processes wait

A mailbox is a first-in, first-out channel between processes. put() adds a message at the back, and get() removes the oldest one. If the mailbox is empty, get() blocks until a message arrives, so the consumer needs no polling loop.

Declare it with the type it carries, as in mailbox #(packet) gen2drv = new(4);, and the compiler checks every put and get against that type. A mailbox is an object, so the variable holds no mailbox until new() creates one.

Backpressure from a bounded mailbox

new() or new(0) creates an unbounded mailbox, where put() never blocks. That is the opening story: the generator can create every transaction at time 0, however slowly the driver works.

An unbounded mailbox also hides a driver that stalls. If the driver stops taking items because of a DUT hang, the generator keeps going, and the backlog grows without any message in the log.

new(N) with N greater than 0 creates a bounded mailbox that holds at most N messages. When it is full, put() blocks until the consumer takes one. This holding back of a producer by a slower consumer is called backpressure.

With a bound, the generator runs at the driver's pace. When it reports done, at most N items are still waiting, so the end of the test only has to wait for a short, known drain. Choose N from the design: 1 makes the generator hand over one item at a time, and a larger N models a master with a request queue of that depth.

Nonblocking calls return a status

try_get() and try_put() never wait, so they need another way to say that nothing happened. Each returns a nonzero value on success and 0 on failure. A failed try_get(t) delivers no message, so t still holds an old value, which looks exactly like a real message.

void'(mb.try_get(t));
check(t);   // may check the old t again

if (mb.try_get(t))
  check(t);

Use the try_ forms when a process must not stall, for example a model that services several channels in one loop. Everywhere else, the blocking forms are simpler and harder to get wrong.

num() is a snapshot. Another process can put or get right after you read it, so do not use num() to decide whether a later get() will block. It is reliable at the end of the test, once every producer and consumer has stopped, for checking that nothing was left behind.

A mailbox carries handles

A mailbox of class objects stores handles, references to objects, not copies of the objects (Module 4 covers classes in depth). Suppose a generator creates one object, then changes its fields and puts it again for every transaction. All the messages then point at the same object, and the driver sees only the latest values.

Create a new object for every message with new(), and treat an object as the receiver's once you have put it. The producer must not change it afterwards.

Knowing when the stream has ended

A consumer that loops on get() forever never learns that the producer has finished. Give it a way to know. The simplest is a fixed count agreed with the producer, as in repeat (n) mb.get(t);. Another is a counter of items sent, which the end of the test can wait on with wait (n_taken == n_sent).

A special end message also works, such as a null handle in a mailbox of objects, provided it can never be confused with a real item. The consumer stops when it gets that message, and the producer sends it only after its last real item.

Then finish with a check that the mailbox is empty. A leftover message means an item was generated but never driven, which is exactly the bug in the opening story.

Try it

The first two puts return at once. From then on each put() returns only when a get() makes room, so the producer is held to the consumer's pace. Both processes only record times; the parent prints everything after join.

Change new(2) to new() and predict the put times before you run it. Then try new(1).

Check yourself

module tb;
  mailbox #(int) mb = new(1);
  int ok1, ok2, v;
  initial begin
    ok1 = mb.try_put(5);
    ok2 = mb.try_put(6);
    mb.get(v);
    $display("%0d %0d %0d %0d", ok1 > 0, ok2 > 0, v, mb.num());
  end
endmodule

if (mb.try_get(v)) begin
  n++;
  sum += v;
end

if (mb.num() > 0) begin
  mb.get(v);
  n++;
  sum += v;
end

if (mb.try_peek(v)) begin
  void'(mb.try_get(v));
  n++;
  sum += v;
end

void'(mb.try_get(v));
n++;
sum += v;

Practice

• Exact-count consumer Implement · Easy