Part 2 · Phases & Lifecycle · Intermediate

Elaboration Debug: Triage Before run_phase

Symptom-first debug for elaboration and start_of_simulation failures — topology surprises, sanity fatals, and banner gaps.

Symptom matrix

Elaboration failures usually point back to build or connect — use this matrix before investigating run_phase.

diagram

[PHASE][UVM] elaboration triage matrix

SYMPTOM                              LIKELY CAUSE
──────────────────────────────────────────────────────────────
ELAB fatal: agent count mismatch     build loop vs cfg bitmap
ELAB fatal: sb enabled but null      conditional build bug
topology missing component           build never created it
topology wrong type                  factory override issue
SANITY fatal: vif null               config_db get failed in build
no RUN_BANNER in log                 start_of_simulation override typo
hang before time 0                   illegal wait in function phase

systemverilog

// start_of_simulation typo — override never runs, no banner:
function void start_of_simulation(uvm_phase phase);  // WRONG NAME
  super.start_of_simulation_phase(phase);
endfunction

Key takeaways

Elaboration debug starts with topology print, not run logs.
Sanity fatals are gifts — they fail before expensive run time.
Missing banner often means phase method signature typo.

Common pitfalls

Jumping to run_phase debug when elaboration fatal already fired.
Disabling sanity asserts to 'get tests running'.
Ignoring topology print in log — scroll past the answer.

Deterministic debug toolkit

Ordered checklist for elaboration and start failures — fast iteration with smoke tests.

Debug recipe

diagram

[PHASE] elaboration debug commands

simv +UVM_TESTNAME=smoke_test \
     +UVM_PHASE_TRACE \
     +UVM_VERBOSITY=UVM_MEDIUM

Steps:
  1) grep ELAB / SANITY / FATAL before first time advance
  2) find print_topology block — diff vs expected
  3) grep RUN_BANNER / META — confirm start_of_simulation ran
  4) if hang at 0 time: grep wait/# in function phases
  5) trace back to build/connect logs for missing component

systemverilog

function void end_of_elaboration_phase(uvm_phase phase);
  super.end_of_elaboration_phase(phase);
  elaboration_check_count++;
  uvm_top.print_topology();
  `uvm_info("ELAB_DBG",
    $sformatf("checks=%0d comp=%s", elaboration_check_count, get_full_name()),
    UVM_LOW)
endfunction

Reproduction checklist

Run smoke_test with build+connect logging enabled.
Capture topology print from end_of_elaboration.
Confirm RUN_BANNER and META lines present.
If sanity fatal: read message, jump to build_phase cause.
If hang: search all function phases for # and wait.
Fix at build/connect source, rerun exact plusarg combo.

Keep elaboration asserts enabled in CI — never silence globally.
Store topology print as CI artifact for failed regressions.
Compare topology between passing smoke and failing scenario.

diagram

[PHASE][UVM] elaboration pass criteria

smoke test shows:
  ✓ topology matches cfg agent bitmap
  ✓ RUN_BANNER with correct seed
  ✓ no ELAB fatal/error
  ✓ time still 0 at run_phase entry log