Building the Register Model

📋 Integration Architecture

After the register model is built (UVM-24), three more pieces are needed to make it functional inside the testbench. Together they form the complete RAL integration stack:

• Adapter — translates between the generic uvm_reg_bus_op struct and the bus-specific sequence item. One adapter per bus protocol.
• Sequencer link — map.set_sequencer(seqr, adapter) in connect_phase routes register method calls to the correct sequencer.
• Predictor — listens on the monitor’s analysis port and updates the register model mirror after every observed bus transfer.

📋 uvm_reg_bus_op — the Generic Item

The RAL framework does not generate bus-specific sequence items. Instead it generates a generic uvm_reg_bus_op struct with six fields. The adapter’s job is to map these fields to and from the bus-specific sequence item.

📋 The Adapter Class

The adapter extends uvm_reg_adapter and overrides two pure virtual functions: reg2bus() converts a uvm_reg_bus_op into a bus sequence item; bus2reg() does the reverse — after the driver completes, it extracts the response from the bus item and populates the uvm_reg_bus_op struct.

Two properties must be set in the constructor:

• supports_byte_enable — set to 1 if the bus protocol and driver support byte lane enables. APB does not; AHB does.
• provides_responses — set to 1 if the driver returns a separate response item (using put(rsp)). Set to 0 if the driver uses get_next_item()/item_done() and the response is in the same item. Getting this wrong locks the simulation or silently returns wrong data.

📋 Complete APB Adapter

class reg2apb_adapter extends uvm_reg_adapter;
  `uvm_object_utils(reg2apb_adapter)

  function new(string name = "reg2apb_adapter");
    super.new(name);
    // APB has no byte enables
    supports_byte_enable = 0;
    // APB driver uses get_next_item()/item_done() — no separate response
    provides_responses   = 0;
  endfunction

  // ── reg2bus: RAL → APB item ───────────────────────────────
  // Called when reg.write() or reg.read() is invoked
  virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
    apb_seq_item apb;
    apb = apb_seq_item::type_id::create("apb");
    // Map generic fields to APB fields
    apb.read_not_write = (rw.kind == UVM_READ) ? 1 : 0;
    apb.addr           = rw.addr[11:0];  // trim to 12-bit APB address
    apb.write_data     = rw.data;
    apb.byte_en        = 4'b1111;        // full word — APB has no byte_en
    return apb;
  endfunction

  // ── bus2reg: APB item → RAL ───────────────────────────────
  // Called when driver completes — extracts response into rw struct
  virtual function void bus2reg(uvm_sequence_item bus_item,
                                  ref uvm_reg_bus_op rw);
    apb_seq_item apb;
    if (!$cast(apb, bus_item))
      `uvm_fatal("ADPT", "bus_item is not an apb_seq_item")

    rw.kind   = apb.read_not_write ? UVM_READ : UVM_WRITE;
    rw.addr   = apb.addr;
    rw.data   = apb.read_data;   // PRDATA on reads
    // APB PSLVERR → UVM status
    rw.status = apb.error ? UVM_NOT_OK : UVM_IS_OK;
  endfunction

endclass

📋 provides_responses Flag — Getting It Right

This is the single most common source of RAL integration failures. The flag must match what the driver actually does:

📋 Three Prediction Modes

The register model maintains a mirror — a software copy of the expected hardware register state. After each register access, the mirror must be updated. There are three ways this can happen:

📋 Explicit Predictor Wiring

The built-in uvm_reg_predictor #(BUS_ITEM) component is parameterised on the bus item type. It subscribes to the monitor’s analysis port, uses the adapter to decode each bus item into a register operation, looks up the target register in the map, and calls predict() on it.

// ── In gpio_env: declare the predictor ───────────────────
class gpio_env extends uvm_env;
  `uvm_component_utils(gpio_env)

  gpio_agent    m_agent;
  gpio_reg_block m_reg_block;
  reg2apb_adapter m_adapter;

  // Explicit predictor — parameterised on bus item type
  uvm_reg_predictor #(apb_seq_item) m_predictor;

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);

    // Get register block from config
    if (!uvm_config_db #(gpio_reg_block)::get(
          this, "", "gpio_rm", m_reg_block))
      `uvm_fatal("ENV", "No register model!")

    m_agent     = gpio_agent::type_id::create("m_agent",     this);
    m_adapter   = reg2apb_adapter::type_id::create("m_adapter");
    m_predictor = uvm_reg_predictor #(apb_seq_item)::type_id::
                    create("m_predictor", this);
  endfunction

  function void connect_phase(uvm_phase phase);
    // ① Link map → sequencer via adapter (stimulus path)
    m_reg_block.APB_map.set_sequencer(m_agent.m_seqr, m_adapter);

    // ② Configure predictor (mirror-update path)
    m_predictor.map     = m_reg_block.APB_map;
    m_predictor.adapter = m_adapter;

    // ③ Connect monitor ap → predictor input
    m_agent.ap.connect(m_predictor.bus_in);
  endfunction

endclass

📋 Env connect_phase — Full Wiring

Three lines in connect_phase wire up the complete RAL integration. Each targets a different data path:

function void connect_phase(uvm_phase phase);

  // ── LINE 1: Stimulus path ─────────────────────────────────
  // map.set_sequencer(sequencer, adapter)
  // When reg.write/read is called, the map sends a uvm_reg_bus_op
  // to the adapter, which converts it to an APB item and sends
  // it to the sequencer → driver → DUT.
  m_reg_block.APB_map.set_sequencer(m_agent.m_seqr, m_adapter);

  // ── LINE 2: Mirror-update path (predictor config) ─────────
  // Tells the predictor which map to look up registers in,
  // and which adapter to use to decode APB items.
  m_predictor.map     = m_reg_block.APB_map;
  m_predictor.adapter = m_adapter;

  // ── LINE 3: Mirror-update path (analysis connection) ──────
  // Every bus transfer observed by the monitor is forwarded
  // to the predictor's bus_in export via the analysis port.
  m_agent.ap.connect(m_predictor.bus_in);

endfunction

📋 Sub-System Register Maps

At integration level, multiple block-level register blocks are composed into a sub-system block. Each sub-block is added to the integration-level map with a base address offset. The result is a single flat address map that covers all registers across all blocks.

class pss_reg_block extends uvm_reg_block;
  `uvm_object_utils(pss_reg_block)

  rand gpio_reg_block gpio;   // GPIO block at offset 0x0000
  rand spi_reg_block  spi;    // SPI block at offset 0x1000

  uvm_reg_map AHB_map;

  function new(string name = "pss_reg_block");
    super.new(name, UVM_NO_COVERAGE);
  endfunction

  virtual function void build();
    // Create AHB integration map: base=0, 4-byte wide, little-endian
    AHB_map = create_map("AHB_map", 32'h0, 4, UVM_LITTLE_ENDIAN);

    // Create and configure GPIO sub-block
    gpio = gpio_reg_block::type_id::create("gpio");
    gpio.configure(this);     // parent = this pss_reg_block
    gpio.build();

    // Add GPIO's default_map to AHB_map at offset 0x0000
    AHB_map.add_submap(gpio.default_map, 32'h0000);

    // Create and configure SPI sub-block
    spi = spi_reg_block::type_id::create("spi");
    spi.configure(this);
    spi.build();

    // Add SPI's default_map to AHB_map at offset 0x1000
    AHB_map.add_submap(spi.default_map, 32'h1000);

    lock_model();
  endfunction
endclass

// ── Integration env connect_phase: AHB map → AHB sequencer
pss_rm.AHB_map.set_sequencer(m_ahb_agent.m_seqr, m_ahb_adapter);
m_predictor.map     = pss_rm.AHB_map;
m_predictor.adapter = m_ahb_adapter;
m_ahb_agent.ap.connect(m_predictor.bus_in);

📋 Common Integration Pitfalls

📋 Quick Reference