Env Wrapper Role: Composition Boundary and Ownership

Wrapper contract

An env wrapper should expose only stable handles and service points, not scenario behavior. Keep it a reusable integration shell around agents and checkers.

[ENV][UVM][CHECK] wrapper contract

env wrapper owns:
  - child component creation
  - default config object hookup
  - analysis graph stitching
  - health counters and debug hooks

test owns:
  - plusarg policy
  - factory overrides
  - virtual sequence selection
  - objection / timeout strategy

class soc_env extends uvm_env;
  `uvm_component_utils(soc_env)
  ctrl_agent ctrl;
  dma_agent  dma;
  soc_sb     sb;

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    ctrl = ctrl_agent::type_id::create("ctrl", this);
    dma  = dma_agent::type_id::create("dma", this);
    sb   = soc_sb::type_id::create("sb", this);
  endfunction
endclass

• Expose minimal public handles needed by tests and virtual sequences.

• Wrap optional features behind config objects, not ifdefs in tests.

• Document wrapper responsibilities in a short contract comment block.

Key takeaways

• A strict wrapper role prevents test logic from leaking into env internals.

• Stable wrapper APIs lower maintenance across large test matrices.

Common pitfalls

• Adding run_phase scenario code directly into the env wrapper.

• Exposing internals that force tests to poke private hierarchy.

Applied Patterns

Use one wrapper API manifest to keep ownership boundaries clear during fast feature growth.

[ENV] wrapper API manifest

published handles:
  v_sqr
  scoreboards by role
  key monitor analysis exports

hidden internals:
  leaf monitor private queues
  agent driver knobs
  temporary debug probes

evolution rules:
  deprecate before remove
  add compatibility aliases
  gate changes with smoke tests

function void dump_wrapper_manifest();
  `uvm_info("WRAP_API",
    $sformatf("has_v_sqr=%0d has_sb=%0d has_cov=%0d",
      (v_sqr != null), (sb != null), (cov != null)),
    UVM_LOW)
endfunction

• Publish only handles that are part of long-lived workflows.

• Prefer config objects over direct field pokes from tests.

• Tag deprecated wrapper APIs in logs for one release cycle.

Integration Drilldown

When wrapper behavior changes, validate active and passive topologies to ensure compatibility contracts still hold.

[CHECK] wrapper regression matrix

mode A: active ctrl + active dma
mode B: active ctrl + passive dma
mode C: passive ctrl + passive dma

checkpoints:
  wrapper creates legal hierarchy
  connect graph complete
  no test edits required for old scenarios

Key takeaways

• Wrapper compatibility is measured by unchanged tests and clean smoke runs.

Common pitfalls

• Declaring wrapper refactor complete without compatibility matrix runs.