Register Callbacks II: Prediction and the Backdoor

Keep related mirrors consistent with post_predict: an alias, a counter that another register clears, a lock. Give a backdoor the transform its storage needs, after measuring why encode and decode do not do it in uvm-core 2020.3.1.

You Will Be Able To

  • Write post_predict callbacks for an alias pair, a clear on another register's write, and a lock.
  • Say which predictions run post_predict and which do not.
  • Put a storage transform inside a user backdoor.
  • Explain why encode and decode callbacks have no effect in uvm-core 2020.3.1.
Lesson
U18.8
Time
30 min
Runs on
Verilator with UVM
Check
4 questions

A memory stored each byte XORed with a5. The team added a decode callback to the backdoor, as the standard describes, and peek still returned scrambled bytes. The callback ran on every peek; its result never reached the item.

BackdoorBus wrote 77 at offset 2; peek returns
Raw, with a decode callbackd2
Unscrambles in read_func (the fix)77 for what the bus wrote

Measured in the example: the stored byte is 77 ^ a5 = d2.

post_predict Runs When the Mirror Changes

post_predict(fld, previous, value, kind, path, map) is a field callback. The field calls it after every write prediction (kind UVM_PREDICT_WRITE) and read prediction (UVM_PREDICT_READ). Auto prediction, the U13.3 predictor and backdoor accesses all predict. value is an inout: the callback may change what the mirror becomes.

A direct predict (UVM_PREDICT_DIRECT) does not call it. That makes cross-register rules safe: a callback that predicts another register does not start a chain back.

Rulepost_predict onDoes
Alias: two addresses, one storageeach register's fieldpredict the other register with value
Clear on another writethe writing register's fieldpredict 0 for the cleared field
Lock: a field ignores writesthe locked fieldset value = previous while locked

Each rule changes the model's mirror only; the bus is untouched.

Keeping an Alias Pair Equal

CFG at 08 and CFG_A at 0C are one byte in the design. Each register's field gets an alias_cb that predicts the other register. A write through either address now leaves both mirrors equal. So does a read after the design changed the byte by itself.

Remove the callback from CFG_A's field and the pair drifts: after cfg_a.write(5a) the CFG mirror stays 3c. A post_predict callback runs only for the field it is added to.

A Clear and a Lock

In the slice, STATUS counts CMD writes, and command 00 clears the count. STATUS's own hooks never run for a CMD write. So count_cb sits on CMD's field: on each write prediction it predicts STATUS, 0 for command 00 and one more otherwise.

Once CTRL's lock is 1, the design ignores CTRL writes. The bus transfer still happens, though, and auto prediction would take the new value. lock_cb, on both CTRL fields, sets value = previous for a write while the mirrored lock is 1. The mirror keeps 13 after ctrl.write(07).

lock_cb on the mode field only

uvm_reg_field_cb::add(regs.ctrl.mode, lk);

The lock field takes the written 0: mirror 03, design 13 (the quiz predict).

lock_cb on both fields

uvm_reg_field_cb::add(regs.ctrl.mode, lk);
uvm_reg_field_cb::add(regs.ctrl.lock, lk);

Mirror 13, design 13 (the example).

The fields of one register are predicted in order, mode before lock. So while mode is predicted, the lock mirror still holds the value from before this write, which is the one that counts.

The Backdoor Hook Points

A user backdoor (U14.1) overrides write and read_func. The base read calls do_pre_read, then read_func, then do_post_read; the base write is a fatal stub, so your write decides whether to call do_pre_write and do_post_write. These run the backdoor's own pre_*/post_* methods and the callbacks of uvm_reg_bd_cb (uvm_callbacks #(uvm_reg_backdoor, uvm_reg_cbs)).

Two of those callbacks are for storage that is not plain: decode on reads and encode on writes. The standard intends them for scrambled or ECC storage.

peek(2) Through a Backdoor with a Decode CallbackThe memory word at offset 2 (address 48) holds 77 scrambled: 77 ^ a5 = d2. Arrows are calls and returned values.
  • Test
  • Neutral
  • Storage
  • Step
  • Control
  • Data
CallValueReturnWaiting
peek(2) through a backdoor with a decode callbackThe memory word at offset 2 (address 48) holds 77 scrambled: 77 ^ a5 = d2. Arrows are calls and returned values. test Test regs.mem.peek(st, 2,v) neutral raw_backdoor read(): do_pre_read,read_func,do_post_read storage tb.dut.mem[2] stored byte d2 storage a copy of thevalue array get_value_arraycopies step unscramble_cb decode: data[0] ^=a5 read(rw)read_funcget_value_arraydecode(copy)
  1. neutral raw_backdoorread(): do_pre_read, read_func, do_post_read
    • read_func → tb.dut.mem[2]
    • get_value_array → a copy of the value array
  2. storage tb.dut.mem[2]stored byte d2
  3. storage a copy of the value arrayget_value_array copies
    • decode(copy) → unscramble_cb
  4. step unscramble_cbdecode: data[0] ^= a5
  5. test Testregs.mem.peek(st, 2, v)
    • read(rw) → raw_backdoor
  1. Read the storage

    read_func puts the stored byte, d2, into the item.

    Follow the calls, values and waits
    1. return d2: tb.dut.mem[2] → raw_backdoor
  2. Decode a copy

    do_post_read copies the item's value array into a local array and passes that to decode. The callback turns d2 into 77 in the copy.

    Follow the calls, values and waits
    1. data 77 in the copy only: a copy of the value array → unscramble_cb
  3. The copy is dropped

    Nothing copies the array back into the item, so peek returns d2. The fix is a backdoor that unscrambles in read_func.

Read the diagram as text
  • Test: regs.mem.peek(st, 2, v)
  • raw_backdoor: read(): do_pre_read, read_func, do_post_read
  • tb.dut.mem[2]: stored byte d2
  • a copy of the value array: get_value_array copies
  • unscramble_cb: decode: data[0] ^= a5
  • Test → raw_backdoor: read(rw)
  • raw_backdoor → tb.dut.mem[2]: read_func
  • raw_backdoor → a copy of the value array: get_value_array
  • a copy of the value array → unscramble_cb: decode(copy)

Standard behaviour: decode and encode transform backdoor data. Measured on uvm-core 2020.3.1: their changes are lost.

What Uvm-Core 2020.3.1 Does with Encode and Decode

do_post_read calls rw.get_value_array(value_array), which copies the item's dynamic array into a local one, and passes the local array to decode. Nothing writes the local array back. do_pre_write does the same for encode. The callbacks run; their changes are lost.

A raw backdoor plus callbacks

uvm_reg_bd_cb::add(raw, unscr);
regs.mem.peek(st, 2, v);   // d2

decode ran once; peek returned the stored byte.

The transform in the backdoor

rw.set_value(tb.dut.mem[off] ^ 8'ha5, 0);
regs.mem.peek(st, 2, v);   // the plain value

peek and the bus agree.

Try It

The two alias callbacks keep the mirrors equal in both directions. count_cb follows STATUS through two commands and the clear; lock_cb keeps CTRL at 13 when the locked design ignores 07.

The raw backdoor shows both backdoor callbacks running and changing nothing. peek returns the stored d2, and a poke of 11 is stored as 11, read by the bus as b4. The plain backdoor agrees with the bus.

Remove count_cb and run again: the STATUS mirror stays 00 while the design counts.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: cfg.write(3c): cfg mirror 3c, cfg_a mirror 3c cfg_a.write(5a): cfg mirror 5a, cfg_a mirror 5a cmd.write(07), cmd.write(09): status mirror 02, design 02 cmd.write(00): status mirror 00, design 00 ctrl.write(13) then ctrl.write(07): ctrl mirror 13, design 13 raw backdoor + decode callback: frontdoor wrote 77, peek returns d2, decode ran 1 time(s) raw backdoor + encode callback: poke 11, frontdoor reads b4, encode ran 1 time(s) plain backdoor: peek returns b4 plain backdoor: poke 22, frontdoor reads 22

Check Yourself

Predict the outputlock_cb is added to CTRL's mode field only. The test writes 13 (mode 3, lock 1), then 07, which the locked design ignores. What line does the $display print?
`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;

// The register slice of U13-U14 on a small APB bus. Every access completes at once.
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

// 00 CTRL: mode [3:0], lock [4]. The mode only rises: a write that lowers it is ignored.
//    Once lock is 1, writes to CTRL are ignored until reset.
// 04 reads STATUS (commands taken so far); a write to 04 is CMD. Command 00 clears STATUS.
// 08 CFG and 0C CFG_A are two addresses for one byte of storage.
// 40-7C MEM: 16 bytes, stored scrambled (XOR with a5).
// Writes are blocking assignments, so a backdoor can write the same variables.
module slice_csr (apb_if bus);
  logic [7:0] ctrl = 0, cmd = 0, cmds = 0, cfg = 0;
  logic [7:0] mem [16];
  initial foreach (mem[i]) mem[i] = 8'ha5;                 // plain 00 everywhere
  assign bus.pready = 1;
  always_comb
    if (bus.paddr >= 'h40 && bus.paddr < 'h80) bus.prdata = {24'b0, mem[bus.paddr[5:2]] ^ 8'ha5};
    else case (bus.paddr)
      'h00: bus.prdata = {24'b0, ctrl};
      'h04: bus.prdata = {24'b0, cmds};
      'h08, 'h0c: bus.prdata = {24'b0, cfg};
      default: bus.prdata = 0;
    endcase
  always @(posedge bus.clk)
    if (bus.psel && bus.penable && bus.pwrite) begin
      if (bus.paddr >= 'h40 && bus.paddr < 'h80) mem[bus.paddr[5:2]] = bus.pwdata[7:0] ^ 8'ha5;
      else case (bus.paddr)
        'h00: if (!ctrl[4] && bus.pwdata[3:0] >= ctrl[3:0]) ctrl = bus.pwdata[7:0] & 8'h1f;
        'h04: begin cmd = bus.pwdata[7:0]; cmds = (bus.pwdata[7:0] == 0) ? 0 : cmds + 1; end
        'h08, 'h0c: cfg = bus.pwdata[7:0];
      endcase
    end
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

int transfers;                               // every APB transfer the driver completes
class apb_driver extends uvm_driver #(apb_item);
  `uvm_component_utils(apb_driver)
  virtual apb_if vif;
  bit log = 1;
  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);
      vif.psel <= 1; vif.penable <= 0;
      vif.pwrite <= req.write; vif.paddr <= req.addr; vif.pwdata <= req.data;
      @(negedge vif.clk);
      vif.penable <= 1;
      do @(posedge vif.clk); while (!vif.pready);
      if (!req.write) req.data = vif.prdata;
      transfers++;
      if (log) $display("%3d ns  APB %s %02h data=%02h", $time, req.write ? "write" : "read ", req.addr, req.data[7:0]);
      @(negedge vif.clk);
      vif.psel <= 0; vif.penable <= 0;
      seq_item_port.item_done();
    end
  endtask
endclass

class apb_adapter extends uvm_reg_adapter;
  `uvm_object_utils(apb_adapter)
  function new(string name = "apb_adapter"); super.new(name); 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 == UVM_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;
    $cast(t, bus_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 ctrl_reg extends uvm_reg;
  `uvm_object_utils(ctrl_reg)
  rand uvm_reg_field mode, lock;
  function new(string name = "ctrl"); super.new(name, 8, UVM_NO_COVERAGE); endfunction
  function void build();
    mode = uvm_reg_field::type_id::create("mode");
    mode.configure(this, 4, 0, "RW", 0, 0, 1, 1, 0);
    lock = uvm_reg_field::type_id::create("lock");
    lock.configure(this, 1, 4, "RW", 0, 0, 1, 1, 0);
  endfunction
endclass

// An 8-bit register with one field of the given access.
class byte_reg extends uvm_reg;
  `uvm_object_utils(byte_reg)
  rand uvm_reg_field val;
  string access = "RW";
  function new(string name = "byte_reg"); super.new(name, 8, UVM_NO_COVERAGE); endfunction
  function void build();
    val = uvm_reg_field::type_id::create("val");
    val.configure(this, 8, 0, access, 0, 0, 1, 1, 0);
  endfunction
endclass

class slice_regs extends uvm_reg_block;
  `uvm_object_utils(slice_regs)
  rand ctrl_reg ctrl;
  rand byte_reg status, cmd, cfg, cfg_a;
  uvm_mem       mem;
  function new(string name = "regs"); super.new(name, UVM_NO_COVERAGE); endfunction
  function byte_reg one(string name, string access);
    byte_reg r = byte_reg::type_id::create(name);
    r.access = access;
    r.configure(this);
    r.build();
    return r;
  endfunction
  function void build();
    ctrl = ctrl_reg::type_id::create("ctrl");
    ctrl.configure(this);
    ctrl.build();
    status = one("status", "RO");
    cmd    = one("cmd", "WO");
    cfg    = one("cfg", "RW");
    cfg_a  = one("cfg_a", "RW");
    mem = new("mem", 16, 32);                 // one 32-bit bus word per offset; the design keeps 8 bits
    mem.configure(this);
    default_map = create_map("map", 'h0, 4, UVM_LITTLE_ENDIAN);
    default_map.add_reg(ctrl,   'h00, "RW");
    default_map.add_reg(status, 'h04, "RO");             // STATUS and CMD share address 04
    default_map.add_reg(cmd,    'h04, "WO");
    default_map.add_reg(cfg,    'h08, "RW");
    default_map.add_reg(cfg_a,  'h0c, "RW");             // CFG_A is CFG at a second address
    default_map.add_mem(mem,    'h40, "RW");
    lock_model();
  endfunction
endclass

// Keeps CFG and CFG_A equal in the model: whatever is predicted for one is predicted for the other.
class alias_cb extends uvm_reg_cbs;
  `uvm_object_utils(alias_cb)
  uvm_reg other;
  function new(string name = "alias_cb"); super.new(name); endfunction
  // A direct predict runs no post_predict callbacks, so the two cannot call each other.
  function void post_predict(input uvm_reg_field fld, input uvm_reg_data_t previous,
                             inout uvm_reg_data_t value, input uvm_predict_e kind,
                             input uvm_door_e path, input uvm_reg_map map);
    void'(other.predict(value));
  endfunction
endclass

// The memory's backdoor. It reads and writes the stored byte as it is.
class raw_backdoor extends uvm_reg_backdoor;
  `uvm_object_utils(raw_backdoor)
  function new(string name = "raw_backdoor"); super.new(name); endfunction
  virtual task write(uvm_reg_item rw);
    do_pre_write(rw);                        // runs pre_write callbacks and encode
    tb.dut.mem[rw.get_offset()] = rw.get_value(0);
    rw.set_status(UVM_IS_OK);
    do_post_write(rw);
  endtask
  virtual function void read_func(uvm_reg_item rw);
    rw.set_value(tb.dut.mem[rw.get_offset()], 0);
    rw.set_status(UVM_IS_OK);
  endfunction
endclass

// The same, with the scrambling applied inside the backdoor: XOR with a5.
class plain_backdoor extends raw_backdoor;
  `uvm_object_utils(plain_backdoor)
  function new(string name = "plain_backdoor"); super.new(name); endfunction
  virtual task write(uvm_reg_item rw);
    tb.dut.mem[rw.get_offset()] = rw.get_value(0) ^ 8'ha5;
    rw.set_status(UVM_IS_OK);
  endtask
  virtual function void read_func(uvm_reg_item rw);
    rw.set_value(tb.dut.mem[rw.get_offset()] ^ 8'ha5, 0);
    rw.set_status(UVM_IS_OK);
  endfunction
endclass

// The standard's way to describe scrambled storage: decode on backdoor reads, encode on writes.
class unscramble_cb extends uvm_reg_cbs;
  `uvm_object_utils(unscramble_cb)
  int decodes, encodes;
  function new(string name = "unscramble_cb"); super.new(name); endfunction
  virtual function void decode(ref uvm_reg_data_t data[]);
    decodes++;
    data[0] = data[0] ^ 'ha5;
  endfunction
  virtual function void encode(ref uvm_reg_data_t data[]);
    encodes++;
    data[0] = data[0] ^ 'ha5;
  endfunction
endclass

// STATUS counts CMD writes in the design, and command 00 clears it. CMD's write predictions
// carry that rule to STATUS's mirror.
class count_cb extends uvm_reg_cbs;
  `uvm_object_utils(count_cb)
  uvm_reg status;
  function new(string name = "count_cb"); super.new(name); endfunction
  function void post_predict(input uvm_reg_field fld, input uvm_reg_data_t previous,
                             inout uvm_reg_data_t value, input uvm_predict_e kind,
                             input uvm_door_e path, input uvm_reg_map map);
    if (kind != UVM_PREDICT_WRITE) return;
    void'(status.predict(value == 0 ? 0 : status.get_mirrored_value() + 1));
  endfunction
endclass

// Once CTRL's lock is 1, the design ignores CTRL writes. Keep the old mirror for such a write.
class lock_cb extends uvm_reg_cbs;
  `uvm_object_utils(lock_cb)
  uvm_reg_field lock;
  function new(string name = "lock_cb"); super.new(name); endfunction
  function void post_predict(input uvm_reg_field fld, input uvm_reg_data_t previous,
                             inout uvm_reg_data_t value, input uvm_predict_e kind,
                             input uvm_door_e path, input uvm_reg_map map);
    if (kind == UVM_PREDICT_WRITE && lock.get_mirrored_value() == 1) value = previous;
  endfunction
endclass

class lock_test extends uvm_test;
  `uvm_component_utils(lock_test)
  slice_regs                regs;
  apb_adapter               adapter;
  apb_driver                drv;
  uvm_sequencer #(apb_item) sqr;
  lock_cb lk;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    regs = slice_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 apb_if")
  endfunction
  function void connect_phase(uvm_phase phase);
    drv.seq_item_port.connect(sqr.seq_item_export);
    regs.default_map.set_sequencer(sqr, adapter);
    regs.default_map.set_auto_predict(1);
  endfunction
  task run_phase(uvm_phase phase);
    uvm_status_e   st;
    uvm_reg_data_t v;
    int            t0;
    phase.raise_objection(this);
    lk = new("lock"); lk.lock = regs.ctrl.lock;
    uvm_reg_field_cb::add(regs.ctrl.mode, lk);          // the mode field only
    drv.log = 0;
    regs.ctrl.write(st, 'h13);
    regs.ctrl.write(st, 'h07);
    $display("ctrl.write(13) then ctrl.write(07): ctrl mirror %02h, design %02h", regs.ctrl.get_mirrored_value(), tb.dut.ctrl);
    phase.drop_objection(this);
  endtask
endclass

module tb;
  bit clk;
  always #5 clk = ~clk;
  apb_if    bus (clk);
  slice_csr dut (bus);
  initial begin
    uvm_config_db #(virtual apb_if)::set(null, "uvm_test_top", "vif", bus);
    run_test("lock_test");
  end
endmodule
ConceptThe design changes CFG by itself to 22. The test reads through CFG_A, and both fields have alias callbacks that skip predictions whose kind is not UVM_PREDICT_WRITE. What are the mirrors after the read?
ConceptYour backdoor's write stores rw.get_value(0) and never calls do_pre_write. An encode callback is added with uvm_reg_bd_cb::add. Does encode run on a poke?
ConceptWhich field callback keeps a read-to-clear STATUS field's mirror right when another register's write clears it in the design?

Common Mistakes

Wrong Copy previous to the other register in post_predict.

previous is the old mirror; the new one is value.

Fix Predict the other register with value.

Before
void'(other.predict(previous));
After
void'(other.predict(value));

Wrong Keep the alias with other.set(value).

set changes the desired value only; the other mirror stays stale.

Fix Use predict, which sets the mirror and the desired value.

Wrong Describe scrambled storage with a decode callback on a raw backdoor.

uvm-core 2020.3.1 passes decode a copy and throws it away, so peek returns the scrambled value.

Fix Unscramble in the backdoor's read_func and scramble in its write.

Remember

  • post_predict runs for write and read predictions and may change value; a direct predict runs no callbacks.
  • An alias pair needs a callback on each register's field that predicts the other with value. A clear sits on the writing register's field; a lock sets value = previous.
  • Backdoor callbacks run through do_pre_read, do_post_read, do_pre_write and do_post_write; your write must call the write pair.
  • In uvm-core 2020.3.1 encode and decode change a copy only: put storage transforms in the backdoor itself.

Practice

Report a problem with this page