Config DB Failures

UVM Debugging · Module 27 · Page 27.3

The Engineering Problem

You configured a component — set its data width, its mode, its virtual interface — and it used a default instead, as if you'd configured nothing. Or worse: the value was a virtual interface handle, the configuration didn't reach the component, the handle stayed null, and the testbench crashed — not at the configuration, but much later, at the first use of the interface, with a null-object-access fatal that points at the interface, far from where the real problem lives. This is the config DB's characteristic failure (from 27.1's symptom map: a default or null value → config DB), and it's confusing because the config DB is a string-and-type-keyed, time-ordered database: a get retrieves a value only if it matches a prior set on every key — the hierarchical path, the string field name, and the parameterized type — and the set happened before the get. Any mismatch — a path the set targets but the component isn't at, a field name typo, a type that differs between set and get, or a set that runs after the get — makes the get silently return nothing, leaving the default (or a null handle). None of these errors; the get just fails. The crash variant is especially insidious because the crash is far from the cause: the failed get leaves a null handle, but the symptom (the null-access fatal) appears later, at the first use, pointing away from the config-DB set. The problem this chapter solves is config-DB failures: applying the methodology to the config DB — reading the symptom (default value, or null-handle crash), observing with the config-DB trace, and confirming and fixing each root cause so the configuration reaches the component.

Config-DB failures are the silent non-delivery of a configuration — a get returns nothing, leaving a default or a null handle — because the set and get don't agree on a match key or the ordering. The root causes: a path/scope mismatch (the set's target pattern doesn't match the get's location — a different hierarchy name, a missing or wrong wildcard); a field-name mismatch (the string field name differs between set and get — a typo, case, no compile check); a type mismatch (uvm_config_db#(T) is parameterized by type, so a set of one type and a get of another don't match); or ordering (the set ran after the get — the config DB is time-ordered, and build runs top-down, so a set too late or from below the consumer misses). The crash variant: when the value is a virtual interface (or object) handle, the failed get leaves the handle null, and the first use (vif.clk) is a null-object fatal — far from the set. The methodology applied: the symptom is a default/null value (or a null-handle crash); localize to the config DB; observe with +UVM_CONFIG_DB_TRACE (every set and get with their full paths, field names, and types); confirm which key mismatched (or the ordering); and fix (correct the path/wildcard, match the field name, match the type, reorder the set before the get). The cardinal technique: compare the set and get in the config-DB trace — path, field, type, and time — to find the one that doesn't match. This chapter is config-DB failures: the symptom, the match keys, the trace, and the fixes.

Why does a component receive a default or null value it was configured to override — a path/scope mismatch, field-name mismatch, type mismatch, or set-after-get — how does a failed get of a virtual interface crash later at first use rather than at the get, and how do you observe the config-DB trace to find which key mismatched and fix it?

Motivation — why configuration silently fails to arrive

The config DB decouples who sets configuration from who gets it — which is powerful but means delivery depends on agreement across a distance, and a failed delivery is silent. The reasons:

• The keys are strings and types with no compile check. The path and field name are strings; the type is a parameter. A typo, a renamed hierarchy, a case difference, or a type that differs between set and get compiles fine and fails at run time — silently, with the get returning nothing.
• Set and get are written far apart. The set is often in the test or top; the get is deep in an agent's driver. The two ends are written by different code (often different teams, Module 26.5), so a mismatch between them is easy and not locally visible.
• A failed get leaves a default — no error. When a get fails, the component keeps its default (or null handle). There's no exception, no warning by default — the component behaves as if configured with the default, which looks like a configuration choice, not a failure.
• The crash is far from the cause. For a null handle, the failure (the get) and the symptom (the null-access crash on first use) are separated in time and location — the crash points at the interface use, not the config set — so you debug the wrong place.
• Ordering is invisible. Whether the set ran before the get depends on phase and hierarchy order you can't see from either line — and a set below the consumer, or in a later phase, misses a get that already ran.

The motivation, in one line: configuration fails silently to arrive because the config DB matches on string-and-type keys with no compile check, set and get are written far apart, a failed get leaves a default with no error, the null-handle crash appears far from the failed get, and ordering is invisible — so you must observe the config-DB trace to compare the set and get and find which key or ordering broke.

Mental Model

Hold the config DB as a left-luggage counter where you claim only by presenting a ticket that matches the deposit on every detail:

Picture a left-luggage counter, the kind at a train station where you check a bag and reclaim it later. When you deposit an item, it's logged with a label: who it's for, what the item is called, and what kind of item it is. When someone comes to claim it, they present a ticket, and the counter only hands over an item if the ticket matches the deposit on every one of those details — the right recipient, the right item name, the right item type. Get any one wrong — claim under the wrong name, ask for the wrong item, describe the wrong kind of thing — and the clerk checks the log, finds no match, and says politely, "I'm sorry, there's nothing here for you." You walk away empty-handed. And of course you can only claim something that's already been deposited — show up before the bag was checked in, and again, nothing for you. Now here is the cruel part. Suppose what you were expecting to collect was your house key, mailed ahead to the counter. You go to claim it, the ticket doesn't match, you get nothing — but you're in a hurry, you don't inspect the empty hand, you assume it worked, and you leave. You don't discover the problem at the counter. You discover it hours later, standing at your own front door, when you reach for the key that isn't there. The failure happened at the counter; the pain happens at the door — somewhere else entirely, far from where it went wrong. Picture a left-luggage counter. When you deposit an item, it's logged with a label: who it's for, what it's called, what kind of item it is. When someone claims it, they present a ticket, and the counter only hands it over if the ticket matches the deposit on every detail — right recipient, right item name, right item type. Get any one wrong — wrong name, wrong item, wrong kind — and the clerk finds no match and says "there's nothing here for you." You walk away empty-handed. And you can only claim what's already deposited — show up before it was checked in, and again, nothing. Now the cruel part: suppose you were expecting your house key. You claim it, the ticket doesn't match, you get nothing — but you're in a hurry, don't inspect the empty hand, assume it worked, and leave. You don't discover it at the counter. You discover it hours later, at your front door, reaching for the key that isn't there. The failure happened at the counter; the pain happens at the door — far from where it went wrong.

So the config DB is a left-luggage counter: a set is a deposit (logged with a recipient path, an item name = field, and an item type = the parameterized type), and a get is a claim (presenting a ticket = the get's path, field, and type). The counter hands over the value only if all keys match — path, field name, type — and you can only claim what's already deposited (ordering: the set before the get). Any mismatch → "nothing here for you" → the get returns nothing → the component keeps its default. And the cruel part is the null handle: if what you needed was a virtual interface, the failed claim leaves you with null, and you don't crash at the counter (the get) — you crash at the front door (the first use of the interface, vif.clk), far from the failed get. Diagnose a config-DB failure by checking the claim against the deposit on every key — path, field, type, ordering — using the config-DB trace as the counter's log; and remember the null-handle crash happens at the door, not the counter. Match on every key, or you walk away empty-handed.

Visual Explanation — the match keys and ordering

The defining picture is the match keys: a get succeeds only if it matches the set on path/scope, field name, and type, and the set happened first.

The figure shows the four things a get must match. Path/scope (the warning-colored — the most common): the set's target hierarchical pattern must match the get's location, including wildcards. Field name (brand-colored): the string field name must match exactly — a typo or case difference fails, with no compile check. Type (success-colored): uvm_config_db#(T) is parameterized by type, so the set's type and the get's type must be the same T. Ordering (default-colored): the set must happen before the get — the config DB is time-ordered, and build runs top-down, so a set too late or from below the consumer misses. The crucial reading is that all four must hold — the get is a conjunction: it succeeds only if the path matches AND the field matches AND the type matches AND the set happened first. Any one failing makes the get return nothing. This is why config-DB failures are common: there are four independent ways to break delivery, three of them on string or type keys with no compile check, and the fourth on invisible ordering. The warning-colored path is highlighted as the most common because paths are the trickiest: the set's cntxt and instance_path combine into a pattern (often with wildcards like *), the get's cntxt and instance_path combine into a lookup path, and they must match — which is easy to get wrong (a renamed hierarchy level, a missing wildcard, a too-narrow or too-wide pattern). The diagram is the config-DB matching contract: path AND field AND type AND ordering — all four, or nothing is delivered. A config-DB get matches a set only on all four — path/scope, field name, type, and ordering — so any one mismatch silently delivers nothing.

RTL / Simulation Perspective — the keys, the trace, and the fixes

In code, each root cause is a specific mismatch visible in the config-DB trace. The example shows the keys, the failures, and the observation.

// A correct set/get pair — all four keys agree:
//   in the test/top:     set(cntxt,           "instance_path",        "field", value)
uvm_config_db#(virtual my_if)::set(null, "uvm_test_top.env.agent.*", "vif", my_vif);
//   in the driver:       get(this,            "",                     "field", value)
uvm_config_db#(virtual my_if)::get(this, "", "vif", vif);   // this = uvm_test_top.env.agent.driver
 
// ✗ CAUSE 1 — PATH mismatch: set targets env.agent.*, but the driver is at env.agt.driver
uvm_config_db#(virtual my_if)::set(null, "uvm_test_top.env.agent.*", "vif", my_vif);  // agent
// driver at uvm_test_top.env.agt.driver  → get finds NO match → vif stays null
 
// ✗ CAUSE 2 — FIELD-NAME mismatch: set "vif", get "vinterface" (typo) → no match → default/null
uvm_config_db#(virtual my_if)::set(null, "...", "vif", my_vif);
uvm_config_db#(virtual my_if)::get(this, "", "vinterface", vif);   // wrong field name
 
// ✗ CAUSE 3 — TYPE mismatch: set #(virtual my_if), get #(my_if) → different T → no match
uvm_config_db#(virtual my_if)::set(null, "...", "vif", my_vif);
uvm_config_db#(my_if)::get(this, "", "vif", vif);                  // wrong parameterized type
 
// ✗ CAUSE 4 — ORDERING: set runs AFTER the get (e.g., set in connect_phase, get in build_phase)
//   build_phase (get) runs before connect_phase (set) → get ran first → nothing → default
 
// === OBSERVE: the config-DB trace prints every set and get with path, field, type ===
//   simulate with:  +UVM_CONFIG_DB_TRACE
//   → set: Configuration 'uvm_test_top.env.agent.*' (type virtual my_if) field 'vif' ...
//   → get: ... 'uvm_test_top.env.agt.driver' (type virtual my_if) field 'vif' ... NOT matched
//   compare the set line to the get line: the PATH differs (agent vs agt) → the cause

The code shows the keys, failures, and observation. The correct pair: a set(null, "uvm_test_top.env.agent.*", "vif", my_vif) in the test/top and a get(this, "", "vif", vif) in the driver — all four keys agree (path matches via the * wildcard, field "vif", type virtual my_if, set-before-get). Cause 1 (path): the set targets env.agent.* but the driver is at env.agt.driver — no match, vif null. Cause 2 (field): set "vif", get "vinterface" — no match. Cause 3 (type): set #(virtual my_if), get #(my_if) — different T, no match. Cause 4 (ordering): the set in connect_phase runs after the get in build_phase — the get ran first, got nothing. Observe: +UVM_CONFIG_DB_TRACE prints every set and get with its path, field, and type, so comparing the set line to the get line reveals which key differs (here, path: env.agent.* vs env.agt.driver). The shape to carry: each cause is a specific mismatch on one of the four keys, and the config-DB trace makes all four visible for both the set and the get — so you compare them line by line and the mismatch is the cause. You don't guess which key — you read the trace and see which one differs. Observe the config-DB trace to compare the set and get on path, field, type, and ordering — the one that differs is the cause.

Verification Perspective — the null handle crashes far from the cause

The defining trap of config-DB failures is the null virtual-interface handle: the failed get and the crash are separated, so the crash points away from the cause. Seeing the separation clarifies why you localize by the symptom's nature, not its location.

The figure shows the null-handle crash separated from the config-DB failure. The config-DB set fails to deliver (a path mismatch, say — the warning-colored cause), so the get in the driver's build phase returns nothing and the virtual interface handle stays null. Nothing crashes yet — build completes, the run phase starts. Then, well into the run, the driver uses the interface for the first time (vif.clk), and that null-handle access is a fatal (the warning-colored symptom). The verification insight is the separation in time and location: the cause (the failed set/get in the build phase, at the config-DB layer) and the symptom (the null fatal in the run phase, at the interface use) are far apart. The crash message points at vif.clk — the driver's run logic and the interface — so the naive response is to debug the driver's run code or suspect the interface, neither of which is wrong. This is exactly the symptom-location-is-not-cause-location principle (27.1): the null fatal surfaces at the use, but the fault is upstream, at the config-DB set that never delivered. The warning-colored set (cause) → default-colored null propagation → brand-colored use → warning-colored crash (symptom) chain shows the fault traveling silently from the build-phase config failure to the run-phase crash. The crucial point is how you localize this: not by the crash location (the interface use) but by the symptom's nature — a null handle is an unset value, and unset values come from the config DB (an interface handle is configured, so a null one means the configuration didn't arrive). So you recognize "null interface handle" → config DB, and observe the config-DB trace — not the driver's run code. The diagram is the separation: the config-DB set fails in build, the crash appears in run at first use — localize by the null handle's nature (unset → config DB), not by where it crashes. A null-handle crash appears far from its cause — localize it to the config DB by its nature, an unset handle, not by the interface use where it crashes.

Runtime / Execution Flow — diagnosing a config-DB failure

At run time, diagnosing a config-DB failure follows the methodology with the config-DB trace as the observation. The flow shows the config-specific diagnostic.

The flow shows the config-specific diagnostic. Symptom (step 1): a default where a configured value was expected, or a null-handle crash on first interface use. Enable the trace (step 2): +UVM_CONFIG_DB_TRACE prints every set and get with its path, field name, and type. Compare the keys (step 3): path (with wildcards), field-name string, parameterized type, and whether the set ran before the get. The differing key → fix → re-run (step 4): correct the path, field, type, or ordering; re-run to confirm the get now matches. The runtime insight is that the config-DB trace turns a four-way ambiguity into a direct comparison: the symptom (default/null) tells you the config DB failed but not which key, and the trace shows both the set and the get with all their keys, so you compare them and the differing key is the cause — no guessing among the four. The trace is the counter's log: it shows what was deposited (the set lines, with recipient-path/field/type) and what was claimed (the get lines), and whether each get matched a set — so a get that prints as "not matched" tells you the claim failed, and comparing its keys to the nearby set tells you which key didn't match. The crucial discipline is comparing, not assuming: you might assume it's a path problem (the most common) and be wrong (it's a type mismatch) — the trace tells you which, definitively. The brand (symptom) → success (trace + compare) → warning (fix) flow shows evidence (the trace) preceding the fix. This is the methodology (27.1) specialized to the config DB: the config-DB trace is the introspection that makes the invisible matching visible. The flow is the config diagnostic: symptom → config-DB trace → compare set and get keys → the differing key → fix. Diagnose a config-DB failure by enabling the trace and comparing the set and get on all four keys — the one that differs is the cause, no guessing required.

Waveform Perspective — the crash at first use, not at the get

The null-handle crash's separation from its cause is visible on a timeline: build completes, the run starts, and the crash appears only at the first interface use. The waveform shows it.

The waveform shows the crash far from the cause. The config-DB get failed in the build phase and the virtual interface handle stayed null, but nothing crashed then — build completed and the simulation ran normally for a while (the clock toggles, sim_active high). Only when the driver first accesses the interface (vif_access) does the null-handle fatal occur, halting the simulation (sim_active drops, the clock freezes). The crucial reading is the gap: the cause (the failed config get) was in the build phase, before cycle 0 of the run — but the timeline shows nothing wrong for several cycles (the null handle is harmless until used), and the crash appears only at cycle 5, at the first interface access. So reading the timeline naively points you at cycle 5 — the interface use — as where the problem is, when the real cause was much earlier, in a different phase, at the config DB. The picture to carry is that a null handle is a latent failure: it's set (to null) at the failed get but causes no symptom until used, so the crash time reflects when the interface is first touched, not when the configuration failed. This is why you can't localize by the crash's position on the timeline — a crash early in the run and a crash late in the run could have the same config-DB cause, differing only in when the driver first uses the interface. Instead, you localize by the crash's nature: a null-object access on a virtual interface means the interface handle was never set, which means the configuration didn't arrive — config DB. Reading the waveform this way — the testbench ran fine until the interface was touched, then died — is the signature of a null handle from a failed config get, directing you to the config-DB trace (not the run-phase code at cycle 5). A null-handle crash is latent until first use, so it appears far down the timeline from the build-phase config failure that caused it — localize by its nature, an unset handle, not by where it crashes.

DebugLab — the null vif that crashed in the run, set wrong in the top

✗ PATH MISMATCH — set targets the wrong path; the driver's get finds no match:
  // in the testbench top:
  uvm_config_db#(virtual my_if)::set(null, "uvm_test_top.env.agent.driver", "vif", my_vif);
  // but the ACTUAL driver path is uvm_test_top.env.agt.drv  (agent named "agt", driver "drv")
  // → driver's get(this,"","vif",vif) at env.agt.drv finds NO matching set → vif stays NULL
  // → build completes (no crash), run starts, driver hits @(posedge vif.clk) → NULL FATAL (far away)
 
  // the config-DB trace (+UVM_CONFIG_DB_TRACE) shows it:
  //   set: 'uvm_test_top.env.agent.driver' field 'vif' (virtual my_if)
  //   get: 'uvm_test_top.env.agt.drv'      field 'vif' (virtual my_if)  → NOT matched
  //   → the PATHS differ (agent.driver vs agt.drv) — the cause, visible in one comparison
 
✓ FIX — set with a path/scope that matches the driver (a wildcard is robust to naming):
  uvm_config_db#(virtual my_if)::set(null, "uvm_test_top.env.agt.drv", "vif", my_vif);  // correct path
  // or, robustly:  set(null, "*", "vif", my_vif);  // matches any consumer asking for "vif"
  // → the get now matches → vif is non-null → no crash

Common Mistakes

• Debugging the crash site of a null handle. A null-object fatal on an interface points at the use, not the cause; localize a null handle to the config DB and read the trace.
• Assuming a path problem without checking. The most common cause is a path mismatch, but it could be field, type, or ordering; compare all four in the trace rather than guessing.
• Mismatched set/get field-name strings. A typo or case difference in the field name fails silently with no compile check; use shared constants for field names.
• Mismatched parameterized types. A set and get of different types don't match; keep the uvm_config_db type parameter identical between set and get.
• Setting after the get. A set in a later phase or from below the consumer misses a get that already ran; set configuration before the consumer's build-phase get.
• Not using the config-DB trace. Without the trace the matching is invisible; enable +UVM_CONFIG_DB_TRACE to see every set and get and which gets didn't match.

Senior Design Review Notes

Interview Insights

Exercises

1. Find the mismatched key. Given a config-DB trace showing set at env.agent.* field vif type virtual my_if and get at env.agt.drv field vif type virtual my_if not matched, name the mismatched key and the fix.
2. Trace the null vif. Walk through why a vif set at the wrong path crashes in the run phase rather than at the get, and how you localize it.
3. Fix the ordering. Given a set in connect_phase and a get in build_phase, explain why the get fails and where to move the set.
4. Choose the scope. Decide between a precise path and a wildcard for setting a virtual interface, and justify the robustness tradeoff.

Summary

• Config-DB failures are the silent non-delivery of a configuration — a get returns nothing, leaving a default value or a null handle — because the set and get don't agree on a match key or the ordering.
• The four keys a get must match: path/scope (the set's pattern matches the get's location, wildcards included), field name (exact string, no compile check), type (uvm_config_db#(T) — same T), and ordering (set before get; build is top-down).
• The crash variant: a null virtual-interface handle from a failed get crashes not at the get but later, at the first use (vif.clk) — far from the cause, so localize by its nature (an unset handle → config DB), not by where it crashes.
• Observe with +UVM_CONFIG_DB_TRACE — it prints every set and get with path, field, and type — and compare the set to the get to find which key differs; don't assume it's a path problem.
• The durable rule of thumb: when a component uses a default or a null handle crashes on first use, localize to the config DB (an unset value means the configuration didn't arrive) and enable +UVM_CONFIG_DB_TRACE, then compare the set and get on all four keys — path/scope (with wildcards), field-name string, parameterized type, and ordering — to find the one that didn't match; a null virtual-interface crash points at the interface use but is caused by a set/get mismatch far away, which the trace reveals in a single comparison.

Next — TLM Issues: the methodology turns to transaction-level connections. Why transactions sent through a TLM port never arrive, or a connect-phase fatal appears — a port left unconnected, a port connected to the wrong export, a missing implementation of the required interface method, or analysis ports with no subscribers — how to read the symptom (transactions vanish, or a connection error), how to observe it (the topology and connection checks), and how to fix each so transactions flow end to end.