Virtual Interfaces

📋 The Two-Kingdom Problem

SystemVerilog has two fundamentally different worlds that cannot directly communicate with each other:

• The static world (modules, interfaces, always blocks) — this is the synthesisable world. It describes hardware with fixed structure, exists for the entire simulation, and has direct connections to DUT ports. Modules are elaborated at compile time.
• The dynamic world (classes, objects, tasks) — this is the object-oriented world where UVM lives. Classes are instantiated at runtime, garbage-collected when no longer needed, and cannot directly reference signals in the static world.

The problem: your UVM driver (dynamic class world) needs to drive DUT signals (static module world). A class object cannot have a wire or port declaration, and cannot make hierarchical references to module signals.

📋 What a Virtual Interface Is

A virtual interface is a SystemVerilog language construct: a variable whose type is virtual <interface_name>. It acts as a handle — a reference — to an actual interface instance in the static world. It is not a copy of the interface; it is a pointer to the original.

The word “virtual” here does not mean the same as virtual in object-oriented programming (polymorphism). It is the IEEE 1800 committee’s term for “a reference to an interface instance that can be used inside a class.” Think of it as a pointer to a module-world object, usable from the class world.

// ── Actual interface (static, in module world) ────────────
interface apb_if (
  input logic PCLK,
  input logic PRESETn
);
  logic [11:0] PADDR;
  logic        PSELx, PENABLE, PWRITE, PREADY, PSLVERR;
  logic [31:0] PWDATA, PRDATA;
  logic [3:0]  PSTRB;
endinterface

// ── Virtual interface type declaration (in class world) ───
// This is just a type — no memory allocated yet
virtual apb_if vif;           // handle — starts as null

// ── After assignment, use it to drive signals ─────────────
vif.PADDR   <= 12'h004;       // drives the actual interface signal
vif.PSELx   <= 1;
@(posedge vif.PCLK);          // waits on the interface clock
data = vif.PRDATA;             // reads from the interface

📋 Declaring the SV Interface

The SystemVerilog interface declaration lives in its own .sv file. It contains all the signals for one protocol bus. Clocking blocks (covered in the next section) can also be declared inside the interface to control signal sampling timing.

// File: apb_if.sv
interface apb_if (
  input logic PCLK,
  input logic PRESETn
);
  // APB signals
  logic [11:0] PADDR;
  logic        PSELx, PENABLE, PWRITE;
  logic [31:0] PWDATA, PRDATA;
  logic [3:0]  PSTRB;
  logic [2:0]  PPROT;
  logic        PREADY, PSLVERR;

  // Clocking block for driver — synchronises signal drives
  clocking driver_cb @(posedge PCLK);
    default input #1 output #1;
    output PADDR, PSELx, PENABLE, PWRITE, PWDATA, PSTRB, PPROT;
    input  PRDATA, PREADY, PSLVERR;
  endclocking

  // Clocking block for monitor — defines sampling point
  clocking monitor_cb @(posedge PCLK);
    default input #1;
    input PADDR, PSELx, PENABLE, PWRITE, PWDATA, PSTRB, PPROT;
    input PRDATA, PREADY, PSLVERR;
  endclocking

  // Modport for driver (restricts which signals it can access)
  modport driver_mp  (clocking driver_cb,  input PRESETn);
  modport monitor_mp (clocking monitor_cb, input PRESETn);
endinterface

📋 The config_db Pattern

The recommended pattern for passing virtual interfaces through the testbench has four steps. This is the only approach that cleanly separates the static and dynamic worlds while maintaining full reusability.

📋 End-to-End Flow — Complete Code

Step ① — tb_top: instantiate and set

module tb_top;
  import uvm_pkg::*;
  `include "uvm_macros.svh"

  logic clk, rst_n;
  apb_if apb_bus(.PCLK(clk), .PRESETn(rst_n));   // static instance

  gpio_dut dut(
    .PCLK(clk), .PRESETn(rst_n),
    .PADDR(apb_bus.PADDR), .PWRITE(apb_bus.PWRITE) /* ... */
  );

  initial begin
    // ① Pass virtual interface BEFORE run_test()
    uvm_config_db #(virtual apb_if)::set(
      null,             // null = from top-level static context
      "uvm_test_top",  // scope: accessible to test and all below
      "apb_vif",       // key name — test retrieves with this name
      apb_bus           // the actual interface instance handle
    );
    rst_n = 0; #20ns; rst_n = 1;
    run_test();
  end
endmodule

Step ② — test: retrieve and assign into config object

function void build_phase(uvm_phase phase);
  super.build_phase(phase);
  m_env_cfg = gpio_env_cfg::type_id::create("m_env_cfg");
  m_env_cfg.m_agent_cfg = gpio_agent_cfg::type_id::create("m_agent_cfg");

  // ② Retrieve vif from config_db and assign into agent config
  if (!uvm_config_db #(virtual apb_if)::get(
        this,       // this component's context
        "",         // no path suffix — search from this component up
        "apb_vif", // same key as the set() call
        m_env_cfg.m_agent_cfg.vif))
    `uvm_fatal("TEST", "No virtual interface in config_db!")
endfunction

Step ③ — agent: distribute vif from config object

function void build_phase(uvm_phase phase);
  super.build_phase(phase);
  if (!uvm_config_db #(gpio_agent_cfg)::get(
        this, "", "cfg", m_cfg))
    `uvm_fatal("AGT", "No agent config!")

  m_mon = gpio_monitor::type_id::create("m_mon", this);
  if (m_cfg.is_active == UVM_ACTIVE) begin
    m_seqr = gpio_sequencer::type_id::create("m_seqr", this);
    m_drv  = gpio_driver::type_id::create("m_drv", this);
  end

  // ③ Push vif (from config object) down to driver and monitor
  uvm_config_db #(virtual apb_if)::set(
    this, "m_mon", "vif", m_cfg.vif);
  if (m_cfg.is_active == UVM_ACTIVE)
    uvm_config_db #(virtual apb_if)::set(
      this, "m_drv", "vif", m_cfg.vif);
endfunction

Step ④ — driver/monitor: retrieve and use

class gpio_driver extends uvm_driver #(gpio_seq_item);
  `uvm_component_utils(gpio_driver)

  virtual apb_if vif;    // local handle — null until build_phase

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    // ④ Get vif from config_db — fatal if not found
    if (!uvm_config_db #(virtual apb_if)::get(
          this, "", "vif", vif))
      `uvm_fatal("DRV", "No virtual interface!")
  endfunction

  task run_phase(uvm_phase phase);
    // Now safe to use vif — handle is assigned
    @(posedge vif.PCLK);
    vif.PSELx <= 1;
    // ...
  endtask
endclass

📋 Clocking Blocks

A clocking block declared inside a SystemVerilog interface defines the timing relationship between the testbench and the DUT clock. It specifies when signals are sampled (input skew) and when they are driven (output skew) relative to the clock edge. This eliminates race conditions where the testbench drives signals at exactly the same edge the DUT samples them.

// Inside apb_if — clocking block for the driver
clocking driver_cb @(posedge PCLK);
  default input  #1step   // sample 1 step before posedge
          output #1;       // drive 1 time unit after posedge
  output PADDR, PSELx, PENABLE, PWRITE, PWDATA, PSTRB;
  input  PRDATA, PREADY, PSLVERR;
endclocking

// In the driver — access through clocking block
task drive_transfer(gpio_seq_item item);
  @(vif.driver_cb);                   // wait for clock edge
  vif.driver_cb.PADDR  <= item.addr;  // drives 1ns after posedge
  vif.driver_cb.PSELx  <= 1;
  vif.driver_cb.PENABLE <= 0;
  @(vif.driver_cb);                   // next cycle
  vif.driver_cb.PENABLE <= 1;
endtask

📋 Multiple Interfaces

A DUT with multiple protocol interfaces requires one SV interface per bus, one agent per interface, and one virtual interface handle per interface in the relevant config object. Each virtual interface is placed into config_db with a unique key name.

// tb_top — two interfaces for a DUT with APB + AHB
apb_if apb_bus(.PCLK(clk), .PRESETn(rst_n));
ahb_if ahb_bus(.HCLK(clk), .HRESETn(rst_n));

initial begin
  uvm_config_db #(virtual apb_if)::set(
    null, "uvm_test_top", "apb_vif", apb_bus);
  uvm_config_db #(virtual ahb_if)::set(
    null, "uvm_test_top", "ahb_vif", ahb_bus);
  run_test();
end

// test — retrieve both, assign into respective agent configs
if (!uvm_config_db #(virtual apb_if)::get(
      this, "", "apb_vif", m_env_cfg.m_apb_cfg.vif))
  `uvm_fatal("TEST", "No APB vif!")
if (!uvm_config_db #(virtual ahb_if)::get(
      this, "", "ahb_vif", m_env_cfg.m_ahb_cfg.vif))
  `uvm_fatal("TEST", "No AHB vif!")

📋 Common Pitfalls

📋 Quick Reference