Driver-Sequencer Handshake Hub: Execution Contracts and Debug Discipline

Overview

This hub defines a practical contract for Driver-Sequencer Handshake : predictable ownership transfer, explicit completion semantics, and instrumentation that makes deadlocks diagnosable in minutes instead of hours.

The same patterns apply to simple bus drivers and complex VIP: keep pull/completion boundaries visible, classify failures deterministically, and make progress observable.

Sub-lessons in this topic

1. get-next-item-flow - get_next_item Flow.

2. item-done-semantics - item_done Semantics.

3. rsp-port-responses - Response Port Handling.

4. backpressure-stall - Backpressure Stall.

5. handshake-timing-diagram - Handshake Timing Diagram.

6. handshake-debug-hangs - Handshake Debug Hangs.

Architecture map

[UVM][AGT][DRV][TLM] handshake control spine

[UVM] sequence intent
   -> [TLM] sequencer arbitration
   -> [DRV] get_next_item
   -> [DRV] protocol execution
   -> [TLM] item_done / response
   -> [UVM] sequence progress

invariants:
  one grant -> one completion
  bounded wait -> explicit status
  identity-preserving responses

[UVM][AGT][DRV][TLM] timeline anchors

- request granted
- transfer active
- completion emitted
- response consumed

these anchors should appear in logs and counters

[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

• Model handshake semantics as a protocol, not boilerplate.

• Exactly-once completion is the top-level invariant.

• Bounded waits and explicit statuses prevent silent hangs.

• Minimal structured telemetry accelerates root-cause isolation.

Common pitfalls

• Treating get_next_item/item_done as incidental implementation details.

• Mixing response styles without clear sequence-side contract.

• Ignoring reset/timeout branches in completion logic.

• Debugging by waveform first without progress counters.