Virtual Sequencer Hub: Env-Level Multi-Agent Coordination

Overview

A virtual sequencer is an environment-level routing point for child sequencer handles. It lets one virtual sequence coordinate traffic across multiple agents while preserving each agent's protocol-local responsibilities.

Treat the virtual layer as a control plane : it coordinates ordering, dependencies, and scenario phases, but it does not replace driver logic or protocol timing.

Sub-lessons in this topic

1. virtual-sequencer-role - strict role boundaries and non-goals.

2. env-owned-v-sqr - why env owns virtual sequencer lifecycle.

3. agent-sqr-handles - mapping active/passive agent sequencer handles safely.

4. vseq-start-patterns - deterministic virtual-sequence launch templates.

5. multi-agent-orchestration - event-based dependency choreography across interfaces.

6. virtual-sequencer-debug - symptom-first triage for hangs and ordering bugs.

[TEST][UVM][ENV] virtual sequencing architecture

test
  |
  +-- env
       +-- apb_agt.sqr
       +-- axi_agt.sqr
       +-- irq_agt.sqr
       +-- v_sqr
            +-- apb_sqr_h
            +-- axi_sqr_h
            +-- irq_sqr_h

virtual sequence starts on env.v_sqr
and launches child sequences on leaf sequencers
based on explicit dependency barriers

class soc_virtual_sequencer extends uvm_sequencer #(uvm_sequence_item);
  `uvm_component_utils(soc_virtual_sequencer)
  apb_sequencer apb_sqr_h;
  axi_sequencer axi_sqr_h;
  irq_sequencer irq_sqr_h;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction
endclass

Key takeaways

• Virtual sequencer centralizes cross-agent coordination at env scope.

• Tests stay lean by starting one virtual sequence entry point.

• Deterministic handle wiring is a prerequisite for reliable orchestration.

Common pitfalls

• Embedding protocol generation logic directly in virtual sequencer component methods.

• Bypassing virtual sequences by poking drivers from tests.

• Assuming every agent is active without runtime handle checks.

Common Flow

[TEST][UVM] orchestration timeline

T0: test chooses scenario profile
T1: env build/connect creates and wires v_sqr
T2: test starts virtual sequence on env.v_sqr
T3: virtual sequence launches child sequences
T4: events/barriers enforce order and dependencies
T5: scoreboard/coverage confirm scenario closure

• Keep orchestration event-driven instead of delay-driven.

• Log scenario profile, handle map, and barrier checkpoints.

• Drop test objection only after end-of-scenario quiet checks.

Applied Patterns

Use this shared checklist for every virtual-sequencer code review so orchestration style remains uniform across teams.

[TEST][UVM][VSEQ] review checklist

ownership:
  env owns v_sqr component lifecycle
  test owns scenario profile and vseq start
  vseq owns cross-agent ordering

connectivity:
  map active child sequencers in connect_phase
  set passive handles to null explicitly
  validate required handles in pre_start/end_of_elaboration

synchronization:
  use named events/barriers
  timeout every wait
  avoid guessed #delays

debug:
  print handle map at startup
  print barrier checkpoint timeline
  print closure metrics before objection drop

function void report_phase(uvm_phase phase);
  `uvm_info("VSQR_HEALTH",
    $sformatf("apb=%0d axi=%0d irq=%0d waits=%0d timeouts=%0d",
      apb_sqr_h != null,
      axi_sqr_h != null,
      irq_sqr_h != null,
      wait_cnt,
      timeout_cnt),
    UVM_LOW)
endfunction

• Treat virtual-layer behavior as shared infrastructure, not test-local code.

• Require reproducible startup and barrier logs before merging orchestration changes.

• Keep v_sqr APIs minimal and typed.