Guide - Developing Reusable Verification Components

Never use uvm_config_db to pass individual parameters (one set() call per field). Bundle all agent parameters into a single configuration object. This makes the agent's interface explicit and prevents silent misconfiguration when parameters are added later.

Expose TLM Analysis Ports on the Agent

The monitor's analysis port should be promoted to the agent level. This allows scoreboards and coverage collectors in the environment to connect directly to the agent without reaching into its internals.

class axi_agent extends uvm_agent;
  uvm_analysis_port #(axi_transaction) ap; // Promoted from monitor

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    ap  = new("ap", this);
    mon = axi_monitor::type_id::create("mon", this);
    // ...
  endfunction

  function void connect_phase(uvm_phase phase);
    mon.ap.connect(this.ap); // Forward monitor's port outward
  endfunction
endclass

Guideline 3: Write Reusable Sequences

Sequences are the primary mechanism for stimulus reuse. A well-written sequence can be used as-is, extended, or composed into virtual sequences without modification.

Parameterize Sequences - Never Hardcode Values

Any value that varies between test scenarios - data payload, address ranges, burst counts - must be a rand field that tests constrain externally, not a constant embedded in the sequence body.

class axi_write_seq extends uvm_sequence #(axi_transaction);
  `uvm_object_utils(axi_write_seq)

  rand bit [31:0] base_addr;
  rand int unsigned num_transactions;

  constraint default_c {
    num_transactions inside {[1:16]};
    base_addr[1:0] == 2'b00; // Word-aligned
  }

  virtual task body();
    axi_transaction tx;
    repeat(num_transactions) begin
      `uvm_do_with(tx, { tx.addr == base_addr; tx.wr_rd == 1; })
    end
  endtask
endclass

A test applies its own constraints externally without touching the sequence class:

// In the test's run_phase - constrain and start the sequence
axi_write_seq seq;
seq = axi_write_seq::type_id::create("seq");
assert(seq.randomize() with { base_addr == 32'hA000_0000; num_transactions == 4; });
seq.start(env.agent.seqr);

Build Sequence Libraries, Not Monolithic Sequences

Break complex stimulus into small, single-purpose sequences that can be composed. A single 500-line sequence covering initialization, burst writes, and error injection is impossible to reuse partially. Three focused sequences can be combined in any order by any test.

// Small, single-purpose sequences
class axi_init_seq    extends uvm_sequence #(axi_transaction); ... endclass
class axi_write_seq   extends uvm_sequence #(axi_transaction); ... endclass
class axi_read_seq    extends uvm_sequence #(axi_transaction); ... endclass
class axi_err_inj_seq extends uvm_sequence #(axi_transaction); ... endclass

// Composed in a virtual sequence
class axi_full_test_seq extends uvm_sequence;
  virtual task body();
    `uvm_do(init_seq)
    `uvm_do(write_seq)
    `uvm_do(read_seq)
  endtask
endclass

Register sequences with `uvm_object_utils so the factory can override them. This allows a test to substitute a more constrained version of a sequence without modifying the environment.

Guideline 4: Use the Factory for All Component Creation

The UVM factory is the mechanism that makes component substitution possible without touching the original source files. A component that bypasses the factory cannot be overridden by downstream users.

Register Every Class with the Factory

Use `uvm_component_utils for components and `uvm_object_utils for objects and sequences. Without registration, factory override will silently fail.

class axi_driver extends uvm_driver #(axi_transaction);
  `uvm_component_utils(axi_driver)   // Registers with factory
  // ...
endclass

class axi_transaction extends uvm_sequence_item;
  `uvm_object_utils(axi_transaction) // Registers with factory
  // ...
endclass

Always Create Components and Objects via the Factory

Use type_id::create() everywhere - never new() directly. A direct new() call cannot be intercepted by a factory override.

// WRONG - bypasses the factory
axi_driver drv = new("drv", this);

// CORRECT - factory can substitute a different type
axi_driver drv = axi_driver::type_id::create("drv", this);

// 1. Define the callback class
class axi_driver_cbs extends uvm_callback;
  `uvm_object_utils(axi_driver_cbs)

  // Called before driving each transaction
  virtual task pre_drive(axi_driver drv, axi_transaction tx);
  endtask

  // Called after driving each transaction
  virtual task post_drive(axi_driver drv, axi_transaction tx);
  endtask
endclass

// 2. Register and invoke callbacks in the driver
class axi_driver extends uvm_driver #(axi_transaction);
  `uvm_component_utils(axi_driver)
  `uvm_register_cb(axi_driver, axi_driver_cbs)

  virtual task run_phase(uvm_phase phase);
    forever begin
      seq_item_port.get_next_item(req);
      `uvm_do_callbacks(axi_driver, axi_driver_cbs, pre_drive(this, req))
      drive_transaction(req);
      `uvm_do_callbacks(axi_driver, axi_driver_cbs, post_drive(this, req))
      seq_item_port.item_done();
    end
  endtask

  // Rest of the code (drive_transaction task, etc.)
endclass

// Custom callback for error injection
class err_inject_cb extends axi_driver_cbs;
  virtual task pre_drive(axi_driver drv, axi_transaction tx);
    if ($urandom_range(0,9) == 0)
      tx.addr[1:0] = 2'b11; // Force misaligned address
  endtask
endclass

// In the test:
err_inject_cb cb = new("cb");
uvm_callbacks #(axi_driver, axi_driver_cbs)::add(env.agent.drv, cb);

// WRONG - hardcoded absolute path breaks in any other testbench
uvm_config_db #(axi_agent_cfg)::set(null, "uvm_test_top.env.axi_agent", "cfg", my_cfg);

// CORRECT - set from the context of the component that owns it
uvm_config_db #(axi_agent_cfg)::set(this, "axi_agent", "cfg", my_cfg);

class axi_monitor extends uvm_monitor;
  `uvm_component_utils(axi_monitor)

  uvm_analysis_port #(axi_transaction) ap;
  virtual axi_if vif;

  virtual task run_phase(uvm_phase phase);
    axi_transaction tx;
    forever begin
      @(posedge vif.clk);
      if (vif.valid && vif.ready) begin
        tx = axi_transaction::type_id::create("tx");
        tx.addr = vif.addr;
        tx.data = vif.data;
        // Broadcast to all connected subscribers
        ap.write(tx);
      end
    end
  endtask

  // Rest of the code (constructor, build_phase, protocol assertions)
endclass

class axi_coverage extends uvm_subscriber #(axi_transaction);
  `uvm_component_utils(axi_coverage)

  axi_agent_cfg cfg;
  axi_transaction tx;

  covergroup axi_cg;
    cp_op:    coverpoint tx.wr_rd   { bins write = {1}; bins read = {0}; }
    cp_burst: coverpoint tx.burst_len;
    cp_cross: cross cp_op, cp_burst;
  endgroup

  function void write(axi_transaction t);
    if (cfg.en_coverage) begin
      tx = t;
      axi_cg.sample();
    end
  endfunction

  // Rest of the code (constructor, build_phase to fetch cfg)
endclass

$display("AXI write to addr %0h", tx.addr);

`uvm_info("AXI_DRV", $sformatf("Write to addr %0h", tx.addr), UVM_HIGH)