Desired values, mirrors and reset

A model of the registers, in classes

The incrementer now has a small register slice. CTRL, at address 0, holds an 8-bit mode field that software reads and writes; it resets to 0x01. STATUS, at address 4, holds an 8-bit level that only the hardware changes.

A register model describes those registers as objects, so tests can say regs.ctrl.write(...) instead of building bus items by hand. UVM supplies the base classes: uvm_reg_field for a field, uvm_reg for a register and uvm_reg_block for a group of registers with their addresses.

Each field gets its size, position, access policy and reset value in one configure call. The access policy is a string such as "RW" (read-write), "RO" (read-only) or "W1C" (write 1 to clear). The model uses it to work out what a read or write should do to the field.

//             parent size lsb access volatile reset has_reset is_rand indiv
mode.configure(this,  8,   0,  "RW",  0,       8'h01, 1,       1,      0);

volatile marks a field the hardware may change by itself, like STATUS. has_reset says whether the reset value is real. is_rand lets randomize() pick a value for the field, and indiv says whether the field can be accessed on its own.

The block and its address map

The block creates each register, calls its configure and build, and then creates an address map. The map records where each register sits on a bus. Here create_map("map", 'h0, 4, UVM_LITTLE_ENDIAN) describes a bus with 4-byte words, and add_reg places CTRL at 0 and STATUS at 4.

The map does not know about any bus yet. It only records offsets and the width of a bus word. Lesson U13.2 connects it to a real sequencer, and from then on the same map turns register calls into bus transfers. A block can hold several maps, one per bus that reaches the registers, such as a processor bus and a debug port.

Finally lock_model() freezes the structure and computes the address tables. The model cannot be used for accesses until it is locked, and nothing can be added after. A block is a uvm_object, not a component, so the test creates it and calls build() itself.

Real projects rarely type these classes. A generator writes them from the register specification (IP-XACT, SystemRDL or a spreadsheet), together with the RTL decoder and the software headers, so the model cannot drift from the design. U14.4 shows a generated model and why you never edit it by hand.

Two values per field

Every field keeps two values. The mirrored value is the model's best belief about what the hardware holds right now. The desired value is what the test wants the hardware to hold next. Most of the time they are equal.

set changes only the desired value, so after set('h5a) the model says "I want 5a, I believe 01". needs_update() then returns 1, and a later update() writes the difference to the hardware. Several set calls before one update cost a single bus write.

set follows the access policy. On the read-only STATUS field it changes nothing, because software cannot change that field: status.set('h33) leaves the desired value at 00.

How the access policy shapes the values

The access string is not only documentation. The model uses it each time it works out a new mirrored value after an access. A few common access types show the idea.

For "RW", a write stores the written value, and a read returns it. For "RO", a write has no effect on the field, so the mirror keeps its old value. For "W1C", each 1 in the written value clears that bit and each 0 leaves it alone: writing 0x01 to a W1C field that holds 0x03 leaves 0x02.

Read side effects are modelled too. A "RC" field clears itself when read, so after a predicted read the mirror becomes 0. That is how a status register that clears on read stays correct in the model.

Take each field's access type from the register specification. A wrong access string does not break the model at once. The mirror drifts from the hardware after the first access, and the next mirror check reports an error that looks like a design bug.

predict changes both values

predict(v) tells the model "the hardware now holds v". It sets the mirrored value, and it sets the desired value too. Any pending set is lost, which is the hook's bug: after set('h22) and predict('h44), both values are 44, needs_update() returns 0 and update() sends nothing.

So keep predict for what it is meant for: recording something that really happened on the hardware. Lesson U13.3 lets a predictor component call it for every transfer a monitor sees. A test that wants a new value should use set and update, or write.

regs.ctrl.set('h22);
void'(regs.ctrl.predict('h44));
regs.ctrl.update(status);   // sends nothing

regs.ctrl.set('h22);
regs.ctrl.update(status);   // one bus write of 0x22

Resetting the model

regs.reset() sets every field's desired and mirrored values to its reset value. It is pure bookkeeping: it does not drive the design's reset pin. Call it when the design really is reset, so the model starts from the same values as the hardware.

Reset values matter beyond the first access. Many tests start with a quick check that every register reads back its reset value. That check compares the design with the model's reset values, so a typo in one configure call shows up as a design failure on the first day.

The model's idea of reset comes only from configure. A field configured with has_reset = 0 has no reset value, and reset() leaves it alone. Its desired and mirrored values then keep whatever they held before.

Try it

Each line shows CTRL's desired value, its mirror and needs_update(), plus STATUS's desired value. Compare them with the trace above: only set makes the two CTRL values differ, and predict and reset bring them together again.

Change STATUS's access from "RO" to "RW" and run again: status.set('h33) now changes its desired value. Then set CTRL's has_reset argument to 0 and see what the second reset() does.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class ctrl_reg extends uvm_reg;
  `uvm_object_utils(ctrl_reg)
  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, 0, 0);
  endfunction
endclass
class regs_c extends uvm_reg_block;
  `uvm_object_utils(regs_c)
  ctrl_reg ctrl;
  function new(string name = "regs_c"); 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
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void end_of_elaboration_phase(uvm_phase phase);
    regs_c regs = regs_c::type_id::create("regs");
    regs.build();
    regs.reset();
    regs.ctrl.set('h33);
    void'(regs.ctrl.predict('h44));
    $display("desired=%0h mirrored=%0h needs_update=%0d",
             regs.ctrl.get(), regs.ctrl.get_mirrored_value(), regs.ctrl.needs_update());
  endfunction
endclass
module tb;
  initial run_test("my_test");
endmodule

mode.configure(this, 8, 0, "RW", 1, 8'h0f, 1, 0, 0);

mode.configure(this, 8, 0, "RW", 0, 8'h0f, 0, 1, 0);

mode.configure(this, 8, 0, "RW", 0, 8'h0f, 1, 0, 0);

mode.configure(this, 8, 0, "RW", 0, 8'h0f, 1, 1, 1);