Register Callbacks I: Access Hooks

Hook register and memory accesses with uvm_reg_cbs. Know the order of field and register hooks, and where uvm-core departs from the standard. Refuse an access before the bus, list a register's callbacks, and use the library's read-only and write-only callbacks.

You Will Be Able To

  • Predict the order of field and register hooks around one register write, in the standard and in uvm-core 2020.3.1.
  • Refuse an access in pre_write so no bus transfer happens, reading the old value from the mirror.
  • Hook reads (pre_read, post_read) and memories (uvm_mem_cb), and list callbacks with uvm_reg_cb_iter.
  • Say when the map adds uvm_reg_read_only_cbs and uvm_reg_write_only_cbs by itself.
Lesson
U18.7
Time
30 min
Runs on
Verilator with UVM
Check
4 questions

In this register slice the CTRL mode only rises: the design ignores a write that lowers it. The test lowered the mode, the bus transfer went out, and auto prediction set the mirror to the new value. The design still held the old one, and a later mirror check failed far from the cause.

CTRL at mode 9, write 03Bus transfersStatusMirrorDesign
With the ratchet in the mode field's pre_write (the example)0UVM_NOT_OK0909

Measured in the example: the callback refuses the write before the bus, so the model and the design still agree.

Where the Hooks Run

uvm_reg_cbs is the hook class of the register layer. Its tasks pre_write, post_write, pre_read and post_read receive the uvm_reg_item of the access. The pools are typedefs: uvm_reg_field_cb for fields, uvm_reg_cb for registers, uvm_mem_cb for memories and uvm_reg_bd_cb for backdoors.

  1. Each field, in order

    The field's own pre_write method, then its callbacks in add order. A callback may change the field value: mode_legal turned c into 9.

    modec -> 9
    lock0
  2. The register

    The register's pre_write method, then its callbacks. They see the merged value.

    value09
  3. Status check

    If any hook set a status other than UVM_IS_OK, the access ends here: no transfer, no prediction.

    lowered modeends here
  4. The bus

    The adapter turns the item into a bus transfer; auto prediction updates the mirror.

    APBwrite 00 data=09
  5. Post hooks

    Register callbacks, then the register method; then for each field its callbacks, then its method.

    ordercallbacks before methods

These steps are what uvm-core 2020.3.1 does; the example prints every hook, so you can read the order from the log. Reads follow the same plan with pre_read and post_read.

Pre hookStandard (§18.11.2.2 b)uvm-core 2020.3.1 (measured)
Firstregister method, register callbackseach field: method, callbacks
Theneach field: method, callbacksregister method, register callbacks
A register callback seesthe value as writtenthe value after field callbacks changed it

Write portable callbacks so that neither level depends on the other having run first.

The judgement this leaves you: a register-level check sees field edits (like 9 for c) only on uvm-core. Put a rule that needs the edited value on the field that edits it, or repeat the edit in the check.

ctrl.write(0c) on Uvm-Core 2020.3.1: Every Hook, in OrderThe order the example measured. The standard puts the register before its fields (step 2 note). Arrows follow the run.
  • Model
  • Step
  • Control
  • Data
ctrl.write(0c) on uvm-core 2020.3.1: every hook, in orderThe order the example measured. The standard puts the register before its fields (step 2 note). Arrows follow the run. model mode field method, thenmode_legal (c -> 9),mode_ratchet,mode_log model lock field method, then lock_log model ctrl register method, then ctrl_log;value 09 step status check UVM_NOT_OK: stophere step APB write 00 then auto prediction:mirror 09 step post hooks register callbacks,method; per fieldcallbacks, method next fieldmerged valueall pre hooks doneUVM_IS_OKtransfer done
  1. model mode fieldmethod, then mode_legal (c -> 9), mode_ratchet, mode_log
    • next field → lock field
  2. model lock fieldmethod, then lock_log
    • merged value → ctrl register
  3. model ctrl registermethod, then ctrl_log; value 09
    • all pre hooks done → status check
  4. step status checkUVM_NOT_OK: stop here
    • UVM_IS_OK → APB write 00
  5. step APB write 00then auto prediction: mirror 09
    • transfer done → post hooks
  6. step post hooksregister callbacks, method; per field callbacks, method
  1. Fields first (uvm-core)

    Each field runs its own pre_write method, then its callbacks. mode_legal changes the reserved mode c to 9.

  2. Then the register (uvm-core)

    The register's method and callbacks see the merged value 09. Standard behaviour (IEEE 1800.2-2020 §18.11.2.2 b): the register runs before its fields.

  3. One check

    After all pre hooks comes one status check. OK goes to the bus; anything else returns at once, with no transfer. On the second write mode_ratchet set UVM_NOT_OK.

  4. Post hooks

    After the transfer, callbacks run before methods: register, then each field. Here uvm-core and the standard agree.

Read the diagram as text
  • mode field: method, then mode_legal (c -> 9), mode_ratchet, mode_log
  • lock field: method, then lock_log
  • ctrl register: method, then ctrl_log; value 09
  • status check: UVM_NOT_OK: stop here
  • APB write 00: then auto prediction: mirror 09
  • post hooks: register callbacks, method; per field callbacks, method
  • mode field → lock field: next field
  • lock field → ctrl register: merged value
  • ctrl register → status check: all pre hooks done
  • status check → APB write 00: UVM_IS_OK
  • APB write 00 → post hooks: transfer done

Measured on uvm-core 2020.3.1 with Verilator 5.052. Only the pre hooks depart from the standard: fields before the register.

Refusing an Access Before the Bus

ratchet_cb is a field callback on CTRL's mode. In pre_write it compares the new mode with the mirrored one; if the new mode is lower, it sets the item's status to UVM_NOT_OK. The other pre-write hooks still run, then do_write returns before the bus. The mirror stays at 09, and write returns UVM_NOT_OK.

Ratchet in post_write

task post_write(uvm_reg_item rw);
  if (rw.get_value(0) < mode.get_mirrored_value())
    rw.set_status(UVM_NOT_OK);
endtask

Too late: the transfer went out and the mirror already holds 3, so the check never fires.

Ratchet in pre_write

task pre_write(uvm_reg_item rw);
  if (rw.get_value(0) < mode.get_mirrored_value())
    rw.set_status(UVM_NOT_OK);
endtask

No transfer, mirror unchanged (the example).

A register callback that sets UVM_NOT_OK stops the access too. The status check comes after the field and register pre hooks, whichever ran first. Put the check where its rule lives: this rule is about one field, so it sits on the field.

One value is already changed when your hook runs: write sets the desired value first. The refused write leaves desired 03 and mirror 09, so a later update would try to send 03.

Memories have the same hooks. uvm_mem_cb::add(regs.mem, cb) attaches a callback to a memory; rw.get_offset() says which word. A memory's pre_write or pre_read can refuse the access the same way. In the example mem_log prints offset 2 around a write and a read.

Read-Only and Write-Only Registers at One Address

STATUS (read-only) and CMD (write-only) share address 04. The library has two singleton callbacks for this. uvm_reg_read_only_cbs refuses writes with UVM/REG/READONLY; uvm_reg_write_only_cbs refuses reads with UVM/REG/WRTEONLY. Each sets UVM_NOT_OK before the bus.

You do not add them for such a pair. When add_reg finds a read-only and a write-only register at one address, the map adds both callbacks itself. In the example status.write and cmd.read are refused although the test added nothing; adding them again only prints CBPREG.

To see what is attached, walk the register's pool with uvm_reg_cb_iter: first(), then next() until null. Fields have uvm_reg_field_cb_iter, memories uvm_mem_cb_iter. In the example STATUS lists the map's uvm_reg_read_only_cbs before the test's status_log.

Add the read-only callback yourself when a register must refuse writes on its own. An example is a register that a lock turns read-only. remove takes it off again.

What to Hook, and What to Subclass

UseHookWhy there
Protection: lock, mode, privilegeregister or field pre_write, pre_readRuns before the bus; can refuse
Legal values, reserved bitsfield pre_writeCan change the field value
Access log or auditpost_write, post_readSees the final value and status
Coverage of accessespost_write, post_readCounts only accesses that happened
Cross-register rulespost_predictRuns after each read or write prediction (U18.8)

Register callbacks add behaviour to a generated model without editing it.

A generated register model is regenerated when the specification changes, so edits inside its classes are lost. Callbacks live in your bench and survive regeneration. Subclass a register only when its own methods must change for every user.

Try It

The first write prints every hook in uvm-core's order, fields before the register, with the field callback changing mode c to 9. The second write is refused by mode_ratchet: the other pre hooks still print, but no APB line follows, and the mirror stays 09. The two UVM_ERROR lines come from the library's read-only and write-only callbacks.

The iterator shows what is attached: the map's singletons and the test's status_log. The read and the memory accesses print their pre_read, post_read and memory hooks; the memory stores 5a scrambled as ff.

Move the ratchet's check into post_write and run again: an APB write appears, the mirror becomes 03, and the design still holds 09.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: ctrl.write(0c): mode c, lock 0 mode.pre_write method value=c mode_legal.pre_write callback value=c -> 9 mode_log.pre_write callback value=9 lock.pre_write method value=0 lock_log.pre_write callback value=0 ctrl.pre_write method value=9 ctrl_log.pre_write callback value=9 25 ns APB write 00 data=09 ctrl_log.post_write callback value=9 status=UVM_IS_OK ctrl.post_write method value=9 mode_log.post_write callback value=9 status=UVM_IS_OK mode.post_write method value=9 lock_log.post_write callback value=0 status=UVM_IS_OK lock.post_write method value=0 status=UVM_IS_OK mirror=09 dut=09 ctrl.write(03): lowers the mode mode.pre_write method value=3 mode_ratchet.pre_write callback refuses: 3 is below 9 mode_log.pre_write callback value=3 ctrl_log.pre_write callback value=3 status=UVM_NOT_OK transfers=0 mirror=09 desired=03 dut=09 status.write(01): STATUS is read-only status=UVM_NOT_OK transfers=0 commands taken=0 cmd.read: CMD is write-only status=UVM_NOT_OK transfers=0 callbacks on STATUS: uvm_reg_read_only_cbs status_log callbacks on CMD: uvm_reg_write_only_cbs cmd.write(07) then status.read status_log.pre_read callback 85 ns APB read 04 data=01 status_log.post_read callback value=1 status=UVM_IS_OK 1 command(s) taken mem.write(2, 5a) then mem.read(2) mem_log.pre_write callback offset=2 value=5a 115 ns APB write 48 data=5a mem_log.post_write callback offset=2 value=5a status=UVM_IS_OK mem_log.pre_read callback offset=2 145 ns APB read 48 data=5a mem_log.post_read callback offset=2 value=5a status=UVM_IS_OK read 5a, stored ff

Check Yourself

Predict the outputCFG is a read-write register alone at 08. CFG_A is alone at 0C. The test writes CFG, then calls uvm_reg_read_only_cbs::add(regs.cfg_a) and writes CFG_A. Both registers reach the same byte of storage. 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

class ro_test extends uvm_test;
  `uvm_component_utils(ro_test)
  slice_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 = 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);
    drv.log = 0;
    t0 = transfers;
    regs.cfg.write(st, 'h01);                          // CFG: read-write, no callback
    v = transfers - t0;
    uvm_reg_read_only_cbs::add(regs.cfg_a);            // CFG_A: treat it as read-only
    t0 = transfers;
    regs.cfg_a.write(st, 'h02);
    $display("cfg.write: %0d transfer(s); cfg_a.write: %s, %0d transfer(s); design holds %02h", v, st.name(), transfers - t0, tb.dut.cfg);
    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("ro_test");
  end
endmodule
ConceptA register callback sets UVM_NOT_OK in pre_write. A second register callback was added after it. What happens to the second callback and to the bus?
ConceptA refused write leaves desired 03 and mirror 09. The test later calls regs.ctrl.update(st). What does update do?
ConceptWhy keep a mode ratchet in a callback rather than editing the generated ctrl_reg class?

Common Mistakes

Wrong Refuse a write that breaks a rule in post_write.

The transfer has already happened and auto prediction has already moved the mirror.

Fix Set UVM_NOT_OK in pre_write (or pre_read), before the bus.

Wrong Compare the new mode with mode.get() inside the callback.

write sets the desired value to the new value before any hook runs, so get returns the request itself.

Fix Use get_mirrored_value(), the model's view of the design.

Before
if (rw.get_value(0) < mode.get())
After
if (rw.get_value(0) < mode.get_mirrored_value())

Wrong Add uvm_reg_read_only_cbs to a read-only register that shares its address with a write-only one.

The map already added it when it mapped the pair, so each add only prints CBPREG.

Fix Add it yourself only for a register that must refuse writes on its own.

Remember

  • Pre-hook order: the standard runs the register before its fields; uvm-core 2020.3.1 runs the fields first. Post hooks run callbacks before methods, register then fields, in both. Do not depend on the pre order.
  • A status other than UVM_IS_OK after the pre hooks ends the access with no transfer and no prediction.
  • Read rules from the mirror: write has already set the desired value.
  • Memories take callbacks through uvm_mem_cb; uvm_reg_cb_iter and its field and memory twins list what is attached.
  • The map adds read-only and write-only callbacks itself for a pair at one address; add them yourself only for a register alone.

Practice

Report a problem with this page