Factory Overrides in Practice

📋 Quick Review — How the Factory Works

The factory maps registered class types to class wrappers. When type_id::create() is called, the factory checks its override table before constructing. If an override is registered, the substitute type is constructed instead. The caller receives the result via a base-class handle — polymorphism handles the rest.

Two prerequisites must be satisfied for any override to work:

1. Both classes must be registered with the factory using `uvm_component_utils or `uvm_object_utils.
2. The substitute class must extend the original class (directly or transitively). A factory override is not a general type substitution — it requires a valid is-a relationship.

📋 Type Override in Practice

A type override replaces every instance of the original type with the substitute type across the entire testbench hierarchy. Use it when you want to globally change the behaviour of a component for a specific test without touching any environment source.

// ── fast_driver extends base_driver — required for override
class fast_driver extends base_driver;
  `uvm_component_utils(fast_driver)
  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction
  task run_phase(uvm_phase phase);
    // faster drive implementation
  endtask
endclass

// ── In test build_phase — BEFORE creating env ─────────────
function void build_phase(uvm_phase phase);
  super.build_phase(phase);

  // ① Register override — must be before create()
  base_driver::type_id::set_type_override(
    fast_driver::get_type());

  // Optional: replace=1 forces override even if one already exists
  base_driver::type_id::set_type_override(
    fast_driver::get_type(), 1);

  // ② Now create env — fast_driver replaces base_driver everywhere
  m_env = my_env::type_id::create("m_env", this);
endfunction

📋 Instance Override in Practice

An instance override targets a specific component by its hierarchy path. All other instances of the same type are unaffected. Use it when only one agent in a multi-agent environment needs a specialised component.

// ── Target only the APB agent's driver, leave others alone
function void build_phase(uvm_phase phase);
  super.build_phase(phase);

  // Replace ONLY the driver at this specific path
  base_driver::type_id::set_inst_override(
    error_driver::get_type(),
    "uvm_test_top.m_env.m_apb_agent.m_drv");

  // Wildcard: replace all drivers inside apb_agent subtree
  base_driver::type_id::set_inst_override(
    error_driver::get_type(),
    "uvm_test_top.m_env.m_apb_agent.*");

  m_env = my_env::type_id::create("m_env", this);
endfunction

📋 Abstract / Concrete Pattern

The most powerful factory pattern: the environment is written against an abstract (do-nothing) base class. Tests activate concrete implementations via type override. This completely separates environment architecture from protocol-specific implementation.

// ── Abstract base — protocol-independent, does nothing ───
class base_driver extends uvm_driver#(bus_seq_item);
  `uvm_component_utils(base_driver)
  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction
  task run_phase(uvm_phase phase);
    // Default: raise/drop immediately — no stimulus
    phase.raise_objection(this);
    `uvm_info("DRV", "Abstract driver — no stimulus generated", UVM_LOW)
    phase.drop_objection(this);
  endtask
endclass

// ── Concrete APB implementation ───────────────────────────
class apb_driver extends base_driver;
  `uvm_component_utils(apb_driver)
  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction
  task run_phase(uvm_phase phase);
    // Full APB protocol drive implementation
    forever begin
      bus_seq_item item;
      seq_item_port.get_next_item(item);
      // ... drive APB signals ...
      seq_item_port.item_done();
    end
  endtask
endclass

// ── APB test — wires the concrete driver ──────────────────
class apb_test extends uvm_test;
  `uvm_component_utils(apb_test)
  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction
  function void build_phase(uvm_phase phase);
    // One line activates the concrete APB driver everywhere
    base_driver::type_id::set_type_override(apb_driver::get_type());
    m_env = my_env::type_id::create("m_env", this);
  endfunction
endclass

📋 Overriding Sequences

Sequences are objects — the same override mechanism applies. A derived test can substitute a specialised sequence for the standard one without changing the test’s run_phase structure.

// ── Base sequence for normal data transfers ───────────────
class data_seq extends uvm_sequence#(bus_seq_item);
  `uvm_object_utils(data_seq)
  function new(string name="data_seq"); super.new(name); endfunction
  task body();
    // normal write/read transfers
  endtask
endclass

// ── Derived sequence injects errors ───────────────────────
class error_seq extends data_seq;
  `uvm_object_utils(error_seq)
  function new(string name="error_seq"); super.new(name); endfunction
  task body();
    super.body();            // run normal transfers first
    inject_errors();          // then add error cases
  endtask
endclass

// ── Error test — overrides sequence, keeps run_phase ──────
class error_test extends base_test;
  `uvm_component_utils(error_test)
  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction
  function void build_phase(uvm_phase phase);
    // Substitute error_seq for data_seq — run_phase unchanged
    data_seq::type_id::set_type_override(error_seq::get_type());
    super.build_phase(phase);   // builds env normally
  endfunction
  // run_phase inherited from base_test — creates data_seq which is now error_seq
endclass

📋 Command-Line Overrides

The factory supports overrides directly from the simulator command line — no source code changes or recompilation required. This is the most powerful use of the factory for regression and debug.

// ── Type override from command line ──────────────────────
// +uvm_set_type_override=OriginalType,SubstituteType
// Example:
// vsim tb_top +uvm_set_type_override=base_driver,fast_driver

// ── Instance override from command line ───────────────────
// +uvm_set_inst_override=OriginalType,SubstituteType,PathString
// Example:
// vsim tb_top +uvm_set_inst_override=base_driver,error_driver,
//             uvm_test_top.m_env.m_apb_agent.m_drv

// ── Select test class from command line ───────────────────
// +UVM_TESTNAME=test_class_name
// Overrides the string argument to run_test()
// vsim tb_top +UVM_TESTNAME=apb_test

Command-line overrides apply after any in-code overrides. They allow regression scripts to sweep through component variants without modifying testbench source — the same compiled testbench can run with different drivers, sequences, or monitors.

📋 When to Use Each Override Type

📋 Factory Debug

// ── Print full factory state — call from end_of_elaboration
function void end_of_elaboration_phase(uvm_phase phase);
  uvm_factory::get().print(1);     // 1 = show overrides
  uvm_top.print_topology();         // show component tree
endfunction

// ── Debug what type would be created at a specific path ───
uvm_factory::get().debug_create_by_type(
  base_driver::get_type(),
  "uvm_test_top.m_env.m_apb_agent",
  "m_drv");

// ── Common factory debug checklist ───────────────────────
// 1. Is the substitute class registered? (`uvm_component_utils present?)
// 2. Does substitute extend original? ($cast fails if not)
// 3. Was override set before create() was called?
// 4. If instance override, is the path string exactly right?
// 5. Use +UVM_FACTORY_TRACE command-line flag for per-create logging

📋 Quick Reference