finish_item()

Sequences · Module 9 · Page 9.4

The Engineering Problem

The previous chapter covered start_item — winning the grant and opening the randomization window (Module 9.3). This chapter is the call that closes that window and completes the handshake: finish_item. Where start_item blocks on the grant, finish_item blocks on the driver — it delivers the finalized item and then waits until the driver has driven it. Misunderstand that and you either mutate an item the driver has already taken (so your change never reaches the pins), or you stare at a sequence frozen at finish_item because the driver never signalled completion.

finish_item(item) is the second half of the two-phase handshake. It does three things in order: it closes the randomization window (the item is now final), it delivers the item to the driver (satisfying the driver's get_next_item), and it blocks until the driver calls item_done. So what finish_item waits on is the driver's completion — the time-consuming driving from Module 8.3 — which makes finish_item the point where the sequence is paced by the driver (back-pressure). It's also the point of no return: once finish_item has handed the item over, the item belongs to the driver, and changing it afterward can't affect what's driven. This chapter is finish_item: what it sends, what it blocks on, why it's the point of no return, and why a finish_item that never returns means the driver never said item_done.

What does finish_item do — how does it close the window, deliver the item to the driver, and block until item_done — why is it the point of no return and the back-pressure point, and why does a hung finish_item mean the driver never completed the item?

Motivation — why "finish" is a separate, blocking call

finish_item is a distinct, blocking call (rather than a fire-and-forget send) because delivering the item and waiting for it to be driven are both essential, and in that order:

• The item must be delivered after it's finalized, so "finish" closes the window. start_item opened the window to randomize (Module 9.3); something has to close it and mark the item final. finish_item is that boundary — after it, the item is the driver's, so it must come after the randomization.
• The sequence must wait for the driver, so "finish" blocks. A sequence that fired items without waiting would race ahead of a driver that hasn't consumed them. Blocking until item_done means the sequence advances in lockstep with the driver — one item fully driven before the next is prepared (Module 8.3).
• Blocking on item_done is the back-pressure mechanism. Because the driver calls item_done only when it (and the DUT behind it) has finished, finish_item's wait is governed by the design's pace. This is how stimulus is automatically paced to the DUT, with no manual flow control (Module 8.3).
• It's the point of no return, which keeps the model coherent. Once the item is delivered, the driver reads its values; allowing later changes to matter would make "what was driven" ambiguous. Making finish_item a hard handoff means the item driven is exactly the item as it was at finish_item.
• It's the response rendezvous point. If the driver returns a response with item_done(rsp), it becomes available after finish_item (retrieved via get_response, Module 8.2) — so finish_item completing is also when a request's answer has been produced.

The motivation, in one line: finish_item must deliver the finalized item and then wait for the driver to drive it, so it's a separate blocking call — closing the window, handing the item over (a point of no return), and suspending the sequence until item_done, which is exactly what paces the sequence to the driver.

Mental Model

Hold finish_item as submitting the form and waiting at the counter until it's processed:

finish_item is handing your completed form to the clerk and waiting until they've fully processed it before you do anything else — and once it's in their hands, you can't change it. In the previous step you filled in the form on your turn (start_item + randomize). finish_item is submitting it: you slide it across the counter (deliver the item to the driver), and now it's theirs — you can't reach over and edit it, and any scribble you make on your copy afterward changes nothing about what they process (the point of no return). Then you wait at the counter (finish_item blocks) until the clerk has finished processing it and stamps it done (item_done) — and only then do you step away to handle your next item. The waiting matters: you can't fire off ten forms and walk away; the clerk processes one at a time at their pace, so a slow clerk slows you down (back-pressure). And if the clerk takes your form but never stamps it done — gets distracted, drops the step — you wait at the counter forever (finish_item hangs because item_done never comes).

So finish_item is submit-and-wait-until-done: hand over the finalized item, accept that it's now the driver's, and stay blocked until the driver stamps it complete. The wait is the pacing; the handoff is the point of no return.

Visual Explanation — closing the window, sending, waiting

The defining picture is finish_item's three ordered actions: close the window, deliver to the driver, block until item_done — the mirror of start_item's "open."

The figure shows finish_item as the closing mirror of start_item's opening. Step 1, it closes the randomization window: whatever the item was set to in the window (Module 9.3) is now final — finish_item is the boundary past which the item can't be meaningfully changed. Step 2, it delivers the item to the driver, satisfying the driver's pending get_next_item — and this is the point of no return, because the item now belongs to the driver, which will read its values to drive the pins. Step 3, finish_item blocks: the sequence is suspended while the driver drives the item over clock cycles (the time-consuming "how", Module 8.1), and the length of this block is the driver's driving time — which makes it the back-pressure point where the driver (and the DUT behind it) paces the sequence. Step 4, when the driver calls item_done, finish_item unblocks and returns to the sequence, which can now prepare its next item (and retrieve any response, Module 8.2). The shape to carry is the symmetry with start_item: start_item opens (request grant → window), finish_item closes (deliver → wait for done) — together they bracket the item, with the randomization safely in between and the driver's work in the finish_item block.

RTL / Simulation Perspective — finish_item in code

finish_item is one call that pairs with start_item, and the surrounding callbacks (mid_do, post_do) mark the send and completion points.

task my_seq::body();
  bus_item req = bus_item::type_id::create("req");
  start_item(req);                    // ① grant + open window (Module 9.3)
  assert(req.randomize());            // ② finalize the item in the window
 
  finish_item(req);                   // ③ CLOSE window, DELIVER to driver, BLOCK until item_done
                                      //    (mid_do called before send; post_do after item_done)
  // ── finish_item has returned → the driver has driven the item ──
  get_response(rsp);                  // optional: retrieve the response (Module 8.2)
endtask
 
// ── DRIVER side: get_next_item is satisfied by finish_item; item_done unblocks it ──
task my_driver::run_phase(uvm_phase phase);
  forever begin
    seq_item_port.get_next_item(req); // receives the item finish_item delivered
    drive_on_pins(req);               // CONSUMES TIME — this is finish_item's block (Module 8.3)
    seq_item_port.item_done();        // ← signals completion → unblocks the sequence's finish_item
  end
endtask

The idiom is the closing half of the pair. After start_item and the randomization (Module 9.3), finish_item(req) does the three actions in one call: it closes the window (the item is now final), delivers the item to the driver (satisfying the driver's seq_item_port.get_next_item), and blocks until the driver calls item_done. The line after finish_item does not execute until the driver is done — so finish_item's return is the signal that the item has been driven. On the driver side, get_next_item(req) receives exactly the item finish_item delivered, drive_on_pins(req) is the time-consuming work that constitutes finish_item's block (Module 8.3), and item_done() is what unblocks the sequence's finish_item. The two sides interlock precisely: finish_item↔get_next_item for the handoff, item_done↔finish_item-return for the completion. Around finish_item, UVM calls the mid_do callback (after finalize, before the send) and post_do (after item_done) — hooks for per-item logic at the send and completion points. And if the driver returns a response (item_done(rsp)), it's available after finish_item via get_response (Module 8.2). The shape: finish_item is the blocking "deliver and wait" call, and the driver's item_done is what releases it.

Verification Perspective — the finish_item ↔ item_done interlock

finish_item's blocking is one side of a precise interlock with the driver: the sequence's finish_item and the driver's get_next_item/item_done wait on each other, which is what synchronizes them.

The interlock is the heart of finish_item's behavior. There are two synchronization points between the sequence and the driver. The first is delivery: the sequence's finish_item hands the item over, satisfying the driver's get_next_item — so the driver, which was blocked waiting for an item (Module 8.3), now has one. The second is completion: after the driver drives the item (the time-consuming work), it calls item_done, which unblocks the sequence's finish_item. Between these two points, the sequence is suspended inside finish_item while the driver works — neither side runs ahead of the other. This mutual waiting is exactly what makes the sequence and driver advance in lockstep: the driver can't get a second item until the sequence delivers one (it's blocked in get_next_item), and the sequence can't deliver a second item until the driver finishes the first (it's blocked in finish_item). The consequence is the back-pressure of Module 8.3: because finish_item waits for item_done, and item_done comes only as fast as the driver (and DUT) allow, the sequence's rate is set by the driver's rate. So finish_item isn't just "send" — it's the sequence's half of a two-point interlock that paces it to the driver, and understanding both points (delivery and completion) is what lets you reason about where a stalled handshake is stuck.

Runtime / Execution Flow — the point of no return and pacing

At run time, finish_item marks the transition from "the sequence's item" to "the driver's item," and its block is the entire driving span — so it's both the point of no return and the pacing point.

The runtime view ties finish_item's two famous properties to its mechanics. Before finish_item (step 1), the item is the sequence's: it's still in the window, finalizable, owned by the sequence. At finish_item (step 2), ownership transfers to the driver — the driver reads the item's values to drive the pins — and this is the point of no return: a change to the item after finish_item is delivered can't affect what's driven, because the driver already has (and is reading) the item as it was at delivery. This is why you must finalize before finish_item (Module 9.3's window) and why mutating afterward is a bug. During finish_item's block (step 3), the sequence is suspended for the entire driving span, so its progress is gated by the driver — the pacing/back-pressure point: one item advances per DUT-paced driving cycle, and a slow DUT naturally slows the sequence (Module 8.3). After item_done (step 4), finish_item returns and the sequence prepares the next item. So the two properties are one mechanism viewed two ways: the handoff makes it the point of no return, and the wait for item_done makes it the pacing point. Both follow from finish_item being a blocking delivery — which is exactly why it's a separate call from start_item, and why the line after it runs only once the driver is done.

Waveform Perspective — finish_item's block is the driving time

finish_item's defining behavior — blocking for the whole driving span — is clearest on a timeline: the call returns only when the driver, after driving across many cycles, signals item_done.

The waveform shows finish_item's block is the driving time. From the moment of delivery, fi_wait is high: the sequence is blocked inside finish_item, having handed the item to the driver. The drv_active trace and the data beats (D0–D4) show the driver driving the item over several cycles — and this entire span is finish_item's block, because the sequence can't proceed until the driver is done. When the driver completes and pulses item_done, fi_wait falls: finish_item returns, and the sequence advances to its next item. So the length of finish_item equals the length of the driving — which is precisely the back-pressure relationship: the sequence is paced by how long the driver (and DUT) take. Compare this with start_item (Module 9.3), whose block was the grant wait; together, start_item waits for the grant, then finish_item waits for the drive, so the full handshake's time is grant-wait plus drive-time, with the small randomization window in between. The diagnostic reading mirrors start_item's: if fi_wait never falls, finish_item is stuck waiting for an item_done that isn't coming — the driver took the item but never signalled completion (the DebugLab). The timeline makes finish_item's nature concrete: a blocking delivery whose duration is the driver's driving time.

DebugLab — the finish_item that never returned

driver run loop:
  get_next_item(req);          // receives the item finish_item delivered
  if (req.is_read && special) begin
     handle_special(req);
     continue;                 // ✗ early continue — item_done() NEVER called for this item
  end
  drive_on_pins(req);
  item_done();                 // only reached on the normal path
 
sequence:
  finish_item(req);            // delivered the item, now BLOCKS waiting for item_done...
                               // → item_done never comes → finish_item never returns
 
result:  the sequence is suspended at finish_item indefinitely (no error — a completion hang)
         and the driver's next get_next_item may also error ("get_next_item called twice
         without item_done") because the prior item was never completed
fix — pair every get_next_item with item_done on EVERY path:
  get_next_item(req);
  if (req.is_read && special) begin handle_special(req); item_done(); continue; end  // ✓ complete it
  drive_on_pins(req);
  item_done();                 // ✓ normal path

Common Mistakes

• Mutating the item after finish_item. Past delivery the item belongs to the driver; later changes don't reach the pins. Finalize everything before finish_item (in the window, Module 9.3).
• A driver path that skips item_done. The sequence's finish_item hangs waiting for a completion that never comes; pair every get_next_item with exactly one item_done on all paths.
• Expecting finish_item not to block. It blocks for the entire driving time — the sequence is suspended until item_done. Treat it as a synchronization point, not a fire-and-forget send.
• finish_item without a preceding start_item. The handshake must be opened first; finish_item alone has no granted item to send.
• Calling get_response when the driver returns none. It blocks waiting for a response that never comes; only retrieve responses for items the driver answers (Module 8.2).
• Confusing a finish_item hang with a start_item hang. A start_item hang is the grant (Module 9.3); a finish_item hang is item_done. Identify which call is stuck.

Senior Design Review Notes

Interview Insights

Exercises

1. Order the calls. List the sequence-side and driver-side calls for one item in execution order (start_item, randomize, finish_item, get_next_item, drive, item_done), and mark which two sequence-side calls block and on what.
2. Fix the hang. A driver continues on a special case before item_done. Describe the symptom and rewrite the path so finish_item returns.
3. Explain the boundary. A sequence changes a field after finish_item and the change doesn't appear on the pins. Explain why, naming the property of finish_item.
4. Reason about pacing. Explain why a sequence slows down when the DUT inserts wait states, referencing what finish_item blocks on.

Summary

• finish_item(item) is the second half of the handshake: it closes the randomization window (the item is now final), delivers the item to the driver (satisfying get_next_item), and blocks until the driver calls item_done.
• It blocks on the driver's completion — the time-consuming driving — so finish_item's duration is the driving time, making it the back-pressure point where the sequence is paced by the driver (and the DUT behind it).
• It's the point of no return: once delivered, the item belongs to the driver, which reads its values to drive — so a change after finish_item can't reach the pins (finalize before, in the window of Module 9.3).
• finish_item and the driver interlock at two points — delivery (finish_item→get_next_item) and completion (item_done→finish_item returns) — so neither runs ahead, advancing the sequence and driver in lockstep.
• The durable rule of thumb: finalize the item before finish_item, then finish_item to deliver and wait for item_done — and when finish_item never returns, the driver took the item but skipped item_done (pair every get_next_item with exactly one item_done, on every path), because finish_item's wait is entirely the driver's completion signal.

Next — Sequence Control: with the item handshake (start_item/finish_item) understood, the next chapter steps up to controlling sequences themselves — running them in order or in parallel, nesting sub-sequences, and the macros and methods that orchestrate stimulus above the single-item level.