Config Distribution Hub: Test-to-Env Policy Propagation

Overview

Configuration distribution defines how test intent becomes env and agent behavior. The goal is deterministic policy propagation, not scattered ad-hoc setters.

Most teams combine config_db path conventions, typed config objects, and controlled randomization to keep large environments maintainable.

Sub-lessons in this topic

1. test-build-config-push - pushing typed cfg during test build_phase.

2. config-object-factory - factory-created cfg objects and overrideable policy.

3. hierarchical-set-patterns - scoped set paths for env/agent partitions.

4. env-agent-cfg-receive - robust cfg receive/get paths in env and agents.

5. rand-cfg-from-test - constrained random cfg generation at test level.

6. config-distribution-debug - deterministic triage for cfg propagation failures.

[TEST][UVM][ENV] distribution pipeline

test.build_phase
  -> create cfg objects
  -> apply defaults + plusargs + randomization
  -> config_db::set("env*", "cfg", env_cfg)
  -> create env

env/agent.build_phase
  -> config_db::get(this, "", "cfg", cfg_handle)
  -> validate required fields
  -> use cfg to construct behavior

policy lives in cfg objects, not in hardcoded per-component knobs

function void build_phase(uvm_phase phase);
  super.build_phase(phase);
  cfg = env_cfg::type_id::create("cfg");
  cfg.apply_defaults();
  parse_plusargs_into_cfg(cfg);
  uvm_config_db#(env_cfg)::set(this, "env*", "cfg", cfg);
  env = my_env::type_id::create("env", this);
endfunction

Key takeaways

• Config flow should be explicit, typed, and deterministic.

• Push cfg before creating env/components that consume it.

• Keep scenario policy in tests and cfg objects, not env internals.

Common pitfalls

• Using wildcard paths without ownership conventions.

• Mixing string/int knobs across many independent set calls.

• Creating components before config objects are published.

Enterprise config conventions

Adopt one path strategy and one validation strategy for the entire project to minimize integration surprises.

Conventions checklist

[UVM][ENV][TEST] config conventions

pathing:
  - test sets "env*" root cfg
  - env sets child agent cfg via explicit paths

typing:
  - one typed cfg class per major subsystem
  - avoid raw scalar set/get except legacy bridges

validation:
  - get() failure is fatal for required cfg
  - optional cfg has explicit fallback policy

• Document every required cfg field in class comments.

• Keep cfg mutation out of run_phase unless intentional.

• Publish cfg summary at start-of-test for reproducibility.

function void log_cfg(env_cfg c);
  `uvm_info("CFG_SUMMARY",
    $sformatf("agents=%0d sb=%0d cov=%0d timeout_ns=%0d mode=%s",
      c.num_agents, c.enable_sb, c.enable_cov, c.timeout_ns, c.mode.name()),
    UVM_LOW)
endfunction

[TEST] ownership model

test owns:
  cfg creation + scenario randomization + top-level set

env owns:
  cfg fanout to child cfg objects

agent owns:
  strict cfg get + local validation

driver/monitor own:
  behavior derived from received cfg only