Part 7 · Environment & Tests · Intermediate

Env/Agent Config Receive: Typed get() and Validation

Reliable config reception patterns in env and agent classes, including required-vs-optional policy and field validation.

Receive contract

Every component should treat cfg retrieval as an explicit contract with clear required/optional semantics.

diagram

[ENV][AGT][UVM] receive policy

required cfg:
  get() failure -> fatal

optional cfg:
  get() failure -> default + info log

after get():
  validate fields
  freeze or avoid mutation in run phase

systemverilog

function void build_phase(uvm_phase phase);
  super.build_phase(phase);
  if (!uvm_config_db#(agent_cfg)::get(this, "", "cfg", cfg))
    `uvm_fatal("AGT_CFG", {"missing cfg for ", get_full_name()});
  validate_cfg(cfg);
endfunction

function void validate_cfg(agent_cfg c);
  if (c.timeout_cycles == 0)
    `uvm_fatal("AGT_CFG", "timeout_cycles must be >0");
  if (c.role != AGENT_MASTER && c.role != AGENT_SLAVE)
    `uvm_fatal("AGT_CFG", "invalid role");
endfunction

Key takeaways

Fail fast when required cfg is absent or invalid.
Validation belongs close to the receiving component.
Required/optional policy should be documented per key.

Common pitfalls

Silent defaults for missing required cfg fields.
Performing validation too late in run_phase.
Mutating shared cfg objects from multiple components.

Receive diagnostics and compatibility

Add compatibility guards so old tests fail with clear messages when cfg schema evolves.

Versioned cfg fields

systemverilog

class agent_cfg extends uvm_object;
  `uvm_object_utils(agent_cfg)
  int unsigned schema_version = 2;
  rand int unsigned timeout_cycles;
  rand agent_role_e role;
endclass

function void check_schema(agent_cfg c);
  if (c.schema_version < 2)
    `uvm_fatal("CFG_SCHEMA", "agent_cfg schema too old")
endfunction

Increment schema version on incompatible field changes.
Provide migration notes for major schema bumps.
Track schema version in logs for failing regressions.

Receive telemetry

diagram

[AGT] receive telemetry fields

- component full name
- cfg object type name
- schema version
- key field summary
- get source scope (if tracked)

systemverilog

function void log_cfg_receive(agent_cfg c);
  `uvm_info("CFG_RX",
    $sformatf("inst=%s type=%s schema=%0d timeout=%0d role=%s",
      get_full_name(), c.get_type_name(), c.schema_version,
      c.timeout_cycles, c.role.name()),
    UVM_LOW)
endfunction

Common pitfalls

Schema changes without validation updates.
No telemetry to correlate cfg with failing components.
Treating backwards compatibility as optional in shared VIP.

Practice this lessonQuestions tagged for this topic in the bank