UVM RAL: Register Abstraction Layer Explained

A register abstraction layer (RAL) is the part of a UVM testbench that lets you reach a design's registers by name instead of by raw address. You describe the register map once as SystemVerilog objects, then call reg.write() and reg.read() from any sequence — no hand-coded bus cycles per register. This guide builds a small uvm ral model from scratch and shows how the block, register, field, adapter, predictor, and back-door access fit together.

Before you start: every UVM snippet below is syntax-only. The UVM class library ships with commercial tools, so these examples need a UVM-capable simulator — industry-standard simulation tools, VCS, or industry-standard simulators — or a free cloud setup such as EDA Playground. Icarus Verilog and Verilator cannot compile the UVM package. Only the one plain-SystemVerilog illustration near the end runs with no UVM library at all.

Why a register abstraction layer?

A medium DUT can have hundreds of registers. Writing 0x3 to address 0x0000 in every test is brittle: when the map moves, every test breaks, and nobody checks that a read-back matches what was written. RAL fixes this with three ideas. It is a single source of truth for the address map. It keeps a mirror — a predicted copy of each register's value — so reads are checked automatically. And it is bus-agnostic: the same reg.write() call works over APB or AXI because only the adapter changes.

The model: uvm_reg_block, uvm_reg, uvm_reg_field

The model is a hierarchy. A uvm_reg_field is one named bit-slice (say a 2-bit mode). A uvm_reg groups fields into one addressable register. A uvm_reg_block groups registers and owns the map. Start with a register of two fields:

class ctrl_reg extends uvm_reg;
  `uvm_object_utils(ctrl_reg)

  rand uvm_reg_field enable;   // 1 bit
  rand uvm_reg_field mode;     // 2 bits

  function new(string name = "ctrl_reg");
    super.new(name, .n_bits(32), .has_coverage(UVM_NO_COVERAGE));
  endfunction

  virtual function void build();
    enable = uvm_reg_field::type_id::create("enable");
    mode   = uvm_reg_field::type_id::create("mode");
    //         parent, size, lsb, access, volatile, reset, has_reset, is_rand, indiv.
    enable.configure(this, 1, 0, "RW", 0, 1'h0, 1, 1, 0);
    mode.configure  (this, 2, 1, "RW", 0, 2'h0, 1, 1, 0);
  endfunction
endclass

The configure() arguments trip people up: after the parent register come the field size, its lsb position, the access policy ("RW", "RO", "W1C"), the volatile flag, the reset value, whether it has a reset, whether it is randomizable, and whether it is individually accessible. build() is called by the block, not by UVM phasing.

Now wrap the registers in a block and lay out the map:

class dut_reg_block extends uvm_reg_block;
  `uvm_object_utils(dut_reg_block)

  rand ctrl_reg   ctrl;
  rand status_reg status;
  uvm_reg_map     map;

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

  virtual function void build();
    ctrl = ctrl_reg::type_id::create("ctrl");
    ctrl.configure(this);
    ctrl.build();

    status = status_reg::type_id::create("status");
    status.configure(this);
    status.build();

    // name, base address, bytes per word, endianness
    map = create_map("map", 0, 4, UVM_LITTLE_ENDIAN);
    map.add_reg(ctrl,   32'h0000, "RW");
    map.add_reg(status, 32'h0004, "RO");

    lock_model();   // finalize addresses; no more registers may be added
  endfunction
endclass

create_map() fixes the base address, the word size in bytes, and endianness; add_reg() places each register at an offset with its access right. lock_model() finalizes the layout — forget it and address computations silently misbehave.

The adapter: turning RAL calls into bus traffic

RAL speaks in a generic struct, uvm_reg_bus_op (address, data, kind, status). Your bus agent speaks in its own item, for example apb_item. The uvm_reg_adapter is the translator. You implement exactly two functions: reg2bus() converts a RAL request into a bus item the driver can run, and bus2reg() converts the driver's response back so RAL can record it.

class reg2apb_adapter extends uvm_reg_adapter;
  `uvm_object_utils(reg2apb_adapter)

  function new(string name = "reg2apb_adapter");
    super.new(name);
  endfunction

  // RAL request turned into a concrete bus transaction
  virtual function uvm_sequence_item reg2bus(const ref uvm_reg_bus_op rw);
    apb_item item = apb_item::type_id::create("item");
    item.addr  = rw.addr;
    item.data  = rw.data;
    item.write = (rw.kind == UVM_WRITE);
    return item;
  endfunction

  // Bus response translated back into RAL terms
  virtual function void bus2reg(uvm_sequence_item bus_item, ref uvm_reg_bus_op rw);
    apb_item item;
    $cast(item, bus_item);
    rw.addr   = item.addr;
    rw.data   = item.data;
    rw.kind   = item.write ? UVM_WRITE : UVM_READ;
    rw.status = UVM_IS_OK;
  endfunction
endclass

This is the only file you rewrite when the protocol changes — the model, sequences, and tests stay identical, which is the whole point of the abstraction.

The predictor: keeping the mirror honest

Every register tracks three values: the desired value you intend to write, the mirrored value RAL believes the hardware holds, and the actual value in the RTL. The predictor is what keeps the mirror aligned with reality. In explicit prediction (recommended), a uvm_reg_predictor subscribes to the bus monitor's analysis port; every observed transaction — including ones your own code did not initiate — updates the mirror. Wire it up in connect_phase:

// Inside the environment connect_phase:
// 1. Point the register map at the bus sequencer through the adapter.
reg_block.map.set_sequencer(apb_sqr, adapter);

// 2. Create a predictor and let it watch the monitor's analysis port.
predictor = uvm_reg_predictor#(apb_item)::type_id::create("predictor", this);
predictor.map     = reg_block.map;
predictor.adapter = adapter;
apb_monitor.ap.connect(predictor.bus_in);   // observed items feed the mirror

Explicit prediction beats the default auto-prediction because it also catches writes from other agents or the DUT itself. To picture the mirror without any UVM library, here is the same idea in plain SystemVerilog — a write updates the mirror, a read checks against it, and a silent register change is caught as a mismatch:

// Plain-SystemVerilog illustration of the RAL idea: a mirrored value.
// No UVM library required. The top module is named tb.
module tb;
  logic [7:0] dut_reg;   // the real register living inside the DUT
  logic [7:0] mirror;    // what RAL predicts the register currently holds
  logic [7:0] rdata;

  // A bus write: the hardware updates AND the "predictor" updates the mirror.
  task automatic bus_write(input [7:0] data);
    dut_reg = data;
    mirror  = data;
    $display("WRITE data=0x%02h  mirror=0x%02h", data, mirror);
  endtask

  // A bus read returns the actual hardware value.
  task automatic bus_read(output [7:0] data);
    data = dut_reg;
    $display("READ  data=0x%02h  mirror=0x%02h", data, mirror);
  endtask

  initial begin
    dut_reg = 8'h00;
    mirror  = 8'h00;

    // reg.write(0xA5): drive the bus; the predictor tracks the value.
    bus_write(8'hA5);

    // reg.read(): compare the read-back against the predicted mirror.
    bus_read(rdata);
    if (rdata === mirror) $display("PASS: read-back matches mirror (0x%02h)", rdata);
    else                  $display("FAIL: 0x%02h does not match 0x%02h", rdata, mirror);

    // Inject an RTL bug: the register changes with no bus transaction,
    // so the mirror is never updated and the prediction diverges.
    dut_reg = 8'h3C;
    bus_read(rdata);
    if (rdata === mirror) $display("PASS: still in sync");
    else                  $display("MISMATCH caught: actual 0x%02h vs predicted 0x%02h", rdata, mirror);

    $finish;
  end
endmodule

WRITE data=0xa5  mirror=0xa5
READ  data=0xa5  mirror=0xa5
PASS: read-back matches mirror (0xa5)
READ  data=0x3c  mirror=0xa5
MISMATCH caught: actual 0x3c vs predicted 0xa5
/var/folders/l0/gs5hnkm56g54bmxg32r6nnwr0000gn/T/tmp253u3a0a/ral_mirror_tb.sv:40: $finish called at 0 (1s)

Front-door vs back-door access

RAL can reach a register two ways. A front-door access drives a real transaction through the adapter and bus, consuming simulation time and exercising the decode logic. A back-door access uses a registered HDL path to read or write the RTL signal directly, in zero time, bypassing the bus entirely.

A common pattern: a back-door poke() forces a hard-to-reach state, then a front-door read() confirms the bus returns it.

reg.write(), reg.read(), and friends in a sequence

With the model built and connected, register access from a sequence reads like software:

class ctrl_cfg_seq extends uvm_sequence;
  `uvm_object_utils(ctrl_cfg_seq)
  dut_reg_block regs;

  function new(string name = "ctrl_cfg_seq");
    super.new(name);
  endfunction

  virtual task body();
    uvm_status_e   status;
    uvm_reg_data_t value;

    // Front-door write: a real APB transaction is driven on the bus.
    regs.ctrl.write(status, 32'h0000_0003);

    // Front-door read: returns the actual value sampled from the bus.
    regs.ctrl.read(status, value);

    // Back-door peek: reads the RTL signal directly, no bus cycles.
    regs.status.peek(status, value);

    // mirror(): read and auto-compare actual vs predicted value.
    regs.ctrl.mirror(status, UVM_CHECK);
  endtask
endclass

The key calls: write() and read() are front-door by default (pass UVM_BACKDOOR as the path to switch). peek() and poke() are always back-door. mirror(status, UVM_CHECK) reads the register and automatically compares the result against the mirror, flagging any mismatch. update() does the opposite — it writes every field whose desired value differs from the mirror, which is the fast way to push a whole configuration.

Common mistakes

• Forgetting lock_model(), so the map never finalizes and addresses come out wrong.
• Never calling set_sequencer(), so front-door accesses hang with no driver attached.
• Relying on auto-prediction while another agent also writes the bus — the mirror drifts and false mismatches appear.
• Skipping build() on a register or calling it before configure(), leaving fields unparented.
• Using back-door access without registering an hdl_path, which fails silently or errors at run time.