This is a quick one about uvm_root class. This is uvm1.1d BTW. Things may be different in 1.2

uvm_top Link to heading

There is singelton of uvm_root class in uvm_root.svh

class uvm_root extends uvm_component;

  // Function: get()
  // Get the factory singleton
  //
  extern static function uvm_root get();

const uvm_root uvm_top = uvm_root::get();

public APIs Link to heading

There are few public API that can be called on the singelton object of uvm_root. Most famous one is probably run_test

  extern virtual task run_test (string test_name="");

  // Variable: top_levels
  //
  // This variable is a list of all of the top level components in UVM. It
  // includes the uvm_test_top component that is created by <run_test> as
  // well as any other top level components that have been instantiated
  // anywhere in the hierarchy.

  uvm_component top_levels[$];

which is called from global run_test

task run_test (string test_name="");
  uvm_root top;
  top = uvm_root::get();
  top.run_test(test_name);
endtask

Side note, run_test create the uvm_test_top object from factory.

task uvm_root::run_test(string test_name="");

  uvm_factory factory= uvm_factory::get();
  bit testname_plusarg;
  int test_name_count;
  string test_names[$];
  string msg;
  uvm_component uvm_test_top;
  ...
  ...
    $cast(uvm_test_top, factory.create_component_by_name(test_name,
          "", "uvm_test_top", null));

There are find and find_all functions that look up components from top level component in uvm_root.

  // Function: find

  extern function uvm_component find (string comp_match);

  // Function: find_all
  //
  // Returns the component handle (find) or list of components handles
  // (find_all) matching a given string. The string may contain the wildcards,
  // * and ?. Strings beginning with '.' are absolute path names. If optional
  // comp arg is provided, then search begins from that component down
  // (default=all components).

  extern function void find_all (string comp_match,
                                 ref uvm_component comps[$],
                                 input uvm_component comp=null);

function void uvm_root::find_all(string comp_match, ref uvm_component comps[$],
                                 input uvm_component comp=null);

  if (comp==null)
    comp = this;
  m_find_all_recurse(comp_match, comps, comp);

endfunction

function uvm_component uvm_root::find (string comp_match);
  uvm_component comp_list[$];

  find_all(comp_match,comp_list);

  if (comp_list.size() > 1)
    uvm_report_warning("MMATCH",
    $sformatf("Found %0d components matching '%s'. Returning first match, %0s.",
              comp_list.size(),comp_match,comp_list[0].get_full_name()), UVM_NONE);

  if (comp_list.size() == 0) begin
    uvm_report_warning("CMPNFD",
      {"Component matching '",comp_match,
       "' was not found in the list of uvm_components"}, UVM_NONE);
    return null;
  end

  return comp_list[0];
endfunction

Finally, there is print_topology usually called before test starting to show the hierarchy of components.

  // Function: print_topology
  //
  // Print the verification environment's component topology. The
  // ~printer~ is a <uvm_printer> object that controls the format
  // of the topology printout; a ~null~ printer prints with the
  // default output.

  extern function void print_topology  (uvm_printer printer=null);

How to get handle of test Link to heading

One cool feature of uvm_root is we can get handle to uvm_test_top through uvm_root.

uvm_test test = uvm_root::get().find("uvm_test_top");