uvm_root & the Singleton Pattern

// ── Get the singleton ─────────────────────────────────────────────────
uvm_root root = uvm_root::get();   // always returns the same instance
 
// ── Find a component anywhere in the hierarchy ────────────────────────
uvm_component found;
found = root.find("uvm_test_top.env.apb_agent.drv");
if (found != null) begin
`uvm_info("ROOT",$sformatf("Found: %s type=%s",
found.get_full_name(), found.get_type_name()),UVM_LOW)
end
 
// ── Find all components matching a wildcard path ──────────────────────
uvm_component q[$];
root.find_all("uvm_test_top.*.drv", q);   // returns all drivers in any agent
foreach(q[i])
`uvm_info("ROOT",q[i].get_full_name(),UVM_LOW)
 
// ── Set / get simulation timeout ──────────────────────────────────────
// Timeout fires if no objections are raised/dropped after this time
root.set_timeout(100ms, 1);   // 100ms timeout, fatal=1 (uvm_fatal on expiry)
root.set_timeout(500ns, 0);   // 500ns timeout, fatal=0 (uvm_error, simulation continues)
 
// ── Print the complete component hierarchy ────────────────────────────
root.print_topology();               // default: tree format to transcript
root.print_topology(uvm_default_printer);  // explicit printer
 
// ── Check component count in hierarchy ───────────────────────────────
`uvm_info("ROOT",$sformatf("Root has %0d direct children",
root.get_num_children()),UVM_LOW)
 
// ── Access via run_test() — the most common usage ─────────────────────
// run_test() is actually a shorthand for:
// uvm_root::get().run_test("my_test");
// Both are equivalent — use whichever reads more clearly

// ── In start_of_simulation_phase — hierarchy is fully built ──────────
function void start_of_simulation_phase(uvm_phase phase);
uvm_root      root = uvm_root::get();
uvm_component drv;
uvm_component all_comps[$];
super.start_of_simulation_phase(phase);
 
// Print the entire component hierarchy — great for debug
root.print_topology();
 
// Find a specific component by exact path
drv = root.find("uvm_test_top.env.apb_agent.drv");
if (drv == null)
`uvm_error("TOPO","Driver not found — check agent naming")
else
`uvm_info("TOPO",$sformatf("Found driver: %s",drv.get_type_name()),UVM_LOW)
 
// Find ALL monitors across ALL agents using wildcard
root.find_all("uvm_test_top.*.mon", all_comps);
`uvm_info("TOPO",$sformatf("Found %0d monitors total",all_comps.size()),UVM_LOW)
foreach(all_comps[i])
`uvm_info("TOPO",$sformatf("  Monitor: %s",all_comps[i].get_full_name()),UVM_LOW)
endfunction
 
// ── Timeout: kill simulation if it runs too long ─────────────────────
function void build_phase(uvm_phase phase);
super.build_phase(phase);
// Set a 1ms timeout — prevents hung simulations in regression
uvm_root::get().set_timeout(1ms, 1);   // fatal=1: uvm_fatal fires on expiry
`uvm_info("TEST","Simulation timeout set to 1ms",UVM_LOW)
endfunction

// ── Custom singleton: global transaction counter ──────────────────────
// Pattern: private constructor + static get() method
class txn_counter;
 
// The single instance — static class variable
static txn_counter m_inst = null;
 
// Instance data
int total = 0;
int errors = 0;
int warnings = 0;
 
// "Private" constructor — protected by convention, not language enforcement
// In SV, we can't truly enforce privacy, but we document the intent
function new(); endfunction
 
// ── The critical get() method ─────────────────────────────────────
static function txn_counter get();
if (m_inst == null)
m_inst = new();   // lazy initialization — created on first call only
return m_inst;
endfunction
 
// ── Instance methods ──────────────────────────────────────────────
function void increment(bit is_error = 0, bit is_warning = 0);
total++;
if (is_error)   errors++;
if (is_warning) warnings++;
endfunction
 
function void report();
$display("=== Transaction Counter Report ===");
$display("  Total:    %0d", total);
$display("  Errors:   %0d", errors);
$display("  Warnings: %0d", warnings);
endfunction
endclass
 
// ── Usage from anywhere — monitor, scoreboard, sequence ───────────────
// Monitor:
txn_counter::get().increment(0, 0);   // normal transaction
 
// Scoreboard (on mismatch):
txn_counter::get().increment(1, 0);   // error
 
// Test's report_phase:
txn_counter::get().report();
 
// All three access THE SAME counter object — no passing handles needed

// Sequences don't have a parent component handle — they can't walk up the hierarchy.
// But uvm_root::get().find() gives them access to any component.
 
class corner_case_seq extends uvm_sequence#(apb_txn);
`uvm_object_utils(corner_case_seq)
function new(string n="corner_case_seq"); super.new(n); endfunction
 
task body();
uvm_component scb_comp;
apb_scoreboard scb;
 
// Find the scoreboard by path — uvm_root makes this possible from a sequence
scb_comp = uvm_root::get().find("uvm_test_top.env.scb");
if (scb_comp == null) begin
`uvm_fatal("SEQ","Cannot find scoreboard — check env topology")
return;
end
 
// Downcast to the actual scoreboard type
if (!$cast(scb, scb_comp)) begin
`uvm_fatal("SEQ","Component is not apb_scoreboard")
return;
end
 
// Now configure scoreboard mode before sending transactions
scb.set_check_mode(apb_scoreboard::CHECK_STRICT);
`uvm_info("SEQ","Scoreboard configured for strict mode",UVM_LOW)
 
// Now run the corner-case transactions
repeat(10) begin
apb_txn t = apb_txn::type_id::create("t");
start_item(t);
void'(t.randomize());
finish_item(t);
end
endtask
endclass

// How UVM implements the singleton — simplified from uvm_root source
 
class uvm_root extends uvm_component;
 
// The one-and-only instance
local static uvm_root m_inst;
 
// Protected/local constructor — cannot be called from outside
// (in real UVM source it's protected; shown as local here for clarity)
local function new();
super.new("__top__", null);  // name="__top__", no parent
endfunction
 
// The ONLY way to get uvm_root — lazy initialization
static function uvm_root get();
if (m_inst == null) begin
m_inst = new();             // created ONCE — ever
end
return m_inst;
endfunction
 
// What run_test("my_test") actually does:
task run_test(string test_name = "");
// 1. Create the test class via factory
// 2. Set up objection mechanism
// 3. Start phase execution engine
// 4. Wait for phases to complete
// 5. Call $finish
endtask
endclass
 
// The global run_test() shorthand is just:
// task run_test(string test_name = "");
//   uvm_root::get().run_test(test_name);
// endtask

// ── Bug 1: find() in build_phase — too early ──────────────────────────
// ❌ WRONG — driver may not exist yet
function void build_phase(uvm_phase phase);
super.build_phase(phase);
drv = uvm_root::get().find("uvm_test_top.env.apb_agent.drv");
// drv is null — agent hasn't been built yet
endfunction
 
// ✓ CORRECT — use start_of_simulation_phase (hierarchy is complete)
function void start_of_simulation_phase(uvm_phase phase);
super.start_of_simulation_phase(phase);
drv = uvm_root::get().find("uvm_test_top.env.apb_agent.drv");
if (drv == null) `uvm_fatal("TOPO","Driver not found — check naming")
endfunction
 
// ── Bug 2: Singleton custom class with static initializer issues ───────
// ❌ WRONG — calling new() directly creates a SECOND instance
class my_manager;
static my_manager m_inst;
function new(); endfunction        // public constructor — anyone can call this
static function my_manager get();
if(m_inst==null) m_inst=new(); return m_inst;
endfunction
endclass
 
my_manager a = my_manager::get();    // ← correct — singleton
my_manager b = new();                 // ← WRONG — creates second instance!
// a and b are different objects — a == b is 0
 
// ── Bug 3: set_timeout() in run_phase — too late ──────────────────────
// ❌ WRONG — timeout mechanism starts at beginning of run_phase
task run_phase(uvm_phase phase);
#100ns;
uvm_root::get().set_timeout(50ns, 1);  // set AFTER 100ns have passed
// timeout fires immediately — 50ns already expired
endtask
 
// ✓ CORRECT — set timeout in build_phase or start_of_simulation_phase
function void build_phase(uvm_phase phase);
super.build_phase(phase);
uvm_root::get().set_timeout(1ms, 1);
endfunction
 
// ── Bug 4: find() path case sensitivity ───────────────────────────────
// find() is CASE SENSITIVE
root.find("uvm_test_top.Env.apb_agent.drv");   // ← "Env" with capital E → null!
root.find("uvm_test_top.env.apb_agent.drv");   // ← correct case → returns handle

// uvm_root_demo.sv — uvm_root and singleton pattern demonstration
// Questa : vlog -sv uvm_root_demo.sv && vsim -c root_demo_top -do "run -all; quit"
// VCS    : vcs -sverilog -ntb_opts uvm uvm_root_demo.sv && ./simv
// Xcelium: xrun -sv -uvm uvm_root_demo.sv -input "run; exit"
 
`include "uvm_macros.svh"
import uvm_pkg::*;
 
// ── Custom singleton following UVM pattern ─────────────────────────────
class sim_stats;
local static sim_stats m_inst = null;
int total_txns = 0;
int errors = 0;
function new(); endfunction
static function sim_stats get();
if(m_inst==null) m_inst=new(); return m_inst;
endfunction
function void record(bit err=0); total_txns++; if(err) errors++; endfunction
function void print_report();
$display("=== Simulation Stats (singleton) ===");
$display("  Total: %0d  Errors: %0d", total_txns, errors);
endfunction
endclass
 
// ── Simple child component ─────────────────────────────────────────────
class my_driver extends uvm_component;
`uvm_component_utils(my_driver)
function new(string n, uvm_component p); super.new(n,p); endfunction
task run_phase(uvm_phase phase);
sim_stats::get().record(0);
sim_stats::get().record(1);   // simulate an error
sim_stats::get().record(0);
endtask
endclass
 
class my_env extends uvm_env;
`uvm_component_utils(my_env)
my_driver drv;
function new(string n, uvm_component p); super.new(n,p); endfunction
function void build_phase(uvm_phase p);
super.build_phase(p);
drv = my_driver::type_id::create("drv",this);
endfunction
endclass
 
class root_demo_test extends uvm_test;
`uvm_component_utils(root_demo_test)
my_env env;
function new(string n, uvm_component p); super.new(n,p); endfunction
 
function void build_phase(uvm_phase phase);
super.build_phase(phase);
env = my_env::type_id::create("env",this);
uvm_root::get().set_timeout(1ms, 1);
`uvm_info("TEST",$sformatf("uvm_root path: '%s'",
uvm_root::get().get_full_name()),UVM_NONE)
endfunction
 
function void start_of_simulation_phase(uvm_phase phase);
uvm_component found;
uvm_component all[$];
super.start_of_simulation_phase(phase);
 
`uvm_info("TEST","=== Topology ===",UVM_NONE)
uvm_root::get().print_topology();
 
found = uvm_root::get().find("uvm_test_top.env.drv");
`uvm_info("TEST",$sformatf("find(drv) = %s",
found!=null ? found.get_type_name() : "NULL"),UVM_NONE)
 
uvm_root::get().find_all("uvm_test_top.*", all);
`uvm_info("TEST",$sformatf("find_all(uvm_test_top.*) found %0d",all.size()),UVM_NONE)
 
// Verify singleton — both calls return same object
`uvm_info("TEST",$sformatf("sim_stats singleton: %s",
(sim_stats::get() === sim_stats::get()) ?
"same instance (correct)" : "different instance (BUG)"),UVM_NONE)
endfunction
 
task run_phase(uvm_phase phase);
phase.raise_objection(this);
#10ns;
phase.drop_objection(this);
endtask
 
function void report_phase(uvm_phase phase);
super.report_phase(phase);
sim_stats::get().print_report();
endfunction
endclass
 
module root_demo_top;
initial run_test("root_demo_test");
endmodule
 
// EXPECTED OUTPUT (abridged):
// TEST: uvm_root path: ''  (empty string — root has no name)
// TEST: === Topology ===
// UVM_INFO: uvm_test_top [root_demo_test]
//   env [my_env]
//     drv [my_driver]
// TEST: find(drv) = my_driver
// TEST: find_all(uvm_test_top.*) found 2  (env and drv)
// TEST: sim_stats singleton: same instance (correct)
// === Simulation Stats (singleton) ===
//   Total: 3  Errors: 1