UVM Root [uvm_root]

What is uvm_root ?

uvm_root is a singleton class that serves as the top-level container for all UVM components in a verification environment whose instance is called uvm_top. It is automatically created when UVM is initialized and is available throughout the entire simulation. Users should not create any other instance of uvm_root !

Class Hierarchy

Implicit Top-Level

uvm_top is the implicit top-level component and any component whose parent is not specified becomes a child of uvm_top.

class my_env extends uvm_env;
	`uvm_component_utils (my_env)

	// Note that if parent is not explicitly passed during creation, it will be null
	function new(string name = "my_env", uvm_component parent = null);
		super.new(name, parent);
	endfunction

endclass

class my_test extends uvm_test;
	`uvm_component_utils (my_test)

	my_env 		m_env_1;
	my_env 		m_env_2;
	...

	virtual function void build_phase(uvm_phase phase);
		super.build_phase(phase);

		// Parent is set to my_test 
		m_env_1 = my_env::type_id::create("m_env_1", this);

		// Parent is null, and hence set to uvm_top
		m_env_2 = my_env::type_id::create("m_env_2");
	endfunction
endclass

Search Functionality

uvm_top instance can be used to search for components by their full hierarchical name in a testbench using wildcards. The component hierarchy will be searched in top to bottom fashion in alphanumeric order. The functions find() and findall() can be used to return component handles that match the provided wildcard pattern.

class my_test extends uvm_test;
	`uvm_component_utils (my_test)

	my_env 		m_env;

	virtual function void build_phase(uvm_phase phase);
		super.build_phase(phase);
	
		m_env = my_env::type_id::create("m_env", this);		
	endfunction

	virtual function void end_of_elaboration_phase(uvm_phase phase);
		uvm_component 	comp;
		uvm_component 	comp_q [$];

		super.end_of_elaboration_phase(phase);

		// Gets handle to the driver indicated by the path
		comp = uvm_top.find("m_env.m_agent.m_driver");

		// Gets the first handle to the driver that matches the pattern
		comp = uvm_top.find("*apb_driver*");
		
		// Gets queue of all handles that match the pattern
		comp_q = uvm_top.find_all("*apb_driver*");

		foreach (comp_q[i]) begin
			`uvm_info (get_type_name(), $sformatf("Found component %s", comp_q[i].get_full_name()), UVM_LOW)
		end

	endfunction
endclass

Report Configuration

uvm_top can set a global report verbosity which affects verbosity for all components in simulation. Its reporting mechanism is also accessible from anywhere outside uvm_component, like modules, sequences, etc.

class my_test extends uvm_test;
	
	...

	virtual function void build_phase(uvm_phase phase);
		super.build_phase(phase);

		uvm_top.set_report_verbosity_level_hier(UVM_HIGH);
	endfunction
endclass

Also note that the name of uvm_top is set to empty string "" so that it doesn't appear in the full hierarchical name of child components. Another common usage is while setting or getting an object in configuration database using uvm_config_db.

// Set m_cfg to the top level and let everything else beneath it have access
uvm_config_db #(my_cfg)::set(uvm_root::get(), "*", "my_cfg", m_cfg);

if (! uvm_config_db #(my_cfg)::get(uvm_root::get(), "*", "my_cfg", m_cfg))
	`uvm_fatal (get_type_name(), $sformatf("[ERROR] my_cfg not found in config_db !"))