Resource DB Debugging

Resource Database · Module 23 · Page 23.4

The Engineering Problem

A configuration value didn't arrive — a driver got a null interface, a component used a default it shouldn't have — or it arrived wrong (an unexpected value, not the one you set). The previous chapters gave you the patterns and the check-the-get discipline (Module 23.3), so the get fired loudly — but now you must find why. And configuration misses are uniquely confusing because the value is often in the pool — set correctly, present — yet the get misses, so the symptom (a default value, a crash) seems to contradict the evidence (the value is there). The cause is a mismatch between the set and the get — in scope, naming, timing, or — the trickiest — type: config_db is type-parameterized, so a set#(int) and a get#(bit[31:0]) with matching scope and name still miss, because the types differ. Or the value arrived wrong because multiple sets competed and precedence picked a different winner than you expected. The problem this chapter solves is resource DB debugging: using the dump as ground truth, classifying a missed get by its cause, reading precedence to find which set won, and the systematic process from a wrong or missing value to its root cause.

Resource DB debugging is finding why a configuration value didn't arrive or is wrong. The primary tool is the resource database dump (uvm_config_db::dump(), print_resources()) — it prints what's actually in the pool: every resource's scope, name, value, type, who set it, and precedence. The dump is ground truth — compare it to your mental model to find the discrepancy. For a missed get, classify the cause by auditing the set/get pair: scope mismatch (paths don't match), naming mismatch (field-name typo), timing (set after the get), or type mismatch (the trickiest — config_db is type-parameterized, so set#(int) ≠ get#(bit[31:0]) even with matching scope and name). For a wrong value (not missing), read the precedence: multiple sets matched, and hierarchical precedence (higher/later wins) picked the winner — the dump shows the competing sets, so you trace which won and why. The systematic process: dump → compare to expectation → classify the miss (or read precedence) → fix the root cause. The combo that localizes: the checked get (loud failure location) + the dump (pool contents) + the set/get pair audit (scope/name/type/timing). This chapter is resource DB debugging: the dump, classifying misses, reading precedence, the type trap, and the systematic process.

How do you debug configuration — use the resource database dump to see what's actually in the pool, classify a missed get by its cause (scope, naming, timing, or type mismatch), read precedence to find which set won when a value is wrong, and follow a systematic process from a missing or wrong value to its root cause?

Motivation — why config bugs need the dump, not guessing

Configuration bugs are confusing precisely because the value is often present but missed — so guessing fails and the dump is essential. The reasons:

• The symptom contradicts the evidence. A missed get produces a default/null (crash or wrong behavior), but the value is often in the pool (set correctly). So the symptom ("the value isn't there") contradicts the evidence ("the value is there") — baffling until you dump and see the discrepancy.
• The dump is ground truth. Guessing about what's in the pool is unreliable — the dump shows it: every resource, its scope, name, value, type, setter, precedence. The dump resolves the contradiction by showing what's actually there versus what you looked for.
• The four miss-causes are distinct, and the dump distinguishes them. A miss is a scope, naming, timing, or type mismatch — and each needs a different fix. The dump + the set/get audit tell you which: is the value there (so scope/name/type), and is it there in time (timing)?
• The type mismatch is invisible without the dump. A set#(int) / get#(bit[31:0]) mismatch has matching scope and name — so it looks correct, and only the dump (showing the value under the set's type) reveals that the get's type doesn't match.
• A wrong value is a precedence question. When a get returns the wrong value, multiple sets competed, and precedence picked the winner. Reading the precedence (from the dump) tells you which set won and why — not guessable, but visible in the dump.

The motivation, in one line: config bugs are confusing because the value is often present but missed (symptom contradicts evidence), so guessing fails — the dump is essential as ground truth (what's actually in the pool, with scope/name/value/type/precedence), distinguishing the four miss-causes (scope/naming/timing/type), revealing the invisible type mismatch, and showing the precedence winner for a wrong value.

Mental Model

Hold config debugging as reconciling your delivery records against the actual warehouse inventory — the dump is the manifest, and the discrepancy is the cause:

When a delivery doesn't arrive, you don't guess — you pull the warehouse inventory and reconcile it against your records. Configuration debugging is the same. The dump is the warehouse manifest: it lists every parcel actually in the pool, with its address (scope), its label (name), its contents and type (value and parameterized type), who shipped it (the setter), and its priority (precedence). Your records are what you think you set and what the recipient looked for. You compare the two. Often the confusing part is that the parcel is in the inventory — it was shipped and received into the warehouse — but the recipient couldn't find it, which means the recipient looked under the wrong address, the wrong label, the wrong type of parcel, or looked before it arrived. The manifest shows you exactly which: the parcel is there under address A, but the recipient searched address B (scope mismatch); it's labeled X, but they asked for Y (naming); it's a crate of one kind, but they expected another (type); it wasn't there yet when they looked (timing). And if the wrong parcel arrived, the manifest shows two parcels competed for the same slot, and the higher-priority one was delivered (precedence). So you never guess about what's in the pool — you read the manifest, reconcile it against your expectation, and the discrepancy between manifest and expectation is the root cause. Picture config debugging as warehouse reconciliation. When a delivery (config) doesn't arrive, you don't guess — you pull the inventory (the dump) and reconcile it against your records. The dump is the manifest: it lists every parcel actually in the pool, with its address (scope), label (name), contents and type (value and parameterized type), who shipped it (the setter), and its priority (precedence). Your records are what you think you set and what the recipient looked for. You compare. The confusing part is often that the parcel is in the inventory — shipped and received — but the recipient couldn't find it, meaning they looked under the wrong address, label, type, or before it arrived. The manifest shows exactly which: there under address A, but searched address B (scope); labeled X, asked for Y (naming); a crate of one kind, expected another (type); not there yet when they looked (timing). And if the wrong parcel arrived, the manifest shows two parcels competed and the higher-priority one was delivered (precedence). So you never guess about the pool — you read the manifest, reconcile it against expectation, and the discrepancy is the root cause.

So config debugging is warehouse reconciliation: the dump is the manifest (ground truth — every parcel's address, label, type, value, setter, priority), and debugging is comparing the manifest to your expectation (what you set, what the recipient looked for). The discrepancy is the cause: present-but-mis-addressed (scope), mislabeled (naming), wrong-type (type), late (timing), or out-prioritized (precedence). Don't guess the pool — dump it, reconcile against expectation, and the discrepancy is the root cause.

Visual Explanation — the systematic debug process

The defining picture is the process: dump (ground truth) → compare to expectation → classify the miss (or read precedence) → fix.

The figure shows the systematic debug process. Dump (step 1): uvm_config_db::dump() / print_resources() — every resource's scope, name, value, type, setter, precedence. Compare (step 2): is the value present, under the scope/name/type you expected, and was it set before the get? Classify (step 3): missing/mis-keyed → scope/naming/timing/type mismatch (audit set vs get); wrong value → which set won (read precedence). Fix (step 4): align scope/name/type, fix timing, or adjust precedence/override — the specific discrepancy the dump revealed. The crucial reading is that the dump anchors the whole process — it replaces guessing with reconciliation. Without the dump, you'd speculate about what's in the pool (and why the get missed) — unreliable. With it, you see the ground truth and compare it to your expectation, and the discrepancy is right there. The branch at step 3 is key: a missing value (the get found nothing) is a mismatch between set and get (scope/naming/timing/type — one of four, found by auditing the pair), while a wrong value (the get found something, but not what you expected) is a precedence question (multiple sets matched — which won?). The two branches have different diagnostics: classify the mismatch (for missing) versus read the precedence (for wrong). The brand-colored dump/compare are the anchor (ground truth + expectation), the success-colored classify/read-precedence is the diagnosis, and the default-colored fix is the resolution. The diagram is the debug process: dump (ground truth) → compare (vs expectation) → classify-or-read-precedence → fix — reconciliation, not guessing. Dump the pool, compare to expectation, classify the miss or read the precedence, and fix the discrepancy the dump revealed.

RTL / Simulation Perspective — the dump and the set/get audit

In code, the debug is dump the pool and audit the set/get pair. The example shows a dump, and the four miss-causes found by comparing set and get.

// === THE DUMP: ground truth — what's ACTUALLY in the pool ===
uvm_config_db#(int)::dump();         // or:  uvm_resource_db::dump();  /  print_resources()
//   prints each resource: scope, name, value, TYPE, who set it, precedence
//   e.g.:  scope="uvm_test_top.env.agent.driver"  name="addr_width"  type=int  value=32  set_by=env
 
// === AUDIT THE SET/GET PAIR for the FOUR miss-causes ===
// the SET (in env):
uvm_config_db#(int)::set(this, "agent.driver", "addr_width", 32);
 
// (1) SCOPE mismatch — getter's path doesn't resolve to the setter's target
//   uvm_config_db#(int)::get(this, "wrong.path", "addr_width", aw);   // scope ≠ → MISS
// (2) NAMING mismatch — field name differs
//   uvm_config_db#(int)::get(this, "", "addr_w", aw);                 // "addr_w" ≠ "addr_width" → MISS
// (3) TIMING — get ran before the set (set too late / wrong phase)
//   get in build_phase, set in connect_phase → value not in pool yet → MISS
// (4) TYPE mismatch — config_db is TYPE-PARAMETERIZED: different type → MISS (DebugLab)
//   uvm_config_db#(bit[31:0])::get(this, "", "addr_width", aw);       // bit[31:0] ≠ int → MISS!
//     ← scope AND name match, but TYPE differs → the dump shows it present as `int`, get as bit misses
 
// === FOR A WRONG (not missing) value: read PRECEDENCE — which competing set won? ===
// dump shows two sets for the same scope/name → the HIGHER/LATER one won (hierarchical precedence)
 
// THE COMBO: checked get (loud WHERE) + dump (pool CONTENTS) + set/get audit (the mismatch)

The code shows the debug tools. The dump (uvm_config_db#(int)::dump(), print_resources()) prints each resource: scope, name, value, type, setter, precedence — ground truth. Auditing the set/get pair for the four miss-causes: given a set (set(this, "agent.driver", "addr_width", 32)), a miss is (1) scope mismatch (get(this, "wrong.path", ...) — path doesn't resolve to the setter's target), (2) naming mismatch (get(..., "addr_w", ...) — addr_w ≠ addr_width), (3) timing (get in build_phase, set in connect_phase — value not in pool yet), or (4) type mismatch (get#(bit[31:0]) — config_db is type-parameterized, so bit[31:0] ≠ int → miss, even though scope and name match — the DebugLab). For a wrong value, read precedence: the dump shows two sets for the same scope/name → the higher/later one won. The closing comment marks the combo: checked get (loud where) + dump (pool contents) + set/get audit (the mismatch). The shape to carry: the dump is the ground truth (what's in the pool, with scope/name/value/type/setter/precedence), and auditing the set/get pair against it finds the mismatch — scope (paths), naming (field names), timing (set-before-get), or type (the parameterized type). The type cause is the most insidious — config_db#(T) stores and looks up by T, so set#(int) and get#(bit[31:0]) don't match despite identical scope and name, and only the dump (showing the value as int) reveals it. The precedence read (for a wrong value) is a different diagnostic — the dump shows the competing sets and which won. Dump the pool, audit the set/get pair for scope/name/timing/type, and read precedence for a wrong value.

Verification Perspective — the four causes of a missed get

The core of debugging a missing value is classifying the miss into its cause — scope, naming, timing, or type. Seeing the four together, each a mismatch between set and get, is the diagnostic.

The figure shows the four causes of a missed get, each a mismatch between the set and the get. Scope mismatch: the getter's path doesn't resolve to the setter's target. Naming mismatch: the field names differ (typo). Timing: the get ran before the set, so the value wasn't in the pool yet. Type mismatch (the warning-colored — the trickiest): config_db is type-parameterized, so set and get with different parameterized types miss even when scope and name match exactly. The verification insight is that the dump distinguishes them: a value present under the set's scope/name/type, while the get used a different one, points at scope, naming, or type (the value is in the pool, but the get's key doesn't match); a value absent at get time points at timing (the value wasn't in the pool yet). So the first dump question is "is the value in the pool at all?" — if yes, it's scope/naming/type (a key mismatch); if no (at the get's time), it's timing. Then, for a key mismatch, you compare the set's and get's scope, name, and type to find which differs. The type cause (the warning-colored) is separated out because it's the most deceptive: scope and name match exactly, so the get looks correct, and only the type (the #(T) parameter) differs — invisible without the dump (which shows the value's type) and easy to overlook (you check scope and name, see they match, and miss the type). The warning-colored missed get and type mismatch bracket the brand-colored scope/naming/timing — and classifying the miss into one of the four (via the dump and the set/get audit) is the diagnosis. The diagram is the miss-cause classification: scope (paths), naming (field names), timing (set-before-get), type (parameterized types — scope/name still match!) — four mismatches, distinguished by the dump. A missed get is a scope, naming, timing, or type mismatch — the dump tells you whether the value is present (key mismatch) or absent at get time (timing).

Runtime / Execution Flow — reading precedence for a wrong value

When a value is wrong (not missing), the diagnostic differs: multiple sets matched, and precedence picked the winner — so you read the precedence from the dump. The flow shows it.

The flow shows reading precedence for a wrong value. Wrong value (step 1): the get succeeded (not a miss) but the value isn't what you set — multiple sets matched the resource. Dump (step 2): the pool lists all sets matching that scope/name, each with its setter and precedence. Read (step 3): which set won and why — a higher-component or later set wins (perhaps an unintended wildcard match or a forgotten higher-level override). Fix (step 4): remove the unintended set, narrow the scope, or adjust precedence so the intended set wins. The runtime insight is that a wrong value is a fundamentally different bug than a missing one — and needs a different diagnostic. A missing value means no set matched (a mismatch — Figure 2); a wrong value means the wrong set won (a precedence outcome). For the wrong case, the dump is still the key tool, but you read it differently: not "is the value there?" (it is) but "which of the competing sets won, and why?". The common causes of a surprising winner are an unintended wildcard match (a broad "*" or "env.*.driver" set matched a component you didn't mean to configure) or a forgotten higher-level override (a test or base env set you forgot about, which outranks your intended set by hierarchy). Reading the precedence — the hierarchical proximity and set order the dump shows — reveals which won and why, so you can fix it (remove the unintended set, narrow the over-broad wildcard, or adjust the precedence). The brand-colored wrong-value/dump feed the success-colored precedence read, yielding the default-colored fix. The flow is the precedence diagnostic: unexpected value → dump the competing sets → read which won and why → fix the precedence — the complement to the miss-classification (Figure 2) for the wrong-value case. A wrong value is a precedence outcome — dump the competing sets, read which won and why, and fix the unintended set or precedence.

Waveform Perspective — present in the pool, but missed by the get

The most confusing config bug is visible as a contradiction: the value is in the pool (the dump shows it), yet the get misses — because the get's key (scope/name/type) doesn't match the set's. The waveform shows the present-but-missed signature.

The waveform shows the present-but-missed signature. The set places a value in the pool (set_done), and a dump confirms it is present (dump_shows_present stays high — the value is there). Later, the get runs with a mismatched key — a different scope, name, or type than the set used — so it misses (get_miss), even though the value is present, and the component uses a default (default_used). The crucial reading is the contradiction that defines the hardest config bug: the dump says present, the get says missed — both true, because the value is in the pool (under the set's key) but the get looked under a different key. This contradiction is the diagnostic signature: when a dump confirms the value is present yet the get misses, the discrepancy is in the get's key (scope/name/type), not a missing set. This redirects the debug decisively — away from "the value wasn't set" (it was) and toward "the get's key doesn't match the set's" (compare scope, name, type). The value present the whole time (dump_shows_present high throughout) rules out timing (the value was there before the get) — so it's scope, naming, or type. The picture to carry is that the dump's "present" against the get's "missed" is the signature of a key mismatch — and the only way to see it is to dump the pool (the value's actual key) and compare it to the get's key. Without the dump, you'd assume the value wasn't set (and chase the setter) — wasting effort on the wrong side. Reading the waveform this way — does the dump show the value present while the get misses? — is recognizing a key mismatch. The present-and-missed contradiction is the signature of scope/naming/type (not timing, not missing) — the get is looking in the wrong place. When the dump shows the value present but the get misses, the bug is the get's key (scope/name/type), not a missing set — compare them.

DebugLab — the type mismatch that hid behind a matching scope and name

✗ SET as int, GET as bit[31:0] — scope AND name match, but the TYPE differs:
  // env:    uvm_config_db#(int)     ::set(this, "agent.driver", "addr_width", 32);   // type = int
  // driver: uvm_config_db#(bit[31:0])::get(this, "", "addr_width", aw);              // type = bit[31:0]
  //   config_db is TYPE-PARAMETERIZED: #(int) and #(bit[31:0]) are DIFFERENT lookups
  //   scope ("agent.driver") matches, name ("addr_width") matches — but TYPE doesn't → MISS
  //   the dump shows the value present as `int` → the get (as bit[31:0]) can't find it → baffling
 
✓ MATCH the parameterized type between set and get (use the dump to spot the type):
  // dump reveals: type=int → make the get use the SAME type:
  uvm_config_db#(int)::get(this, "", "addr_width", aw);   // type=int → MATCHES the set → found
  // (or standardize the field's type project-wide so set and get always agree)

Common Mistakes

• Guessing instead of dumping. Speculating about what's in the pool is unreliable; dump the pool for ground truth and reconcile against expectation.
• Checking scope and name but not type. config_db is type-parameterized; a set#(int) and get#(bit[31:0]) miss despite matching scope and name — compare the type via the dump.
• Assuming a miss means a missing set. The value is often present but mis-keyed; a dump showing it present redirects debug to the get's scope/name/type.
• Confusing a wrong value with a missing one. A missing value is a set/get mismatch; a wrong value is a precedence outcome — read the competing sets for the latter.
• Ignoring unintended wildcard matches. A broad wildcard set can match components you didn't intend, producing a surprising precedence winner; narrow the scope.
• Not localizing with the checked get. A checked get tells you where the miss happened; combined with the dump and the set/get audit, it pinpoints the cause.

Senior Design Review Notes

Interview Insights

Exercises

1. Read the dump. Given a dump showing a resource as type int and a get parameterized as bit[31:0] under the same scope/name, name the bug and the fix.
2. Classify the miss. For a get that found nothing, list the four causes and how the dump distinguishes them.
3. Trace the precedence. A get returns an unexpected value. Describe how you'd use the dump to find which set won and why.
4. Recognize present-but-missed. Explain why a dump showing the value present while the get misses rules out timing and a missing set.

Summary

• Resource DB debugging is finding why a configuration value didn't arrive or is wrong — and the primary tool is the dump (uvm_config_db::dump() / print_resources()), which prints what's actually in the pool: each resource's scope, name, value, type, setter, and precedence — ground truth to reconcile against expectation.
• For a missed get, classify the cause by auditing the set/get pair: scope mismatch, naming mismatch, timing (set after the get), or type mismatch — the trickiest, because config_db is type-parameterized, so set#(int) and get#(bit[31:0]) miss even when scope and name match exactly.
• For a wrong (not missing) value, read the precedence: multiple sets matched, and hierarchical precedence (higher/later wins) chose the winner — the dump shows the competing sets, so you trace which won and why (often an unintended wildcard match or a forgotten higher-level override).
• The present-but-missed contradiction (dump shows present, get misses) is the signature of a key mismatch (scope/naming/type, not timing) — redirecting debug from "value not set" to "get's key is wrong".
• The durable rule of thumb: debug configuration by dumping the pool for ground truth and reconciling it against expectation — for a missing value, classify the set/get mismatch (scope, naming, timing, or type, remembering config_db is type-parameterized so a perfectly-scoped, perfectly-named get still misses on a type mismatch that only the dump reveals); for a wrong value, read the precedence to find which competing set won and why; and use the checked get to localize the miss — never guess about the pool's contents when the dump shows them.

Next — Messaging Infrastructure: the next module turns to how a UVM testbench communicates — the reporting system. Every component emits messages — info, warnings, errors, fatals — and at scale this becomes a flood that must be controlled: filtered by verbosity, routed to logs, counted for pass/fail, and made actionable. The module opens with the messaging infrastructure: the report macros, severities, and the machinery that turns scattered prints into a managed, filterable, accountable reporting system.