Resource Usage Patterns

Resource Database · Module 23 · Page 23.3

The Engineering Problem

You know what the config and resource databases are (Modules 23.1, 23.2) — now you need the patterns that use them predictably across a real testbench. Configuration at scale is fragile if done ad hoc: a set placed after the consumer was built arrives too late and the get misses; a field name that doesn't match between the setter and the getter makes the get miss; a get whose return is unchecked lets a missed config silently leave the field at its default, so the component proceeds with the wrong value — a subtle bug far from its cause. And scattered, individual config sets become unmanageable as the component count grows. The patterns — the canonical set-higher/get-lower-in-build_phase flow, the virtual interface handoff, the config object, wildcard scoping, and the check-the-get discipline — are what turn fragile, ad hoc configuration into predictable, debuggable configuration. The problem this chapter solves is resource usage patterns: how configuration is written and read across the testbench — the canonical flow and its timing, the common patterns, and the conventions that keep config reliable at scale.

Resource usage patterns are the practical conventions for configuring a UVM testbench predictably. The canonical flow: a higher component (test/env) sets a value in its build_phase — before the lower component is built — and the lower component gets it in its build_phase; the timing matters because UVM builds top-down, so the parent's set runs before the child's get. The virtual interface handoff: the top module sets the vif into config_db and the driver/monitor gets it — bridging the static RTL world to the dynamic class world. The config object pattern: a config object (a class bundling related parameters) is set by a higher component and got by a lower one, so related config travels as a unit. Wildcard scoping: "*", "env.*.driver" configure many components at once, with specific overrides. And the disciplines: set in build_phase (before the consumer builds), use config objects over scattered fields, consistent naming, and — above all — always check that config_db::get succeeded (if (!get(...)) uvm_fatal), because a missed get (typo, wrong scope, set-too-late) unchecked leaves the field at its default and the component silently uses the wrong value. This chapter is resource usage patterns: the canonical flow and timing, the vif and config-object patterns, wildcard scoping, and the check-the-get discipline.

What are the practical patterns for configuration across a UVM testbench — the canonical set-higher/get-lower in build_phase flow and its timing, the virtual interface handoff, the config object pattern, wildcard scoping, and the disciplines (especially always checking config_db::get succeeded) that keep configuration predictable?

Motivation — why patterns, not ad hoc configuration

Configuration works in a small testbench done any way — but scales only with patterns. The reasons:

• Timing is unforgiving. A config_db get in a component's build_phase only sees sets that happened before. UVM builds top-down, so a parent set in build_phase is visible to a child get in build_phase — but a set placed too late (after the child built) misses. The canonical timing is not optional.
• A missed get fails silently if unchecked. config_db::get returns a success bit. If you don't check it, a missed config (typo, wrong scope, late set) leaves the field unset (null/default), and the component silently uses the wrong value — a subtle, hard-to-trace bug. Checking the get makes the failure loud and immediate.
• Scattered config doesn't scale. Individual sets for every parameter become unmanageable as components multiply. Config objects bundle related parameters, so one set/get passes a unit — organized and maintainable.
• Reuse needs a clear config interface. A reusable component (agent, driver) has a config interface — what it expects from config_db. Conventions (consistent names, a config object) make that interface clear, so users configure it correctly.
• The vif handoff is a fixed pattern. Bridging the static RTL/interface world to the dynamic UVM class world always goes through config_db (top sets the vif, driver gets it). Knowing this canonical pattern is essential — it's how every testbench connects to its DUT.

The motivation, in one line: configuration scales only with patterns — the timing (set before the consumer builds) is unforgiving, a missed get fails silently if unchecked, scattered config doesn't scale (use config objects), and reuse needs a clear config interface — so the canonical flow, the vif/config-object patterns, wildcards, and the check-the-get discipline are what make configuration predictable and debuggable at scale.

Mental Model

Hold configuration patterns as a disciplined supply chain delivering config down the hierarchy — deliver before the recipient needs it, bundle related items, use distribution lists, and require a read-receipt:

Configuration is a supply chain: higher components deliver configuration down to lower ones, and the patterns are the standard operating procedures that make the supply chain reliable. First, deliver before the recipient needs it: a component reads its configuration when it's built, so the delivery — the set — must happen before that, which the top-down build order guarantees if you set in the parent's build_phase. A late delivery is missed entirely. Second, bundle related items: rather than sending dozens of individual parcels (one set per parameter), you pack related configuration into one crate — a config object — and ship it as a unit, so it arrives together and is easy to track. Third, use distribution lists for broadcasts: a wildcard scope addresses many recipients at once — configure all drivers, all agents — with the option of a specific override to one. Fourth, and most important, require a read-receipt: every delivery must be confirmed received, because a delivery can fail silently — a wrong address (scope), a mismatched label (field name), a late send — and if you don't check the receipt, the recipient just uses whatever it had (a default), and you discover the missing delivery only later, downstream, far from where it failed. So you check that the get succeeded and raise an alarm if it didn't. A supply chain run this way — deliver early, bundle, broadcast with lists, confirm receipt — delivers configuration predictably; run ad hoc, it drops parcels silently. Picture configuration as a supply chain: higher components deliver configuration down to lower ones, and the patterns are the standard operating procedures that make the chain reliable. First, deliver before the recipient needs it: a component reads its config when it's built, so the delivery (the set) must happen before — which the top-down build order guarantees if you set in the parent's build_phase; a late delivery is missed. Second, bundle related items: rather than dozens of individual parcels (one set per parameter), pack related config into one crate (a config object) and ship it as a unit. Third, use distribution lists for broadcasts: a wildcard scope addresses many recipients at once (all drivers, all agents), with a specific override option. Fourth, and most important, require a read-receipt: every delivery must be confirmed, because a delivery can fail silently — a wrong address (scope), a mismatched label (field name), a late send — and if you don't check the receipt, the recipient uses whatever it had (a default), and you discover the miss later, downstream, far from where it failed. So you check that the get succeeded and raise an alarm if it didn't.

So configuration patterns are a disciplined supply chain: deliver before needed (set in the parent's build_phase, before the child builds), bundle related items (config objects, not scattered sets), use distribution lists (wildcard scopes for broadcasts), and require a read-receipt (check config_db::get's return, fatal on miss). Run this way, config delivers predictably; run ad hoc (late sets, unchecked gets), it drops parcels silently. Deliver config early in build_phase, bundle it in config objects, broadcast with wildcards, and always confirm the get succeeded.

Visual Explanation — the canonical set-higher / get-lower flow

The defining picture is the canonical flow: a higher component sets in build_phase, before the lower component is built, and the lower component gets in its build_phase.

The figure shows the canonical configuration flow and why the timing works. Parent set (step 1): the test/env sets the config in its build_phase, before constructing the child component. Child constructed (step 2): UVM builds top-down, so the parent's build_phase (and its set) runs before the child is built. Child get (step 3): the child gets the config in its own build_phase — the set is already in the pool from step 1. Get succeeds (step 4): the value is found because it was set first; the child checks the get's return and proceeds. The crucial reading is the timing guarantee from the build order: UVM's build_phase executes top-down (parent before child), so a set in the parent's build_phase is guaranteed to be in the pool before the child's build_phase get — configuration arrives before the consumer needs it. This is why the canonical pattern is set-higher/get-lower, both in build_phase: the set (higher, earlier) precedes the get (lower, later) by construction of the phase ordering. The failure this avoids is a set placed too late — e.g. in connect_phase (after all build_phases), or in a build_phase after the child was already built — which the child's build_phase get would miss (the value isn't in the pool yet when the child looks). The brand-colored parent set and child construction (the top-down build) precede the success-colored child get, yielding the found value. The diagram is the canonical timing: parent set (build_phase, before child built) → child built → child get (build_phase, value already present) → success — the top-down build order making the set precede the get. Set higher and earlier in build_phase, get lower and later — the top-down build order guarantees the value is there.

RTL / Simulation Perspective — the patterns in code

In code, the patterns are the vif handoff, the config object, wildcards, and the checked get. The example shows each.

// === VIRTUAL INTERFACE HANDOFF: top module sets the vif, driver gets it (static → dynamic bridge) ===
// in the top testbench module (static world):
initial uvm_config_db#(virtual bus_if)::set(null, "uvm_test_top.env.agent.driver", "vif", dut_if);
// in the driver (dynamic world), in build_phase:
if (!uvm_config_db#(virtual bus_if)::get(this, "", "vif", vif))   // CHECK the get!
  `uvm_fatal("CFG", "no virtual interface set for driver")        // loud + immediate on miss
 
// === CONFIG OBJECT: bundle related params, set by env, got by agent (related config as a unit) ===
class agent_config extends uvm_object;
  virtual bus_if vif;  bit is_active = 1;  int max_len = 16;  bit [31:0] base_addr;
endclass
// env build_phase: configure the agent with ONE object (not scattered individual sets)
agent_config acfg = agent_config::type_id::create("acfg"); acfg.is_active = 0; /* ... */
uvm_config_db#(agent_config)::set(this, "agent", "cfg", acfg);
// agent build_phase: get the whole config object, then distribute its fields to driver/monitor
if (!uvm_config_db#(agent_config)::get(this, "", "cfg", m_cfg)) `uvm_fatal("CFG","no agent_config")
 
// === WILDCARD SCOPING: configure MANY components at once, with a specific override ===
uvm_config_db#(int)::set(this, "env.*.driver", "max_len", 16);     // ALL drivers: default
uvm_config_db#(int)::set(this, "env.agent3.driver", "max_len", 64); // agent3's driver: override
 
// ✗ MISTAKE: get with UNCHECKED return + a NAMING MISMATCH → silent default, wrong behavior (DebugLab)
//   void'(uvm_config_db#(int)::get(this, "", "max_len", max_len));  // set as "max_length" → MISS → max_len=0

The code shows the patterns. Virtual interface handoff: the top testbench module (static world) sets the vif (set(null, "uvm_test_top.env.agent.driver", "vif", dut_if)), and the driver (dynamic world) gets it in build_phase — with the get checked (if (!get(...)) uvm_fatal("CFG", "no virtual interface set")), loud and immediate on a miss. This bridges the static RTL/interface world to the dynamic UVM class world. Config object: an agent_config class bundles related params (vif, is_active, max_len, base_addr); the env configures the agent with one object (set(this, "agent", "cfg", acfg), not scattered individual sets), and the agent gets the whole object (checked) then distributes its fields to driver/monitor. Wildcard scoping: set(this, "env.*.driver", "max_len", 16) configures all drivers, with set(this, "env.agent3.driver", "max_len", 64) overriding one. The mistake (commented) is an unchecked get with a naming mismatch (get(..., "max_len", ...) when set as "max_length") → the get misses, max_len stays at its default (0), silent wrong behavior (the DebugLab). The shape to carry: the canonical patterns are the vif handoff (top sets, driver gets, bridging static/dynamic), the config object (bundle related params, set/get as a unit), and wildcards (configure many, override one) — and every get is checked (if (!get(...)) uvm_fatal). The checked get is the cardinal discipline: it appears on every get, turning a missed config (from a typo, wrong scope, or late set) into a loud, immediate fatal instead of a silent default. The config object is what scales — one set/get passes a unit of related config, organizing the configuration. The vif handoff is the one pattern every testbench uses (to connect to the DUT). Hand off the vif checked, bundle config in objects, use wildcards for broadcasts, and check every get.

Verification Perspective — the common configuration patterns

The recurring patterns — the vif handoff, the config object, and wildcard scoping — are the vocabulary of configuration. Seeing them together shows how config is structured in a real testbench.

The figure shows the three recurring patterns. The virtual interface handoff bridges the static RTL world to the dynamic class world: the top module (static) sets the DUT interface into config_db (the warning-colored vif handoff), and the driver and monitor (dynamic) get it. The config object bundles related parameters into one class (the warning-colored config object) set by a higher component (env) and got by a lower one (agent), which distributes its fields to sub-components. Wildcard scoping configures many components at once (all drivers, all agents) with a specific override. The verification insight is that these patterns structure configuration at different levels: the vif handoff is the interface-connection pattern (every testbench, one per interface — connecting static to dynamic); the config object is the component-configuration pattern (group related config, pass as a unit, distribute down); and wildcards are the broad-configuration pattern (set many, override few). The warning-colored vif-handoff and config-object are the key bridges (warning because they're the critical connection points — the vif handoff is where the testbench meets the DUT, the config object is where related config is organized). The vif handoff is non-negotiable — it's how the dynamic UVM class world gets a handle to the static interface (you can't directly pass a static interface into a class; it goes through config_db). The config object is the scaling pattern — without it, configuring a complex agent means many individual sets (fragile, unmanageable); with it, one object holds all the agent's config. Wildcards are the efficiency pattern — configure all drivers with one set, override the exception. The diagram is the configuration vocabulary: vif handoff (static→dynamic), config object (bundle + distribute), wildcards (broadcast + override) — the recurring patterns that structure a testbench's configuration. The vif handoff bridges static to dynamic, the config object bundles and distributes, and wildcards broadcast with overrides.

Runtime / Execution Flow — the disciplines that keep config predictable

At run time, the disciplines — set in build_phase, check the get, config objects, consistent naming — are what make config predictable. The flow shows them as a checklist.

The flow shows the disciplines. Set in build_phase (the brand-colored top — before the consumer builds): the top-down build order makes a parent's set precede a child's get — a late set is missed. Use config objects (bundle related params): group related configuration into one object set/got as a unit — organized, scalable, maintainable. Consistent field names (getter matches setter): a naming convention so a get's field name matches the set's — a mismatch makes the get miss. Always check config_db::get's return (the warning-colored bottom): if (!get(...)) uvm_fatal — a missed config is caught loudly at the get, not as a silent default. The runtime insight is that these disciplines each prevent a specific failure: set-in-build prevents timing misses (set too late), config objects prevent unmanageability (scattered sets), consistent naming prevents naming-mismatch misses, and checking the get prevents the silent-default bug (the most important — it catches the result of any of the other failures at the get). The warning-colored check-the-get is highlighted because it's the cardinal discipline: even if the other disciplines are violated (a late set, a naming mismatch), checking the get turns the resulting miss into a loud fatal — so it's the safety net that catches everything. The priority order is check-the-get first (the universal safety net), then set-in-build and consistent naming (prevent the misses), then config objects (scale and organize). Together, these turn ad hoc configuration into predictable, debuggable configuration: config arrives on time (set-in-build), is organized (config objects), matches (naming), and failures are loud (check-the-get). The flow is the discipline checklist: set in build_phase + config objects + consistent naming + check the get — the conventions that make config reliable at scale. Set in build_phase, bundle in config objects, name consistently, and above all check every get — the safety net that catches every config miss.

Waveform Perspective — the build-order timing of set and get

The canonical timing is visible on the phase timeline: the parent's build_phase set happens before the child's build_phase get, so the get finds the value. The waveform shows the top-down build order making the set precede the get.

The waveform shows the build-order timing. UVM builds top-down: the parent's build_phase runs first (parent_bld). The parent sets the config value during its build_phase (parent_set), placing it in the pool. Then the child is built (child_bld) and its build_phase runs, where it gets the value (child_get) — the value is already in the pool, so the get succeeds (get_ok). The crucial reading is the ordering: parent_set (cycle 1, in the parent's build_phase) precedes child_get (cycle 4, in the child's build_phase) — because the build order is top-down (parent before child). So the value is in the pool by the time the child looks, and the get finds it. The contrast (noted in the caption) is a set placed too late — after the child's build_phase (e.g. in connect_phase, or a build_phase set on a sibling that runs after the child) — which would not be in the pool when the child looked, so that get would miss. This is the timing discipline made visible: the set must precede the get, and the canonical way to guarantee that is set in the parent's build_phase (which runs before the child's build_phase by the top-down order). The picture to carry is that configuration timing follows the build order: a higher component's build_phase set is guaranteed visible to a lower component's build_phase get, because build_phase executes top-down — and a set outside this window (too late) misses. Reading the timeline this way — does the set happen in a phase that runs before the get's phase? — is verifying config timing. The parent_set preceding child_get, get succeeding is the signature of correct config timing — the top-down build order delivering the value before the consumer needs it. Set in the parent's build_phase so it precedes the child's build_phase get — the top-down build order delivers config before the consumer needs it.

DebugLab — the zero-length transactions from an unchecked, misnamed get

✗ NAMING MISMATCH + UNCHECKED get → silent default:
  // env:    uvm_config_db#(int)::set(this, "agent.driver", "max_length", 64);  // name: "max_length"
  // driver: void'(uvm_config_db#(int)::get(this, "", "max_len", max_len));     // name: "max_len" → MISS
  //   the names differ → get returns 0 (not found) → BUT return is discarded (void')
  //   → max_len stays at its DEFAULT (0) → driver silently drives len=0 → no error, baffling
 
✓ CHECK the get (and fix the naming mismatch):
  if (!uvm_config_db#(int)::get(this, "", "max_length", max_len))   // matching name + CHECKED
    `uvm_fatal("CFG", "max_length not configured for driver")
  // the check would have FIRED on the mismatch immediately → "max_length not configured" → fix the name
  // a config error caught LOUDLY at the get, not debugged downstream from zero-length transactions

Common Mistakes

• Not checking config_db::get's return. An unchecked get silently leaves the field at its default on a miss; always wrap in if (!get(...)) uvm_fatal.
• Naming mismatch between set and get. A getter's field name or scope not matching the setter's makes the get miss even when the value is in the pool; use consistent names.
• Setting config too late. A set after the consumer's build_phase is missed; set in the parent's build_phase, before constructing the child.
• Scattering individual config sets. Many loose sets don't scale; bundle related parameters into a config object set and got as a unit.
• Forgetting the vif goes through config_db. A static interface reaches the dynamic class world only via config_db; set it from the top, get it in the driver/monitor.
• Overusing wildcards without overrides in mind. A broad wildcard set is convenient, but plan the specific overrides; an unintended wildcard match can misconfigure a component.

Senior Design Review Notes

Interview Insights

Exercises

1. Order the cascade. Describe the set/get sequence from test to driver across build_phase, and why each set precedes its get.
2. Check the get. Rewrite an unchecked config_db::get so a missing value fails loudly, and explain what it prevents.
3. Bundle the config. Convert four individual agent parameter sets into a config object set and got as a unit.
4. Broadcast and override. Write the wildcard set that defaults all drivers and the specific set that overrides one.

Summary

• The canonical configuration flow is set higher, get lower, both in build_phase: a parent sets a value before constructing the child, and the child gets it in its build_phase — the top-down build order makes the set precede the get, so config arrives before the consumer needs it (a late set is missed).
• The common patterns: the virtual interface handoff (top module sets the vif, driver/monitor get it — bridging static RTL to dynamic classes), the config object (a class bundling related params, set by a higher component and got by a lower one, distributed down), and wildcard scoping ("env.*.driver" to configure many, with specific overrides).
• The disciplines: set in build_phase (before the consumer builds), use config objects over scattered fields, consistent naming (getter matches setter), and — above all — always check config_db::get's return (if (!get(...)) uvm_fatal).
• A missed get (naming mismatch, wrong scope, set-too-late) left unchecked silently leaves the field at its default, so the component proceeds with the wrong value — a subtle bug far from its cause with no error; checking the get makes the miss loud and immediate at the source.
• The durable rule of thumb: configure predictably with the canonical patterns — set higher and get lower in build_phase so the top-down order delivers config before it's needed, hand off the virtual interface through config_db, bundle related parameters into config objects, broadcast with wildcards and override specifically, name fields consistently, and above all check every config_db::get's return and fatal on a miss, because a config that is set and in the pool can still be missed by a misnamed or mis-scoped get, and an unchecked miss is a silent default and a baffling downstream bug.

Next — Resource DB Debugging: the module closes with debugging configuration — when a value doesn't arrive, how to find out why. Using the resource database dump to see what's actually in the pool, tracing a missed get to its cause (scope mismatch, naming, timing, type), reading precedence to find which set won, and the systematic process from a wrong or missing configuration value to its root cause.