Test build_phase Config Push: Order and Path Discipline

Order is policy

The strict sequence is create cfg -> mutate cfg -> set cfg -> create env. Any deviation produces hard-to-debug partial configuration.

[TEST][UVM] required ordering

1) cfg = create()
2) cfg.apply_defaults()
3) apply plusargs/random knobs
4) config_db::set(...)
5) env = create()

if env is created before step 4, child gets may fail

function void build_phase(uvm_phase phase);
  super.build_phase(phase);

  env_cfg cfg;
  cfg = env_cfg::type_id::create("cfg");
  cfg.apply_defaults();
  cfg.enable_cov = has_plusarg("+ENABLE_COV");
  cfg.num_agents = 2;

  uvm_config_db#(env_cfg)::set(this, "env*", "cfg", cfg);
  env = my_env::type_id::create("env", this);
endfunction

Key takeaways

• Ordering bugs often masquerade as random test instability.

• Publish one primary env cfg object from the test.

• Prefer explicit typed sets over many scalar sets.

Common pitfalls

• Scattering config_db::set calls across multiple helper files.

• Calling set after env creation then expecting rebuild behavior.

• Using broad '*' paths without guardrails.

Path strategy patterns

Choose path granularity early: broad env root set from test, finer partition sets from env.

Pattern comparison

[UVM][ENV] path options

Option A: test sets "env*"
  + simple test code
  + env controls fanout
  - env must actively partition child cfg

Option B: test sets each child path directly
  + explicit from test
  - brittle to hierarchy refactors
  - duplicates path strings

• Prefer Option A for reusable envs.

• Keep hierarchy strings in one utility when needed.

• Add smoke tests that fail fast on missing cfg gets.

Guarding path typos

function void require_cfg_get(bit ok, string where, string field);
  if (!ok)
    `uvm_fatal("CFG_GET",
      $sformatf("missing field=%s at %s", field, where))
endfunction

[TEST] typo prevention

- wrap set/get in helper API
- keep keys as localparams
- add static review checklist for path changes
- log successful cfg gets at UVM_LOW during bring-up

Common pitfalls

• Unreviewed string literal changes in path arguments.

• Using different key names for logically same cfg object.

• Suppressing get() failures with defaults too early.