An APB adapter and frontdoor access

From a register call to a bus item

In U13.1 the model only kept books. Now its calls reach the design. A frontdoor access uses the real bus, through the same driver a test would use. When a test calls regs.ctrl.write(status, 'h5a), the call travels through four layers and comes back.

None of this is visible to the test. It calls one task and gets back a status, and the same call works whether the design sits on APB, AXI or a custom bus. That is the main reason to use a register model: tests talk about registers and fields, and only the adapter knows the protocol.

On the way back, the adapter's bus2reg turns the finished item into a uvm_reg_bus_op again. The map reads its data and its status, and write returns that status to the test.

The adapter in two functions

An adapter extends uvm_reg_adapter and overrides two functions. reg2bus(rw) creates a bus item from a register operation. bus2reg(item, rw) fills a register operation from a bus item. Everything protocol-specific stays in the adapter, so the same register model can run on APB today and on another bus later.

virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
  apb_item t = apb_item::type_id::create("t");
  t.write = (rw.kind inside {UVM_WRITE, UVM_BURST_WRITE});
  t.addr  = rw.addr;
  t.data  = rw.data;
  return t;
endfunction

virtual function void bus2reg(uvm_sequence_item bus_item, ref uvm_reg_bus_op rw);
  apb_item t;
  if (!$cast(t, bus_item)) `uvm_fatal("NOTAPB", "bus2reg needs an apb_item")
  rw.kind   = t.write ? UVM_WRITE : UVM_READ;
  rw.addr   = t.addr;
  rw.data   = t.data;      // for a read, the value the driver captured
  rw.status = UVM_IS_OK;
endfunction

The adapter is a uvm_object, created once by the environment and shared by every register access on that bus. It keeps no state between calls, so one adapter can serve any number of maps that use the same driver.

Two flags in the constructor describe the driver. supports_byte_enable says whether the bus can write single bytes; this APB slice cannot. provides_responses says how the driver returns results. With 0, the driver writes read data into the request object, and the map calls bus2reg on that same object. With 1, the map waits for a separate response item, as in U4.2.

Which one applies is a property of the driver, not of the protocol. The same APB bus can have a driver of either kind, so read the driver before setting the flag.

The flag must match the driver. Set it to 1 for a driver that never sends a response item, and every access hangs, as the hook showed. On this bench the APB write completed at 25 ns and write never returned. Set it to 0 for a driver that does send responses, and those responses pile up unread.

Connecting the model to the sequencer

One call in connect_phase joins the layers: regs.default_map.set_sequencer(sqr, adapter). From then on, every frontdoor access through default_map goes to sqr and is translated by adapter.

A second call chooses how the mirror is kept up to date. set_auto_predict(1) tells the map to update the mirror itself after each access it makes. It is the simplest choice, and the example uses it. Lesson U13.3 shows the other choice, a predictor fed by a monitor, and why it matters when other code also uses the bus.

Four frontdoor operations

update is where U13.1's two values pay off. A test can set several fields and then call update once. For a nonvolatile read-write register like CTRL, update writes only when the desired value differs from the mirror. So calling update again sends nothing. A volatile writable field always counts as needing an update.

mirror with UVM_CHECK is the register model's checker. It reads the register and compares the result with what the model expected. A mismatch is reported as a UVM_ERROR, so a design that loses a write fails the test.

Always check the status

Every frontdoor call returns a status through its first argument. UVM_IS_OK means the access completed. UVM_NOT_OK means the bus reported an error or the map could not perform it, for example because the register has no address in that map. UVM_HAS_X means a read returned unknown bits.

A test that ignores the status can pass while the design refuses every access. The read data then holds whatever the adapter copied, often 0, and a check against 0 may even succeed.

regs.ctrl.read(status, value);
if (value != 'h5a) `uvm_error("CTRL", "wrong value")

regs.ctrl.read(status, value);
if (status != UVM_IS_OK) `uvm_error("CTRL", status.name())
else if (value != 'h5a) `uvm_error("CTRL", "wrong value")

The status is only as good as the adapter. If bus2reg always writes UVM_IS_OK, as this small example does, errors on the bus never reach the test.

Reading the transfers

The example writes 0x5a, reads it back, sets 0x33 and updates, updates again, and finally mirrors with a check. The driver prints one line per transfer, at the edge where the design accepts it.

Count the transfers in the log: four, not five. The second update sent nothing because the mirror already matched. Every call returned UVM_IS_OK, which the adapter set in bus2reg. A real APB adapter would copy the bus's error signal, pslverr, into that status, so a refused access is reported as UVM_NOT_OK.

Register sequences and the model handle

Tests rarely call the model from run_phase for long. Register stimulus goes into a sequence that extends uvm_reg_sequence, which adds a model handle of type uvm_reg_block and helpers such as write_reg, read_reg and update_reg. The helpers pass the sequence as the parent of each access, so the accesses belong to it.

class ctrl_setup_seq extends uvm_reg_sequence;
  `uvm_object_utils(ctrl_setup_seq)
  function new(string name = "ctrl_setup_seq"); super.new(name); endfunction
  virtual task body();
    incr_regs    r;
    uvm_status_e status;
    if (!$cast(r, model)) `uvm_fatal("SEQ", "model is not an incr_regs")
    write_reg(r.ctrl, status, 'h5a);
    if (status != UVM_IS_OK) `uvm_error("SEQ", status.name())
  endtask
endclass

seq.model = regs;
seq.start(null);    // the map supplies the APB sequencer for each access

Because the sequence holds only model, the same sequence runs on any bench that builds an incr_regs, at block or chip level. It finds the model through its model handle, set by the test or read from the configuration database.

Try it

Each APB line is a transfer the driver completed; the other lines are the test reporting what each register call returned. Four calls produce transfers; the second update produces none.

Change the design so it stores only the low four bits (ctrl <= {4'b0, bus.pwdata[3:0]};) and run again. The read now returns 0a, and mirror with UVM_CHECK reports the mismatch as a UVM_ERROR.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;

// The incrementer's register slice on a small APB bus.
interface apb_if (input logic clk);
  logic        psel = 0, penable = 0, pwrite = 0;
  logic [31:0] paddr = 0, pwdata = 0;
  logic [31:0] prdata;
  logic        pready;
endinterface

// CTRL at address 0 (8 bits, read-write); every access completes at once.
module incr_csr (apb_if bus);
  logic [7:0] ctrl = 8'h01;
  assign bus.pready = 1;
  assign bus.prdata = (bus.paddr == 0) ? {24'b0, ctrl} : 32'b0;
  always @(posedge bus.clk)
    if (bus.psel && bus.penable && bus.pwrite && bus.paddr == 0)
      ctrl <= bus.pwdata[7:0];
endmodule

class apb_item extends uvm_sequence_item;
  `uvm_object_utils(apb_item)
  bit          write;
  bit   [31:0] addr, data;
  function new(string name = "apb_item"); super.new(name); endfunction
endclass

class ctrl_reg extends uvm_reg;
  `uvm_object_utils(ctrl_reg)
  rand uvm_reg_field mode;
  function new(string name = "ctrl_reg"); super.new(name, 32, UVM_NO_COVERAGE); endfunction
  function void build();
    mode = uvm_reg_field::type_id::create("mode");
    mode.configure(this, 8, 0, "RW", 0, 8'h01, 1, 1, 0);
  endfunction
endclass

class incr_regs extends uvm_reg_block;
  `uvm_object_utils(incr_regs)
  rand ctrl_reg ctrl;
  function new(string name = "incr_regs"); super.new(name, UVM_NO_COVERAGE); endfunction
  function void build();
    ctrl = ctrl_reg::type_id::create("ctrl");
    ctrl.configure(this);
    ctrl.build();
    default_map = create_map("map", 'h0, 4, UVM_LITTLE_ENDIAN);
    default_map.add_reg(ctrl, 'h0, "RW");
    lock_model();
  endfunction
endclass

// Translates between a register operation and an APB item.
class apb_adapter extends uvm_reg_adapter;
  `uvm_object_utils(apb_adapter)
  function new(string name = "apb_adapter");
    super.new(name);
    supports_byte_enable = 0;
    provides_responses   = 0;   // the driver writes read data into the request itself
  endfunction
  virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
    apb_item t = apb_item::type_id::create("t");
    t.write = (rw.kind inside {UVM_WRITE, UVM_BURST_WRITE});
    t.addr  = rw.addr;
    t.data  = rw.data;
    return t;
  endfunction
  virtual function void bus2reg(uvm_sequence_item bus_item, ref uvm_reg_bus_op rw);
    apb_item t;
    if (!$cast(t, bus_item)) `uvm_fatal("NOTAPB", "bus2reg needs an apb_item")
    rw.kind   = t.write ? UVM_WRITE : UVM_READ;
    rw.addr   = t.addr;
    rw.data   = t.data;
    rw.status = UVM_IS_OK;
  endfunction
endclass

class apb_driver extends uvm_driver #(apb_item);
  `uvm_component_utils(apb_driver)
  virtual apb_if vif;
  int transfers;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    forever begin
      seq_item_port.get_next_item(req);
      @(negedge vif.clk);                       // setup phase
      vif.psel <= 1; vif.penable <= 0;
      vif.pwrite <= req.write; vif.paddr <= req.addr; vif.pwdata <= req.data;
      @(negedge vif.clk);                       // access phase
      vif.penable <= 1;
      do @(posedge vif.clk); while (!vif.pready);
      if (!req.write) req.data = vif.prdata;    // read data goes back in the request
      transfers++;
      @(negedge vif.clk);
      vif.psel <= 0; vif.penable <= 0;
      seq_item_port.item_done();
    end
  endtask
endclass

class ral_test extends uvm_test;
  `uvm_component_utils(ral_test)
  incr_regs                 regs;
  apb_adapter               adapter;
  apb_driver                drv;
  uvm_sequencer #(apb_item) sqr;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    regs = incr_regs::type_id::create("regs");
    regs.build();
    adapter = apb_adapter::type_id::create("adapter");
    sqr = uvm_sequencer #(apb_item)::type_id::create("sqr", this);
    drv = apb_driver::type_id::create("drv", this);
    if (!uvm_config_db #(virtual apb_if)::get(this, "", "vif", drv.vif))
      `uvm_fatal("NOVIF", "no virtual interface")
  endfunction
  function void connect_phase(uvm_phase phase);
    drv.seq_item_port.connect(sqr.seq_item_export);
    regs.default_map.set_sequencer(sqr, adapter);   // register operations go through sqr
    regs.default_map.set_auto_predict(1);           // update the mirror after each access
  endfunction
  task run_phase(uvm_phase phase);
    uvm_status_e status;
    phase.raise_objection(this);
    regs.reset();
    regs.ctrl.write(status, 'h11);
    regs.ctrl.set('h11);
    regs.ctrl.update(status);
    regs.ctrl.set('h22);
    regs.ctrl.update(status);
    regs.ctrl.mirror(status, UVM_NO_CHECK);
    $display("transfers=%0d mirrored=%0h", drv.transfers, regs.ctrl.get_mirrored_value());
    phase.drop_objection(this);
  endtask
endclass

module tb;
  bit clk;
  always #5 clk = ~clk;
  apb_if   bus (clk);
  incr_csr dut (bus);
  initial begin
    uvm_config_db #(virtual apb_if)::set(null, "uvm_test_top", "vif", bus);
    run_test("ral_test");
  end
endmodule

rw.kind   = t.write ? UVM_WRITE : UVM_READ;
rw.addr   = t.addr;
if (t.write) rw.data = t.data;   // a read has no data to return yet
rw.status = UVM_IS_OK;

rw.status = UVM_IS_OK;
rw.data   = t.data;
rw.addr   = t.addr;
rw.kind   = t.write ? UVM_WRITE : UVM_READ;

if (t.write) rw.kind = UVM_WRITE;
else         rw.kind = UVM_READ;
rw.addr   = t.addr;
rw.data   = t.data;
rw.status = UVM_IS_OK;

rw.kind   = t.write ? UVM_WRITE : UVM_READ;
rw.addr   = t.addr;
rw.data   = t.data;
rw.status = UVM_IS_OK;

Practice

• Registers that all read zero Fix · Easy