Part 7 · Environment & Tests · Intermediate

Agent Sequencer Handles: Robust Mapping for Active/Passive Modes

Map and validate agent sequencer handles consistently across active/passive variants and scenario requirements.

Handle Mapping Basics

Handle mapping should be explicit, typed, and mode-aware. Every potentially inactive interface should map to null and be checked before use.

diagram

[TEST][UVM] handle state table

interface  mode      mapped handle
-------------------------------------------
apb        active    v_sqr.apb_sqr_h != null
apb        passive   v_sqr.apb_sqr_h == null
axi        active    v_sqr.axi_sqr_h != null
axi        passive   v_sqr.axi_sqr_h == null
irq        active    v_sqr.irq_sqr_h != null
irq        passive   v_sqr.irq_sqr_h == null

systemverilog

function void map_child_handles();
  v_sqr.apb_sqr_h = (cfg.apb_mode == UVM_ACTIVE) ? apb_agt.sqr : null;
  v_sqr.axi_sqr_h = (cfg.axi_mode == UVM_ACTIVE) ? axi_agt.sqr : null;
  v_sqr.irq_sqr_h = (cfg.irq_mode == UVM_ACTIVE) ? irq_agt.sqr : null;
endfunction

Key takeaways

Null is a valid state for passive agents and should be intentional.
Typed handles reduce accidental cross-interface misuse.
Mapping policy belongs in env, not in tests.

Common pitfalls

Leaving stale handles from prior mode settings.
Implicitly assuming all handles are always valid.
Assigning handles in ad hoc debug-only code paths.

Requirement-Specific Validation

diagram

[TEST][UVM] scenario requirement matrix

scenario                 requires handles
-----------------------------------------------
smoke_boot               apb, axi
throughput_nightly       apb, axi
interrupt_stress         apb, axi, irq
observe_only_lp          apb

validate before start()

systemverilog

class soc_vseq_base extends uvm_sequence #(uvm_sequence_item);
  bit need_apb;
  bit need_axi;
  bit need_irq;
  `uvm_declare_p_sequencer(soc_virtual_sequencer)

  task pre_start();
    p_sequencer.validate_handles(need_apb, need_axi, need_irq);
  endtask
endclass

systemverilog

function void validate_handles(bit need_apb, bit need_axi, bit need_irq);
  if (need_apb && apb_sqr_h == null)
    `uvm_fatal("VSQR_REQ", "need_apb true but handle null")
  if (need_axi && axi_sqr_h == null)
    `uvm_fatal("VSQR_REQ", "need_axi true but handle null")
  if (need_irq && irq_sqr_h == null)
    `uvm_fatal("VSQR_REQ", "need_irq true but handle null")
endfunction

Align required handles with scenario profile, not with env defaults.
Run validation before any child sequence starts.
Use precise fatal messages to pinpoint missing resources quickly.

Applied Patterns

diagram

[TEST][UVM][ENV] handle-debug pattern

startup banner:
  print configured mode for every agent
  print mapped handle state
  print scenario requirements

runtime checks:
  pre_start validation in every vseq
  timeout-based waits only

closure:
  report handle map + requirements in final summary

systemverilog

function string handle_snapshot();
  return $sformatf(
    "mode(apb=%s axi=%s irq=%s) map(apb=%0d axi=%0d irq=%0d)",
    cfg.apb_mode.name(), cfg.axi_mode.name(), cfg.irq_mode.name(),
    apb_sqr_h != null, axi_sqr_h != null, irq_sqr_h != null);
endfunction

Snapshot logs make active/passive mismatches obvious.
Keep requirement and mapping summaries together in logs.
Never rely on waveform-only discovery for missing handles.

Practice this lessonQuestions tagged for this topic in the bank