item_done Semantics

Core concept

This lesson focuses on item_done Semantics as a first-class handshake behavior. The implementation goal is deterministic progress and explicit ownership boundaries between sequence, sequencer, and driver.

A robust implementation keeps one completion path, bounded waits, and clear status semantics so regressions remain debuggable under stress and reset churn.

[UVM][AGT][DRV][TLM] item_done Semantics flow

1) [TLM] driver pulls item from sequencer
2) [DRV] validates request and timing window
3) [DRV] executes protocol phase task
4) [DRV] classifies completion status
5) [TLM] item_done/response returns upstream
6) [UVM] sequence continues deterministic progress

• Preserve one-request/one-completion invariant.

• Keep failure semantics explicit in response status.

• Prefer boundary logs over noisy per-cycle traces.

Reference implementation

Use a minimal orchestration loop and delegate protocol detail to helper tasks. This keeps code review focused on contract semantics rather than incidental complexity.

class item_done_semantics_driver extends uvm_driver #(req_t);
  `uvm_component_utils(item_done_semantics_driver)

  task run_phase(uvm_phase phase);
    req_t req;
    rsp_t rsp;
    forever begin
      seq_item_port.get_next_item(req);
      rsp = rsp_t::type_id::create("rsp");
      rsp.set_id_info(req);
      drive_one(req, rsp);
      seq_item_port.item_done(rsp);
    end
  endtask
endclass

[UVM][AGT][DRV][TLM] timeline view

t0 req granted
 t1 setup phase
 t2 transfer wait
 t3 capture/response
 t4 completion edge
 t5 next arbitration cycle

• Initialize response identity from request before driving.

• Classify non-OK outcomes without skipping completion.

• Record wait cycles and retries when relevant.

Debug and validation pattern

Instrument progress counters and runbook-style checks to isolate handshake stalls quickly. Counter imbalance usually reveals the first broken boundary.

[DRV] validation checklist

- grant counter increments
- done counter increments
- timeout counter bounded
- response IDs correlate
- reset branches still complete

[UVM] triage order

1) issued vs granted
2) granted vs completed
3) completed vs response-consumed
4) inspect state snapshot and wait condition

[UVM][AGT][DRV][TLM] review drill

contract checks:
- ownership acquired exactly once per request
- completion emitted exactly once per request
- response identity copied before emission

progress checks:
- grant and done counters stay balanced
- timeout paths classified with explicit status
- reset paths still close lifecycle

debug checks:
- timeline anchors are logged
- triage order is deterministic

Key takeaways

• item_done Semantics must preserve deterministic completion behavior.

• Counter-first observability reduces hang triage time.

• Bounded waits convert silent deadlocks into classified outcomes.

• Consistent response semantics simplify sequence policy code.

Common pitfalls

• Multiple hidden completion branches that drift over time.

• Unbounded waits on external readiness signals.

• Missing ID propagation between request and response objects.

• Late debug-only fixes without invariant checks.