Part 7 · Environment & Tests · Intermediate

Hierarchical set Patterns: Scope Without Fragility

Balancing wildcard convenience and explicit hierarchy paths when distributing config across nested env/agent topologies.

Scope design

Hierarchy paths are an interface. Design them for stability, readability, and refactor tolerance.

diagram

[ENV][UVM] scoping examples

test:
  set(this, "env*", "cfg", env_cfg)

env:
  set(this, "agt_tx*", "cfg", tx_cfg)
  set(this, "agt_rx*", "cfg", rx_cfg)

agent:
  get(this, "", "cfg", cfg)

avoid:
  set(null, "*", "cfg", anything)

systemverilog

function void build_phase(uvm_phase phase);
  super.build_phase(phase);
  if (!uvm_config_db#(env_cfg)::get(this, "", "cfg", cfg))
    `uvm_fatal("CFG", "env cfg missing");

  tx_cfg = agent_cfg::type_id::create("tx_cfg");
  rx_cfg = agent_cfg::type_id::create("rx_cfg");
  derive_agent_cfgs(cfg, tx_cfg, rx_cfg);
  uvm_config_db#(agent_cfg)::set(this, "agt_tx*", "cfg", tx_cfg);
  uvm_config_db#(agent_cfg)::set(this, "agt_rx*", "cfg", rx_cfg);
endfunction

Key takeaways

Use top-down fanout: test -> env -> agents.
Minimize path literals at test level for env reuse.
Avoid global wildcard scope except controlled bring-up.

Common pitfalls

Setting child-agent cfg directly from many test files.
Using same cfg key for incompatible object types.
Assuming wildcard coverage without verifying instance names.

Path robustness techniques

Invest in helper APIs and key constants to make path changes safer.

Key and path constants

systemverilog

package cfg_keys_pkg;
  localparam string ENV_CFG_KEY   = "cfg";
  localparam string AGENT_CFG_KEY = "cfg";
  localparam string ENV_SCOPE      = "env*";
  localparam string TX_SCOPE       = "agt_tx*";
  localparam string RX_SCOPE       = "agt_rx*";
endpackage

Place key constants near cfg class definitions.
Enforce key usage with lint or review templates.
Never change key names without migration notes.

Fanout validation

diagram

[TEST][ENV] validation script idea

for each expected component:
  assert cfg handle is non-null
  print essential fields
  compare against source env cfg

fail build early if mismatch

systemverilog

function void assert_cfg_consistency(agent_cfg c, string inst);
  if (c == null)
    `uvm_fatal("CFG_NULL", $sformatf("null cfg at %s", inst));
  if (c.protocol_id == "")
    `uvm_fatal("CFG_FIELD", $sformatf("protocol_id empty at %s", inst));
endfunction

Common pitfalls

No automated check that each agent received cfg.
Path updates merged without running smoke tests.
Inconsistent key naming between envs in same project.

Practice this lessonQuestions tagged for this topic in the bank