UVM Factory

Using the factory involves three basic operations

We’ll briefly cover each of these steps here.  More reference information can be found at Utility Macros, uvm_component_registry #(T,Tname), uvm_object_registry #(T,Tname), uvm_component.

1 -- Registering objects and component types with the factory

When defining uvm_object and uvm_component-based classes, simply invoke the appropriate macro.  Use of macros are required to ensure portability across different vendors’ simulators.

Objects that are not parameterized are declared as

class packet extends uvm_object;
  `uvm_object_utils(packet)
endclass

class packetD extends packet;
  `uvm_object_utils(packetD)
endclass

Objects that are parameterized are declared as

class packet #(type T=int, int WIDTH=32) extends uvm_object;
  `uvm_object_param_utils(packet #(T,WIDTH))
 endclass

Components that are not parameterized are declared as

class comp extends uvm_component;
  `uvm_component_utils(comp)
endclass

Components that are parameterized are declared as

class comp #(type T=int, int WIDTH=32) extends uvm_component;
  `uvm_component_param_utils(comp #(T,WIDTH))
endclass

The `uvm_*_utils macros for simple, non-parameterized classes will register the type with the factory and define the get_type, get_type_name, and create virtual methods inherited from uvm_object.  It will also define a static type_name variable in the class, which will allow you to determine the type without having to allocate an instance.

The `uvm_*_param_utils macros for parameterized classes differ from `uvm_*_utils classes in the following ways:

• The get_type_name method and static type_name variable are not defined.  You will need to implement these manually.
• A type name is not associated with the type when registeriing with the factory, so the factory’s *_by_name operations will not work with parameterized classes.
• The factory’s print, debug_create_by_type, and debug_create_by_name methods, which depend on type names to convey information, will list parameterized types as <unknown>.

It is worth noting that environments that exclusively use the type-based factory methods (*_by_type) do not require type registration.  The factory’s type-based methods will register the types involved “on the fly,” when first used.  However, registering with the `uvm_*_utils macros enables name-based factory usage and implements some useful utility functions.

2 -- Designing components that defer creation to the factory

Having registered your objects and components with the factory, you can now make requests for new objects and components via the factory.  Using the factory instead of allocating them directly (via new) allows different objects to be substituted for the original without modifying the requesting class.  The following code defines a driver class that is parameterized.

class driverB #(type T=uvm_object) extends uvm_driver;

  // parameterized classes must use the _param_utils version
  `uvm_component_param_utils(driverB #(T))

  // our packet type; this can be overridden via the factory
  T pkt;

  // standard component constructor
  function new(string name, uvm_component parent=null);
    super.new(name,parent);
  endfunction

  // get_type_name not implemented by macro for parameterized classes
  const static string type_name = {"driverB #(",T::type_name,")"};
  virtual function string get_type_name();
    return type_name;
  endfunction

  // using the factory allows pkt overrides from outside the class
  virtual function void build_phase(uvm_phase phase);
    pkt = packet::type_id::create("pkt",this);
  endfunction

  // print the packet so we can confirm its type when printing
  virtual function void do_print(uvm_printer printer);
    printer.print_object("pkt",pkt);
  endfunction

endclass

For purposes of illustrating type and instance overrides, we define two subtypes of the driverB class.  The subtypes are also parameterized, so we must again provide an implementation for uvm_object::get_type_name, which we recommend writing in terms of a static string constant.

class driverD1 #(type T=uvm_object) extends driverB #(T);

  `uvm_component_param_utils(driverD1 #(T))

  function new(string name, uvm_component parent=null);
    super.new(name,parent);
  endfunction

  const static string type_name = {"driverD1 #(",T::type_name,")"};
  virtual function string get_type_name();
    ...return type_name;
  endfunction

endclass

class driverD2 #(type T=uvm_object) extends driverB #(T);

  `uvm_component_param_utils(driverD2 #(T))

  function new(string name, uvm_component parent=null);
    super.new(name,parent);
  endfunction

  const static string type_name = {"driverD2 #(",T::type_name,")"};
  virtual function string get_type_name();
    return type_name;
  endfunction

endclass

// typedef some specializations for convenience
typedef driverB  #(packet) B_driver;   // the base driver
typedef driverD1 #(packet) D1_driver;  // a derived driver
typedef driverD2 #(packet) D2_driver;  // another derived driver

Next, we’ll define a agent component, which requires a utils macro for non-parameterized types.  Before creating the drivers using the factory, we override driver0’s packet type to be packetD.

class agent extends uvm_agent;

  `uvm_component_utils(agent)
  ...
  B_driver driver0;
  B_driver driver1;

  function new(string name, uvm_component parent=null);
    super.new(name,parent);
  endfunction

  virtual function void build_phase(uvm_phase phase);

    // override the packet type for driver0 and below
    packet::type_id::set_inst_override(packetD::get_type(),"driver0.*");

    // create using the factory; actual driver types may be different
    driver0 = B_driver::type_id::create("driver0",this);
    driver1 = B_driver::type_id::create("driver1",this);

  endfunction

endclass

Finally we define an environment class, also not parameterized.  Its build method shows three methods for setting an instance override on a grandchild component with relative path name, agent1.driver1, all equivalent.

class env extends uvm_env;

  `uvm_component_utils(env)

  agent agent0;
  agent agent1;

  function new(string name, uvm_component parent=null);
    super.new(name,parent);
  endfunction

  virtual function void build_phase(uvm_phase phase);

    // three methods to set an instance override for agent1.driver1
    // - via component convenience method...
    set_inst_override_by_type("agent1.driver1",
                              B_driver::get_type(),
                              D2_driver::get_type());

    // - via the component's proxy (same approach as create)...
    B_driver::type_id::set_inst_override(D2_driver::get_type(),
                                         "agent1.driver1",this);

    // - via a direct call to a factory method...
    factory.set_inst_override_by_type(B_driver::get_type(),
                                      D2_driver::get_type(),
                                      {get_full_name(),".agent1.driver1"});

    // create agents using the factory; actual agent types may be different
    agent0 = agent::type_id::create("agent0",this);
    agent1 = agent::type_id::create("agent1",this);

  endfunction

  // at end_of_elaboration, print topology and factory state to verify
  virtual function void end_of_elaboration_phase(uvm_phase phase);
    uvm_top.print_topology();
  endfunction

  virtual task run_phase(uvm_phase phase);
    #100 global_stop_request();
  endfunction

endclass

3 -- Configuring the factory with type and instance overrides

In the previous step, we demonstrated setting instance overrides and creating components using the factory within component classes.  Here, we will demonstrate setting overrides from outside components, as when initializing the environment prior to running the test.

module top;

  env env0;

  initial begin

    // Being registered first, the following overrides take precedence
    // over any overrides made within env0's construction & build.

    // Replace all base drivers with derived drivers...
    B_driver::type_id::set_type_override(D_driver::get_type());

    // ...except for agent0.driver0, whose type remains a base driver.
    //     (Both methods below have the equivalent result.)

    // - via the component's proxy (preferred)
    B_driver::type_id::set_inst_override(B_driver::get_type(),
                                         "env0.agent0.driver0");

    // - via a direct call to a factory method
    factory.set_inst_override_by_type(B_driver::get_type(),
                                      B_driver::get_type(),
                                  {get_full_name(),"env0.agent0.driver0"});

    // now, create the environment; our factory configuration will
    // govern what topology gets created
    env0 = new("env0");

    // run the test (will execute build phase)
    run_test();

  end

endmodule

When the above example is run, the resulting topology (displayed via a call to uvm_root::print_topology in env’s uvm_component::end_of_elaboration_phase method) is similar to the following:

# UVM_INFO @ 0 [RNTST] Running test ...
# UVM_INFO @ 0 [UVMTOP] UVM testbench topology:
# ----------------------------------------------------------------------
# Name                     Type                Size                Value
# ----------------------------------------------------------------------
# env0                     env                 -                  env0@2
#   agent0                 agent               -                agent0@4
#     driver0              driverB #(packet)   -               driver0@8
#       pkt                packet              -                  pkt@21
#     driver1              driverD #(packet)   -              driver1@14
#       pkt                packet              -                  pkt@23
#   agent1                 agent               -                agent1@6
#     driver0              driverD #(packet)   -              driver0@24
#       pkt                packet              -                  pkt@37
#     driver1              driverD2 #(packet)  -              driver1@30
#       pkt                packet              -                  pkt@39
# ----------------------------------------------------------------------